`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
3.8 KiB
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
- Leave (1) as it is and make the frame-socket timeout reachable. (recommended
for (1)) The honest small fix: let
shot,recordandstatustake atimeoutargument and emit it as a global flag before the verb, whichhhstream_mcp.tools.argvcannot 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. - 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
execpaths this design avoids. Worth it only if a hang is observed in practice. - For (2): a
--sg-groupflag on the server that re-execs itself throughsgonce, 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 spellsg hhstream -c hhstream-mcp. - 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.