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:
1 parent
9d33639c04
commit
887ed17be2
9 files changed
+341
-33
No files matched your search
+27
-8
@@ -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
|
||||
|
||||
Reference in new issue
Block a user