47950671fa
- docs/v1-vs-v2/: full v1→v2 regression analysis (SUMMARY + 21 per-module docs + ACTION-ITEMS rollup with decisions + timezone recreation spec). - container/agent-runner/scripts/sdk-signal-probe.ts: empirical harness used to characterise Claude Agent SDK event/hook/stderr timing for the stuck-detection design in item 9. - src/channels/chat-sdk-bridge.ts: document the conversations Map staleness in a code comment; fix deferred to when dynamic group registration lands (ACTION-ITEMS item 17). No runtime behavior change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
60 lines
3.8 KiB
Markdown
60 lines
3.8 KiB
Markdown
# container mcp-tools: v1 vs v2
|
|
|
|
## Scope
|
|
- v1: `container/agent-runner/src/v1/mcp-tools.ts` (81 LOC) — single tool (`send_message`)
|
|
- v2: `container/agent-runner/src/mcp-tools/` — 7 modules (~971 LOC): `index.ts`, `core.ts`, `scheduling.ts`, `interactive.ts`, `agents.ts`, `self-mod.ts`, `types.ts`
|
|
|
|
## Tool map
|
|
|
|
| v1 tool | v2 file | Status | Schema / behavior diff |
|
|
|---|---|---|---|
|
|
| `send_message(text, channel, platformId, threadId)` | `core.ts:50-95` | **kept, enhanced** | v2 uses named destinations (`to`), auto-resolves via session default or lookup, preserves `thread_id` intelligently |
|
|
| — | `core.ts:133-177` `send_file` | **new** | Copies file to outbox dir, routes via destinations |
|
|
| — | `core.ts:179-218` `edit_message` | **new** | Edit previously-sent message by seq id |
|
|
| — | `core.ts:220-259` `add_reaction` | **new** | Emoji reaction by seq id |
|
|
| — | `scheduling.ts:33-79` `schedule_task` | **new** | One-shot or recurring (cron) |
|
|
| — | `scheduling.ts:81-137` `list_tasks` | **new** | Pending/paused tasks grouped by series |
|
|
| — | `scheduling.ts:139-165` `cancel_task` | **new** | |
|
|
| — | `scheduling.ts:167-192` `pause_task` | **new** | |
|
|
| — | `scheduling.ts:194-219` `resume_task` | **new** | |
|
|
| — | `scheduling.ts:221-266` `update_task` | **new** | Modify prompt/recurrence/processAfter/script |
|
|
| — | `interactive.ts:36-129` `ask_user_question` | **new** | Blocking with timeout — writes to outbound.db then polls inbound.db for response |
|
|
| — | `interactive.ts:131-166` `send_card` | **new** | Structured Chat SDK cards |
|
|
| — | `self-mod.ts:34-74` `install_packages` | **new** | apt/npm install, regex name validation, admin approval |
|
|
| — | `self-mod.ts:76-113` `add_mcp_server` | **new** | Wire existing MCP server |
|
|
| — | `self-mod.ts:115-141` `request_rebuild` | **new** | Async container rebuild |
|
|
| — | `agents.ts:30-63` `create_agent` | **new** | Admin-only sub-agent creation; not exposed to non-admin containers |
|
|
|
|
## New tools in v2
|
|
16 new tools split across 5 capability domains:
|
|
- **Message manipulation**: `send_file`, `edit_message`, `add_reaction`
|
|
- **Scheduling**: 6 task-management tools
|
|
- **Interactive**: `ask_user_question`, `send_card`
|
|
- **Self-modification**: `install_packages`, `add_mcp_server`, `request_rebuild`
|
|
- **Agent management**: `create_agent`
|
|
|
|
## Missing from v2
|
|
**None.** v2 strictly adds; v1's only tool (`send_message`) was kept and enhanced.
|
|
|
|
## Behavioral discrepancies
|
|
1. **Destination resolution**: v1 used explicit channel/platformId/threadId params; v2 resolves named destinations from `destinations` map with fallback to session routing
|
|
2. **Two-DB split pattern**: all scheduling/self-mod tools write system actions to **outbound.db**; host processes (applies to inbound.db). Container never writes directly to inbound
|
|
3. **`ask_user_question` is blocking**: synchronously polls inbound.db until response arrives or timeout — agent perception is blocking, transport is async
|
|
4. **Admin enforcement**: `create_agent` + self-mod tools check admin approval host-side (`NANOCLAW_ADMIN_USER_IDS` env controls tool visibility)
|
|
5. **Message editing/reactions**: use internal seq id (not user-visible numeric message ID) — requires outbound.db lookup
|
|
|
|
## Transport pattern (v2 common)
|
|
1. Agent invokes tool → validation (regex, enum, length)
|
|
2. Tool writes `messages_out` or system-action row
|
|
3. Tool returns success immediately (fire-and-forget)
|
|
4. Host polls outbound.db, applies approval / routing / side effects
|
|
|
|
## Worth preserving?
|
|
**Yes, fully.** The v2 modular architecture is a large improvement:
|
|
- Clear separation by capability domain
|
|
- Two-DB constraint cleanly encoded (container → outbound, host → inbound)
|
|
- Named destination abstraction (better UX than raw JIDs)
|
|
- Admin-only tool filtering at the MCP server level
|
|
|
|
v1 is retained as historical reference only. No merge-back.
|