Merge feat/mcp-server (9708154) into feat/mcp-auth

The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge.  Six files
conflicted; the interesting resolutions are the two that were not
textual.

**The contract is mcp-v3.1, not v2.1.**  This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive.  Both point releases, both correct, and they cannot both be
the same document.  So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.

**The counts are no longer literals.**  This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6.  Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`.  That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice.  A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.

The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.

One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.

Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-12 00:47:14 +00:00
commit f83717ba71
37 files changed
+4241 -101

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 │ stdio: spawned per client
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│ http: one unit, one port,
│ 23 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 10 resources (the state)│ http: one unit, one port,
└───────────────────────────┘ a bearer token per request
```
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
+66 -13
View File
@@ -1,4 +1,4 @@
# CONTRACT — the MCP server (mcp-v2.1)
# CONTRACT — the MCP server (mcp-v3.1)
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,13 +10,17 @@ 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.1 (2026-10-11). v1 was the first freeze and lasted one day;
v2 lasted about as long.
Version: mcp-v3.1 (2026-10-12). v1 was the first freeze and lasted one day; v2
split state out into resources; v3 added the live stream; v3.1 adds a second
transport. Only v2 ever broke anything.
**v2.1 is additive and breaks nothing.** No tool was renamed, no argument
changed shape, no resource moved. A client written against v2 over stdio is a
client that still works, which is why this is a point release and not v3 — v2
was a bump because it *removed* five tools.
**v3.1 is additive and breaks nothing.** No tool was renamed, no argument
changed shape, no resource moved. A client written against v3 over stdio is a
client that still works — which is why this is a point release, the same way v3
was additive over v2 and for the same reason. v2 is still the only major bump,
because it is the only one that *removed* anything.
v3.1 changes, all of them the HTTP transport and the credential it needs:
| § | Change | Why |
| --- | --- | --- |
@@ -25,6 +29,16 @@ was a bump because it *removed* five tools.
| §3 | A token may carry its own `toolsets`, and the **intersection** with the server's `--toolsets` applies. | `--toolsets` is a launch-time flag, and one HTTP process serves many callers: a per-process tool budget stops being a per-caller one the moment the transport is shared. |
| §10 | What the HTTP transport's token **is not**: not OAuth 2.1, not RFC 9728, no metadata discovery. | A limit worth stating in the same register as the two the SDK imposes. |
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.**
@@ -260,7 +274,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` |
@@ -294,13 +308,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.
@@ -310,6 +326,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
@@ -372,6 +403,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:
@@ -489,13 +527,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
@@ -516,6 +563,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 stdio server is spawned per client.
+162 -11
View File
@@ -1,4 +1,4 @@
# CONTRACT — sessions build (sessions-v3)
# CONTRACT — sessions build (sessions-v4)
This file is the interface for the **session** work: the broker, containers,
compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which
@@ -9,11 +9,31 @@ else. If something here is wrong or missing, **stop and report it in your final
message** — the parent edits this file, not you. Do not widen your slice to work
around a gap.
Version: sessions-v3 (2026-10-04). v1 was the freeze the four slices built
Version: sessions-v4 (2026-10-11). v1 was the freeze the four slices built
against; v2 recorded the decisions their reports asked for; v3 adds the
keyboard. Every change in both has been an addition or a clarification — **no
v1 or v2 signature changed meaning** — so earlier code stays valid except where
noted.
keyboard; v4 adds the **per-session live stream**. Every change in all of them
has been an addition or a clarification — **no v1, v2 or v3 signature changed
meaning** — so earlier code stays valid except where noted.
v4 changes, all of them the stream
(`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2):
| § | Change | Why |
| --- | --- | --- |
| §3.5 | New: `hhstreamd/live.py`, the broker's end of `/run/hhstream/live.sock`, and that socket's wire format. | The stream is captured by `hhstream-live`, a third executor beside the pointer driver. `grim` blocks tens to hundreds of milliseconds, so it must not run in the broker, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. The broker therefore *tells* a process what to publish, exactly as it tells the driver where to warp. |
| §4 | Verbs `stream.enable`, `stream.disable`, `stream.list`, `stream.status`. `enable` and `disable` are in the mutation set; `list` and `status` are not. | `enable` mints or rotates a phrase and opens a capture — a retried `enable` that minted a second phrase would invalidate the URL somebody is already holding. |
| §4 | `start` gains `stream?`, `stream_phrase?` and `stream_fps?`. | A stream needs the session's container output, which `start` creates; sequencing "start, then enable" in a *caller* means every caller repeats the ordering and the failure handling. One request, one answer, and the phrase comes back with the session. |
| §4 | **A connected viewer is activity.** The broker asks the daemon for viewer counts about once a minute and stamps `touch` when any is non-zero. | The one new way the idle clock moves, and the only exception to "`touch` is the only mark of activity" since that rule was written. A session an operator is watching on his phone must not be reaped at three hours *because* watching is all he is doing. An enabled stream with **no** viewer runs no `grim` and keeps nothing alive, so this cannot hold a session open by itself. |
| §4 | Error names `stream_unavailable` (exit 10), `stream_busy` (exit 8), `stream_budget` (exit 6). **No new exit numbers.** | The failures are the ones the table already has: no container is a compositor-side failure, a phrase collision is a busy, a viewer cap is a policy budget. |
| §5 | `/run/hhstream/live.sock`, the unit `hhstream-live`, and the stream port 9988. | Named here with the other frozen paths, because two processes have to agree on them. |
| §6 | Registry **schema 3 → 4**: the record gains `stream`. | A phrase has to survive a broker restart and a re-enable, so it lives in the record. Older records migrate to `stream: null` and are adopted, not refused. |
v4 deliberately does **not** give the broker the port, the bind address or the
capture command. Those are the daemon's, from its own unit's argv, for the
reason the keyboard layout is the driver's: the broker's TOML is read by
`hhstreamd`, and a setting an operator could change in it while the listener
stayed where it was would be worse than no setting at all. The broker learns
the URL prefix *from* the daemon, in the `attach` reply.
v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as
amended by `docs/plans/2026-10-04-keyboard-verification.md`):
@@ -375,6 +395,79 @@ the lease; a real-compositor case is still missing — see
lease state** — the broker owns the lease; the driver is an executor that must
never be trusted to serialise anything.
### 3.5 `hhstreamd/live.py` (v4) — the broker's end of the stream daemon
A third executor beside the pointer driver, and the same shape as §3.4: the
broker holds the *decision* (which session streams, under which phrase) and the
daemon holds the *capture*. `hhstream-live` owns the port, the bind address and
the capture command, from its own unit's argv; the broker never passes them and
never reads them from its own TOML.
```python
class LiveUnavailable(Exception):
"""The stream daemon could not be reached, or did not answer intelligibly."""
class LiveRejected(Exception):
"""The daemon refused. `kind` maps to an exit code, as the driver's does."""
def __init__(self, message: str, *, kind: str | None = None) -> None: ...
@dataclass(frozen=True)
class Attachment:
phrase: str; output: str; fps: int; session: str | None
url: str # the daemon's own prefix, e.g. http://127.0.0.1:9988/<phrase>/
viewers: int
class LiveStreams:
def __init__(self, socket_path: Path | str, *, timeout_s: float = 2.0) -> None: ...
def attach(self, *, phrase: str, output: str, fps: int,
session: str | None = None, label: str = "") -> Attachment: ...
def detach(self, phrase: str) -> bool: ... # False if it was not attached
def list(self) -> list[Attachment]: ...
def viewers(self) -> dict[str, int]: ... # phrase -> connected viewers
def close(self) -> None: ...
```
Private socket protocol, newline-delimited JSON, the driver's conventions
exactly — `{"ok": true, …}` or `{"ok": false, "error": "…", "kind": "…"}`:
```json
{"op": "attach", "phrase": "amber-otter-lantern-harbor-7k2qp", "output": "hh-x",
"session": "x", "label": "chromium", "fps": 5} // fps is OPTIONAL
-> {"ok": true, "stream": {"phrase": "…", "output": "hh-x",
"fps": 5, "session": "x", "url": "http://…/", "viewers": 0}}
{"op": "detach", "phrase": "…"} -> {"ok": true, "detached": true}
{"op": "list"} -> {"ok": true, "streams": [ {…}, … ]}
{"op": "viewers"} -> {"ok": true, "viewers": {"<phrase>": 2}}
```
Four rules that are not interchangeable:
- **The daemon holds no session state and no idea of an idle clock.** It
publishes what it was told to publish. `viewers` is a *reading*, and what the
broker does with it (§4) is the broker's.
- **`fps` is optional, and omitting it is the normal case.** The default rate is
the daemon's, from its own unit's argv (`sessions.stream.fps`), for the same
reason the port is. The broker sends one only when a caller named one, or
when re-attaching a stream that already had one. A broker that sent its own
default on every attach would make the operator's option a setting that
changed nothing — the same failure `--xkb-layout` (§3.4) exists to avoid.
- **`attach` is idempotent on the phrase.** Re-attaching the same phrase to the
same output returns the existing stream rather than starting a second
capture, because a re-`enable` after a broker restart must not double the
`grim` rate on one output. The same phrase aimed at a *different* output is
`{"kind": "invalid_argument"}`.
- **The phrase is never logged by either side.** It is the stream's only
credential. The daemon logs the output and the viewer count; the broker's
audit log records the session and the output (§4), and neither records the
phrase.
`url` comes back from the daemon rather than being built by the broker, for the
reason the port is the daemon's: a URL the broker assembled from a port it was
told about once is a URL that silently lies the first time an operator moves
the listener.
---
---
## 4. Wire format (broker control socket) — B, C and D do not implement this
@@ -395,6 +488,44 @@ code will be called with):
| `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` |
| `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` |
| `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` |
| `stream.enable` (v4) | `id`, `phrase?`, `fps?` | `stream` |
| `stream.disable` (v4) | `id` | `stream`, `detached` |
| `stream.list` (v4) | — | `streams[]`, `available` |
| `stream.status` (v4) | `id?` | `stream` \| `streams[]` |
**v4, the stream.** `stream.enable` and `stream.disable` are in the
`request_id` mutation set; `stream.list` and `stream.status` are not.
`start` additionally accepts `stream?` (bool), `stream_phrase?` and
`stream_fps?`, and when `stream` is true its reply's session carries the same
`stream` object `stream.enable` would have returned.
The `stream` object is the record's, with the daemon's `url` and `viewers`
merged in when it could be asked:
```json
{"enabled": true, "phrase": "amber-otter-lantern-harbor-7k2qp",
"output": "hh-x", "fps": 5, "port": 9988,
"url": "http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/",
"viewers": 0, "enabled_at": "2026-10-11T…Z", "attached": true}
```
`attached` is its own field and is **not** folded into `enabled`: a record may
say a session is enabled while the daemon is down, and "the operator asked for
this stream" and "a capture is running right now" are two different facts. A
caller that wants the second one reads `attached`; `url` and `viewers` are
absent when it is false, rather than stale.
**`stream.enable` requires the session's container output.** Without one it is
`stream_unavailable` (exit 10). A stream never falls back to the main output:
that output carries every other session, and putting it on a phone is the one
mistake this feature must not make. Re-enabling an enabled session returns the
same phrase; a `phrase` that differs from the stored one is `stream_busy`
(exit 8). `disable` then `enable` rotates it.
**Teardown order is load-bearing.** `kill` detaches the stream *before*
`hyprctl output remove`, because a capture aimed at a removed output fails every
time and the daemon's own failure budget would close the viewers with
"unknown output" instead of "the session ended".
**v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is
no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard
@@ -417,10 +548,26 @@ explicitly rather than inheriting.
| 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE |
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` **and
`keyboard.*`** verb do **not** reset the idle clock. A session being typed into
is still a session nobody has said they want kept.
**v4 adds error names and no numbers.** `stream_unavailable` → 10 (no
container, or the daemon is unreachable — the session itself is fine either
way), `stream_busy` → 8 (a `phrase` that is not this session's), `stream_budget`
→ 6 (the daemon's viewer or stream cap). A bad `fps` is `invalid_argument` → 2,
as every other bad argument is.
Activity accounting is load-bearing and has **one** exception as of v4:
**`touch` is the only mark of activity a caller can make**; `list`, `status`,
`logs`, `gc`, every `pointer.*` **and `keyboard.*`** verb, and every
`stream.*` verb do **not** reset the idle clock. A session being typed into is
still a session nobody has said they want kept.
The exception is **a connected viewer**. About once a minute the broker asks
the daemon for viewer counts and stamps `touch` on every session whose stream
has at least one; the audit entry names the session, the output and the count,
never the phrase. This is not a caller's verb and cannot be invoked — it is the
broker observing 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 on its own: an enabled stream with no viewer runs no `grim` and stamps
nothing.
The *lease* clock is a different one, and v3 widens it: every `pointer.*` and
`keyboard.*` gesture verb refreshes the lease's idle deadline, because they all
@@ -438,14 +585,18 @@ go through the same gate. `pointer acquire`'s own stderr says so.
| Frame socket (published) | `<runtime dir>/stream.sock` — default `/run/hypr-stream/stream.sock`. Also frozen in `docs/CONTRACT.md`, which v1 of this file left disagreeing with it. |
| Broker control socket | `/run/hhstream/control.sock` |
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
| Broker↔stream socket | `/run/hhstream/live.sock` (v4) |
| Stream port | **option default** `9988` (`sessions.stream.port`), fixed and single — no range, no fallback. The daemon owns it; the broker learns the URL from the daemon (§3.5). |
| Stream bind | **option default** `127.0.0.1` (`sessions.stream.bind`) |
| Broker state dir | **option default** `/var/lib/hhstream`; this machine sets `/var/lib/hermes/hhstream-sessions` (`sessions.stateDir`). v1 listed the deployed value, which read as a contradiction of the module. |
| Session runtime dir | `/run/hhstream/sessions/<session-id>` |
| Container output name | `hh-<session-id>` |
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
| Container mode | `1280x720` |
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer`, `hhstream-live` (v4) |
| Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. |
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer`, `hhstream-live` |
| Registry schema | **4** (v4; 3 → 4 adds `stream`, migrating to `null`) |
| Service account | `hermes`, supplementary group `hhstream` |
---
+3 -1
View File
@@ -14,9 +14,11 @@ Each file answers three questions and stops:
| [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | works live; unproven in a gate |
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | partly fixed: the module passes grim's store path and a check reads real frames; the app still never checks its capture binary |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
| [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md) | low | the phrase survives and the sweep works; `attached` reports false until re-enabled |
| [a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md) | low | the other direction: a capture that permanently gave up still reads `LIVE: YES` |
| [mcp-http-auth-is-not-oauth](mcp-http-auth-is-not-oauth.md) | medium | a static bearer token, not OAuth 2.1 + RFC 9728: the cost is which clients can connect, not how exposed the desktop is |
| [mcp-tokens-do-not-scope-resources](mcp-tokens-do-not-scope-resources.md) | medium | `token mint --toolsets frames` narrows the tools and not the eight resources; nothing until a second token is minted for someone else |
@@ -0,0 +1,58 @@
# A stream whose capture gave up still reports `attached: true`
## The issue
`hhstream_live.publisher` stops a stream after `FAILURE_LIMIT` (10) consecutive
capture failures, and the stop is sticky on purpose — the case it guards is an
output that was removed, and that does not come back. The stream object stays in
`StreamRegistry` with `stopped = True`; the HTTP handler returns as soon as it
notices, so viewers are dropped and new ones get a page that ends immediately.
Nothing on the broker side can see that. `Control._describe` returns
`spec.public()` plus `url` and `viewers` — not `stopped`, `captured`,
`failures` or `last_frame_age_s`, all of which `Stream.status()` already
computes. So `LiveStreams.list()` reports the phrase, `_attachments()` finds it
and `_stream_public` sets `attached = True`. `hhstream session stream status`
says `LIVE: YES` for a capture that has permanently given up.
MEASURED, in checks/vm-stream.nix, by the bug that check found: the
`hhstream-live` unit had the compositor's group but not its environment, so
every `grim` exited 1 with
error: XDG_RUNTIME_DIR is invalid or not set in the environment.
The unit was `active (running)`, the broker's record was intact, `stream status`
said `attached: true` with a URL, and the only place the truth appeared was a
single `WARNING` in the daemon's journal. The environment bug is fixed
(`execLive` in nix/module.nix); the reporting gap it exposed is not.
## Ideas
1. **Carry the publisher's health through `list`.** *(recommended)* Add
`stopped` and `last_frame_age_s` to `Control._describe` — both already exist
on `Stream.status()` — parse them in `hhstreamd.live.Attachment`, and have
`_stream_public` report `attached: false` (or a third state) when the daemon
says the capture is dead. The cost is one more field pair in
CONTRACT-sessions.md §3.5 and a `render_stream` line; the gain is that
`attached` means what it was added to mean.
2. **Drop a stopped stream from the registry.** Then `list` stops naming it and
`attached` goes false for free, with no new fields. Rejected as the first
move because it destroys the evidence: `failures` and the phrase are what an
operator needs in order to understand what happened, and a 404 on the URL
reads as "wrong phrase".
3. **Leave it.** What ships. `stream disable` then `stream enable` revives it
(a fresh `Stream`, same phrase, same URL), which is what an operator reaches
for anyway, and the daemon's journal does say what happened.
## Why it matters
Low severity because the capture only gives up for a reason that is itself a
failure — a removed output, a compositor that went away, a misconfigured unit —
and in two of those three the session is in trouble in ways `status` does show.
It matters because `attached` exists specifically to separate "the operator
asked for this" from "a capture is running right now" (CONTRACT-sessions.md
§3.5), and this is the second case where it answers the second question wrongly;
see [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md)
for the first. A field that is right only when nothing is wrong is not worth
reading.
@@ -27,6 +27,19 @@ worst way. The unit starts, the port opens, the landing page answers, and
`"failures": 10`. A viewer sees an empty frame area and nothing else says why.
Only the unit's log names the reason, one line above the giving-up entry.
**Half of this is now fixed.** The module passes grim's absolute store path
(idea 1), checks/vm-stream.nix starts the unit and reads real JPEGs off the
stream — the check this file asked for — and that check immediately found the
sibling fault: the unit had the compositor's *group* but not its *environment*,
so grim exited 1 with "XDG_RUNTIME_DIR is invalid or not set", ten times, with
the same silence. Fixed too (`execLive`). What is still open is idea 2: the app
resolves its capture command by name and never checks it, so a standalone
`hhstream-live serve` and any deployment shape that is not this module still
discover a missing or unusable capture binary ten failures later. The quiet
half — a stream that gave up while the broker still reports it attached — has
its own file now:
[a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md).
## Ideas
1. **An absolute binary, as the module already does elsewhere** *(recommended)*.
@@ -0,0 +1,66 @@
# A broker restart leaves an enabled stream recorded but not attached
## The issue
`docs/plans/2026-10-04-session-stream-webapp.md` §6 says what a restart should
do:
> If `hhstream-live` is still up, the broker asks it for the list and
> re-attaches them to the session records, so `status` and teardown still see
> them.
Stage 2 did not build that half. What happens today, measured in
`tests/sessions/unit/test_stream_verbs.py`
(`test_a_down_daemon_turns_attached_false_rather_than_failing_the_read`) and by
reading `SessionManager.startup`:
* the record keeps its phrase, so nothing is lost and a later `enable` restores
the *same* URL — which is the property §4 exists for, and it works;
* but `startup` does not call `LiveStreams.list()`, so the broker does not
learn about streams the daemon is still publishing;
* so `stream list` and `stream status` report `attached: false` for a stream
that is, in fact, up and serving. The viewer sweep then skips it, because it
only touches sessions whose phrase the daemon reports a viewer for — and it
asks `viewers`, which *would* name it. So the sweep actually still works;
what is wrong is the reporting.
The symptom is therefore narrow and confusing rather than broad: after
`systemctl restart hhstream-sessions`, somebody watching a stream keeps
watching it, the session keeps being touched, and `hhstream session stream
list` says `LIVE: NO`. An operator reading that would reasonably `enable`
again — which is harmless (`attach` is idempotent on the phrase) but should not
be necessary.
The other half of §6 *is* implemented: if the daemon restarted too, the records
keep their phrases and the streams stay off until re-enabled, because an open
port and a running capture are explicit acts.
## Ideas
1. **Ask the daemon in `startup` and merge.** *(recommended)* One
`LiveStreams.list()` where `reconcile_containers()` already runs, matching
attachments to records by phrase. Small and local: `_stream_public` already
merges an attachment into a record, so this is about *having* the
attachments at start-up rather than only at read time. The one thing to get
right is a phrase the daemon is publishing that no live record claims —
which is the stream equivalent of an orphan `hh-*` output, and should
probably be detached rather than adopted.
2. **Ask on every read instead.** `_attachments()` already does, which is why
the *reads* are nearly right. The reason it is not enough: there is no
record-side state to update, so a restart's first `stream list` is correct
and `attached` is still computed per call — this is really just (1) done
lazily, and it hides the orphan case entirely.
3. **Leave it.** What ships. The phrase survives, re-enabling is idempotent and
costs one record write, and the sweep keeps working. The cost is a status
field that lies after a restart.
## Why it matters
Low severity because nothing breaks and nothing is lost: the stream keeps
serving, the viewer keeps being counted, and the fix an operator will reach for
by instinct (`enable` again) is exactly the right one and is idempotent.
It matters at all because `attached` was added specifically so that "the
operator asked for this" and "a capture is running right now" could be told
apart — and after a restart it reports the second one wrongly, which is the one
job that field has.
+56 -9
View File
@@ -175,12 +175,54 @@ one at a time; no browser in a VM check.
3. **Port 9988**, fixed and single, no range fallback.
4. **Capture pauses at zero viewers** (v1's choice, kept).
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the
router, the pages, the phrase and the publisher, runnable standalone via
`hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and
`/run/hhstream/live.sock` are Stage 2.
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`): the router, the
pages, the phrase and the publisher, runnable standalone via `hhstream-live
serve --stream PHRASE=OUTPUT`.
**Stage 3 has started, out of order and on purpose** (2026-10-11). A machine
**Stage 2 is built** (2026-10-11), and §5's surface is what shipped:
`stream.enable|disable|list|status` on the control socket, `hhstream session
stream …` on the CLI, the record field at **registry schema 4**,
`/run/hhstream/live.sock` with `hhstreamd/live.py` on the broker's end and
`hhstream_live/control.py` on the daemon's, the teardown order, and the viewer
heartbeat. `docs/CONTRACT-sessions.md` went to **sessions-v4** for it.
Two decisions §5 left open, settled in the building:
1. **`start` takes `--stream`.** A stream needs the container output that
starting creates, so "start, then enable" made every caller repeat the
ordering and the half-done case in between. One call, and the URL comes
back with the session id. A stream that cannot be opened does **not** fail
the start — the application is on the screen, and `stream_error` says what
went wrong.
2. **The default rate is the daemon's, not the broker's.** §5 did not say who
owns it, and the first cut had the broker send its own default on every
attach — which would have made `sessions.stream.fps` a setting that changed
nothing, the exact failure `--xkb-layout` exists to avoid. `fps` is now
omitted from `attach` unless a caller named one.
What Stage 2 did **not** do: `stream.enable` carries no `--port`, and §6's
restart re-attachment is not implemented. A broker restart leaves the records'
phrases intact and their streams off until re-enabled, which is §6's own
fallback ("an open port and a running capture are explicit acts") — but it does
*not* ask a surviving daemon for its list and re-attach, so `attached` reads
false until somebody enables again. Recorded in `docs/TODO/`.
**Stage 3 is built** (2026-10-11), the unit included — `hhstream-live.service`
runs the app with `--control-socket`, the module's own capture command (`grim`
is not on a unit's PATH), and `sessions.stream.{enable,fps,port,bind,openFirewall}`.
What follows is why the firewall half landed first.
The unit has to be handed two things, and both were found by
`checks/vm-stream.nix` rather than reasoned about: the capture command with
grim's store path, because a unit's `PATH` has no `grim`; and the compositor's
session — `XDG_RUNTIME_DIR` plus the `wayland-N` the compositor actually bound,
discovered at start by `execLive`. Without the second the unit was
`active (running)`, the broker attached, `stream status` said `attached: true`,
and every capture exited 1 with "XDG_RUNTIME_DIR is invalid or not set" until
the publisher gave up. Both failures are silent in the same way, which is why
the check reads JPEG bytes instead of asserting a 200.
**Stage 3 started out of order and on purpose.** A machine
had to be able to *reach* a stream before the rest of the app is settled: the
operator asked for the port to be open on the deployment machine, where the app
runs by hand, and a hand-written firewall line in one machine's config is the
@@ -189,7 +231,12 @@ openFirewall }` and the single rule it stands for are in `nix/module.nix`, with
`checks/vm-stream-firewall.nix` asking the *running* firewall — and a peer
outside the guest — whether the configured port is the one that opened.
What that does **not** do: no unit, no phrases, no `session stream
enable|disable|list|status`, and nothing in the module turns a stream on. The
app is still started by hand, and the option's whole job is to describe where a
stream will be reachable from.
At the time that did **not** include a unit, phrases or the verbs; those are
above. What is still true of it is the last sentence: nothing in the module
turns a stream *on*. `sessions.stream.enable` runs a listener serving one form,
and a stream exists only for the sessions somebody enabled it on.
**Stage 4 — the host pass — has not been done.** Nothing here has had a real
browser pointed at it; `checks/vm-stream.nix` reads the MJPEG with a
hand-rolled client inside the guest, which proves the framing and the capture
but not that a phone paints it.