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
`tests/pointer/test_vendored_protocol.py` asserts the root pyproject
names `pywayland` and `xkbcommon`, with a comment saying why neither may
be optional. The MCP distribution had no equivalent, which left the
previous commit's argument resting on a comment.
So: `starlette` and `uvicorn` by name, and `anyio` beside them as the
precedent they follow. The point of the test is that leaving them out
would *work* -- the SDK propagates all three today -- which is exactly
what makes a tripwire worth having rather than redundant.
Skipped outside a checkout, the same way its sibling is: the build
sandbox copies only `tests/`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
`starlette` and `uvicorn` arrive through the MCP SDK today -- measured,
both of them -- and relying on that is exactly the trap this project
already wrote down twice. `src/hhstream_mcp/pyproject.toml` declares
`anyio` rather than taking it for granted through the SDK because
`server.py` uses it by name; `http.py` imports `uvicorn` by name and sits
on Starlette's `Request` through the SDK's `TransportSecuritySettings`,
so both belong in the metadata on the same argument. An SDK release that
moved its HTTP transport behind an optional extra would otherwise break
`serve --http` with an ImportError naming somebody else's package.
`nix/mcp.nix` carries them for the same reason.
The worse half was in the gate. `tests/unit/test_mcp_http.py` opened
with `pytest.importorskip("starlette.testclient")`, which is the pattern
`checks/unit.nix`'s own comment argues against in as many words: "a file
that skipped when the SDK was absent would be green in exactly the build
where that mattered". It would not skip today -- `mcp` propagates
starlette and httpx -- but the day it did, 43 tests would leave the gate
and nothing would say so, because pytest exits 0 when every test was
skipped.
So the import is unconditional now, `checks/unit.nix` declares `starlette`
and `httpx` explicitly, and the check proves them importable before
pytest runs, beside the lines that already do that for `hhstream` and the
tool table.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
Three layers, because the stream has three and each one can be wrong on its own.
`tests/live/test_live_control.py` (20 tests) runs `Control` against a fake
capture: the four ops, `attach` idempotent on the phrase, the same phrase aimed
at another output refused, a malformed phrase refused *without the value in the
message*, and `fps` defaulting to the daemon's when the broker sends none.
`tests/sessions/unit/test_stream_verbs.py` (24 tests) runs the broker against a
fake daemon, and its subjects are the decisions rather than the plumbing: no
container output is a refusal and never a fallback to the main output; a
re-`enable` returns the same phrase and a different one is exit 8; a down daemon
turns `attached` false rather than failing a read; the sweep touches a watched
session and leaves an unwatched one alone; teardown detaches before the
container is destroyed.
`tests/unit/test_mcp_*` grow the two tools, the two resources and the three
`session_start` arguments, with the read-only half asserted *absent* as a tool
by name -- re-adding one should be a failure, not a silent widening.
`checks/vm-stream.nix` is the new guest check, and it exists for the two things
none of the above can say:
1. **That `grim` captures a real compositor from inside a unit.** It reads
actual JPEGs off `/<phrase>/stream.mjpg` with `checks/lib/mjpeg_read.py`, a
hand-rolled multipart reader that shares no code with the server -- a parser
that did could not tell you the boundary was wrong. It framed on SOI/EOI
rather than `Content-Length` for the same reason. This is what caught the
unit's missing `XDG_RUNTIME_DIR`: `frames: [25827, 25827, 25827]` now, ten
capture failures and a stream that gave up before.
2. **That a connected viewer moves the idle clock.** That needs the broker's
real sweep, on a real timer, with a client genuinely still there a minute
later -- hence `--hold`, and hence a check that spends ~90 seconds twice. The
negative control runs first, because if the sweep touched an unwatched stream
the positive case would pass for the wrong reason. Measured in the guest:
with nobody watching `580s -> 502s` remaining, with a viewer `499s -> 596s`.
It also asserts the phrase is in neither the audit log nor a 404 body, that the
old URL stops serving after `disable`, that `disable` then `enable` rotates it,
that `kill` takes the stream down and leaves the daemon up, and that
`start --stream` yields an id and a URL that serves frames.
No clock is injected anywhere in this check. An injected one would prove the
arithmetic, which the unit tests already do, and not the daemon.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
`Starlette(routes=[Mount("/mcp", app=handle)])` serves `/mcp/` and
answers `/mcp` with a **307** -- or a 404 with `redirect_slashes` off.
Measured both ways. Every MCP client configuration spells the URL
without the trailing slash, and a redirected POST has to be re-sent with
its body: `urllib` will not do that at all, and some clients get it
wrong.
So the routing is three lines of its own (`http.Endpoint`) instead: both
spellings are the endpoint, neither is a redirect to the other, and
anything else is a 404. Starlette's router is gone from the request
path; the lifespan protocol is handled directly, which `manager.run()`
needs anyway because its task group must be exited by the task that
entered it.
This got through the unit suite once, and that is the more useful half of
this commit. `starlette.testclient` follows redirects by default, so
every assertion in `test_mcp_http.py` passed against a server a real
client could not talk to -- the 307 only surfaced in
`checks/vm-mcp-http.nix`, from a `urllib` client over a real socket.
`post()` now passes `follow_redirects=False`, and
`test_the_exact_path_does_not_redirect` asserts both spellings answer
200 directly. A test client that papers over a redirect is a test client
that cannot see one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
373 unit tests, up from 266. Three files, split the way the modules are:
`test_mcp_authorizations.py` is standard library and touches no SDK,
`test_mcp_http.py` drives a real ASGI stack, and the additions to
`test_mcp_server.py` are about the command line now that it has
subcommands.
Four of these exist for properties that a refactor breaks silently rather
than loudly, which is the only reason they are worth their length:
* **the file never holds a token.** A store that started writing the
secret instead of its digest would pass every functional test here, so
one test reads the bytes on disk and looks for the token and for a
usable prefix of it.
* **a concurrent mint is not lost.** Thirty threads mint into one table
and all thirty tokens must still verify. The atomic replace stops a
torn read; it does nothing about two writers loading the same table and
the second replacing the first's addition. Without the flock this
fails.
* **`--toolsets` before the subcommand survives it.** argparse copies a
subparser's namespace over the top-level one, so an ordinary default on
the subcommand's copy would overwrite the value with `None` and
`hhstream-mcp --toolsets=frames serve` would quietly serve all
twenty-one tools. `SUPPRESS` prevents it and this test notices if it
goes.
* **a token verb never claims the transport.** `mint` prints a secret on
stdout, which on stdio *is* the transport, so `claim_transport` is
monkeypatched to fail the test if it is ever reached.
The refusal tests assert the absence of information as much as the status
code: an empty body, no echo of the token in body or headers, and
unknown/revoked/expired arriving as one answer byte for byte -- telling
them apart would tell someone who guessed a real id that they had. An
unknown path is a 401 before a 404, so an unauthenticated caller does not
learn what is mounted; the token is checked before the Host, so it does
not learn the allowlist either.
`test_resources_are_not_narrowed_by_a_token` asserts a *limit*, on
purpose: a token scoped to `frames` can still read `hhstream://sessions`,
and that is written down rather than left for someone to discover.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
46 more unit tests, and `vm-mcp` rewritten around the new split (21 subtests,
up from 14).
`test_mcp_resources.py` is the new file and its subject is what the resource
layer actually decides: which entry a URI resolves to, which query parameters
it will accept, and the argv each read builds. The cases that matter are the
ones a reshuffle would quietly break -- a literal route beating a template
(`hhstream://sessions` is the listing, not a session with a blank id), a
switch parameter becoming a bare flag or nothing at all (`--all=false` is not
something the CLI takes), an undeclared parameter being refused rather than
dropped, a frame's media type being sniffed rather than assumed, and a refusal
being *raised* instead of returned as the body.
One test exists only to stop a future kindness: there must be no resource for
the reconciling container read, because that one writes.
`test_mcp_server.py` grows the protocol-level half -- both listings, a read
that returns JSON, a read that returns a blob, a refused read arriving as
`McpError`, and a toolset selection that narrows the tools while leaving the
resources alone. The tool and toolset tests move with the surface: the
read-only verbs are asserted *absent* by name rather than merely missing, so
re-adding one is a failure instead of a silent widening of what mcp-v2
narrowed.
In the guest, the subtest the whole surface turns on is now measured rather
than described: two reads of `hhstream://sessions/<id>` must NOT move the idle
deadline, and `session_touch` must. It also asks for the same container two
ways and checks the answers agree, reads one output's frame as a blob and
confirms the `shot` tool reports the same geometry, and proves `--toolsets`
makes an omitted tool unreachable and not merely unlisted.
`checks/lib/mcp_client.py` gains `--resources`, `--read` and `--server-arg`,
and exits 3 rather than 2 on a protocol error -- so "the server refused this
read" stays distinguishable from "the server did not answer at all", which is
the distinction that keeps the refusal subtests from passing for the wrong
reason.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
101 unit tests under `tests/unit/` and one new VM check.
The unit suite's subject is the only thing this layer decides: the argv list.
`mcp_fake.FakeCli` is a recording stand-in put where the CLI goes, so every
test can assert on the exact argv a tool handed over -- the `=` form of each
flag, the `--` before each positional, the omission of a flag the caller did
not give. Three tests drive the **real** entry point against a control socket
that does not exist, which proves the dispatch, the capture and the exit-code
mapping against the CLI's actual parser with no daemon standing up: argparse's
exit 2 for a bad `--button`, exit 5 for the unreachable broker, exit 9 for a
gesture with no lease.
`test_mcp_server.py` imports the MCP SDK unconditionally and runs the server
in process over the SDK's memory transport. It is not allowed to skip: the tool
table is stdlib and tested without the SDK, but whether every schema validates
and every name is one the specification allows is a question only the SDK can
answer, and a file that skipped when it was absent would be green in exactly
the build where that mattered. `checks/unit.nix` therefore puts `mcp` in the
test environment and `hhstream-mcp` on PYTHONPATH beside `hhstream`.
`checks/vm-mcp.nix` boots the session machine with `mcp.enable = true` and
drives the real binary over a real pipe with `checks/lib/mcp_client.py` -- raw
JSON-RPC, deliberately not the SDK's client, for the reason
`tests/assert_stream.py` is a second implementation of the frame contract. It
asserts the handshake, the 26-tool listing with its annotations and its two
rules, a call that reaches the live broker, `shot` as image content, the lease
granted/used/returned against the real driver, and exits 9 and 3 arriving as
tool errors.
The geometry assertion in that check is one it got wrong first time and now
records: the published frame is 2560x720 on a guest configured for 1280x720,
because the publisher's default capture takes the whole compositor layout and a
session's container is a second output beside the main one. `shot` with the
container's own `output` is the one that is exactly 1280x720.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
grim's `-c` ("include cursors in the screenshot") exists because the screencopy
protocol takes the decision from the client: Hyprland's capture_output carries
an overlayCursor argument and the frame is only composited with the cursor when
it is set. Without it a frame shows that *something* changed and never where it
was clicked -- and a click on the wrong element looks exactly like a click on
the right one, which is the whole reason the pointer work is verifiable at all.
Found by reading Hyprland's Screencopy.cpp rather than guessing at a compositor
setting: `no_hardware_cursors` was already on, and the cursor was invisible
because nobody had asked for it.
Slice A renamed the runtime directory in the module, but the old path was still
live in the code and checks it does not own, so the VM gates pointed at a
directory the module no longer creates. This moves the 21 remaining live
occurrences (client/server defaults, the unit tests that pin them, all three VM
checks, the diagnostics script, both READMEs) and deliberately leaves the three
mentions that are history rather than configuration: the plan's problem
statement, module.nix's note about the previous name, and cli.py's explanation
for spelling its default out.
Also here: docs/CONTRACT-sessions.md is now v2 with every gap the four slices
reported resolved as a decision (Monitor.id, stable_id, pid -1, Event.data,
mark(), the quarantine argv type, the corrected wlr XML path, and the state
dir/frame socket rows), and docs/CONTRACT.md is v2 because its documented socket
default moved -- wire format unchanged.
Two comments that stated the old, wrong diagnosis (a 'misnamed' IPC socket) now
state the measured one: the event socket did not fit in sun_path.
Fill in the bodies the skeleton left as NotImplementedError, to docs/CONTRACT.md:
- protocol: the `\n`-terminated JSON Hello and the `<ascii length>\n<payload>`
frame, both directions. Malformed input raises (ValueError for a bad length
prefix, EOFError for a truncated payload), never hangs on endless garbage and
never silently truncates; a huge length prefix is not pre-allocated.
- capture: CommandCapture runs the configured command and reports a missing
binary, a non-zero exit, a timeout and empty output as CaptureError, with the
helper's stderr folded into the message so nothing leaks to the server's own
stdio. The Hello's pixel size is read from the frame's PNG/JPEG header, so no
compositor query is needed and an injected fake command behaves the same.
- server: one capture thread holding only the newest frame plus one thread per
client, which is what drops frames for a slow client instead of queueing
them. Survives a client dying mid-write, keeps the socket up across capture
failures, withholds the Hello until a size is known, replaces a stale socket
file (but never a non-socket one) and publishes it mode 0660.
- client: fetch()/read_stream() and the CLI, with --out suffixing per frame.
--capture-command folds its separated form into `--flag=value` before argparse
sees it, so the contract's default `grim -t png -` can actually be passed: its
tokens start with a dash.
Unit tests under tests/unit cover framing round-trips (including a payload
containing `\n` and a zero-length frame), truncated and garbage prefixes, a
stalled client not blocking a second one, a client dying mid-frame, frames being
dropped rather than queued, and every capture failure mode. A fake capture
command stands in for grim, so nothing needs a compositor or a GPU. They are
deliberately not wired into flake.nix: `checks` belongs to another workstream.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FYJ8ZQ5AZaDErYTwXZe7N9
Wires a `checks` output into the flake, one file per check under checks/,
all three asserting docs/CONTRACT.md rather than the implementation:
- unit: pytest over tests/unit/ in the build sandbox, against the
nix/package.nix build. Refuses an empty suite -- pytest exits 0 when
every test was skipped or deselected, so checks/lib/check_report.py
parses the JUnit report and fails on zero collected or zero executed.
- vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py,
which emits one fixed deterministic PNG. Because the image never changes,
"two frames arrived and they are the same bytes" is an assertion about
the framing rather than a coincidence.
- vm-hyprland: the same machine with no captureCommand override, so grim
captures the real compositor. Deliberately impatient -- bounded timeouts,
no retry loops, and a full diagnostics dump (compositor log, hyprctl
monitors, both journals) before any failure propagates.
tests/assert_stream.py is a second, independent reader of the contract: it
shares no code with hhstream.client, so a framing bug present in both the
server's writer and the shipped client's reader still fails. The unit
suite's negative tests use a `rejects` fixture instead of
pytest.raises(Exception), which an unimplemented stub's
NotImplementedError would otherwise satisfy.
Three defects found in code this branch does not own, recorded in
README.dev.md rather than worked around:
- nix/module.nix has no config side, so neither unit exists and both VM
checks fail at their first wait;
- services.hyprland-headless-stream.package is declared with no default,
against docs/CONTRACT.md;
- src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz