docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it

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

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

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

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 11:50:12 +00:00
1 parent 56493721f0
commit e636472106
7 files changed
+290 -85

No files matched your search

+9 -2
View File
@@ -51,7 +51,8 @@ import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio
hhstream-mcp --list-tools # the 21 acting verbs
hhstream-mcp --list-resources # the 8 read-only URIs
```
## The checks
@@ -68,7 +69,7 @@ hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio
| `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 |
| `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 21 tools and 8 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
All of them at once:
@@ -122,6 +123,12 @@ output is on that path beside it, and `mcp` is in the test environment, because
— 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 MCP suite is four files, split along what each can be tested without:
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
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
deselected, so `checks/lib/check_report.py` parses the JUnit report and refuses
+39 -13
View File
@@ -37,16 +37,31 @@ 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
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
Protocol](https://modelcontextprotocol.io) surface, 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`.
application without writing command lines. 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.
It is split the way the protocol splits things:
- **Resources are the state** — eight of them, read by URI, and reading one
changes nothing. `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
an application's own output, `hhstream://pointer` is who holds the input
lease, `hhstream://screen` is a frame of the screen.
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
`session_start` puts an application on the screen, `pointer_acquire` takes the
input lease, `keyboard_type` types, `session_kill` ends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why `shot` is still a tool
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
It is a thin wrapper and nothing more: every tool and every resource 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:
@@ -86,16 +101,27 @@ server cannot recover that for itself the way the CLI does — see
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.
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
exit, which is the quickest way to check an install.
If twenty-one tools is more than a client has room for, `--toolsets` narrows
what is offered to whichever families are wanted — `frames`, `sessions`,
`pointer`, `keyboard`:
```json
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
```
Resources are deliberately *not* narrowed by it: they are the host's context,
not the model's tool budget. Nothing else about the server is configurable — it
holds no state and 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/CONTRACT-mcp.md` | the MCP surface: the resource URIs, the tool names, their arguments and the 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` |
+17 -10
View File
@@ -37,7 +37,8 @@
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 26 tools, one per verb │◀─── an MCP client's JSON-RPC
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│
└───────────────────────────┘
```
@@ -64,15 +65,21 @@ piece at all:
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.
Model Context Protocol surface on it, so an agent reads state by URI and
acts by calling tools instead of writing command lines. It is drawn above
the CLI rather than beside the broker because that is where it sits: every
tool and every resource 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.
The split between its two halves is *who decides*, not what it costs. A
resource is the host's to include (`hhstream://sessions` is state anyone may
want in context); a tool is the model's to call (`session_kill` is a
decision). That is why `shot` is both — a tool because deciding to look is
an act, and `hhstream://screen` because a frame is also just state.
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
+151 -52
View File
@@ -1,22 +1,45 @@
# CONTRACT — the MCP server (mcp-v1)
# CONTRACT — the MCP server (mcp-v2)
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).
This file is the interface of `hhstream-mcp`: the resource URIs, 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).
Version: mcp-v2 (2026-10-11). v1 was the first freeze and lasted one day.
**v2 is a breaking change, and the only one: the verbs that merely read are
resources now, not tools.**
| § | Change | Why |
| --- | --- | --- |
| §3, §4 | `status`, `session_list`, `session_status`, `session_logs` and `pointer_state` are **removed from the tool list** and are `hhstream://…` resources instead. 26 tools became 21. | The protocol's own split. A resource is *application*-controlled context — the host decides what to put in front of the model — and "what is on this machine right now" is the host's question. A tool is *model*-controlled: an act the model chooses. Nothing in those five acts. |
| §4 | Eight resources: five fixed, three templates, with query parameters for the arguments the verbs took. | A resource read takes nothing but a URI, so `--lines` becomes `?lines=`. Only declared parameters are accepted. |
| §5 | A refused resource read is a **protocol error** carrying the same remedy a tool error would have. | `CallToolResult` has `isError`; `ReadResourceResult` has nothing. Returning the broker's failure object as the body would make "no such session" read as a successful read of a session. |
| §3 | `--toolsets` selects which families are listed as tools. | A tool listing is a budget. MCP has no grouping primitive — the `Tool` object has nowhere to put one — so the only lever is which tools the *server* lists, chosen at launch. |
What did **not** move, and the reasons are the interesting part:
* **`shot` and `record` are still tools**, though neither changes the desktop.
Capturing is an act at a moment: an agent in a loop has to be able to decide
to look *now*, and in many clients a resource is something a person attaches
rather than something a model can fetch on its own initiative. The same frames
are *also* readable as `hhstream://screen` and `hhstream://outputs/{name}`,
for a host that wants to put one in context itself.
* **`session_container` is still a tool**, for a harder reason: with an id the
CLI runs `container.reconcile`, which re-reads the compositor and writes the
record back. It is not a read at all. Only the no-id form is a resource
(`hhstream://containers`). A resource read must never write.
## 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:
It is a **shim**. Each tool and each resource 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 |
| --- | --- |
@@ -27,10 +50,10 @@ back. Nothing in it decides anything:
| 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.
What this layer owns is the argv list, the routing of a URI to one of them, 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 and resources.
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
@@ -64,25 +87,50 @@ the CLI:
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.
The server's own command line:
| flag | what it does |
| --- | --- |
| `--toolsets NAMES` | comma-separated families to offer as **tools**: `frames`, `sessions`, `pointer`, `keyboard`. Omitted, every tool is offered. An unknown name is argparse's exit 2, never a silently empty server. **Resources are not filtered by it** — they are the host's context, not the model's tool budget, and making `hhstream://sessions` conditional on the session *tools* would couple two decisions that are not the same decision. |
| `--list-tools` | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
| `--list-resources` | print the resource URIs and templates and exit. |
`$HHSTREAM_MCP_LOG` sets the log level on stderr. Nothing else affects
behaviour; in particular the server holds no state and caches no lease.
**There is no grouping primitive in MCP**, and `--toolsets` is not pretending to
be one. The `Tool` object carries `name`, `title`, `description`,
`inputSchema`, `outputSchema`, `icons`, `annotations`, `_meta` and `execution` —
nowhere to put a family. Tools are a flat list in the specification too. So the
only honest lever is which tools the *server* lists, decided by whoever spawns
it, and the families below are the grouping that is left: a prefix in the name
and a line in this table.
## 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.
**One tool per CLI verb that acts**, named after it, with `_` where the CLI has
a space. Twenty-one tools, in four families. The granularity 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.
| family | tools |
| --- | --- |
| `frames` | `shot`, `record`, `run` |
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
Every tool is in exactly one family — asserted by a unit test, because a tool in
none of them would be one `--toolsets` could never offer.
### 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 |
@@ -107,14 +155,11 @@ running.
| 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_container` | `id` |
| `session_reconcile` | `id?`, `request_id?` |
Every one of these runs with `--json`, so what comes back is the broker's own
@@ -127,7 +172,8 @@ 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.
That is also why it is a tool rather than a resource. The no-id listing, which
only reads, is `hhstream://containers`.
### Input — the pointer lease is an argument, never a cache
@@ -140,7 +186,6 @@ With no `id` it lists.
| `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` |
@@ -157,7 +202,8 @@ 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.
Who *holds* the lease is a read, so it is `hhstream://pointer` rather than a
tool. That is the resource to read after an exit 8.
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.
@@ -170,19 +216,54 @@ 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
## 4. The resource surface
Five fixed resources and three templates, all under one scheme, because they
are all views of one machine's one desktop. Every one of them runs the same CLI
verb a tool would have, with `--json` where the verb has it.
| URI | Body | Query |
| --- | --- | --- |
| `hhstream://status` | `text/plain` — the CLI's own report: both compositor units, the frame socket's path and whether this server can read it, the Wayland socket, one probe frame. `hhstream status` has no JSON form, so neither does this. | — |
| `hhstream://sessions` | `application/json` — the broker's `list` object | `?all=true` includes tombstones |
| `hhstream://pointer` | `application/json` — the holder, since when, and the buttons and **keys** held | — |
| `hhstream://containers` | `application/json` — every container plus the orphan `hh-*` outputs. The **listing** only; see §3. | — |
| `hhstream://screen` | the published main output as an image blob. With containers on this is the whole compositor layout, so it is **wider than any single output's configured size**. | — |
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
Rules this surface keeps:
* **A read never writes.** That is what excludes `session container <id>`.
* **Only declared query parameters are accepted.** An unknown one is refused,
for the reason every tool schema sets `additionalProperties: false`: a
parameter silently ignored is a read that answered a different question from
the one asked. A parameter given twice is refused too.
* **A literal route beats a template.** `hhstream://sessions` is the listing,
not a session whose id happened to be empty.
* **The media type of a frame is read off the bytes**, never off the extension
the server asked the CLI for. The entry's declared `mimeType` is a hint; the
`ReadResourceContents` carries the answer.
* **No subscriptions.** `Server.get_capabilities` in the pinned SDK hardcodes
`ResourcesCapability(subscribe=False, …)` — it never advertises `subscribe`
even if a handler is registered. So resource subscription is *not* available
as the answer to the missing `logs --follow`, which is a shame, because it
would have been the right one. Read it again instead.
## 5. 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 logs --follow` | it polls until interrupted, and a tool call that never returns hangs the client that made it. Read `hhstream://sessions/{id}/logs` again. Resource *subscriptions* would have been the principled fix; see §4. |
| `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. |
| a per-call timeout | §6. |
| `session keyboard` with no verb | it prints help and exits 2. There is nothing for a tool to do with that. |
## 5. Error mapping
## 6. Error mapping
Every refusal the CLI produces comes back as a **tool error** —
Every refusal the CLI produces on a **tool call** comes back as a tool error —
`CallToolResult` with `isError: true` — carrying:
- the remedy sentence, first, naming the code: `exit 9 (NO_LEASE): …`;
@@ -191,22 +272,36 @@ Every refusal the CLI produces comes back as a **tool error** —
- `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.)
`isError` and not a JSON-RPC error, for tools, 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.)
On a **resource read** it is the other way round, and not by preference:
`ReadResourceResult` has no `isError`, so a refusal is raised as a JSON-RPC
error with code `-32602` (`INVALID_PARAMS`), its `message` carrying the same
remedy-then-the-CLI's-own-words text and its `data` carrying the same
`{ok, exit_code, error, reason, hint, remedy}` object. Returning the broker's
failure object as the resource's *body* would make "no such session" read as a
successful read of a session, which is the one outcome a contract has to
forbid. The same error is raised for a URI that names nothing and for an
undeclared query parameter — in both cases before the CLI is reached at all.
"Arrives as" below is for a tool call; on a resource read every one of them is
the protocol error above, with the same remedy.
| 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 |
| 3 | NO_SUCH_SESSION | tool error | read `hhstream://sessions` to see which ids exist |
| 4 | BAD_STATE | tool error | read `hhstream://sessions/<id>` to see which state |
| 5 | DAEMON_UNREACHABLE | tool error | an operator problem; the three frame tools and `hhstream://status` 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" |
| 8 | BUSY | tool error | read `hhstream://pointer` for 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 |
@@ -238,7 +333,7 @@ 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
## 7. 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.
@@ -247,17 +342,19 @@ 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
## 8. The two rules, which every relevant tool and resource 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:
in terms of this surface. They are on the individual tools and resources and
not only in the server instructions, because a client shows a thing'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.
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
session being driven is still a session nobody has said they want kept. The
three resources it applies to say so in their own descriptions, because a
description is what a host shows beside the thing it describes.
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
@@ -266,10 +363,12 @@ use:
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.
`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;
`tests/unit/test_mcp_resources.py` does the same for the five reads the first
rule applies to.
## 8. Packaging
## 9. Packaging
`packages.hhstream-mcp` (`nix/mcp.nix`), a separate derivation from
`packages.hhstream` because `mcp` is a third-party dependency and the frame
+1
View File
@@ -16,6 +16,7 @@ Each file answers three questions and stops:
| [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 |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
Closed since this folder was written:
@@ -2,9 +2,9 @@
## 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
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool or a
resource read builds the argv list `hhstream.cli`'s parser takes, and
`hhstream_mcp.invoke.dispatch` runs the handler argparse selected. That is the seam the design asks for — one place
decides the argv, nothing re-implements a rule — and it costs two things a
subprocess would have given for free. Both are consequences of the same fact, so
they are one item.
@@ -36,11 +36,11 @@ 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.
for (1))* The honest small fix: let `shot` and `record` take a `timeout`
argument, and `hhstream://status` and the frame resources a `?timeout=`,
emitted as a global flag *before* the verb — which `hhstream_mcp.tools.argv`
cannot express today. That hands the one knob the CLI already has to the
caller, and does not pretend this layer can enforce a deadline it cannot.
2. **Run each call in a forked child after all.** Restores a killable deadline,
at the cost of a process per tool call and of re-introducing the two `exec`
paths this design avoids. Worth it only if a hang is observed in practice.
@@ -0,0 +1,65 @@
# A resource cannot be followed, because the SDK will not advertise subscriptions
## The issue
`hhstream://sessions/{id}/logs` is the right shape for watching an application:
a URI whose content changes, which is exactly what MCP resource
**subscriptions** are for (`resources/subscribe`, then
`notifications/resources/updated`). An agent waiting for a build to finish, or
for a page to load, would subscribe once instead of reading in a loop.
It is not available. `mcp.server.lowlevel.Server.get_capabilities` computes the
resource capability like this (mcp 1.29.0, `server/lowlevel/server.py`):
```python
if types.ListResourcesRequest in self.request_handlers:
resources_capability = types.ResourcesCapability(
subscribe=False, listChanged=notification_options.resources_changed
)
```
`subscribe=False` is hardcoded. Registering a `@server.subscribe_resource()`
handler does not change it, so a client is told the server cannot be subscribed
to and correctly never tries. The handlers exist on the `Server` class and are
unreachable through the advertised capability.
This is why `docs/CONTRACT-mcp.md` §4 says there is no following, and why the
`session-logs` resource's own description tells the reader to read it again. It
is also the reason the CLI's `session logs --follow` has no equivalent anywhere
in this surface: the tool form would hang the client, and the resource form is
switched off upstream.
## Ideas
1. **Set the capability after construction.** *(recommended)*
`create_initialization_options()` returns the computed capabilities, and the
server is handed them by `serve()` -- so one line in
`hhstream_mcp.server.serve` could set `capabilities.resources.subscribe =
True` before `server.run`, with `subscribe_resource`/`unsubscribe_resource`
handlers behind it. Small, local, and reversible when the SDK grows the
knob. The cost is that it reaches past the SDK's own computation, which is
the kind of thing that breaks on an upgrade without saying so -- so it wants
a unit test asserting the advertised capability, not just the handler.
2. **Poll on the server's side and notify.** Keep `subscribe=False`, and have
the server itself re-read and send `notifications/resources/updated`. Does
not work: a client that was told `subscribe=False` has no reason to have
subscribed, so there is nobody to notify.
3. **Upstream it.** The hardcoded `False` looks like an oversight rather than a
decision; a patch that derives it from whether a `subscribe_resource`
handler was registered would match how every other capability on that method
is computed. Slowest, and the right long-term answer.
4. **Leave it, and say so.** What ships today, in the contract and in the
resource's own description.
## Why it matters
It is the difference between an agent that waits and an agent that polls. Every
read is a CLI call in process, so a loop that reads a session's logs every
second is a `hhstream session logs` every second, serialised against every other
call this server makes -- which is exactly the contention the other TODO in this
folder describes. Subscriptions would remove the loop rather than make it
cheaper.
Medium rather than high because reading again *works*, and because the one
caller who really needs to follow output can run `hhstream session logs
--follow` in a terminal, which is what it is for.