docs(stream): mcp-v3, the seventh box, and two TODOs the check wrote

`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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 22:54:26 +00:00
1 parent 9d33639c04
commit 887ed17be2
9 files changed
+341 -33

No files matched your search

+59 -8
View File
@@ -1,4 +1,4 @@
# CONTRACT — the MCP server (mcp-v2)
# 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
@@ -10,7 +10,19 @@ containers and the input lease).
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 (2026-10-11). v1 was the first freeze and lasted one day.
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.**
@@ -120,7 +132,7 @@ 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` |
| `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` |
@@ -154,13 +166,15 @@ running.
| Tool | Arguments |
| --- | --- |
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
| `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.
@@ -170,6 +184,21 @@ 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
@@ -232,6 +261,13 @@ verb a tool would have, with `--json` where the verb has it.
| `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:
@@ -349,13 +385,22 @@ 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
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
three resources it applies to say so in their own descriptions, because a
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
@@ -376,6 +421,12 @@ 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