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
@@ -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`:
|
||||
|
||||
|
||||
Reference in new issue
Block a user