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:
commit
f83717ba71
37 files changed
+4241
-101
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 │ 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
@@ -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
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user