The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge. Six files
conflicted; the interesting resolutions are the two that were not
textual.
**The contract is mcp-v3.1, not v2.1.** This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive. Both point releases, both correct, and they cannot both be
the same document. So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.
**The counts are no longer literals.** This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6. Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`. That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice. A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.
The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.
One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.
Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
646 lines
39 KiB
Markdown
646 lines
39 KiB
Markdown
# CONTRACT — the MCP server (mcp-v3.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-v3.1 (2026-10-12). v1 was the first freeze and lasted one day; v2
|
|
split state out into resources; v3 added the live stream; v3.1 adds a second
|
|
transport. Only v2 ever broke anything.
|
|
|
|
**v3.1 is additive and breaks nothing.** No tool was renamed, no argument
|
|
changed shape, no resource moved. A client written against v3 over stdio is a
|
|
client that still works — which is why this is a point release, the same way v3
|
|
was additive over v2 and for the same reason. v2 is still the only major bump,
|
|
because it is the only one that *removed* anything.
|
|
|
|
v3.1 changes, all of them the HTTP transport and the credential it needs:
|
|
|
|
| § | 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. |
|
|
|
|
v3 changes, all of them the per-session live stream
|
|
(`docs/CONTRACT-sessions.md` §4, v4):
|
|
|
|
| § | Change | Why |
|
|
| --- | --- | --- |
|
|
| §3 | Tools `session_stream_enable` and `session_stream_disable`. 21 tools became 23. | Switching a stream on is an *act*, and a consequential one: it publishes a desktop on the LAN behind a phrase. Nothing about it is a read. |
|
|
| §3 | `session_start` gains `stream`, `stream_phrase` and `stream_fps`, and its reply carries the URL. | A stream needs the container output that starting creates, so sequencing start-then-enable in the caller means every caller repeats the ordering and the half-done case. One call, one answer, and the phrase comes back with the session. |
|
|
| §4 | Resources `hhstream://streams` and `hhstream://sessions/{id}/stream`. 8 resources became 10. | What is being published, and who is watching, is state — so it is read, not called. |
|
|
| §6 | A connected viewer is the **one exception** to the idle-clock rule. | About once a minute the broker stamps `touch` on any session somebody is watching. It is not a verb and cannot be invoked; it is the broker noticing that a person is looking. |
|
|
|
|
**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`, `session_stream_enable`, `session_stream_disable` |
|
|
| `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?`, `stream?`, `stream_phrase?`, `stream_fps?`, `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?` |
|
|
| `session_stream_enable` | `id`, `phrase?`, `fps?` |
|
|
| `session_stream_disable` | `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_stream_enable` returns the **URL** on the first line of its text part,
|
|
because that is the whole point of the call: it is what gets handed to a person.
|
|
It publishes the session's own container output and never the main one — that
|
|
output carries every other session, and putting it behind one session's phrase
|
|
is the mistake the broker refuses to make (exit 10 with no container). Re-enabling
|
|
returns the same URL; a different `phrase` is exit 8, not a silent rotation,
|
|
because rotating under somebody holding the old URL is the one outcome neither
|
|
answer can be mistaken for. `session_stream_disable` is marked **destructive**:
|
|
it forgets the phrase, so anyone holding that URL loses it.
|
|
|
|
`session_start` with `stream: true` is one call rather than two, and a stream
|
|
that cannot be opened **does not fail the start** — the application is on the
|
|
screen, and killing it over a web page would be the wrong trade. The reply
|
|
carries `stream_error` whenever `stream` was asked for, `null` when it worked.
|
|
|
|
`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. | — |
|
|
| `hhstream://streams` | `application/json` — every session a stream was enabled on, with its URL, rate and connected viewer count, plus `available` (whether the stream daemon answered) | — |
|
|
| `hhstream://sessions/{id}/stream` | `application/json` — one session's stream, or `null`. `attached` is separate from `enabled`, and the URL is absent rather than stale when it is false. | — |
|
|
|
|
**The URLs in those two bodies contain their phrases**, which are the only thing
|
|
protecting those streams. Both descriptions say so, because a host that puts
|
|
`hhstream://streams` into a model's context has put a credential there — and
|
|
the one place it must never go is anywhere the streamed session can see.
|
|
|
|
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 a *caller* can do that resets a
|
|
session's idle clock.** Reading `hhstream://sessions`,
|
|
`hhstream://sessions/{id}` or its logs does not, `session_gc` does not, the
|
|
stream tools do not, and neither does any pointer or keyboard tool. A
|
|
session being driven is still a session nobody has said they want kept. The
|
|
resources it applies to say so in their own descriptions, because a
|
|
description is what a host shows beside the thing it describes.
|
|
|
|
**The one exception is a connected viewer** (`docs/CONTRACT-sessions.md` §4,
|
|
v4): about once a minute the broker stamps `touch` on any session somebody
|
|
is watching through its live stream. It is not a tool and cannot be
|
|
invoked — it is the broker noticing that a person is looking, which is the
|
|
one form of "still wanted" that does not come down the control socket. It
|
|
cannot hold a session open by itself: an enabled stream with no viewer
|
|
captures nothing and stamps nothing.
|
|
|
|
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.
|
|
|
|
The stream tools and the two stream resources additionally need
|
|
`services.hyprland-headless-stream.sessions.stream.enable`, which runs the
|
|
`hhstream-live` unit and gives the broker the socket it switches streams on
|
|
over. Without it they answer exit 10 (`stream_unavailable`) — the session is
|
|
unaffected, which is what that code means.
|
|
|
|
`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.
|