Files
hyprland-headless-stream-pl…/docs/TODO/mcp-in-process-has-no-call-deadline.md
T
HermenixandClaude Opus 5 e636472106 docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it
`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because
v1 lasted a day and an agent that learned it deserves to be told what moved
rather than to discover it. The new §4 freezes the resource surface: the eight
URIs, their bodies, their query parameters, and the five rules the layer keeps
(a read never writes; only declared parameters; a literal route beats a
template; a frame's media type comes from its bytes; no subscriptions). §6
gains the other half of the error mapping -- for a resource read every exit
code arrives as `-32602` with the remedy in `message` and the structured object
in `data`, because `ReadResourceResult` has no `isError` to use instead.

§2 records what `--toolsets` is and is not: there is no grouping primitive in
MCP, the `Tool` object has nowhere to put a family, and tools are a flat list
in the specification too -- so the only lever is which tools the server lists,
decided by whoever spawns it.

README.md leads with the split rather than with a tool count, since that is the
thing a reader has to understand before any of the names make sense, and shows
the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth
box grows its second half and says why `shot` is on both sides.

A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit
that cost the most: `Server.get_capabilities` hardcodes
`ResourcesCapability(subscribe=False, …)`, so registering a
`subscribe_resource` handler changes nothing and a client is correctly told not
to try. Subscriptions would have been the principled answer to the missing
`logs --follow` -- it is the one place this design wanted a capability the SDK
will not advertise -- so the file names the one-line local override, says what
it risks, and recommends upstreaming the real fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:50:12 +00:00

3.9 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.