Files
hyprland-headless-stream-pl…/docs/TODO/mcp-in-process-has-no-call-deadline.md
T
HermenixandClaude Opus 5 6a40c7e2e4 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
2026-10-11 06:33:07 +00:00

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

  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.