admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: register isphere file receive list tool

Browse Source
This commit is contained in:
zhaoyilun
2026-07-10 00:53:04 +08:00
parent fe242145bb
commit bd03cf5d83
9 changed files with 327 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/current-status-card.md
View File

@@ -14,7 +14,7 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
## Current completed state
- Go MCP foundation exists: `cmd/isphere-mcp`, `internal/mcpserver`, `internal/helperclient`, and `internal/tools` build a stdio MCP server.
- The current MCP surface exposes seven read-oriented tools:
- The current MCP surface exposes eight read-oriented tools:
- `win_helper_version`
- `win_helper_self_check`
- `win_helper_scan_windows`
@@ -22,14 +22,15 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
- `isphere_receive_messages`
- `isphere_search_contacts`
- `isphere_search_groups`
- `isphere_receive_files`
- C# `ISphereWinHelper` exists under `native/ISphereWinHelper` and uses the `isphere.helper.v1` stdin/stdout JSON contract.
- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, seven-tool MCP surface, default empty-source receive/contact/group calls, and synthetic configured-source receive/contact/group smoke.
- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, eight-tool MCP surface, default empty-source receive/contact/group/file calls, and synthetic configured-source receive/contact/group/file smoke.
- N12-pre and N12R documents define safe offline evidence intake and internal-sandbox live UIA capture procedures.
- N13/N14/N15 produced selector catalog/report validation infrastructure, but those are supporting validation assets only.
## What cannot be claimed externally
- The project has not yet implemented business MCP tools for message sending, file receiving/download, or file sending; `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups` have operator-local encrypted log-file support but not a production ingestion path.
- The project has not yet implemented business MCP tools for message sending, file download, or file sending; `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode have operator-local encrypted log-file support but not a production ingestion path.
- The project has not completed production iSphere integration.
- The project has not proven a stable real message source for the full business workflow beyond decrypted PacketReader log evidence and synthetic/redacted tests.
- The project has not implemented real message sending or real file upload.
@@ -41,8 +42,8 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
- The repository has a Go MCP + C# WinHelper foundation for controlled Windows-side read-only observation.
- The helper protocol boundary is explicit and keeps Windows/UIA work separate from the Go MCP service layer.
- The current code can support future MCP business tools by routing low-level Windows/UIA fallback work through a bounded helper layer.
- The project has repeatable verification scripts for the helper/MCP foundation and the current seven-tool surface.
- The project now has a corrected business contract and plan for core MCP communication tools, plus registered receive/contact/group read tools that can use `ISPHERE_PACKET_LOG_FILE` for operator-local encrypted PacketReader log lines.
- The project has repeatable verification scripts for the helper/MCP foundation and the current eight-tool surface.
- The project now has a corrected business contract and plan for core MCP communication tools, plus registered receive/contact/group/file-list read tools that can use `ISPHERE_PACKET_LOG_FILE` for operator-local encrypted PacketReader log lines.
## N13/N14/N15 positioning
@@ -50,7 +51,7 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme
## Current loop
Current loop: `Stage C / Loop C14 - register isphere_receive_files list mode`.
Current loop: `Stage C / Loop C15 - send message source evidence precheck`.
Plan file: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`.
@@ -75,11 +76,12 @@ Current loop output so far:
10. C10: log-backed group candidate extraction from groupchat/conference JIDs.
11. C11: `isphere_search_groups` MCP registration and seven-tool verification.
12. C12: file evidence precheck confirmed enough PacketReader/Smark evidence for file metadata listing, but not enough for real cache/download mapping.
13. C13: `internal/isphere.ListFilesFromMessages` extracts synthetic/redacted file metadata candidates from normalized messages; MCP registration is next.
13. C13: `internal/isphere.ListFilesFromMessages` extracts synthetic/redacted file metadata candidates from normalized messages.
14. C14: `isphere_receive_files` MCP list mode registered and verify-go-mcp now covers eight tools plus default/configured file-list smoke.
## Next business mainline
1. Run Stage C Loop C14: register `isphere_receive_files` list mode on top of `ListFilesFromMessages`.
2. Leave actual download/cache mapping as a later connector node until a message-to-cache hash or client download source is validated.
3. Add `isphere_send_message` and `isphere_send_file` after source discovery and connector selection.
1. Run Stage C Loop C15: verify available evidence for `isphere_send_message` connector selection before implementing any write-capable path.
2. Leave actual file download/cache mapping as a later connector node until a message-to-cache hash or client download source is validated.
3. Add `isphere_send_message` and `isphere_send_file` only after source discovery, preview semantics, execution metadata, and audit shape are defined.
4. Keep UIA selector/report work as fallback support, not as the primary roadmap.

21
docs/go-mcp-runbook.md
View File

@@ -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 plus the first log-backed business read tool, `isphere_receive_messages`, through Go MCP. The receive tool is registered with an empty default source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file.
Current scope: expose four WinHelper observation operations plus four log-backed business read tools through Go MCP: `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. These business read tools use an empty default source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file.
## 1. Prerequisites
@@ -90,14 +90,15 @@ The verification confirms:
- C# helper can be built.
- Go MCP binary can be built.
- MCP initialize/list/call flow works through the SDK harness.
- Exactly seven tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups`.
- Exactly eight tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`.
- `win_helper_version` returns `ISphereWinHelper`.
- `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
- A synthetic configured-source smoke check proves `ISPHERE_PACKET_LOG_FILE` can drive `isphere_receive_messages` end-to-end with one redacted fixture message.
- `isphere_search_contacts` is callable and returns JID-derived contact candidates from the same configured synthetic message fixture.
- `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture.
- `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
- Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
- Contact/group/file/search/send business tools remain later-stage work.
- File download/cache mapping and send business tools remain later-stage work.
## 6. Configure optional message source
@@ -154,7 +155,7 @@ E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
## 8. Allowed tools
These seven tools are currently allowed:
These eight tools are currently allowed:
| Tool | Source/op | Purpose |
| --- | --- | --- |
@@ -165,6 +166,7 @@ These seven tools are currently allowed:
| `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source. The default server source is empty until a loader is wired. |
| `isphere_search_contacts` | log-backed message JIDs | Search contact candidates extracted from sender/receiver bare JIDs in the configured message source. |
| `isphere_search_groups` | log-backed groupchat JIDs | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source. |
| `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. |
Allowed parameters:
@@ -175,10 +177,11 @@ Allowed parameters:
- `isphere_receive_messages`: `limit` only.
- `isphere_search_contacts`: `query`, `limit` only.
- `isphere_search_groups`: `query`, `limit` only.
- `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `limit` only. C14 supports `mode` empty or `list`; download is deferred.
## 9. Current tool surface and next-stage route
The current runbook verifies seven tools:
The current runbook verifies eight tools:
- `win_helper_version`
- `win_helper_self_check`
@@ -186,10 +189,12 @@ The current runbook verifies seven tools:
- `win_helper_dump_uia`
- `isphere_receive_messages`
- `isphere_search_contacts`
- `isphere_search_groups`
- `isphere_receive_files`
`isphere_receive_messages` currently has 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`; this is still not a production ingestion claim because raw evidence remains local and uncommitted.
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`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_files` currently supports list mode only; download/cache mapping is deferred.
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send/file capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
## 10. Real-login UIA capture procedure
@@ -248,7 +253,7 @@ win_helper_scan_windows
win_helper_dump_uia
```
The MCP server also registers `isphere_receive_messages`, but its default source is empty and it should not be used as N12R UIA evidence collection.
The MCP server also registers the log-backed read tools (`isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`), but their default source is empty and they should not be used as N12R UIA evidence collection.
After receiving an N12R package, validate it with `docs/n12r-return-package-validation-checklist.md` before using it as evidence for selector-design review. Prefer the scripted read-only validator:

2
docs/source-discovery/capability-source-matrix.md
View File

@@ -20,7 +20,7 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` 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` | C5 env loader wired through ISPHERE_PACKET_LOG_FILE; default source remains empty when unset | fixture-backed configured-source operator smoke |
| `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages | decrypted roster/contact 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` | C8 MCP tool registered and verify-go-mcp covers default/configured contact smoke; JID-only display/account fallback | enrich display names from roster/db/uia evidence |
| `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs | `MsgLib.db` group/conversation tables after DB wrapper is solved; UIA helper source if group display names are missing | C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C11 MCP tool registered and verify-go-mcp covers default/configured group smoke; JID-only display fallback | enrich group display/member data from roster/db/uia evidence |
| `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas for metadata listing via `internal/isphere.ListFilesFromMessages`; `zyl\importal\<hash>` cache entries remain unlinked | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck` | C13 source behavior implemented for metadata listing; no log-to-cache/download mapping yet | register `isphere_receive_files` MCP list mode |
| `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas via `internal/isphere.ListFilesFromMessages` and `isphere_receive_files` list mode; `zyl\importal\<hash>` cache entries remain unlinked | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck` | C14 MCP list mode registered and verify-go-mcp covers default/configured file-list smoke; no log-to-cache/download mapping yet | defer download mapping; run send-message source evidence precheck |
## Stage C entry rule

58
docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md
View File

@@ -1341,7 +1341,7 @@ Implemented and verified in this loop:
- Output shape: `ok`, `mode`, `files`, `next_cursor`, and `audit`, aligned with `docs/mcp-core-tools-contract.md`.
- Default empty source returns `ok: true`, `mode: "list"`, `files: []`.
- [ ] **Step 1: Write failing MCP tool test**
- [x] **Step 1: Write failing MCP tool test**
Create `internal/tools/isphere_files_test.go` and run:
@@ -1351,15 +1351,15 @@ go test ./internal/tools -run TestISphereReceiveFilesToolReturnsLogBackedFiles -
Expected initial failure: file receive tool registration does not exist.
- [ ] **Step 2: Implement file tool registration**
- [x] **Step 2: Implement file tool registration**
Register `isphere_receive_files` with source injection for tests. Use `ListFilesFromMessages` and return a contract-shaped map with minimal audit metadata.
- [ ] **Step 3: Wire server and verification**
- [x] **Step 3: Wire server and verification**
Register file receive in server construction. Update server tool-count tests and `scripts/verify-go-mcp.ps1` to expect eight tools and call `isphere_receive_files` against default empty source and synthetic configured file-transfer fixture.
- [ ] **Step 4: Run full verification and commit**
- [x] **Step 4: Run full verification and commit**
Run:
@@ -1374,6 +1374,56 @@ Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. C
---
## Loop C14 Result
Implemented and verified in this loop:
- `internal/tools.RegisterISphereFileTools(server, source)` registers `isphere_receive_files` over the same receive-message source used by receive/contact/group tools.
- `internal/mcpserver.NewServerWithReceiveSource` now exposes eight tools: four WinHelper tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`.
- `scripts/verify-go-mcp.ps1` now expects eight tools, allows the file-list read tool, and verifies default empty file results plus configured synthetic file-transfer extraction.
- `isphere_receive_files` currently supports list mode only; download/cache mapping remains deferred because C12 found no message-to-cache hash link.
- Verification completed for C14 with affected package tests and `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1`; full verification is run again before commit.
---
## Loop C15: Send message source evidence precheck
**Goal:** Before implementing `isphere_send_message`, identify the lowest-risk connector path and preview/audit shape from existing bridge/API, local data, UIA, or network evidence; do not implement write-capable behavior without a validated connector decision.
**Planned files:**
- Modify: `docs/source-discovery/capability-source-matrix.md`
- Modify: `docs/current-status-card.md`
- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`
- Optionally create a focused source-discovery note under `docs/source-discovery/` if evidence is non-trivial.
**Planned behavior:**
- Inspect existing docs/contracts and committed helper/UIA/source-discovery artifacts for a send-message source candidate.
- Rank candidate connector paths: existing bridge/API/local service, UIA draft/send path, network/protocol path, or blocked pending internal sandbox evidence.
- If a safe connector exists, write C16 around preview-first `isphere_send_message` design or implementation.
- If evidence is insufficient, mark send-message blocked on live/internal-sandbox connector evidence and choose the next read hardening node.
- [ ] **Step 1: Inspect current source evidence for send-message connector candidates**
Use committed docs and generated selector/source-discovery reports only. Do not infer a write path from unrelated read evidence.
- [ ] **Step 2: Update matrix and next loop**
Record whether send-message implementation can proceed, and rewrite C16 accordingly.
- [ ] **Step 3: Verify docs-only change and commit**
Run:
```powershell
git diff --check
go test ./...
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1
```
Expected: all exit 0. Commit exact C15 paths only.
---
## Self-Review
- Spec coverage: the plan follows the user's cyclic requirement: plan first, implement one loop at a time, update the next loop after each result, and ask only on blockers.