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:
1 parent
fea55eecde
commit
6a40c7e2e4
6 files changed
+473
-11
No files matched your search
+38
-10
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user