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

+53 -5
View File
@@ -35,6 +35,52 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
The socket is a plain file descriptor: the server serves every client that
connects, and keeps running when one disconnects.
## Watching a session: one port, a phrase per session
A session can publish its own screen on a web page, so a person can watch what
an agent is doing from a phone. One port for the whole machine, and a path that
is four words and a short tail:
```bash
hhstream session stream enable chromium-k3f9d2
# http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/
```
That URL is the whole interface — a browser `<img>` is the entire client, over
MJPEG — and the phrase in it is its **only** protection. No TLS, no second
factor: anyone who can reach the port and guess four words can watch. It is
never written to the audit log, and `stream list` does not print it.
Four things worth knowing before switching one on:
- **It is per session and off by default.** A session does not stream because
it exists; it streams because somebody enabled it. What is published is that
session's own container output, never the main one — the main output carries
every other session, and putting it behind one session's phrase is the
mistake this refuses to make.
- **The phrase survives a restart.** It lives in the session's record, so
somebody you read it out to keeps the URL you gave them. `disable` then
`enable` rotates it.
- **Capture runs only while somebody is connected.** An enabled stream nobody
is watching costs no `grim` and no CPU.
- **Watching counts as activity.** This is the one exception to "`touch` is the
only mark of activity": about once a minute the broker notices a connected
viewer and resets that session's idle clock, so a long job you are watching
on a phone is not reaped at three hours. An enabled stream with nobody
watching keeps nothing alive.
```nix
services.hyprland-headless-stream.sessions.stream = {
enable = true; # runs hhstream-live; turns no stream on
# bind = "0.0.0.0"; # and openFirewall, to reach it from another device
# openFirewall = true;
};
```
Loopback by default, where the path to a phone is `ssh -L 9988:127.0.0.1:9988`.
`hhstream session start <app> --stream` starts an application and prints its
URL in one go, which is the usual way an agent sets one up.
## Driving it from an agent: the MCP server
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
@@ -45,14 +91,16 @@ application without writing command lines. The interface is frozen in
It is split the way the protocol splits things:
- **Resources are the state** — eight of them, read by URI, and reading one
- **Resources are the state** — ten of them, read by URI, and reading one
changes nothing. `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
an application's own output, `hhstream://pointer` is who holds the input
lease, `hhstream://screen` is a frame of the screen.
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
lease, `hhstream://screen` is a frame of the screen, `hhstream://streams` is
what is being published and who is watching.
- **Tools are the acts** — twenty-three, one per CLI verb that does something.
`session_start` puts an application on the screen, `pointer_acquire` takes the
input lease, `keyboard_type` types, `session_kill` ends a session.
input lease, `keyboard_type` types, `session_stream_enable` publishes the
screen for a person to watch, `session_kill` ends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why `shot` is still a tool
@@ -104,7 +152,7 @@ account in the group.
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
exit, which is the quickest way to check an install.
If twenty-one tools is more than a client has room for, `--toolsets` narrows
If twenty-three tools is more than a client has room for, `--toolsets` narrows
what is offered to whichever families are wanted — `frames`, `sessions`,
`pointer`, `keyboard`: