diff --git a/README.dev.md b/README.dev.md index d56722a..d0978bd 100644 --- a/README.dev.md +++ b/README.dev.md @@ -7,8 +7,8 @@ decides, and if the document is wrong it gets a version bump, not an edit. ## Prerequisites - Nix with flakes enabled. -- `/dev/kvm` readable, for the six VM checks. They are `nixosTest`s; without - KVM they still run, just slowly enough that the timeouts below get tight. +- `/dev/kvm` readable, for the VM checks. They are `nixosTest`s; without KVM + they still run, just slowly enough that the timeouts below get tight. - No GPU. Nothing in the test suite needs one — the compositor runs on Hyprland's headless backend over software rendering. @@ -21,21 +21,38 @@ socket outside the build sandbox or the test VM. nix develop ``` -Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH -and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree -rather than an installed copy. +Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH, +plus both packages (`hhstream` and `hhstream-mcp`) and the `mcp` SDK, and sets +`PYTHONPATH=$PWD/src`, so `import hhstream` and `import hhstream_mcp` both pick +up the working tree rather than an installed copy. ## Build ```bash nix build .#hhstream # the package ls result/bin # hhstream-server, hhstream-client, hhstream, - # hhstreamd, hhstream-pointer + # hhstreamd, hhstream-pointer, hhstream-live + +nix build .#hhstream-mcp # the MCP server, a SEPARATE derivation +ls result/bin # hhstream-mcp ``` -Five entry points: the frame server and a reference reader for it, the `hhstream` -front-door CLI (frames, `run`, and the `session` namespace), the session broker, -and the pointer driver. +The first package's entry points: the frame server and a reference reader for +it, the `hhstream` front-door CLI (frames, `run`, and the `session` namespace), +the session broker, the pointer driver and the session-stream web app. + +`hhstream-mcp` is its own derivation on purpose. It is the CLI as Model Context +Protocol tools (`docs/CONTRACT-mcp.md`), it depends on the third-party `mcp` +SDK, and `packages.hhstream` is stdlib-only by policy — see the header of +`nix/mcp.nix`. It depends on the `hhstream` package as a *library*: the tools +call `hhstream.cli`'s handlers in process rather than spawning the CLI. The dev +shell has both, plus `python3.pkgs.mcp` so `tests/unit/test_mcp_server.py` can +import the SDK: + +```bash +nix develop +hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio +``` ## The checks @@ -51,6 +68,7 @@ and the pointer driver. | `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes | | `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes | | `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes | +| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 26 tools are listed with their annotations and their two rules, a call reaches the live broker and returns its own protocol object, `shot` arrives as image content at the configured geometry, the pointer lease is granted/used/returned, and exits 9 and 3 arrive as tool *errors* carrying the frozen code | yes | All of them at once: @@ -75,6 +93,7 @@ nix build -L .#checks.x86_64-linux.vm-pointer nix build -L .#checks.x86_64-linux.vm-keyboard nix build -L .#checks.x86_64-linux.vm-keyboard-de nix build -L .#checks.x86_64-linux.vm-stream-firewall +nix build -L .#checks.x86_64-linux.vm-mcp ``` `-L` is not optional in practice: without it, Nix hides the build log, and the @@ -97,7 +116,11 @@ warning. pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on -purpose, so this is the only place the suite runs in a build). +purpose, so this is the only place the suite runs in a build). `nix/mcp.nix`'s +output is on that path beside it, and `mcp` is in the test environment, because +`tests/unit/test_mcp_*.py` import `hhstream_mcp` and one of them imports the SDK +— not optionally: a file that skipped when the SDK was absent would be green in +exactly the build where a malformed tool schema mattered. The check fails if the suite is **empty**, not just if it is red. `pytest` exits 5 on "collected nothing", but it exits 0 when every test was skipped or @@ -230,6 +253,11 @@ checks/ (layout us) and `vm-keyboard-de` -- because the layout reaches the keymap only through the driver unit's argv vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall + vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw + JSON-RPC client against the live broker + lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately + NOT the MCP SDK's -- the SDK on both ends would agree + with itself about a framing neither side had to get right lib/test-tools.nix packages the tests/ helpers for the guest lib/session-tools.nix packages the two guest programs below lib/session-machine.nix the guest the three session checks share diff --git a/README.md b/README.md index e750c12..a350a28 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,67 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png The socket is a plain file descriptor: the server serves every client that connects, and keeps running when one disconnects. +## Driving it from an agent: the MCP server + +`hhstream-mcp` is the `hhstream` CLI as [Model Context +Protocol](https://modelcontextprotocol.io) tools, so an agent can look at this +desktop, put an application on it, and aim its one pointer and keyboard at that +application through typed tools instead of a shell. One tool per CLI verb, +twenty-six of them; the interface is frozen in `docs/CONTRACT-mcp.md`. + +It is a thin wrapper and nothing more: every tool builds the argv list the CLI's +own parser takes, runs the CLI's own handler, and maps what came back. The idle +clock, the pointer lease, the allowlist and the exit-code table all stay where +they were. + +Install it with the module — off by default, because it is the surface through +which a language model starts processes on this machine: + +```nix +services.hyprland-headless-stream = { + enable = true; + sessions.enable = true; # the session, pointer and keyboard tools need the broker + mcp.enable = true; # puts `hhstream-mcp` on the system PATH +}; +``` + +Then register it with a client. The transport is **stdio** — one process per +client, spawned by the client, no port and no daemon — so the whole +configuration is a command and an environment: + +```json +{ + "mcpServers": { + "hhstream": { + "command": "hhstream-mcp", + "env": { + "HHSTREAM_SOCKET": "/run/hhstream/control.sock", + "HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock" + } + } + } +} +``` + +Both variables are the CLI's own and both are shown at their defaults, so they +can be left out unless this machine moved a socket. The account the client runs +as needs what the CLI needs: membership of the compositor's group (`hhstream`) +to read the frame socket, and of the broker's to reach the control socket. The +server cannot recover that for itself the way the CLI does — see +`docs/CONTRACT-mcp.md` §5 — so if `shot` reports it cannot read the socket, the +answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an +account in the group. + +`hhstream-mcp --list-tools` prints the table and exits, which is the quickest +way to check an install. Nothing else about the server is configurable: it holds +no state, caches no lease, and the pointer lease is an explicit argument on +every gesture tool for exactly that reason. + | Document | What it is | |---|---| | `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against | +| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease | +| `docs/CONTRACT-mcp.md` | the MCP tools: their names, arguments and error mapping | | `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client | | `README.dev.md` | how to build, test and hack on it | | `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ad6cb06..75bb9d1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -32,9 +32,17 @@ │ AF_UNIX control.sock, mode 0660 ▼ hhstream session ... (the CLI an agent drives) + ▲ + │ in-process: argv in, exit code out + │ + ┌────────────┴──────────────┐ + │ hhstream-mcp │ spawned per client, stdio only + │ 26 tools, one per verb │◀─── an MCP client's JSON-RPC + └───────────────────────────┘ ``` -Five pieces, deliberately separate: +Five pieces, deliberately separate, and a sixth that is deliberately not a +piece at all: 1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual outputs. It knows nothing about frames on a socket. @@ -53,6 +61,23 @@ Five pieces, deliberately separate: a separate process because a Wayland client needs its own connection and a driver blocked on the compositor must not stall session lifecycle. +And the sixth, which is a *shim* and not a layer: + +6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a + Model Context Protocol surface on it, so an agent calls typed tools instead + of writing command lines. It is drawn above the CLI rather than beside the + broker because that is where it sits: each tool builds the argv list the + CLI's parser takes and runs the CLI's own handler **in the same process**, + and it is the one component here that owns no state at all — not even the + pointer lease, which is an explicit argument on every gesture tool. Add it + to the diagram's list of things that can go wrong and nothing new appears: + every failure it reports is the CLI's or the broker's, carrying their exit + code. + + It is also the only part with a third-party dependency (the `mcp` SDK), + which is why it is a separate derivation (`nix/mcp.nix`) and why + `packages.hhstream` — the compositor's own units — keeps the closure it had. + ## Why containers are outputs A session's container is a headless **output**, not just a workspace, and the diff --git a/docs/CONTRACT-mcp.md b/docs/CONTRACT-mcp.md new file mode 100644 index 0000000..7429e3d --- /dev/null +++ b/docs/CONTRACT-mcp.md @@ -0,0 +1,283 @@ +# CONTRACT — the MCP server (mcp-v1) + +This file is the interface of `hhstream-mcp`: the tool names, the arguments each +takes, what comes back, and which of the CLI's exit codes arrives as which kind +of MCP error. It is the sibling of `docs/CONTRACT.md` (the frame socket's wire +format) and `docs/CONTRACT-sessions.md` (the broker, the containers and the +input lease). + +**Immutable without a version bump.** An agent that has learned these names and +these argument shapes is a consumer like any other, and renaming a tool breaks +it exactly as renaming a wire verb would. + +Version: mcp-v1 (2026-10-11). + +## 0. What this is, and what it is not + +It is a **shim**. Each tool builds the argv list the `hhstream` CLI's own parser +takes, hands it to the CLI's own handler **in this process**, and maps what came +back. Nothing in it decides anything: + +| Rule | Whose it is | +| --- | --- | +| the idle clock, and that only `touch` resets it | the broker | +| the pointer lease: who holds it, its TTL, what it lifts | the broker | +| the allowlist, and which arguments an app may be given | the broker's policy | +| the exit-code table | `docs/CONTRACT-sessions.md` §4 | +| the refusal messages (`reason`, `hint`) | the CLI and the broker | +| coordinate normalisation, the scroll bound, the type cap | the broker and the driver | + +What this layer owns is the argv list, the mapping of a result to MCP content, +and one sentence of *remedy* per exit code — the "what to do next" that the CLI +says to a human in the words of a command line and an agent needs in the words +of tools. + +In process, not as a subprocess: `hhstream.cli` is importable Python whose +parser already takes an argv list and whose handlers already return a code from +the frozen table. Two of its paths cannot be called here, and both are +documented in `hhstream_mcp.invoke`: `cli.main`'s `sg` re-exec, and `cmd_run`'s +`execvpe`. Consequences of the first are in §5. + +## 1. Transport + +**stdio, and only stdio.** One process per client, spawned by the client; no +port, no daemon, no socket of its own. There is already a daemon in this system +and it owns all the state. + +The protocol is **not on file descriptor 1** once the server is running: the +tools run the CLI in process, the CLI prints, and `record` spawns an `ffmpeg` +whose output the CLI does not capture. The server takes a private duplicate of +stdin and stdout at start-up, then points fd 1 at its log and fd 0 at +`/dev/null`. A stray write is therefore a log line and never a corrupted +stream. + +## 2. Configuration + +There is no `--socket` flag. The sockets are the CLI's own environment, read by +the CLI: + +| Variable | What it names | Default | +| --- | --- | --- | +| `HHSTREAM_SOCKET` | the broker's control socket | `/run/hhstream/control.sock` | +| `HHSTREAM_FRAME_SOCKET` | the published frame socket | `/run/hypr-stream/stream.sock` | + +Set them in the MCP client's `env` block. One place to configure them is one +place for them to be wrong. + +The server's own command line is two flags: `--list-tools`, which prints the +table and exits (the package's install check uses it), and nothing else that +affects behaviour. `$HHSTREAM_MCP_LOG` sets the log level on stderr. + +## 3. The tool surface + +**One tool per CLI verb**, named after it, with `_` where the CLI has a space. +Twenty-six tools. The rationale — and the alternative that was rejected, one +tool per family with an `action` enum — is in `hhstream_mcp.tools`' docstring. + +Every schema sets `additionalProperties: false`, so an argument this server +would not pass through is refused by the schema rather than dropped on the way +to an argv list. + +### Frames + +| Tool | Arguments | Returns | +| --- | --- | --- | +| `status` | — | the CLI's own text report: both units, the socket's reachability, one probe frame. This verb has no JSON form, so neither does the tool. | +| `shot` | `output?` | **image content** (PNG or JPEG, by the bytes' own magic) plus text naming the geometry, the media type and the byte count | +| `record` | `seconds?`, `out?`, `output?`, `fps?`, `work_dir?`, `keep?` | the artefact's **path** and the *measured* rate — never the video | +| `run` | `argv`, `settle_s?` | the application's pid, and that it is unmanaged | + +`shot` captures to a temporary file and reads it back, because that is the CLI's +only output shape. The media type comes from the bytes and not from the +extension: the publisher serves `image/jpeg` on some machines and `hhstream +shot` writes the payload it was given verbatim. + +`record` hands back a path because an mp4 of a 720p desktop is megabytes and a +tool reply is a message in a model's context. The rate is the one the capture +measured, read off the CLI's own line. + +`run` is spawned with `posix_spawn` into its own session and not waited for. +`settle_s` (default 1.5) is how long the server watches it before reporting the +pid: a launch that fails — no Wayland socket, no such executable — fails inside +that window and comes back as an error, one that survives it comes back as +running. + +### Session lifecycle + +| Tool | Arguments | +| --- | --- | +| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` | +| `session_list` | `all?` | +| `session_status` | `id`, `events?` | +| `session_touch` | `id` | +| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` | +| `session_gc` | `request_id?` | +| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` | +| `session_logs` | `id`, `lines?` | +| `session_container` | `id?` | +| `session_reconcile` | `id?`, `request_id?` | + +Every one of these runs with `--json`, so what comes back is the broker's own +protocol object: in the text part verbatim, and in `structuredContent` parsed. +The human rendering is a table for a terminal; scraping it would be inventing a +second wire format. + +`home` and `ephemeral_home` are mutually exclusive, and the schema says so — +the CLI's argparse group, moved forward to where the refusal is free. + +`session_container` is **not** marked read-only, and that is not an oversight: +with an `id` the CLI runs `container.reconcile`, which writes the record back. +With no `id` it lists. + +### Input — the pointer lease is an argument, never a cache + +| Tool | Arguments | +| --- | --- | +| `pointer_acquire` | `id`, `ttl?`, `no_restore?` | +| `pointer_move` | `id`, `lease`, exactly one of `to` / `by` (each `[x, y]`) | +| `pointer_click` | `id`, `lease`, `button?` | +| `pointer_scroll` | `id`, `lease`, `axis?`, `amount?` | +| `pointer_down` | `id`, `lease`, `button?` | +| `pointer_up` | `id`, `lease`, `button?` | +| `pointer_release` | `id`, `lease` | +| `pointer_state` | — | +| `keyboard_type` | `id`, `lease`, `text` | +| `keyboard_key` | `id`, `lease`, `name` | +| `keyboard_down` | `id`, `lease`, `name` | +| `keyboard_up` | `id`, `lease`, `name` | + +**`lease` is required on every gesture.** The CLI caches the lease id between +invocations (`hhstream_session.lease`) because its surface is flagless and it is +one process per verb; this server passes `--lease` explicitly on every call and +so never reads that cache. The reason is worth stating in full: a cached lease +is a lease an agent cannot see, and the failure it +produces — a gesture that went to a lease the agent did not know it held — is +not one a transcript can explain. + +`pointer_acquire`'s reply puts `lease_id` on the first line of the text part, +because that is what the next call needs. + +`pointer_state` takes no session id. There is one cursor. + +Durations (`ttl`, `idle_timeout`, `wait_ready`, `grace`) are **strings** in the +CLI's own vocabulary: `30s`, `5m`, `3h`, `2d`, or a bare number of seconds. +They are passed through untouched, so the parsing and the refusal are the CLI's. + +### Flag form + +Every option value is passed as one `--name=value` token, and a literal `--` +precedes every positional. Not a style choice: `--by -0.1,0.5` and a `text` +beginning with a dash are both values argparse reads as option strings, and one +uniform rule is one fewer thing to get wrong per flag. + +## 4. What is deliberately absent + +| Not exposed | Why | +| --- | --- | +| `session logs --follow` | it polls until interrupted, and a tool call that never returns hangs the client that made it. Call `session_logs` again. | +| `session start --no-container` | the CLI's flag exists in order to *refuse*: the broker's `start` verb carries no such field (`docs/CONTRACT-sessions.md` §4), so the CLI exits 2 and names the disagreement. A tool argument whose only possible outcome is a refusal is a trap. | +| `hhstream --frame-socket` / `session --socket` | §2: the environment configures them, in one place. | +| a per-call timeout | §5. | +| `session keyboard` with no verb | it prints help and exits 2. There is nothing for a tool to do with that. | + +## 5. Error mapping + +Every refusal the CLI produces comes back as a **tool error** — +`CallToolResult` with `isError: true` — carrying: + +- the remedy sentence, first, naming the code: `exit 9 (NO_LEASE): …`; +- the CLI's own `error`, `reason` and `hint` when it printed a protocol object; +- everything it said, verbatim, under `hhstream said:`; +- `structuredContent` with `ok: false`, `exit_code`, `remedy`, and the + protocol object's own fields. + +`isError` and not a JSON-RPC error, throughout. A JSON-RPC error reaches the +client's log; "another session holds the lease" is something the calling agent +has to read and act on. (The SDK's `call_tool` handler also converts anything +raised into `isError`, so this is the only channel there is in practice.) + +| Exit | Name | Arrives as | The remedy an agent is given | +| --- | --- | --- | --- | +| 0 | OK | a result | — | +| 1 | *not in the frozen table* | tool error | the frame verbs' own failure: no frame published, or `grim`/`ffmpeg` missing from the server's PATH. Also what an uncaught exception in a handler becomes, with its traceback — which is what a CLI process would have done. | +| 2 | USAGE | tool error | fix the arguments; a retry fails identically | +| 3 | NO_SUCH_SESSION | tool error | `session_list` to see which ids exist | +| 4 | BAD_STATE | tool error | `session_status` to see which state | +| 5 | DAEMON_UNREACHABLE | tool error | an operator problem; the four frame tools may still work | +| 7 | TIMEOUT | tool error | read the state back, then retry with the same `request_id` | +| 6 | POLICY | tool error | a configuration decision; no retry changes it | +| 8 | BUSY | tool error | `pointer_state` names the holder; wait. **Never** "acquire one" | +| 9 | NO_LEASE | tool error | `pointer_acquire`, then pass the new `lease_id` | +| 10 | COMPOSITOR | tool error | the session is **not** lost; it is degraded | + +8 and 9 must never read alike, and a unit test holds them apart: an agent that +sees 8 must wait, one that sees 9 must acquire. + +Two failures are not the CLI's verdict and are reported in the same channel +anyway, because the agent holding the tool is the one who has to say so: + +- a tool name that does not exist — the reply names the ones that do; +- an argument the schema rejects — the SDK refuses before an argv list exists, + so the CLI is never reached. + +**The `sg` re-exec is not available here.** `hhstream` recovers from an +unreadable frame socket by re-executing itself through the setuid `sg` wrapper +to join the compositor's group. That is an `exec`, and performing it would +replace this server and drop the client's connection. So a frame verb that +cannot reach the socket fails with the CLI's own message plus a sentence saying +what the CLI would have done and how to avoid needing it: run the server as a +member of that group (`sg hhstream -c hhstream-mcp` in the client's spawn +command, or add the account to the group). The hint is added only when the +condition is actually true, asked of the CLI's own predicate, and only for the +verbs it could be true of. + +**There is no per-call timeout.** In process there is nothing to kill: a thread +cannot be interrupted. The deadlines are therefore the ones that already exist +— the session client's 60 s socket timeout, the broker's per-verb deadline, and +the frame socket's own `--timeout` — and a call that outlives all of them +outlives this server too. A subprocess design could have killed it; that is the +one thing given up by calling the CLI in process. + +## 6. Concurrency + +Tool calls are **serialised**. The CLI prints to a process-global `sys.stdout`, +so two concurrent calls would interleave their output into each other's reply. +One lock around the whole call is the honest fix, and costs nothing a caller +would notice: the broker already serialises every mutation, and the CLI was one +process per verb anyway. The event loop stays free, so a `ping` is answered +while a `record` runs. + +## 7. The two rules, which every relevant tool repeats + +These are `hhstream_session.ACTIVITY_NOTE` and `KEYBOARD_LEASE_NOTE` restated +in terms of tools. They are on the individual tools and not only in the server +instructions, because a client shows a tool's own description at the point of +use: + +1. **`session_touch` is the only thing that resets a session's idle clock.** + `session_list`, `session_status`, `session_logs` and `session_gc` do not, and + neither does any pointer or keyboard tool. A session being driven is still a + session nobody has said they want kept. + +2. **Every keyboard tool needs the pointer lease, and holds only while it + holds.** There is no keyboard lease: one compositor seat means one keyboard + focus. A held non-modifier key floods the window until it is lifted or the + lease expires, because the *application* does the repeating — measured at 25 + a second after 600 ms — and this server cannot rate-limit what it does not + generate. + +`tests/unit/test_mcp_tools.py` asserts both notes are present on every tool +they apply to, and holds the CLI's own constants as a tripwire against drift. + +## 8. Packaging + +`packages.hhstream-mcp` (`nix/mcp.nix`), a separate derivation from +`packages.hhstream` because `mcp` is a third-party dependency and the frame +socket, the CLI and the broker are stdlib-only by policy. `packages.hhstream` +must not grow that dependency; the root `pyproject.toml` excludes +`hhstream_mcp*` from its package discovery so it cannot acquire it by accident. + +`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the +binary on the system PATH. That is the whole of the option: there is no unit, no +socket and no state directory, because the server is spawned per client over +stdio. diff --git a/docs/TODO/README.md b/docs/TODO/README.md index 4a57b10..d9f3aba 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -15,6 +15,7 @@ Each file answers three questions and stops: | [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature | | [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions | | [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` | +| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery | Closed since this folder was written: diff --git a/docs/TODO/mcp-in-process-has-no-call-deadline.md b/docs/TODO/mcp-in-process-has-no-call-deadline.md new file mode 100644 index 0000000..c068edb --- /dev/null +++ b/docs/TODO/mcp-in-process-has-no-call-deadline.md @@ -0,0 +1,67 @@ +# 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.