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

+27 -8
View File
@@ -26,9 +26,17 @@
│ hhstream-sessions.service │─────▶│ hhstream-pointer.service │
│ hhstreamd │ │ one Wayland connection │
│ registry, containers, │ JSON │ one virtual pointer │
│ the pointer lease │ over │ per output │
└────────────┬──────────────┘ a └──────────────────────────┘
│ private socket
│ the pointer lease, │ over │ per output │
│ the stream phrases │ a └──────────────────────────┘
└────────────┬────────┬─────┘ private socket
│ │ ┌──────────────────────────┐
│ └─────────────▶│ hhstream-live.service │
│ live.sock │ one port (9988) │
│ │ grim ─▶ MJPEG per │
│ │ phrase, while watched │
│ └───────────┬──────────────┘
│ │ HTTP
│ a browser ┘ /<phrase>/
│ AF_UNIX control.sock, mode 0660
▼
hhstream session ... (the CLI an agent drives)
@@ -37,12 +45,12 @@
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│
│ 23 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 10 resources (the state)│
└───────────────────────────┘
```
Five pieces, deliberately separate, and a sixth that is deliberately not a
Six pieces, deliberately separate, and a seventh that is deliberately not a
piece at all:
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
@@ -62,9 +70,20 @@ piece at all:
a separate process because a Wayland client needs its own connection and a
driver blocked on the compositor must not stall session lifecycle.
And the sixth, which is a *shim* and not a layer:
6. **The stream daemon** (`hhstream-live`) publishes one session's output as
MJPEG on one port, behind a four-word phrase, while somebody is connected.
A third executor on the pointer driver's pattern and for its reasons: `grim`
blocks tens to hundreds of milliseconds so it must not run where `touch` and
`kill` are answered, and a LAN-facing HTTP parser must not run in the frame
server whose one-socket contract cannot grow one. The broker owns the
*decision* (which session, under which phrase, in the record); the daemon
owns the port, the capture and the URL. It knows nothing about sessions or
idle clocks — it publishes what it is told to publish, and reports a viewer
count the broker chooses to read as activity.
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
And the seventh, which is a *shim* and not a layer:
7. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
Model Context Protocol surface on it, so an agent reads state by URI and
acts by calling tools instead of writing command lines. It is drawn above
the CLI rather than beside the broker because that is where it sits: every