docs(mcp): freeze the tool surface, and record what the in-process seam costs

`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:33:07 +00:00
1 parent fea55eecde
commit 6a40c7e2e4
6 files changed
+473 -11

No files matched your search

+1
View File
@@ -15,6 +15,7 @@ Each file answers three questions and stops:
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
Closed since this folder was written:
@@ -0,0 +1,67 @@
# The MCP server cannot abandon a call, and cannot re-join the compositor's group
## The issue
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool builds the
argv list `hhstream.cli`'s parser takes, and `hhstream_mcp.invoke.dispatch` runs
the handler argparse selected. That is the seam the design asks for — one place
decides the argv, nothing re-implements a rule — and it costs two things a
subprocess would have given for free. Both are consequences of the same fact, so
they are one item.
**1. There is no per-call deadline.** A subprocess can be killed; a Python
thread cannot be interrupted. So the only deadlines are the ones that already
exist inside the CLI: `hhstream_session.client`'s 60 s socket timeout, the
broker's own per-verb deadline, and the frame socket's `--timeout` (10 s by
default, and not currently reachable as a tool argument — it is a *global* CLI
flag, before the verb, and the argv builders emit the verb first).
Measured consequence: nothing in the current surface is known to hang — every
path either talks to the broker under its 60 s timeout or to the frame socket
under its own — but `record` with a large `seconds`, or a `grim` wedged on a
compositor that has stopped answering, would hold the worker thread until it
returns. The event loop stays responsive (a `ping` is answered), and the calls
are serialised by design, so the visible symptom is every *subsequent* tool call
queueing behind one that will not finish.
**2. The `sg` re-exec is unavailable.** `cli.main` recovers from a frame socket
it cannot read by `os.execv`-ing itself through the setuid `sg` wrapper to join
the compositor's group. Performing that here would replace the MCP server
mid-session and drop the client's connection, so `dispatch` deliberately does
not call `cli.main` and the recovery does not happen. `shot` and `record`
instead fail with the CLI's own message plus a sentence naming what the CLI
would have done (`hhstream_mcp.invoke.access_hint`), and the operator is told to
run the server as a member of the group instead.
## Ideas
1. **Leave (1) as it is and make the frame-socket timeout reachable.** *(recommended
for (1))* The honest small fix: let `shot`, `record` and `status` take a
`timeout` argument and emit it as a global flag *before* the verb, which
`hhstream_mcp.tools.argv` cannot express today. That hands the one knob the
CLI already has to the agent, and does not pretend this layer can enforce a
deadline it cannot.
2. **Run each call in a forked child after all.** Restores a killable deadline,
at the cost of a process per tool call and of re-introducing the two `exec`
paths this design avoids. Worth it only if a hang is observed in practice.
3. **For (2): a `--sg-group` flag on the server** that re-execs itself through
`sg` *once, before claiming the transport*, so the group is joined while
there is still no client to drop. *(recommended for (2))* It keeps the
recovery the CLI has, in the one moment it is safe, and is strictly better
than asking every client's configuration to spell `sg hhstream -c
hhstream-mcp`.
4. **For (2): accept it and document only.** What ships today. Correct, and the
message says what to do — but it makes a working CLI and a failing tool out
of the same machine, which is exactly the kind of difference an agent cannot
diagnose.
## Why it matters
(2) is the one an operator meets first: the CLI works from their shell, the
`shot` tool does not, and the two differ only in a recovery that is invisible
from either side. The message carries the answer, which is why this is medium
and not high.
(1) is latent. It becomes real the first time a compositor stops answering while
an agent is driving it: the agent's next tool call waits behind the stuck one
with no way to give up, where a CLI user would have pressed ctrl-C.