feat(mcp): S2 — hand-rolled stdio client (JSON-RPC) + lifecycle

[ndemianc]

Second MCP slice (docs/MCP.md). Stacked on #29 — the diff here is S2 only. Still wired to nothing; S3 is the router line in agent.js.

Pure / IO split

Following the codebase's own pattern (sse.js thin IO, translate.js pure), the parts most likely to be wrong are testable without spawning anything:

mcpProtocol.js (pure) — framing + result flattening. Both are easy to get wrong:

• A pipe doesn't respect message boundaries, so a framer that assumes one chunk = one message works right until a big tools/list arrives. And a stray non-JSON log line on stdout — a well-known MCP footgun — must be skipped, not desync the stream.
• A tool result is typed content blocks, but tool_result is a string. Non-text degrades to a placeholder (never raw base64 into the transcript), failures take the agent's ERROR: prefix, and the result is capped — the generic tool path bounds nothing.

mcpClient.js (IO) — spawn, handshake, request/response, teardown.

Four things it owes the agent

	Why
Per-call timeout	Tools run sequentially in agent.js — one wedged server would hang the entire run
Capped, flattened string	tool_result is text
call() never throws	A failure returns ERROR: …, so one bad server can't break the turn loop
reapMcp()	A detached child outlives the window otherwise — the same reason reapCommands() exists

Security choices

• shell:false — args are passed as argv, never re-parsed by a shell.
• Server→client requests are REFUSED, not ignored — a server cannot drive our model (sampling/*) or prompt the user (elicitation/*). It gets a clean JSON-RPC error instead of hanging.
• This module deliberately does not decide whether a server may start — that gate is S4.

Tested against a real subprocess, not mocks

test/fixtures/mock-mcp-server.js speaks just enough protocol to drive the client, with tools that succeed, fail, and never answer, plus --noise / --crash / --sample modes. So the handshake, framing over a live pipe, the timeout, the sampling refusal, and process teardown are genuinely exercised.

Verification

• 15 protocol + 13 client tests pass; full CI gate: 18 extension suites, 0 failures
• Requires are child_process + the pure module only — no vscode
• ps is clean after the run: dispose() and reapMcp() really do kill the process group, asserted in-test by polling the pid past the SIGTERM→SIGKILL grace

Next

S3 wires it in — TOOLS/TOOLS_TOKENS_EST become per-run, and the router goes immediately before the unknown tool fallthrough at agent.js:442. Then S4 (trust-on-first-use + the approval card), which must not be skipped.

🤖 Generated with Claude Code