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

68 lines
3.9 KiB
Markdown

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