Files
hyprland-headless-stream-pl…/docs/TODO/mcp-in-process-has-no-call-deadline.md
T
HermenixandClaude Opus 5 d788d5723e docs(mcp): what a shared transport does to the call-deadline limit
One property and one consequence, in the two places that own them.

`docs/CONTRACT-mcp.md` §1 gains the operational fact an operator meets
first: tool calls are serialised across every caller, not per session, so
two agents on two tokens queue behind each other.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` gains why that matters
for the limit it already describes. The serialisation is not new -- it is
the same process-wide lock -- but over stdio a call only ever queued
behind the same client's previous call. One process for everyone means a
stuck call delays other people's agents, and whoever notices is not
necessarily whoever caused it. That makes the reachable-timeout idea
worth more than it was and the forked-child idea less unreasonable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-11 22:44:53 +00:00

4.5 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 or a resource read 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 and record take a timeout argument, and hhstream://status and the frame resources a ?timeout=, emitted 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 caller, 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.

The HTTP transport widens (1) without changing it. The serialisation was always there — Runner holds a process-wide lock because the CLI prints to a shared stdout — but over stdio each client had a process of its own, so a call only ever queued behind that same client's previous call. mcp.http.enable puts every caller in one process, so a stuck call now delays other people's agents too, and the one of them who can see something is wrong is not necessarily the one who caused it. That makes idea 1 (a reachable frame-socket timeout) worth more than it was, and idea 2 (a forked child per call) less unreasonable than it was.