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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:33:07 +00:00
1 parent fea55eecde
commit 6a40c7e2e4
6 files changed
+473 -11

No files matched your search

+38 -10
View File
@@ -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
+58
View File
@@ -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` |
+26 -1
View File
@@ -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
+283
View File
@@ -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.
+1
View File
@@ -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:
@@ -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.