One property and one consequence, in the two places that own them. `docs/CONTRACT-mcp.md` §1 gains the operational fact an operator meets first: tool calls are serialised across every caller, not per session, so two agents on two tokens queue behind each other. `docs/TODO/mcp-in-process-has-no-call-deadline.md` gains why that matters for the limit it already describes. The serialisation is not new -- it is the same process-wide lock -- but over stdio a call only ever queued behind the same client's previous call. One process for everyone means a stuck call delays other people's agents, and whoever notices is not necessarily whoever caused it. That makes the reachable-timeout idea worth more than it was and the forked-child idea less unreasonable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
593 lines
35 KiB
Markdown
593 lines
35 KiB
Markdown
# CONTRACT — the MCP server (mcp-v2.1)
|
|
|
|
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-v2.1 (2026-10-11). v1 was the first freeze and lasted one day;
|
|
v2 lasted about as long.
|
|
|
|
**v2.1 is additive and breaks nothing.** No tool was renamed, no argument
|
|
changed shape, no resource moved. A client written against v2 over stdio is a
|
|
client that still works, which is why this is a point release and not v3 — v2
|
|
was a bump because it *removed* five tools.
|
|
|
|
| § | Change | Why |
|
|
| --- | --- | --- |
|
|
| §1 | A **second transport**: Streamable HTTP, opt-in, behind a bearer token. stdio stays the default and stays unauthenticated. | A token means nothing on stdio — the client spawns the server, so it has already passed a filesystem permission check and holds the broker's `0660` socket either way. A port is the first time the caller is someone who did neither, and the transport and the credential are therefore one feature. |
|
|
| §2 | `serve --http` and its flags; `token mint\|list\|revoke\|prune` beside it. The bare `hhstream-mcp` and `hhstream-mcp --toolsets=…` forms are unchanged. | A client's `command` entry is a configuration someone else wrote. |
|
|
| §3 | A token may carry its own `toolsets`, and the **intersection** with the server's `--toolsets` applies. | `--toolsets` is a launch-time flag, and one HTTP process serves many callers: a per-process tool budget stops being a per-caller one the moment the transport is shared. |
|
|
| §10 | What the HTTP transport's token **is not**: not OAuth 2.1, not RFC 9728, no metadata discovery. | A limit worth stating in the same register as the two the SDK imposes. |
|
|
|
|
**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 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 |
|
|
| --- | --- |
|
|
| 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 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
|
|
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
|
|
|
|
**Two, and stdio is the default.**
|
|
|
|
| transport | how | authentication |
|
|
| --- | --- | --- |
|
|
| **stdio** | `hhstream-mcp`, or `hhstream-mcp serve`. One process per client, spawned by the client; no port and no daemon. | **None, deliberately.** See below. |
|
|
| **Streamable HTTP** | `hhstream-mcp serve --http`, or the `mcp.http.enable` unit. One process, many clients, one port. | A bearer token on every request, or `401`. |
|
|
|
|
### Why stdio is unauthenticated, and why that is not an oversight
|
|
|
|
The stdio server is spawned *by* its client. To do that the client already had
|
|
to pass a filesystem permission check, and whoever can run `hhstream-mcp` can
|
|
run `hhstream` — which talks to the same `0660` control socket owned by
|
|
`sessions.user`, in the same group. **Unix permissions are the gate**, and
|
|
`mcp.enable`'s own option text has always said so: it "grants no access the
|
|
`hhstream` CLI does not already grant to whoever runs it". A token checked by a
|
|
process the caller started is a lock whose key is in the same pocket.
|
|
|
|
Which is also the whole argument for the HTTP transport existing. A port is
|
|
reachable by a caller who passed no filesystem check, and at that moment a
|
|
credential is the only gate there is. So the two arrived together: v1 and v2
|
|
said "stdio, and only stdio" because, for what the server then was, that was
|
|
the honest answer.
|
|
|
|
### stdio: 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.
|
|
|
|
This is also why `token mint` prints a secret on stdout and is safe: the token
|
|
verbs return *before* anything claims the transport, which
|
|
`tests/unit/test_mcp_authorizations.py` asserts with a `claim_transport` that
|
|
fails the test if it is reached.
|
|
|
|
### HTTP: what is on the wire
|
|
|
|
* **`Authorization: Bearer <token>` on every request.** The scheme is compared
|
|
case-insensitively (RFC 9110). Anything else — absent, malformed, wrong
|
|
scheme, unknown token, revoked token, expired token — is one answer: `401`,
|
|
an **empty body**, `WWW-Authenticate: Bearer realm="hhstream"`,
|
|
`Cache-Control: no-store`. The token is never echoed, in the body or in a
|
|
header, and the response does not distinguish *which* of those it was —
|
|
telling them apart would tell someone who guessed a real id that they had.
|
|
* **Failed attempts are rate-limited per client**, reusing
|
|
`hhstream_live.server`'s `RateLimiter`; past the limit the refusal is `429`.
|
|
* **The token is checked before the `Host`.** An unauthenticated caller learns
|
|
nothing about the rebinding allowlist, which is itself a hint about how the
|
|
server is deployed.
|
|
* **Any path but the mounted one is a `401` without a token** and a `404` with
|
|
one. An unauthenticated caller does not learn what is mounted, or that
|
|
anything is.
|
|
* **DNS-rebinding protection is on.** The `Host` allowlist is derived from the
|
|
bind address when none is given, because the SDK's check is allowlist-only
|
|
with no implicit localhost — protection on with an empty list `421`s *every*
|
|
request. A wildcard bind derives nothing and is refused at launch, which
|
|
makes binding every interface the one case where the hostnames must be named.
|
|
* **No TLS.** The token crosses the wire in clear text. Loopback is the
|
|
default; anything else wants a reverse proxy and says so in a module warning.
|
|
* **Tool calls are serialised across every caller**, not per session. The
|
|
`Runner` holds a process-wide lock because the CLI it calls prints to a
|
|
stdout this process shares — invisible while each client had a process of its
|
|
own, visible now that one process serves many. Two agents on two tokens queue
|
|
behind each other, and a slow call delays everyone's next one rather than
|
|
only its own caller's. Latency, never a hang: the event loop answers a `ping`
|
|
throughout. See `docs/TODO/mcp-in-process-has-no-call-deadline.md`.
|
|
|
|
## 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 HTTP transport reads one more, and `hhstream-mcp token` reads the same:
|
|
|
|
| Variable | What it names | Default |
|
|
| --- | --- | --- |
|
|
| `HHSTREAM_MCP_STATE_DIR` | where the authorization table lives | `/var/lib/hhstream-mcp` |
|
|
|
|
**Not `sessions.stateDir`.** That directory is `0700` owned by the broker's
|
|
user and holds `events.jsonl`, the audit trail; the MCP server runs as whichever
|
|
user's client spawned it, and parking a token file there would mean granting
|
|
this shim write access to the audit trail's directory for no reason. The two
|
|
also have different lifetimes: revoking every token must not be able to touch a
|
|
session record.
|
|
|
|
The server's own command line. `hhstream-mcp` with no subcommand, and
|
|
`hhstream-mcp serve`, are the same thing — the bare form is not deprecated and
|
|
will not be, because an MCP client's `command` entry is a configuration
|
|
somebody else wrote:
|
|
|
|
| flag | where | what it does |
|
|
| --- | --- | --- |
|
|
| `--toolsets NAMES` | either | 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` | either | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
|
|
| `--list-resources` | either | print the resource URIs and templates and exit. |
|
|
| `--http` | `serve` | Streamable HTTP instead of stdio. |
|
|
| `--address HOST` | `serve` | default `127.0.0.1`. Loopback, because reaching the LAN is a second decision. |
|
|
| `--port N` | `serve` | default `9989`, one past the live stream's `9988`. |
|
|
| `--path P` | `serve` | default `/mcp`. |
|
|
| `--state-dir DIR` | `serve`, `token` | overrides `$HHSTREAM_MCP_STATE_DIR`. |
|
|
| `--allowed-host HOST` | `serve` | repeatable. Omitted, derived from `--address`; a trailing `:*` is a wildcard port. |
|
|
| `--allowed-origin ORIGIN` | `serve` | repeatable. Nothing needs this unless a browser is the client. |
|
|
| `--allow-no-tokens` | `serve` | start although the table is empty. Without it that is a usage error, because a listener that `401`s every request is almost always a forgotten `token mint`. |
|
|
| `--stateless` | `serve` | no session to pin, for a deployment behind a load balancer. |
|
|
| `--json-response` | `serve` | one JSON body instead of an SSE stream. |
|
|
|
|
### `hhstream-mcp token`
|
|
|
|
| verb | what it does |
|
|
| --- | --- |
|
|
| `token mint [--label L] [--expires-in D] [--toolsets NAMES]` | print a new token **once**, on stdout, with the prose for a human on stderr beside it. `D` is `30s`/`5m`/`3h`/`90d` or bare seconds. |
|
|
| `token list [--json]` | the table. The tokens are not in it and cannot be. |
|
|
| `token revoke <id> \| --all` | by **id**, so ending a grant never means pasting a live secret onto a command line that lands in a shell history. |
|
|
| `token prune` | drop expired grants. Housekeeping only — an expired token is refused whether or not it is still on disk. |
|
|
|
|
The table holds **SHA-256 digests, not tokens**, so `authorizations.json` is not
|
|
itself a credential; a token that was not written down can only be revoked and
|
|
replaced. No salt and no KDF: a token is `secrets.token_urlsafe(32)` behind an
|
|
`hhsmcp_` prefix — 256 bits, so there is no dictionary to attack and a work
|
|
factor would only slow the request path. The prefix is there so a leaked token
|
|
is identifiable on sight, which is the convention secret scanners are built
|
|
around.
|
|
|
|
Expiry is **wall clock**, and it is the one place in this project where that is
|
|
right. Every deadline in the broker is `CLOCK_BOOTTIME` (`hhstreamd.clock`)
|
|
because an idle window has to survive an NTP step and count time spent
|
|
suspended. "Valid for thirty days" is a calendar statement that has to outlive
|
|
a reboot, and BOOTTIME resets to zero there.
|
|
|
|
Every read-modify-write takes an exclusive `flock` on a sidecar lock file. Two
|
|
processes write this table — the server stamping `last_used`, and an operator
|
|
running `token mint` — and the atomic replace alone prevents a torn *read*, not
|
|
a lost *update*.
|
|
|
|
These verbs sit **outside** the frozen exit-code table in
|
|
`hhstreamd.protocol`, because nothing they do reaches the broker and no agent
|
|
calls them. Two of the codes are chosen by analogy with it anyway: `0` done,
|
|
`2` usage, `3` no token with that id (the analogue of `NO_SUCH_SESSION`), `4`
|
|
the store itself is unusable (the analogue of `BAD_STATE`).
|
|
|
|
`$HHSTREAM_MCP_LOG` sets the log level on stderr. Nothing else affects
|
|
behaviour; in particular the server holds no state and caches no lease.
|
|
|
|
On the HTTP transport a **token** may carry its own `toolsets`, and the
|
|
**intersection** with the server's own applies — a token cannot widen what the
|
|
unit was started with. That exists because `--toolsets` is a launch-time flag
|
|
and one HTTP process serves many callers: a per-process tool budget stops being
|
|
a per-caller one the moment the transport is shared, and the token is then the
|
|
only place the distinction can live. A tool the caller's token excludes is not
|
|
listed and cannot be reached by name; the refusal names both possible
|
|
narrowings, because the agent cannot tell them apart from where it stands and
|
|
neither is its to change.
|
|
|
|
**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 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 |
|
|
| --- | --- | --- |
|
|
| `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_touch` | `id` |
|
|
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
|
|
| `session_gc` | `request_id?` |
|
|
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_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
|
|
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.
|
|
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
|
|
|
|
| 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` |
|
|
| `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.
|
|
|
|
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.
|
|
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. 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. 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 | §6. |
|
|
| `session keyboard` with no verb | it prints help and exits 2. There is nothing for a tool to do with that. |
|
|
|
|
## 6. Error mapping
|
|
|
|
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): …`;
|
|
- 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, 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 | 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 | 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 |
|
|
|
|
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.
|
|
|
|
## 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.
|
|
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.
|
|
|
|
## 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 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.**
|
|
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
|
|
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;
|
|
`tests/unit/test_mcp_resources.py` does the same for the five reads the first
|
|
rule applies to.
|
|
|
|
## 9. 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 stdio server is spawned per client.
|
|
|
|
`services.hyprland-headless-stream.mcp.http.enable` (default `false`) is the
|
|
other half, and it **is** a unit — `hhstream-mcp.service`, running as
|
|
`sessions.user` with `sessions.group`, because the tools it serves are the
|
|
CLI's own handlers called in process and that CLI opens a `0660` control socket
|
|
owned by that user and a compositor runtime directory owned by that group. It
|
|
is `Wants`/`After` the broker and not `BindsTo`: the frame verbs answer with
|
|
the broker down and the rest answer exit 5, which is a true answer, whereas a
|
|
listener that vanished with the broker would turn that into a connection
|
|
refused and tell a client nothing.
|
|
|
|
The two options are independent and neither implies the other. `http.enable`
|
|
also puts the binary on PATH, because `token mint` is how the credential that
|
|
unit demands gets issued.
|
|
|
|
| option | default |
|
|
| --- | --- |
|
|
| `mcp.stateDir` | `/var/lib/hhstream-mcp`, created `0700` by a tmpfiles entry |
|
|
| `mcp.http.address` | `127.0.0.1` |
|
|
| `mcp.http.port` | `9989` |
|
|
| `mcp.http.path` | `/mcp` |
|
|
| `mcp.http.allowedHosts` / `allowedOrigins` | `[]` — hosts are derived from the address |
|
|
| `mcp.http.toolsets` | `null`, every tool |
|
|
| `mcp.http.openFirewall` | `false`, and not implied by `http.enable` |
|
|
| `mcp.http.extraArgs` | `[]` |
|
|
|
|
**The unit refuses to start while the authorization table is empty**, and
|
|
retries every five seconds rather than giving up
|
|
(`StartLimitIntervalSec = 0`). Both halves are deliberate and neither works
|
|
without the other: the refusal is there because a listener that `401`s every
|
|
request is almost always a forgotten mint, and "connection works, auth fails"
|
|
is far worse to debug than a `systemctl status` that names the remedy — but a
|
|
refusal that gave up would leave every freshly provisioned machine dead, and
|
|
minting the first token would then also need a `systemctl start` nothing told
|
|
anyone about. With the retry, the unit comes up on its own within one interval
|
|
of the first mint. `checks/vm-mcp-http.nix` asserts exactly that, because
|
|
nothing in the Python can.
|
|
|
|
Revoking *every* token does not stop the running process — it keeps its port
|
|
and refuses everyone. The startup refusal exists to catch a forgotten mint, not
|
|
to police a deliberate one.
|
|
|
|
## 10. What the HTTP transport's token is not
|
|
|
|
**Not MCP's authorization specification.** That is OAuth 2.1 plus RFC 9728
|
|
protected-resource metadata: a `401` is meant to carry a `WWW-Authenticate`
|
|
pointing at a metadata document, the client discovers an authorization server,
|
|
and a real flow happens. What this serves is a static token an operator minted
|
|
and pasted into a client's configuration.
|
|
|
|
Stated rather than discovered, because the consequences are not subtle:
|
|
|
|
* a client that can only *discover* an authorization server will not connect to
|
|
this at all;
|
|
* a client that lets you set a header works immediately;
|
|
* there is no refresh, no rotation and no revocation list beyond
|
|
`token revoke`, which is immediate because the table is read per request —
|
|
no restart, and an operator who had to restart a service to lock someone out
|
|
would not have revocation.
|
|
|
|
The gap is `docs/TODO/mcp-http-auth-is-not-oauth.md`, beside the two limits the
|
|
SDK imposes.
|
|
|
|
**A token does not scope resources.** §2 keeps resources out of `--toolsets` on
|
|
the grounds that they are the host's context rather than the model's budget, and
|
|
that argument carries over to the server's own flag. It does not carry over
|
|
cleanly to a *token*, which is an authorization and not a budget — so a token
|
|
scoped to `frames` can still read `hhstream://sessions`. That is a real gap, not
|
|
an oversight: `docs/TODO/mcp-tokens-do-not-scope-resources.md`, and
|
|
`tests/unit/test_mcp_http.py` asserts the current behaviour so that fixing it is
|
|
a visible change rather than a silent one.
|