diff --git a/docs/source-discovery/capability-source-matrix.md b/docs/source-discovery/capability-source-matrix.md index 5eab1de..a788148 100644 --- a/docs/source-discovery/capability-source-matrix.md +++ b/docs/source-discovery/capability-source-matrix.md @@ -1,7 +1,7 @@ # Capability Source Matrix Date: 2026-07-09 -Stage: B source discovery +Stage: C log-backed receive implementation Evidence index: `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md` Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md` @@ -17,7 +17,7 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md` | MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice | | --- | --- | --- | --- | --- | --- | -| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `` stanzas | decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces; wrapped `MsgLib.db` after DB wrapper is solved | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | selected for Stage C log-backed parser | first | +| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `` stanzas via `internal/isphere.EncryptedPacketLogSource` | decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces; wrapped `MsgLib.db` after DB wrapper is solved | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | C3 registered and unit-verified; default server source is empty until operator verification/loader wiring | fixture-backed operator verification and docs | | `isphere_search_contacts` | decrypted packet/send-receive JIDs and later roster stanzas from `Smark.SendReceive` | `MsgLib.db` contact/conversation tables after DB wrapper is solved; UIA helper source if display names are missing | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#log-decryption-result` | candidate pending parser coverage | second | | `isphere_search_groups` | decrypted XMPP group/message stanzas if groupchat/group JIDs appear | `MsgLib.db` group/conversation tables after DB wrapper is solved; UIA helper source if group display names are missing | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | candidate pending group stanza evidence | third | | `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas plus `zyl\importal\` cache mapping | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | candidate pending cache-reference mapping | fourth | diff --git a/docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md b/docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md index a39ceb0..b896234 100644 --- a/docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md +++ b/docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md @@ -655,7 +655,7 @@ Implemented and verified in this loop: - Tool source: `isphere.EncryptedPacketLogSource.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: input.Limit})`. - Tool output shape: a map/object with `messages`, where each message carries `id`, `conversation_id`, `conversation_type`, `sender_id`, `receiver_id`, `text`, `timestamp`, `subject`, `receipt_id`, and `read`. -- [ ] **Step 1: Write failing tool registration tests** +- [x] **Step 1: Write failing tool registration tests** Add or update tests so they fail before implementation: @@ -666,19 +666,19 @@ go test ./internal/mcpserver -run TestNewServerRegistersN8WinHelperToolsWithoutC Expected initial failures: `isphere_receive_messages` is not registered and the server/tool lists still expose only the four helper tools. -- [ ] **Step 2: Implement `internal/tools/isphere_read.go`** +- [x] **Step 2: Implement `internal/tools/isphere_read.go`** Register `isphere_receive_messages` with `mcp.AddTool`, convert the C2 `isphere.Message` slice into the explicit JSON/map output shape, and keep the only public input parameter as `limit`. Use a source interface so tests can inject a synthetic C2 source without raw evidence files. -- [ ] **Step 3: Register business read tool in `mcpserver.NewServer`** +- [x] **Step 3: Register business read tool in `mcpserver.NewServer`** Register the helper tools plus `isphere_receive_messages`. If no live log-line loader exists yet, wire an empty `isphere.EncryptedPacketLogSource{}` as the default so registration is testable without committing raw logs. -- [ ] **Step 4: Update existing helper-tool guard tests** +- [x] **Step 4: Update existing helper-tool guard tests** Rename or adjust the old “exactly four” helper test so it still blocks forbidden write/sending tool names but explicitly allows `isphere_receive_messages`. Update `internal/mcpserver/server_test.go` to expect five tools: four helper tools plus `isphere_receive_messages`. -- [ ] **Step 5: Run full verification** +- [x] **Step 5: Run full verification** Run: @@ -690,22 +690,75 @@ go build ./cmd/isphere-mcp Expected: all exit 0. -- [ ] **Step 6: Commit Loop C3 and rewrite Loop C4** +- [x] **Step 6: Commit Loop C3 and rewrite Loop C4** Commit exact C3 paths only. Rewrite Loop C4 around the actual MCP tool output shape and the fact that default server wiring has no raw evidence loader yet. --- +## Loop C3 Result + +Implemented and verified in this loop: + +- `internal/tools.RegisterISphereReadTools(server, source)` registers `isphere_receive_messages` with a single public input parameter: `limit`. +- `internal/tools.ToolNameReceiveMessages` is `isphere_receive_messages`. +- The tool calls the C2 source interface with `isphere.ReceiveMessagesQuery{Limit: input.Limit}` and returns structured content shaped as `messages: [{ id, conversation_id, conversation_type, sender_id, receiver_id, text, timestamp, subject, receipt_id, read }]`. +- `internal/mcpserver.NewServer()` now registers four WinHelper observation tools plus `isphere_receive_messages`; default source wiring uses an empty `isphere.EncryptedPacketLogSource{}` so no raw evidence is committed or loaded by default. +- Guard tests still keep helper tools scoped to helper observation operations while allowing `receive` as a legitimate read capability name for the new business tool. +- Verification completed for C3 with `git diff --check`, `go test ./...`, and `go build ./cmd/isphere-mcp`; the generated root `isphere-mcp.exe` build artifact was removed. +- Loop C4 was rewritten around the actual five-tool surface and empty default source behavior. + +--- + ## Loop C4: Operator verification and docs -**Current draft goal:** Add a verification command or fixture-backed smoke test for `isphere_receive_messages` and update user-facing docs. +**Goal:** Update the repeatable operator verification and user-facing docs for the five-tool surface after C3 registers `isphere_receive_messages`. **Planned files:** - Modify: `scripts/verify-go-mcp.ps1` - Modify: `docs/go-mcp-runbook.md` - Modify: `docs/current-status-card.md` +- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md` -**Rewrite rule before implementation:** Only write this loop after C3 confirms the actual MCP response shape. +**Interfaces from Loop C3:** +- Server tool list: four WinHelper observation tools plus `isphere_receive_messages`. +- Default `isphere_receive_messages` source: `isphere.EncryptedPacketLogSource{}` with no configured lines, so the operator smoke call should return `messages: []` until a real evidence loader is wired. +- Verification script should still call `win_helper_version`, and should additionally call `isphere_receive_messages` with a small `limit` and assert the returned `messages` field is an array. + +- [ ] **Step 1: Capture current verification red state** + +Run before editing the script: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1 +``` + +Expected: FAIL because the existing harness still expects exactly four tools and treats `receive` as a forbidden term. + +- [ ] **Step 2: Update `scripts/verify-go-mcp.ps1`** + +Change expected tools to five, remove `receive` from the forbidden write/scope terms, and add an SDK call to `isphere_receive_messages` with `{ "limit": 5 }`. Assert `messages` exists and is an array; for the default empty source, assert the smoke result has zero messages. + +- [ ] **Step 3: Update operator docs** + +Update `docs/go-mcp-runbook.md` and `docs/current-status-card.md` so they describe the current five-tool surface, the empty default read source, and the fact that raw N12-pre evidence still stays under ignored `runs/` paths. + +- [ ] **Step 4: Run full verification** + +Run: + +```powershell +git diff --check +go test ./... +go build ./cmd/isphere-mcp +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1 +``` + +Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. + +- [ ] **Step 5: Commit Loop C4 and rewrite next loop** + +Commit exact C4 paths only. Rewrite the next loop around the remaining gap: a safe configurable source loader or fixture path for `isphere_receive_messages`, without committing raw evidence. --- diff --git a/internal/mcpserver/server.go b/internal/mcpserver/server.go index 4ef98ff..1a9a6cc 100644 --- a/internal/mcpserver/server.go +++ b/internal/mcpserver/server.go @@ -4,6 +4,7 @@ import ( "github.com/modelcontextprotocol/go-sdk/mcp" "isphere-ai-bridge/internal/helperclient" + "isphere-ai-bridge/internal/isphere" "isphere-ai-bridge/internal/tools" ) @@ -20,5 +21,6 @@ func NewServer() *mcp.Server { Version: ServerVersion, }, nil) tools.RegisterWinHelperTools(server, helperclient.Client{}) + tools.RegisterISphereReadTools(server, isphere.EncryptedPacketLogSource{}) return server } diff --git a/internal/mcpserver/server_test.go b/internal/mcpserver/server_test.go index 9e5ffe2..0a0ce11 100644 --- a/internal/mcpserver/server_test.go +++ b/internal/mcpserver/server_test.go @@ -52,7 +52,7 @@ func TestNewServerRegistersN8WinHelperToolsWithoutCallingHelper(t *testing.T) { gotNames = append(gotNames, tool.Name) } sort.Strings(gotNames) - wantNames := []string{"win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"} + wantNames := []string{"isphere_receive_messages", "win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"} if !reflect.DeepEqual(gotNames, wantNames) { t.Fatalf("server tool names = %#v, want %#v", gotNames, wantNames) } diff --git a/internal/tools/isphere_read.go b/internal/tools/isphere_read.go new file mode 100644 index 0000000..0cb9531 --- /dev/null +++ b/internal/tools/isphere_read.go @@ -0,0 +1,55 @@ +package tools + +import ( + "context" + + "github.com/modelcontextprotocol/go-sdk/mcp" + + "isphere-ai-bridge/internal/isphere" +) + +const ToolNameReceiveMessages = "isphere_receive_messages" + +type ReceiveMessagesSource interface { + ReceiveMessages(ctx context.Context, query isphere.ReceiveMessagesQuery) (isphere.ReceiveMessagesResult, error) +} + +type ReceiveMessagesArgs struct { + Limit int `json:"limit,omitempty" jsonschema:"maximum number of messages to return; zero or negative returns all available messages"` +} + +func RegisterISphereReadTools(server *mcp.Server, source ReceiveMessagesSource) { + if source == nil { + source = isphere.EncryptedPacketLogSource{} + } + + mcp.AddTool[ReceiveMessagesArgs, map[string]any](server, &mcp.Tool{ + Name: ToolNameReceiveMessages, + Description: "Return iSphere messages from the configured read-only log-backed source.", + }, func(ctx context.Context, _ *mcp.CallToolRequest, input ReceiveMessagesArgs) (*mcp.CallToolResult, map[string]any, error) { + result, err := source.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: input.Limit}) + if err != nil { + return nil, nil, err + } + return nil, receiveMessagesResultToMap(result), nil + }) +} + +func receiveMessagesResultToMap(result isphere.ReceiveMessagesResult) map[string]any { + messages := make([]map[string]any, 0, len(result.Messages)) + for _, message := range result.Messages { + messages = append(messages, map[string]any{ + "id": message.ID, + "conversation_id": message.ConversationID, + "conversation_type": message.ConversationType, + "sender_id": message.SenderID, + "receiver_id": message.ReceiverID, + "text": message.Text, + "timestamp": message.Timestamp, + "subject": message.Subject, + "receipt_id": message.ReceiptID, + "read": message.Read, + }) + } + return map[string]any{"messages": messages} +} diff --git a/internal/tools/isphere_read_test.go b/internal/tools/isphere_read_test.go new file mode 100644 index 0000000..ce27eeb --- /dev/null +++ b/internal/tools/isphere_read_test.go @@ -0,0 +1,104 @@ +package tools + +import ( + "context" + "encoding/json" + "testing" + + "github.com/modelcontextprotocol/go-sdk/mcp" + + "isphere-ai-bridge/internal/isphere" +) + +func TestISphereReceiveMessagesToolReturnsSourceMessages(t *testing.T) { + fake := &fakeReceiveMessagesSource{ + result: isphere.ReceiveMessagesResult{Messages: []isphere.Message{{ + ID: "msg-1", + ConversationID: "sender@imopenfire1-lanzhou|receiver@imopenfire1-lanzhou", + ConversationType: "chat", + SenderID: "sender@imopenfire1-lanzhou", + ReceiverID: "receiver@imopenfire1-lanzhou", + Text: "redacted", + Timestamp: "1783423807000", + Subject: "FILE_TRANSFER_CANCEL", + ReceiptID: "receipt-1", + Read: true, + }}}, + } + session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) { + RegisterISphereReadTools(server, fake) + }) + defer cleanup() + + listResult, err := session.ListTools(context.Background(), &mcp.ListToolsParams{}) + if err != nil { + t.Fatalf("list tools: %v", err) + } + gotNames := make([]string, 0, len(listResult.Tools)) + for _, tool := range listResult.Tools { + gotNames = append(gotNames, tool.Name) + } + assertSameStrings(t, gotNames, []string{ToolNameReceiveMessages}) + + callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{ + Name: ToolNameReceiveMessages, + Arguments: map[string]any{"limit": 5}, + }) + if err != nil { + t.Fatalf("call %s: %v", ToolNameReceiveMessages, err) + } + if callResult.IsError { + t.Fatalf("call result is error: %+v", callResult) + } + if len(fake.queries) != 1 || fake.queries[0].Limit != 5 { + t.Fatalf("queries = %+v, want one limit=5", fake.queries) + } + + var decoded struct { + Messages []struct { + ID string `json:"id"` + ConversationID string `json:"conversation_id"` + ConversationType string `json:"conversation_type"` + SenderID string `json:"sender_id"` + ReceiverID string `json:"receiver_id"` + Text string `json:"text"` + Timestamp string `json:"timestamp"` + Subject string `json:"subject"` + ReceiptID string `json:"receipt_id"` + Read bool `json:"read"` + } `json:"messages"` + } + 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 len(decoded.Messages) != 1 { + t.Fatalf("messages = %+v, want one", decoded.Messages) + } + msg := decoded.Messages[0] + if msg.ID != "msg-1" || msg.Text != "redacted" || msg.Subject != "FILE_TRANSFER_CANCEL" { + t.Fatalf("unexpected message content: %+v", msg) + } + if msg.ConversationID != "sender@imopenfire1-lanzhou|receiver@imopenfire1-lanzhou" { + t.Fatalf("conversation_id = %q", msg.ConversationID) + } + if msg.SenderID != "sender@imopenfire1-lanzhou" || msg.ReceiverID != "receiver@imopenfire1-lanzhou" { + t.Fatalf("sender/receiver = %q/%q", msg.SenderID, msg.ReceiverID) + } + if msg.Timestamp != "1783423807000" || msg.ReceiptID != "receipt-1" || !msg.Read { + t.Fatalf("metadata = %+v", msg) + } +} + +type fakeReceiveMessagesSource struct { + queries []isphere.ReceiveMessagesQuery + result isphere.ReceiveMessagesResult +} + +func (f *fakeReceiveMessagesSource) ReceiveMessages(_ context.Context, query isphere.ReceiveMessagesQuery) (isphere.ReceiveMessagesResult, error) { + f.queries = append(f.queries, query) + return f.result, nil +} diff --git a/internal/tools/winhelper_test.go b/internal/tools/winhelper_test.go index 54c5bf9..185d400 100644 --- a/internal/tools/winhelper_test.go +++ b/internal/tools/winhelper_test.go @@ -21,7 +21,7 @@ var expectedWinHelperToolNames = []string{ "win_helper_dump_uia", } -func TestWinHelperToolsRegisterExactlyFourReadOnlyTools(t *testing.T) { +func TestWinHelperToolsRegisterOnlyHelperTools(t *testing.T) { fake := &fakeHelperCaller{} session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) { RegisterWinHelperTools(server, fake) @@ -37,7 +37,7 @@ func TestWinHelperToolsRegisterExactlyFourReadOnlyTools(t *testing.T) { for _, tool := range result.Tools { gotNames = append(gotNames, tool.Name) lower := strings.ToLower(tool.Name) - forbidden := []string{"send", "search", "file", "login", "conversation", "upload", "download", "receive"} + forbidden := []string{"send", "search", "file", "login", "conversation", "upload", "download"} for _, word := range forbidden { if strings.Contains(lower, word) { t.Fatalf("tool %q contains forbidden action word %q", tool.Name, word)