feat: add receive file download preview contract
This commit is contained in:
zhaoyilun
@@ -59,7 +59,7 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme
|
||||
|
||||
## Current loop
|
||||
|
||||
Current loop: `R10a returned send-sent record diagnostic intake complete`; next R11 receive-file download preview contract.
|
||||
Current loop: `R11 receive-file download preview contract complete`; next R12 receive-message reconciliation helper.
|
||||
|
||||
Active continuous execution plan: `docs/superpowers/plans/2026-07-10-r6f-r14-continuous-execution-plan.md`.
|
||||
|
||||
@@ -240,8 +240,8 @@ Continuous execution plan R6f-R14 is approved and execution has started:
|
||||
- Plan file: `docs/superpowers/plans/2026-07-10-r6f-r14-continuous-execution-plan.md`.
|
||||
- Scope: 15 ordered rounds covering send-message connector/gate hardening, send-file preview/idempotency/package, receive-file download preview, receive-message reconciliation, end-to-end business smoke, and release-candidate report.
|
||||
- Execution rule after approval: one round at a time, status-card update, verification, commit, push, then continue automatically until an evidence-only blocker requires user action.
|
||||
- Last completed round: R10a returned send-sent record diagnostic intake.
|
||||
- Next active round: R11 receive-file download preview contract.
|
||||
- Last completed round: R11 receive-file download preview contract.
|
||||
- Next active round: R12 receive-message reconciliation helper.
|
||||
|
||||
R6g send audit and idempotency replay diagnostics is complete:
|
||||
|
||||
@@ -344,3 +344,13 @@ R10a returned send-sent record diagnostic intake is complete:
|
||||
- Both packages also report `exact_content_seen_after=false`, `content_sha256_seen_after=false`, `after_offline_blocked=true`, `strict_send_record_pass=false`, and `production_send_unlock_recommended=false`.
|
||||
- Decision: production `isphere_send_message` remains blocked; the packages are useful manual evidence but not enough to open the send gate.
|
||||
- Next node: R11 receive-file download preview contract.
|
||||
|
||||
R11 receive-file download preview contract is complete:
|
||||
|
||||
- Added `file_ref` to `isphere_receive_files` download args and introduced a download resolver boundary for tests/future mapping.
|
||||
- `mode="download"` with `preview=true` now returns structured content instead of a generic tool error.
|
||||
- Without an accepted mapping, response is `ok=false`, `download_status="blocked"`, and `blocked_reason_code="file_cache_mapping_missing"`.
|
||||
- With an injected fixture mapping, response is `ok=true`, `download_status="planned"`, `mapping_source`, and `matched_score`.
|
||||
- Both paths keep `file_contents_read=false`, `file_copied=false`, `real_download_attempted=false`, and `raw_paths_returned=false`; real file copy remains blocked.
|
||||
- `scripts\verify-go-mcp.ps1` now asserts `receive_file_download_preview_blocked=true`.
|
||||
- Next node: R12 receive-message reconciliation helper.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This runbook is for the first Go MCP phase of `isphere-ai-bridge`. It lets an operator build and verify the Windows helper and the Go MCP server without reading the source code.
|
||||
|
||||
Current scope: expose four WinHelper observation operations, four business read tools, and two preview-only send tools through Go MCP. Read tools are `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. Send tools are `isphere_send_message` and `isphere_send_file` preview/dry-run only; production send/file upload is blocked. Read tools use an empty default message source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files. Contact/group display names can also be optionally enriched from an operator-local copied `MsgLib.db` through the bounded read-only `MsgLibReadSidecar`; receive messages can use copied DB rows only when the caller explicitly passes `source_preference="msglib_readonly"`.
|
||||
Current scope: expose four WinHelper observation operations, four business read tools, and two preview-only send tools through Go MCP. Read tools are `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode plus download preview/blocked status. Send tools are `isphere_send_message` and `isphere_send_file` preview/dry-run only; production send/file upload is blocked. Read tools use an empty default message source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files. Contact/group display names can also be optionally enriched from an operator-local copied `MsgLib.db` through the bounded read-only `MsgLibReadSidecar`; receive messages can use copied DB rows only when the caller explicitly passes `source_preference="msglib_readonly"`.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
@@ -98,14 +98,14 @@ The verification confirms:
|
||||
- A synthetic configured-directory smoke check proves `ISPHERE_PACKET_LOG_DIR` can drive `isphere_receive_messages`, contact search, group search, and file-list extraction from a temporary directory fixture.
|
||||
- `isphere_search_contacts` is callable and returns JID-derived contact candidates from the same configured synthetic message fixture; exact ID/display/account matches rank before prefix/substring matches and case-insensitive duplicates are collapsed.
|
||||
- `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture; exact ID/display-name matches rank before prefix/substring matches and case-insensitive duplicates are collapsed.
|
||||
- `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
|
||||
- `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture; download preview is callable and returns `download_status="blocked"` with `blocked_reason_code="file_cache_mapping_missing"` when no accepted mapping exists.
|
||||
- `isphere_send_message` is callable in preview mode and returns `send_status="planned"` without raw content in the response; the default runtime still returns `execution_mode="production"` as `send_status="blocked"` and `production_send_enabled=false`.
|
||||
- `isphere_send_file` is callable in preview mode when `ISPHERE_SEND_FILE_ALLOWED_DIR` points to the allowed local directory; it returns file SHA256/size metadata only, does not return file content, and keeps production upload blocked with `production_send_enabled=false`.
|
||||
- `isphere_send_message` also exposes sandbox-only connector metadata and idempotency state: duplicate reuse of the same key for the same target/content is detectable, while conflicting reuse of the same key for different content/target is blocked.
|
||||
- R6f adds a test-only fake/sandbox connector contract for accepted/failed connector outcomes. This is an injected unit-test boundary only; the production MCP server still registers no real connector and performs no real send.
|
||||
- Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
|
||||
- The deterministic verification path clears MsgLib env variables, so it proves the default no-MsgLib behavior remains stable.
|
||||
- File download/cache mapping, production message send, and production file upload remain later-stage work.
|
||||
- Real file download/copy, production message send, and production file upload remain later-stage work; file download preview now returns structured blocked/planned metadata with all copy/read side-effect flags false.
|
||||
|
||||
## 6. Configure optional message source
|
||||
|
||||
@@ -252,7 +252,7 @@ These ten tools are currently allowed:
|
||||
| `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source with a contract-shaped response envelope. The default server source is empty unless `ISPHERE_PACKET_LOG_FILE` or `ISPHERE_PACKET_LOG_DIR` is configured. |
|
||||
| `isphere_search_contacts` | log-backed message JIDs plus optional MsgLib display enrichment | Search contact candidates extracted from sender/receiver bare JIDs in the configured message source, with deterministic exact-match-first ranking, case-insensitive de-duplication, and preserved `source`/`raw_ref`. |
|
||||
| `isphere_search_groups` | log-backed groupchat JIDs plus optional MsgLib display enrichment | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source, with deterministic exact-match-first ranking, case-insensitive de-duplication, and preserved `source`/`raw_ref`. |
|
||||
| `isphere_receive_files` | log-backed file-transfer messages | List file metadata candidates extracted from file-transfer message bodies. Download/cache mapping is not implemented yet. |
|
||||
| `isphere_receive_files` | log-backed file-transfer messages plus download preview resolver boundary | List file metadata candidates extracted from file-transfer message bodies. Download preview returns structured `blocked` or `planned` metadata; real file copy remains blocked. |
|
||||
| `isphere_send_message` | B-route preview/dry-run contract | Plan a text-message send with target/content hash/idempotency/audit metadata. Production send is blocked. |
|
||||
| `isphere_send_file` | file-send preview/dry-run contract | Plan a file send with target/file SHA256/size/idempotency metadata. Production upload is blocked. |
|
||||
|
||||
@@ -265,7 +265,7 @@ Allowed parameters:
|
||||
- `isphere_receive_messages`: `conversation_id`, `query`, `since`, `include_attachment_metadata`, `source_preference`, `preview`, `cursor`, `limit` only. `since` must be RFC3339/RFC3339Nano when supplied; `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty until pagination is implemented.
|
||||
- `isphere_search_contacts`: `query`, `cursor`, `source_preference`, `include_inactive`, `limit` only. `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty until pagination is implemented.
|
||||
- `isphere_search_groups`: `query`, `cursor`, `source_preference`, `include_archived`, `limit` only. `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty until pagination is implemented.
|
||||
- `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `output_dir`, `cursor`, `source_preference`, `preview`, `limit` only. C22 supports `mode` empty or `list`; `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` and `output_dir` must be empty in current list-only mode; download is deferred.
|
||||
- `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `file_ref`, `name_contains`, `mode`, `output_dir`, `cursor`, `source_preference`, `preview`, `limit` only. List mode supports empty/`list`; `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty. Download mode supports preview-only status with `mode="download"`, `preview=true`, `file_ref` or `file_id`, and optional `output_dir`; real copy remains blocked unless a future accepted resolver and copy gate are added.
|
||||
- `isphere_send_message`: `target_type`, `target_id`, `content_text`, `content_sha256`, `idempotency_key`, `execution_mode` only. R6b supports `execution_mode` empty/`preview`/`dry_run` as planned preview. The default runtime returns `execution_mode="production"` as blocked until sandbox-send evidence passes. R6f adds a Go `SendMessageConnector` interface for fake/sandbox tests so accepted, failed, duplicate, and conflict paths can be validated without login. The response and audit store `content_sha256` and `idempotency_key_sha256`, not raw message body or raw idempotency key.
|
||||
- `isphere_send_file`: `target_type`, `target_id`, `file_path`, `file_sha256`, `idempotency_key`, `execution_mode`, `preview` only. `file_path` must stay inside `ISPHERE_SEND_FILE_ALLOWED_DIR`; preview computes/validates `file_sha256` and `file_size_bytes`, returns `real_send_attempted=false`, and does not upload or return file content. The default runtime returns `execution_mode="production"` as blocked.
|
||||
|
||||
@@ -329,9 +329,9 @@ The current runbook verifies ten tools:
|
||||
- `isphere_send_message`
|
||||
- `isphere_send_file`
|
||||
|
||||
The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args, rank exact matches before prefix/substring matches, collapse case-insensitive duplicates across log-derived candidates and optional `MsgLibReadSidecar` display metadata, and preserve `source`/`raw_ref`; receive-message `sender_name` and `conversation.display_name` can use that same optional metadata when MsgLib env is configured. `isphere_receive_files` supports list mode with safe contract arg validation; download/cache mapping remains deferred. `isphere_send_message` supports preview/dry-run metadata, sandbox-only connector-shell metadata, duplicate/conflict idempotency detection, redacted audit, and a test-only `SendMessageConnector` contract for fake accepted/failed outcomes; `isphere_send_file` now exposes preview/dry-run file SHA256/size planning behind `ISPHERE_SEND_FILE_ALLOWED_DIR` with all upload/send side-effect flags false. The default MCP server still has no real message/file connector and production send/file upload remains blocked until dynamic observation, full evidence gates, and controlled sandbox connector passes prove success/ack behavior.
|
||||
The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args, rank exact matches before prefix/substring matches, collapse case-insensitive duplicates across log-derived candidates and optional `MsgLibReadSidecar` display metadata, and preserve `source`/`raw_ref`; receive-message `sender_name` and `conversation.display_name` can use that same optional metadata when MsgLib env is configured. `isphere_receive_files` supports list mode with safe contract arg validation and download preview with machine-readable blocked/planned status; real download/copy remains blocked until accepted cache mapping and a separate copy gate exist. `isphere_send_message` supports preview/dry-run metadata, sandbox-only connector-shell metadata, duplicate/conflict idempotency detection, redacted audit, and a test-only `SendMessageConnector` contract for fake accepted/failed outcomes; `isphere_send_file` now exposes preview/dry-run file SHA256/size planning behind `ISPHERE_SEND_FILE_ALLOWED_DIR` with all upload/send side-effect flags false. The default MCP server still has no real message/file connector and production send/file upload remains blocked until dynamic observation, full evidence gates, and controlled sandbox connector passes prove success/ack behavior.
|
||||
|
||||
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send-message preview metadata and audit records are now in place; send-file preview metadata is in place with allowed-directory validation. Production message send and file upload still wait for later online sandbox evidence gates.
|
||||
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send-message preview metadata and audit records are now in place; send-file preview metadata is in place with allowed-directory validation. Production message send, real file download/copy, and file upload still wait for later evidence gates.
|
||||
|
||||
## 11. Real-login UIA capture procedure
|
||||
|
||||
|
||||
@@ -803,19 +803,19 @@ Created `docs/source-discovery/2026-07-10-returned-send-sent-record-diagnostic.m
|
||||
- If resolver lacks accepted mapping, response: `ok=false`, `download_status="blocked"`, `blocked_reason_code="file_cache_mapping_missing"`.
|
||||
- If resolver has accepted mapping in fixture tests, response: `ok=true`, `download_status="planned"`, no file copy during preview.
|
||||
|
||||
- [ ] **Step 1: Write blocked-preview test**
|
||||
- [x] **Step 1: Write blocked-preview test**
|
||||
|
||||
Add `TestISphereReceiveFilesDownloadPreviewBlockedWithoutMapping`, asserting `blocked_reason_code="file_cache_mapping_missing"` and `file_contents_read=false`.
|
||||
|
||||
- [ ] **Step 2: Write planned-preview fixture test**
|
||||
- [x] **Step 2: Write planned-preview fixture test**
|
||||
|
||||
Add `TestISphereReceiveFilesDownloadPreviewPlannedWithFixtureMapping`, using an injected fixture resolver and asserting `download_status="planned"`, `file_contents_read=false`, and `file_copied=false`.
|
||||
|
||||
- [ ] **Step 3: Implement preview contract**
|
||||
- [x] **Step 3: Implement preview contract**
|
||||
|
||||
Keep non-preview real download blocked unless R10 accepted mapping exists and a separate production-copy gate is added.
|
||||
|
||||
- [ ] **Step 4: Verify and commit**
|
||||
- [x] **Step 4: Verify and commit**
|
||||
|
||||
```powershell
|
||||
git diff --check
|
||||
@@ -830,6 +830,15 @@ git push gitea main
|
||||
|
||||
**Acceptance gate:** 数字员工可以理解“为什么现在不能下载”，并在有映射时得到 planned preview。
|
||||
|
||||
|
||||
**R11 Result:**
|
||||
|
||||
- Actual implementation files are `internal/tools/isphere_files.go` and `internal/tools/isphere_files_test.go`.
|
||||
- Added structured download preview blocked response for missing mapping.
|
||||
- Added injected fixture resolver test for planned preview.
|
||||
- Standard MCP smoke now reports `receive_file_download_preview_blocked=true`.
|
||||
- Real file copy/download remains blocked; preview reads no file contents and returns no raw paths.
|
||||
|
||||
---
|
||||
|
||||
### R12: Receive-message reconciliation helper
|
||||
|
||||
@@ -13,10 +13,35 @@ import (
|
||||
|
||||
const ToolNameReceiveFiles = "isphere_receive_files"
|
||||
|
||||
type ReceiveFileDownloadQuery struct {
|
||||
FileRef string
|
||||
OutputDir string
|
||||
Preview bool
|
||||
}
|
||||
|
||||
type ReceiveFileDownloadResolution struct {
|
||||
Found bool
|
||||
Source string
|
||||
MatchedScore int
|
||||
BlockedReasonCode string
|
||||
BlockedReasonMessage string
|
||||
}
|
||||
|
||||
type ReceiveFileDownloadResolver interface {
|
||||
ResolveReceiveFileDownload(context.Context, ReceiveFileDownloadQuery) (ReceiveFileDownloadResolution, error)
|
||||
}
|
||||
|
||||
type receiveFileDownloadResolverFunc func(context.Context, ReceiveFileDownloadQuery) (ReceiveFileDownloadResolution, error)
|
||||
|
||||
func (f receiveFileDownloadResolverFunc) ResolveReceiveFileDownload(ctx context.Context, query ReceiveFileDownloadQuery) (ReceiveFileDownloadResolution, error) {
|
||||
return f(ctx, query)
|
||||
}
|
||||
|
||||
type ReceiveFilesArgs struct {
|
||||
ConversationID string `json:"conversation_id,omitempty" jsonschema:"conversation id filter for file listing"`
|
||||
MessageID string `json:"message_id,omitempty" jsonschema:"message id filter for file listing"`
|
||||
FileID string `json:"file_id,omitempty" jsonschema:"file id filter for file listing"`
|
||||
FileRef string `json:"file_ref,omitempty" jsonschema:"download file reference; defaults to file_id when omitted"`
|
||||
NameContains string `json:"name_contains,omitempty" jsonschema:"case-insensitive filename substring filter"`
|
||||
Mode string `json:"mode,omitempty" jsonschema:"file receive mode; C14 supports list only"`
|
||||
OutputDir string `json:"output_dir,omitempty" jsonschema:"download output directory; not accepted in current list-only mode"`
|
||||
@@ -27,27 +52,34 @@ type ReceiveFilesArgs struct {
|
||||
}
|
||||
|
||||
func RegisterISphereFileTools(server *mcp.Server, source ReceiveMessagesSource) {
|
||||
RegisterISphereFileToolsWithDownloadResolver(server, source, nil)
|
||||
}
|
||||
|
||||
func RegisterISphereFileToolsWithDownloadResolver(server *mcp.Server, source ReceiveMessagesSource, downloadResolver ReceiveFileDownloadResolver) {
|
||||
if source == nil {
|
||||
source = isphere.EncryptedPacketLogSource{}
|
||||
}
|
||||
|
||||
mcp.AddTool[ReceiveFilesArgs, map[string]any](server, &mcp.Tool{
|
||||
Name: ToolNameReceiveFiles,
|
||||
Description: "List iSphere file metadata candidates from the configured read-only message source; download is deferred until cache mapping is validated.",
|
||||
Description: "List iSphere file metadata candidates from the configured read-only message source; download preview returns structured blocked/planned status until cache mapping is validated.",
|
||||
}, func(ctx context.Context, _ *mcp.CallToolRequest, input ReceiveFilesArgs) (*mcp.CallToolResult, map[string]any, error) {
|
||||
started := time.Now().UTC()
|
||||
mode := strings.ToLower(strings.TrimSpace(input.Mode))
|
||||
if mode == "" {
|
||||
mode = "list"
|
||||
}
|
||||
if mode != "list" {
|
||||
return nil, nil, fmt.Errorf("isphere_receive_files mode %q is not available; only list is supported", input.Mode)
|
||||
if mode != "list" && mode != "download" {
|
||||
return nil, nil, fmt.Errorf("isphere_receive_files mode %q is not available; supported modes are list and download preview", input.Mode)
|
||||
}
|
||||
if err := validateLocalReadonlySourceAndCursor(ToolNameReceiveFiles, input.SourcePreference, input.Cursor); err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
if mode == "download" {
|
||||
return nil, receiveFileDownloadPreviewResult(ctx, input, downloadResolver, started), nil
|
||||
}
|
||||
if strings.TrimSpace(input.OutputDir) != "" {
|
||||
return nil, nil, fmt.Errorf("isphere_receive_files output_dir is only available for download mode, which is not implemented yet")
|
||||
return nil, nil, fmt.Errorf("isphere_receive_files output_dir is only available for download mode")
|
||||
}
|
||||
messages, err := source.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: 0})
|
||||
if err != nil {
|
||||
@@ -64,6 +96,84 @@ func RegisterISphereFileTools(server *mcp.Server, source ReceiveMessagesSource)
|
||||
})
|
||||
}
|
||||
|
||||
func receiveFileDownloadPreviewResult(ctx context.Context, input ReceiveFilesArgs, resolver ReceiveFileDownloadResolver, started time.Time) map[string]any {
|
||||
fileRef := strings.TrimSpace(input.FileRef)
|
||||
if fileRef == "" {
|
||||
fileRef = strings.TrimSpace(input.FileID)
|
||||
}
|
||||
if fileRef == "" {
|
||||
return receiveFileDownloadBlockedResult(fileRef, "file_ref_required", "download preview requires file_ref or file_id", started, time.Now().UTC())
|
||||
}
|
||||
if !input.Preview {
|
||||
return receiveFileDownloadBlockedResult(fileRef, "file_download_production_disabled", "real file download is blocked; pass preview=true for a no-copy plan", started, time.Now().UTC())
|
||||
}
|
||||
if resolver == nil {
|
||||
return receiveFileDownloadBlockedResult(fileRef, "file_cache_mapping_missing", "no accepted receive-file cache mapping is configured", started, time.Now().UTC())
|
||||
}
|
||||
resolution, err := resolver.ResolveReceiveFileDownload(ctx, ReceiveFileDownloadQuery{
|
||||
FileRef: fileRef,
|
||||
OutputDir: strings.TrimSpace(input.OutputDir),
|
||||
Preview: true,
|
||||
})
|
||||
if err != nil {
|
||||
return receiveFileDownloadBlockedResult(fileRef, "file_cache_mapping_error", err.Error(), started, time.Now().UTC())
|
||||
}
|
||||
if !resolution.Found {
|
||||
code := strings.TrimSpace(resolution.BlockedReasonCode)
|
||||
if code == "" {
|
||||
code = "file_cache_mapping_missing"
|
||||
}
|
||||
message := strings.TrimSpace(resolution.BlockedReasonMessage)
|
||||
if message == "" {
|
||||
message = "no accepted receive-file cache mapping matched the requested file_ref"
|
||||
}
|
||||
return receiveFileDownloadBlockedResult(fileRef, code, message, started, time.Now().UTC())
|
||||
}
|
||||
return map[string]any{
|
||||
"ok": true,
|
||||
"mode": "download",
|
||||
"download_status": "planned",
|
||||
"file_ref": fileRef,
|
||||
"output_dir_requested": strings.TrimSpace(input.OutputDir) != "",
|
||||
"mapping_source": resolution.Source,
|
||||
"matched_score": resolution.MatchedScore,
|
||||
"preview": true,
|
||||
"file_contents_read": false,
|
||||
"file_copied": false,
|
||||
"real_download_attempted": false,
|
||||
"raw_paths_returned": false,
|
||||
"audit": receiveFileDownloadAudit("planned", started, time.Now().UTC()),
|
||||
}
|
||||
}
|
||||
|
||||
func receiveFileDownloadBlockedResult(fileRef string, reasonCode string, reasonMessage string, started time.Time, finished time.Time) map[string]any {
|
||||
return map[string]any{
|
||||
"ok": false,
|
||||
"mode": "download",
|
||||
"download_status": "blocked",
|
||||
"blocked_reason_code": reasonCode,
|
||||
"blocked_reason_message": reasonMessage,
|
||||
"file_ref": fileRef,
|
||||
"preview": true,
|
||||
"file_contents_read": false,
|
||||
"file_copied": false,
|
||||
"real_download_attempted": false,
|
||||
"raw_paths_returned": false,
|
||||
"audit": receiveFileDownloadAudit("blocked", started, finished),
|
||||
}
|
||||
}
|
||||
|
||||
func receiveFileDownloadAudit(result string, started time.Time, finished time.Time) map[string]any {
|
||||
return map[string]any{
|
||||
"tool": ToolNameReceiveFiles,
|
||||
"source": "local_readonly",
|
||||
"execution_mode": "download_preview",
|
||||
"started_at": started.Format(time.RFC3339Nano),
|
||||
"finished_at": finished.Format(time.RFC3339Nano),
|
||||
"result": result,
|
||||
}
|
||||
}
|
||||
|
||||
func receiveFilesResultToMap(result isphere.ListFilesResult, started time.Time, finished time.Time) map[string]any {
|
||||
files := make([]map[string]any, 0, len(result.Files))
|
||||
for _, file := range result.Files {
|
||||
|
||||
@@ -148,10 +148,139 @@ func TestISphereReceiveFilesToolValidatesContractArgs(t *testing.T) {
|
||||
}
|
||||
|
||||
downloadResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
|
||||
Name: ToolNameReceiveFiles,
|
||||
Arguments: map[string]any{"mode": "download", "file_id": "msg-file-1:redacted-report.docx"},
|
||||
Name: ToolNameReceiveFiles,
|
||||
Arguments: map[string]any{
|
||||
"mode": "download",
|
||||
"preview": true,
|
||||
"file_id": "msg-file-1:redacted-report.docx",
|
||||
},
|
||||
})
|
||||
if err == nil && !downloadResult.IsError {
|
||||
t.Fatalf("download mode was accepted before cache mapping exists")
|
||||
if err != nil {
|
||||
t.Fatalf("download preview returned transport error: %v", err)
|
||||
}
|
||||
if downloadResult.IsError {
|
||||
t.Fatalf("download preview should return structured blocked content: %+v", downloadResult.Content)
|
||||
}
|
||||
var downloadPayload map[string]any
|
||||
downloadEncoded, _ := json.Marshal(downloadResult.StructuredContent)
|
||||
if err := json.Unmarshal(downloadEncoded, &downloadPayload); err != nil {
|
||||
t.Fatalf("decode download structured content %s: %v", downloadEncoded, err)
|
||||
}
|
||||
if downloadPayload["ok"] != false || downloadPayload["download_status"] != "blocked" || downloadPayload["blocked_reason_code"] != "file_cache_mapping_missing" {
|
||||
t.Fatalf("unexpected download preview block: %s", downloadEncoded)
|
||||
}
|
||||
}
|
||||
|
||||
func TestISphereReceiveFilesDownloadPreviewBlockedWithoutMapping(t *testing.T) {
|
||||
fake := &fakeReceiveMessagesSource{}
|
||||
session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
|
||||
RegisterISphereFileTools(server, fake)
|
||||
})
|
||||
defer cleanup()
|
||||
|
||||
callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
|
||||
Name: ToolNameReceiveFiles,
|
||||
Arguments: map[string]any{
|
||||
"mode": "download",
|
||||
"preview": true,
|
||||
"file_ref": "msg-file-1:redacted-report.docx",
|
||||
"output_dir": "C:\\tmp\\isphere-downloads",
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("download preview call returned transport error: %v", err)
|
||||
}
|
||||
if callResult.IsError {
|
||||
t.Fatalf("download preview should return structured blocked content, got error: %+v", callResult)
|
||||
}
|
||||
|
||||
var decoded struct {
|
||||
OK bool `json:"ok"`
|
||||
Mode string `json:"mode"`
|
||||
DownloadStatus string `json:"download_status"`
|
||||
BlockedReasonCode string `json:"blocked_reason_code"`
|
||||
FileContentsRead bool `json:"file_contents_read"`
|
||||
FileCopied bool `json:"file_copied"`
|
||||
RealDownload bool `json:"real_download_attempted"`
|
||||
}
|
||||
payload, err := json.Marshal(callResult.StructuredContent)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal structured content: %v", err)
|
||||
}
|
||||
if err := json.Unmarshal(payload, &decoded); err != nil {
|
||||
t.Fatalf("decode structured content %s: %v", payload, err)
|
||||
}
|
||||
if decoded.OK || decoded.Mode != "download" || decoded.DownloadStatus != "blocked" {
|
||||
t.Fatalf("unexpected blocked response: %+v payload=%s", decoded, payload)
|
||||
}
|
||||
if decoded.BlockedReasonCode != "file_cache_mapping_missing" {
|
||||
t.Fatalf("blocked reason = %q", decoded.BlockedReasonCode)
|
||||
}
|
||||
if decoded.FileContentsRead || decoded.FileCopied || decoded.RealDownload {
|
||||
t.Fatalf("download side effects must be false: %+v", decoded)
|
||||
}
|
||||
}
|
||||
|
||||
func TestISphereReceiveFilesDownloadPreviewPlannedWithFixtureMapping(t *testing.T) {
|
||||
resolver := receiveFileDownloadResolverFunc(func(ctx context.Context, query ReceiveFileDownloadQuery) (ReceiveFileDownloadResolution, error) {
|
||||
if query.FileRef != "msg-file-1:redacted-report.docx" {
|
||||
t.Fatalf("resolver file_ref = %q", query.FileRef)
|
||||
}
|
||||
if query.OutputDir != "C:\\tmp\\isphere-downloads" {
|
||||
t.Fatalf("resolver output_dir = %q", query.OutputDir)
|
||||
}
|
||||
return ReceiveFileDownloadResolution{
|
||||
Found: true,
|
||||
Source: "fixture-cache-mapping",
|
||||
MatchedScore: 100,
|
||||
}, nil
|
||||
})
|
||||
session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
|
||||
RegisterISphereFileToolsWithDownloadResolver(server, nil, resolver)
|
||||
})
|
||||
defer cleanup()
|
||||
|
||||
callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
|
||||
Name: ToolNameReceiveFiles,
|
||||
Arguments: map[string]any{
|
||||
"mode": "download",
|
||||
"preview": true,
|
||||
"file_ref": "msg-file-1:redacted-report.docx",
|
||||
"output_dir": "C:\\tmp\\isphere-downloads",
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("download preview call returned transport error: %v", err)
|
||||
}
|
||||
if callResult.IsError {
|
||||
t.Fatalf("download preview should return planned content, got error: %+v", callResult)
|
||||
}
|
||||
|
||||
var decoded struct {
|
||||
OK bool `json:"ok"`
|
||||
Mode string `json:"mode"`
|
||||
DownloadStatus string `json:"download_status"`
|
||||
FileRef string `json:"file_ref"`
|
||||
MappingSource string `json:"mapping_source"`
|
||||
MatchedScore int `json:"matched_score"`
|
||||
FileContentsRead bool `json:"file_contents_read"`
|
||||
FileCopied bool `json:"file_copied"`
|
||||
RealDownload bool `json:"real_download_attempted"`
|
||||
}
|
||||
payload, err := json.Marshal(callResult.StructuredContent)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal structured content: %v", err)
|
||||
}
|
||||
if err := json.Unmarshal(payload, &decoded); err != nil {
|
||||
t.Fatalf("decode structured content %s: %v", payload, err)
|
||||
}
|
||||
if !decoded.OK || decoded.Mode != "download" || decoded.DownloadStatus != "planned" {
|
||||
t.Fatalf("unexpected planned response: %+v payload=%s", decoded, payload)
|
||||
}
|
||||
if decoded.FileRef != "msg-file-1:redacted-report.docx" || decoded.MappingSource != "fixture-cache-mapping" || decoded.MatchedScore != 100 {
|
||||
t.Fatalf("unexpected mapping metadata: %+v", decoded)
|
||||
}
|
||||
if decoded.FileContentsRead || decoded.FileCopied || decoded.RealDownload {
|
||||
t.Fatalf("preview side effects must be false: %+v", decoded)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -240,6 +240,7 @@ func main() {
|
||||
defaultContactCount := verifySearchContacts(ctx, session, "sender", "tools/call isphere_search_contacts default", 0)
|
||||
defaultGroupCount := verifySearchGroups(ctx, session, "project", "tools/call isphere_search_groups default", 0)
|
||||
defaultFileCount := verifyReceiveFiles(ctx, session, "report", "tools/call isphere_receive_files default", 0, "", "")
|
||||
receiveFileDownloadPreviewBlocked := verifyReceiveFileDownloadPreviewBlocked(ctx, session)
|
||||
sendPreviewOK, productionSendEnabled := verifySendMessagePreview(ctx, session)
|
||||
sendFilePreviewOK, sendFileProductionEnabled, sendFileDuplicateDetected, sendFileConflictBlocked := verifySendFilePreview(ctx, session, sendFilePath)
|
||||
configuredReceiveCount, configuredContactCount, configuredGroupCount, configuredFileCount := verifyConfiguredReceiveSource(ctx)
|
||||
@@ -256,6 +257,7 @@ func main() {
|
||||
"contact_count": defaultContactCount,
|
||||
"group_count": defaultGroupCount,
|
||||
"file_count": defaultFileCount,
|
||||
"receive_file_download_preview_blocked": receiveFileDownloadPreviewBlocked,
|
||||
"configured_receive_message_count": configuredReceiveCount,
|
||||
"configured_contact_count": configuredContactCount,
|
||||
"configured_group_count": configuredGroupCount,
|
||||
@@ -843,6 +845,36 @@ func verifyReceiveFiles(ctx context.Context, session *mcp.ClientSession, nameCon
|
||||
return len(filesValue)
|
||||
}
|
||||
|
||||
|
||||
func verifyReceiveFileDownloadPreviewBlocked(ctx context.Context, session *mcp.ClientSession) bool {
|
||||
callResult, err := session.CallTool(ctx, &mcp.CallToolParams{Name: "isphere_receive_files", Arguments: map[string]any{
|
||||
"mode": "download",
|
||||
"preview": true,
|
||||
"file_ref": "msg-fixture-1:redacted-report.docx",
|
||||
"output_dir": "C:\\tmp\\isphere-downloads",
|
||||
"source_preference": "local_readonly",
|
||||
"cursor": "",
|
||||
}})
|
||||
if err != nil {
|
||||
fail("tools/call isphere_receive_files download_preview", err)
|
||||
}
|
||||
if callResult.IsError {
|
||||
fail("tools/call isphere_receive_files download_preview", fmt.Errorf("tool returned isError=true: %#v", callResult.Content))
|
||||
}
|
||||
var payload map[string]any
|
||||
encoded, _ := json.Marshal(callResult.StructuredContent)
|
||||
if err := json.Unmarshal(encoded, &payload); err != nil {
|
||||
fail("tools/call isphere_receive_files download_preview", fmt.Errorf("decode structuredContent %s: %w", encoded, err))
|
||||
}
|
||||
if payload["ok"] != false || payload["mode"] != "download" || payload["download_status"] != "blocked" || payload["blocked_reason_code"] != "file_cache_mapping_missing" {
|
||||
fail("tools/call isphere_receive_files download_preview", fmt.Errorf("unexpected blocked payload: %s", encoded))
|
||||
}
|
||||
if payload["file_contents_read"] != false || payload["file_copied"] != false || payload["real_download_attempted"] != false || payload["raw_paths_returned"] != false {
|
||||
fail("tools/call isphere_receive_files download_preview", fmt.Errorf("unexpected download side effects: %s", encoded))
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
func encryptPacketLogLineForHarness(plaintext string) (string, error) {
|
||||
block, err := des.NewCipher([]byte("hyhccdtm"))
|
||||
if err != nil {
|
||||
@@ -909,6 +941,7 @@ func fail(step string, err error) {
|
||||
Assert-True ($script:harnessJson.contact_count -eq 0) "SDK harness contact_count mismatch: $($script:harnessJson.contact_count)"
|
||||
Assert-True ($script:harnessJson.group_count -eq 0) "SDK harness group_count mismatch: $($script:harnessJson.group_count)"
|
||||
Assert-True ($script:harnessJson.file_count -eq 0) "SDK harness file_count mismatch: $($script:harnessJson.file_count)"
|
||||
Assert-True ($script:harnessJson.receive_file_download_preview_blocked -eq $true) "SDK harness receive_file_download_preview_blocked mismatch: $($script:harnessJson.receive_file_download_preview_blocked)"
|
||||
Assert-True ($script:harnessJson.configured_receive_message_count -eq 1) "SDK harness configured_receive_message_count mismatch: $($script:harnessJson.configured_receive_message_count)"
|
||||
Assert-True ($script:harnessJson.configured_contact_count -eq 1) "SDK harness configured_contact_count mismatch: $($script:harnessJson.configured_contact_count)"
|
||||
Assert-True ($script:harnessJson.configured_group_count -eq 1) "SDK harness configured_group_count mismatch: $($script:harnessJson.configured_group_count)"
|
||||
@@ -935,6 +968,7 @@ func fail(step string, err error) {
|
||||
contact_count = $script:harnessJson.contact_count
|
||||
group_count = $script:harnessJson.group_count
|
||||
file_count = $script:harnessJson.file_count
|
||||
receive_file_download_preview_blocked = $script:harnessJson.receive_file_download_preview_blocked
|
||||
configured_receive_message_count = $script:harnessJson.configured_receive_message_count
|
||||
configured_contact_count = $script:harnessJson.configured_contact_count
|
||||
configured_group_count = $script:harnessJson.configured_group_count
|
||||
|
||||
Reference in New Issue
Block a user