feat: add receive file download preview contract
This commit is contained in:
zhaoyilun
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user