`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two resources, three `session_start` arguments, and the one rule that is not a name at all -- a connected viewer is the single exception to the idle-clock rule, and it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is additive; every v2 name still means what it meant. README.md leads the stream with the shape of it rather than the options: one port for the machine, a phrase per session, a browser `<img>` as the entire client, and the four things worth knowing before switching one on -- that it is per session and off by default, that the phrase survives a restart, that capture runs only while somebody is connected, and that watching counts as activity. The phrase is called what it is: the only protection, with no TLS and no second factor. ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`, hanging off the broker by `live.sock` with one port and a browser at the end of it -- and the counts move to 23 and 10. Two TODOs, both written by `checks/vm-stream.nix`: * `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a stream after ten consecutive capture failures and the stop is sticky on purpose, but `Control._describe` does not pass `stopped` on, so `_stream_public` reports `attached: true` for a capture that has permanently given up. That is the second place `attached` answers "is a capture running right now" wrongly, and a field that is right only when nothing is wrong is not worth reading. * `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The module passes grim's store path and this check reads real frames -- which immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`. What is still open is the other half: the app resolves its capture command by name and never checks it, so any deployment that is not this module still discovers a broken capture ten failures later. The plan's status section records Stage 2 and Stage 3 as built, the two decisions §5 left open (that `start` takes `--stream`, and that the default rate is the daemon's), and what Stage 2 deliberately did not do -- §6's restart re-attachment, which has its own TODO. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
26 KiB
CONTRACT — the MCP server (mcp-v3)
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 (2026-10-11). v1 was the first freeze and lasted one day; v2 split state out into resources; v3 adds the live stream. v3 is additive — every v2 name still means what it meant.
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:
shotandrecordare 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 ashhstream://screenandhhstream://outputs/{name}, for a host that wants to put one in context itself.session_containeris still a tool, for a harder reason: with an id the CLI runscontainer.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
stdio, and only stdio. One process per client, spawned by the client; no port, no daemon, no socket of its own. There is already a daemon in this system and it owns all the state.
The protocol is not on file descriptor 1 once the server is running: the
tools run the CLI in process, the CLI prints, and record spawns an ffmpeg
whose output the CLI does not capture. The server takes a private duplicate of
stdin and stdout at start-up, then points fd 1 at its log and fd 0 at
/dev/null. A stray write is therefore a log line and never a corrupted
stream.
2. Configuration
There is no --socket flag. The sockets are the CLI's own environment, read by
the CLI:
| Variable | What it names | Default |
|---|---|---|
HHSTREAM_SOCKET |
the broker's control socket | /run/hhstream/control.sock |
HHSTREAM_FRAME_SOCKET |
the published frame socket | /run/hypr-stream/stream.sock |
Set them in the MCP client's env block. One place to configure them is one
place for them to be wrong.
The server's own command line:
| 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 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://sessionsis 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
mimeTypeis a hint; theReadResourceContentscarries the answer. - No subscriptions.
Server.get_capabilitiesin the pinned SDK hardcodesResourcesCapability(subscribe=False, …)— it never advertisessubscribeeven if a handler is registered. So resource subscription is not available as the answer to the missinglogs --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,reasonandhintwhen it printed a protocol object; - everything it said, verbatim, under
hhstream said:; structuredContentwithok: 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:
-
session_touchis the only thing a caller can do that resets a session's idle clock. Readinghhstream://sessions,hhstream://sessions/{id}or its logs does not,session_gcdoes 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 stampstouchon 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. -
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 server is spawned per client over
stdio.