Files

gavrielc 47950671fa docs: add v1→v2 action-items analysis + SDK signal probe tool

- 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>

2026-04-20 01:00:04 +03:00

3.8 KiB

Raw Blame History

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

Destination resolution: v1 used explicit channel/platformId/threadId params; v2 resolves named destinations from destinations map with fallback to session routing
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
ask_user_question is blocking: synchronously polls inbound.db until response arrives or timeout — agent perception is blocking, transport is async
Admin enforcement: create_agent + self-mod tools check admin approval host-side (NANOCLAW_ADMIN_USER_IDS env controls tool visibility)
Message editing/reactions: use internal seq id (not user-visible numeric message ID) — requires outbound.db lookup

Transport pattern (v2 common)

Agent invokes tool → validation (regex, enum, length)
Tool writes messages_out or system-action row
Tool returns success immediately (fire-and-forget)
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.

3.8 KiB Raw Blame History