feat: let external agents drive codeoid sessions over MCP (/mcp/control)

[saucam]

Closes #251

What

Other agents can now drive codeoid over MCP. Claude Code, Cursor, or a CI job mounts one URL, /mcp/control, and can:

• list sessions, read their transcripts and token/cost usage, and wait for one to finish;
• when the operator allows it, create sessions, prompt them (and get the reply back), interrupt them, and destroy them.

It is off by default. Turning it on makes it observe-only; acting is a second, separate switch.

codeoid mcp config --scopes operate   # prints a ready .mcp.json entry

The entry uses Claude Code's headersHelper, so the client mints a fresh, scope-narrowed token on every connect and after any 401. A short-lived ZeroID token keeps working in a long-lived mount without anyone pasting a token. The default scope preset is observe-only.

How it stays safe

This endpoint can start agents and prompt them, so it gets no shortcuts.

• No second authorization path. The token is checked by the same verifier as the WebSocket login. Each tool becomes an ordinary protocol message, handled by the same function that enforces scopes, tenancy, and audit for every other client. A token that can't create a session over WebSocket can't create one here.
• Driving is not authorizing. There is no approve tool. A session prompted from outside still parks every guarded tool call on its owner's approval. In the live run below, the agent asked to run a shell command and nothing happened until a person approved it.
• Hands off what codeoid steers. The conductor and its workers, collaborative sessions, and a session a live pipeline run is driving can be read from outside, but not prompted, interrupted, or destroyed.
• Every call is attributed in the audit log to the caller, with the principal that delegated to it. A prompt an agent sends shows up in the transcript as that agent's message.
• requireDelegated accepts only delegated agent tokens, so each outside caller is its own revocable principal.

One change reaches beyond the endpoint. Forged tokens can no longer make the daemon refetch ZeroID's signing keys in a loop, over this endpoint or the WebSocket login. Before this, a stream of tokens naming made-up key ids cost one fetch each.

Small protocol additions, all optional:

• scrollback.page without an anchor returns the newest page;
• SessionInfo.turnQueued covers the moment between "prompt accepted" and "turn started", when a session still reads idle;
• SessionInfo.managedBy marks a session a pipeline run is driving.

Verification

Live run against a separate local-mode daemon (its own port, database, and config), driven by the official MCP SDK client, with real Claude:

• a forged token was refused at connect;
• create_session, then send_message with wait, returned the real reply (PONG-251) in 7 s;
• a retried send with the same idempotency key was delivered once;
• a prompt asking the agent to run touch created-by-agent.txt came back waiting_approval, get_session named the parked Bash call, and the file was never created;
• interrupt, wait, usage, and destroy all worked;
• the audit log held an mcp.control.call row for every call, alongside the ordinary session.create / session.send / session.interrupt / session.destroy rows, with one session.send for the de-duplicated retry.

Tests: the full suite passes (3,099 pass, 0 fail; the skip count depends on which backends are installed on the machine), and so do the web typecheck and its 593 tests. New coverage is in mcp-control.test.ts (a real SessionManager with a scripted backend, a fake host for edge cases, and two real daemons for the HTTP mount), mcp-control-cli.test.ts, auth-kid-cooldown.test.ts, and additions to the config, scrollback, session, pipeline-store and pipeline-handler tests. Each security guard was checked by reverting it: removing the guard fails at least one test.

Audit: four rounds. Each round paired a general correctness audit with a security review by a reviewer that had not seen earlier rounds. Every finding was fixed in this branch, one commit per round.

Round	Correctness	Security	Fixed in
1	ship-with-fixes	1 High: a send-only token bypassed the conductor/worker refusal; 4 Mediums	4077a17
2	ship-with-fixes	1 High: my failed-login throttle let any local process lock out every valid caller	93810ab
3	ship-with-fixes	1 High: a header-parser mismatch bypassed the forged-key gate; keep-alive sockets kept a lifted timeout	af10260
4	ship-with-fixes, no High	no Critical/High; 1 Medium (a retired key stayed trusted), 1 Low	87744d4
Final	ship	4 Lows, including a valid rotated key that could be refused for up to 10 s	see below

Did not run:

• The Highflame compose stack and the kind regression suite don't apply: codeoid is not part of either, so the live daemon run above takes their place.
• Oracle doesn't review this repo: highflame-ai/codeoid is not in enabled_repos.
• Round 4 was the last full round. The final audit then reviewed the whole diff, including the round-4 fixes (87744d4), and returned ship. Its four Lows are fixed in the latest commit, each with a test that fails when the fix is reverted; nobody re-reviewed that last commit.

Not in this PR

• Per-agent delegated handshake. An outside agent should trade its own credential for a codeoid-scoped delegated token, so each caller sits in the ZeroID tree under its own identity. Today codeoid mcp headers mints a token from the configured key, and requireDelegated only accepts tokens that were already delegated.
• Transcript scan throttle. read_transcript with a before cursor that isn't in memory scans the on-disk transcript (bounded at 64 MB and 5 s), the same as the WebSocket path. Throttling that is a follow-up.
• Rust protocol parity. codeoid-ui's protocol crate should gain the optional beforeMessageId, turnQueued, and managedBy fields. Nothing breaks without them.

For agents: implementation map

• src/daemon/mcp/control-http.ts: ControlMcpHttp. The tool table is buildTools, and #callTool builds a CallContext whose call() runs parseClientMessage and then ControlHost.handle (SessionManager.handle), raced against a per-call deadline; the whole tool also races a tool deadline. actionTarget fails closed without session:list and refuses role, collaboration, collaborationRole and managedBy. Waits are capped at 16 per subject; send_message claims its slot before sending. After a delivered prompt, failures return sent: true (wait_failed), and a send that hits its deadline returns send_unconfirmed. The whole-tool deadline signals a wind-down 5 s before its hard cut, so a wait ends as still_working first. replyTo anchors on the caller's prompt text. Body reads go through a streaming cap (readCapped). The idle timeout is lifted only for authenticated tools/call after the body is in, and restored in finally, because Bun scopes it to the socket and caps it near 255 s.
• src/daemon/mcp/control-path.ts: the path constant, kept separate so the CLI doesn't import the endpoint.
• src/daemon/server.ts: the mount (404 when off); idleTimeout is explicit via IDLE_TIMEOUT_SECONDS.
• src/daemon/auth.ts: ZeroIdVerifier. decodeLikeSdk / jwtKeyRef mirror the SDK's header decode. Invalid headers are refused. An unseen string kid is checked against a key-id inventory read at most every 10 s (1 s after a failure). A trusted kid is forgotten when the SDK reports it unpublished, and pruned when a fresh list drops it.
• src/daemon/session-manager.ts: #list adds managedBy from PipelineManager.activeSessionIds, which is PipelineStore.activeSessionIds (SQL, json_valid-guarded).
• src/daemon/session.ts: the newest-page branch of pageScrollback; toInfo().turnQueued from preparingTurn.
• src/config.ts: McpControlSchema, env overrides, isLoopbackUrl. resolveLocalToken reads the token file only for loopback URLs.
• src/terminal/token.ts and mcp-control-cli.ts: acquireToken, now shared with TerminalClient, scope presets, controlUrl, and the mcp headers / mcp config logic. The helper command is rebuilt only from validated scopes.
• Docs: docs/mcp-control.md (user guide and security model), CHANGELOG.md, docs/CONFIGURATION.md, docs/FEATURES.md, CLAUDE.md.

🤖 Generated with Claude Code