102 Commits
Author SHA1 Message Date
ari 965485d8e5 Merge pull request 'feat(mcp): an HTTP transport, and the bearer token it exists for' (#5) from feat/mcp-auth into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/5
2026-10-13 19:50:39 +00:00
HermenixandClaude Opus 5 94a1f5988e test(mcp): the http transport, its unit and its token, in a guest
`checks.vm-mcp-http` -- the sibling of `vm-mcp`, on the same session
machine.  That one proves the *surface* over a pipe; this one proves the
two things stdio does not have: a unit systemd supervises, and a
credential on the way in.  So there is one tool call and one resource
read here, just enough to show a request reached the broker through an
authenticated session, and the weight is on the refusals, the state
directory's permissions, and the unit's lifecycle.

**The first subtest is the one that justifies the file.** The server
exits 2 while the authorization table is empty, which leaves a freshly
provisioned machine in a failed state on purpose -- and that trade is
only sound because the unit retries, so the first `token mint` brings it
up with no `systemctl start`. That self-heal lives in
`StartLimitIntervalSec = 0` and nothing in Python can test it. If it
regresses, every machine that enables the option comes up dead and stays
dead, and this is the only thing that would notice.

Also asserted, and each for a reason rather than for coverage: the state
directory is 0700 and owned by the account that mints tokens (which is
also the proof an operator *can* mint one on a machine configured this
way); the table is 0600 and does not contain the token; the port is on
loopback and **not** in the firewall, because neither default may become
implied; the refusals are 401 with an empty body and no echo; two tokens
served by one process see different tool budgets, which is the whole
argument for putting toolsets on a token; a revocation takes effect on
the next request with no restart, because an operator who must restart a
service to lock someone out does not have revocation; and revoking
*every* token does not stop the process, since the startup refusal exists
to catch a forgotten mint rather than to police a deliberate one.

`lib/mcp_http_client.py` is raw JSON-RPC over `urllib` and deliberately
not the SDK's client, for the reason `lib/mcp_client.py` is not either --
the SDK on both ends would agree with itself about a framing and a header
neither side had to get right, and the header is half of what this file
is about. It earned that choice immediately: it is what caught the 307 on
the exact path that the SDK-shaped test client had been following
silently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 18:13:52 +00:00
HermenixandClaude Opus 5 10176356b6 docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 18:00:05 +00:00
HermenixandClaude Opus 5 7eb9afdfa3 test(mcp): the store, the token verbs, and every way a request is refused
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
2026-10-12 18:00:05 +00:00
HermenixandClaude Opus 5 4b3fccbbf5 feat(nix): mcp.http, its unit, and a state directory of its own
`mcp.http.enable` is the fourth unit and the first that listens on a
port.  The comment on the `mcp` block said anything that started a daemon
here "would be inventing a second thing to supervise", so it is rewritten
rather than deleted: what changed is not the cost of supervising it but
what it buys -- a port is reachable by a caller who never touched this
filesystem, which is the first time a token on this surface means
anything.  The two options stay independent and neither implies the
other.

`mcp.stateDir` defaults to /var/lib/hhstream-mcp and is deliberately NOT
`sessions.stateDir`.  That directory is 0700 owned by the broker's user
and holds `events.jsonl`; parking a token file in it would grant this
shim write access to the audit trail's directory for no reason, and the
two have different lifetimes besides.  A tmpfiles entry rather than
`StateDirectory=`, for the reason the broker's state dir is one --
`StateDirectory=` can only name a path under /var/lib and would stop
applying the moment the option is pointed elsewhere.

The unit runs as sessions.user with sessions.group, because its tools are
the CLI's handlers called in process and that CLI opens a 0660 control
socket owned by that user and a compositor runtime directory owned by
that group.  `Wants`/`After` the broker and not `BindsTo`: the frame
verbs answer with the broker down and the rest answer exit 5, which is a
true answer, whereas a listener that vanished with the broker would turn
that into a connection refused and tell a client nothing.  The systemd
default KillMode is right here and `KillMode=process` -- which the broker
and the driver both need -- would be wrong, because every process this
unit starts is part of answering one request.

Two assertions and two warnings, each for a failure that is otherwise
discovered from the far side of an HTTP client:

* http.enable without sessions.enable is an assertion, not the warning
  `mcp.enable` gets against the same condition, because there the frame
  tools still work and here `User=` names an account that does not exist.
* a wildcard bind with no allowedHosts is an assertion, because the
  SDK's rebinding allowlist has no implicit localhost and the unit would
  come up refusing everything with a 421.
* a non-loopback address warns that the token crosses the wire in clear
  text, since the option reads like a bind address and not like a
  decision about what is on it.
* openFirewall warns and is not implied by http.enable, the same way
  sessions.stream.openFirewall is not implied by the stream.

`mcp.http.enable` also puts the binary on PATH, because `token mint` is
how the credential that unit demands gets issued.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 17:54:09 +00:00
HermenixandClaude Opus 5 f4485f7a63 feat(mcp)!: a second transport, and the token it exists for
`hhstream-mcp serve --http` serves the surface over Streamable HTTP behind
a bearer token, and `hhstream-mcp token mint|list|revoke|prune` issues
those tokens.  stdio stays the default and stays unauthenticated.

The two are one feature, because neither works alone.  A token checked by
a process the caller spawned is a lock whose key is in the same pocket:
over stdio the client starts the server and already holds the broker's
0660 control socket, which is why `mcp.enable`'s own option text says it
"grants no access the `hhstream` CLI does not already grant".  A port is
the first time the caller is someone who passed no filesystem check on
the way in, and that is the moment a credential starts meaning something.
So the transport arrives with the credential, and the contract's "stdio,
and only stdio" is rewritten rather than quietly broken.

The store (`authorizations.py`) keeps SHA-256 digests, not tokens:
nothing ever needs the secret back, so `authorizations.json` is not
itself a credential.  No salt and no KDF -- a token is 256 bits of
`secrets`, so there is no dictionary to attack and a work factor would
only slow the request path.  Expiry is wall clock, the one place in this
project where that is right: every broker deadline is CLOCK_BOOTTIME so
an idle window survives an NTP step, but "valid for thirty days" is a
calendar statement that has to outlive a reboot.  Every read-modify-write
takes a flock, because two processes write this file -- the server
stamping `last_used` and an operator running `token mint` -- and the
atomic replace alone prevents a torn read, not a lost update.

`--toolsets` on a token, not just at launch, because the flag is
per-process and one HTTP server has many callers: a per-process tool
budget stops being a per-caller one the moment the transport is shared.
The intersection applies, so a token cannot widen what the unit was
started with.  `server.build` takes a chooser instead of a fixed list to
make that possible; the stdio path passes none and closes over its
selection exactly as before.

Three things in the request path are deliberate.  `default_allowed_hosts`
exists because the SDK's DNS-rebinding check is allowlist-only with no
implicit localhost -- protection on with an empty list 421s *every*
request -- so the allowlist is derived from the bind address rather than
the protection being switched off to get a working default; a wildcard
bind derives nothing and is refused, which makes binding every interface
the case where the hostnames must be said out loud.  The grant travels in
the ASGI scope and not a contextvar, because in stateful mode the session
manager runs the handler in a task owned by its own lifespan and a
contextvar set in middleware would not be visible there.  And a refusal
is a 401 with an empty body that never echoes the token and never says
which of unknown, revoked or expired it was -- the discipline
`hhstream_live.server` already applies to a wrong phrase, with that app's
own RateLimiter reused rather than a second one grown.

This is NOT MCP's authorization specification, which is OAuth 2.1 plus
RFC 9728 metadata discovery.  A client that can only discover an
authorization server will not connect; one that lets you set a header
will.  Documented as a limit rather than hidden, beside the two the SDK
already imposes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 17:53:31 +00:00
ari d26b79c35f Merge pull request 'An MCP server for hhstream, and the per-session live stream behind it' (#3) from feat/mcp-server into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/3
2026-10-12 17:49:35 +00:00
HermenixandClaude Opus 5 9708154eea test(mcp): count the unnarrowed resources against the listing, not a literal
`--toolsets` has to leave the resources alone, and the subtest that says so
asserted `5` and `3` -- so the stream's two resources turned a correct server
into a red check, which is the second literal in this file the surface outgrew
in one day.

Counted against `uris` and `templates` from the listing subtest instead. That
is the comparison the assertion was always about: not "six", but "as many as
this server lists when nothing is narrowed".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 23:08:13 +00:00
HermenixandClaude Opus 5 a61558a0ad docs: the two counts that are prose rather than assertions
`tools.py`'s module docstring and the module's `mcp.enable` warning both state
the size of the surface in words, so neither moved when the stream added to it.
Twenty-three tools, and twenty of them plus seven of the ten resources need the
broker -- counted rather than carried over: the three that do not are `shot`,
`record` and `run`, and `hhstream://status`, `hhstream://screen` and
`hhstream://outputs/{name}` beside them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:59:45 +00:00
HermenixandClaude Opus 5 0c06de4ea7 test(mcp): the stream through the MCP layer, in the guest
`vm-mcp` asserted 21 tools and the eight resource URIs by name, which the stream
made stale -- and by name is the point, so the lists move with the surface: 23
tools, `hhstream://streams` among the fixed resources,
`hhstream://sessions/{id}/stream` among the templates.

Its machine now enables `sessions.stream`, because two of those tools and two of
those resources are about streams and with no daemon they could only be shown to
*refuse*.

Two subtests, and the first is the one worth having: a session started over MCP
with `stream: true` has to hand back the URL in `structuredContent`, in the text
a model actually reads, and again from `hhstream://sessions/{id}/stream` -- three
places that must agree, because the URL is the daemon's to name, is never stored,
and a reply assembled from the broker's record alone carries a phrase and no URL.
That is exactly how it went wrong once. The second takes the stream away over
MCP and reads both resources again.

What this does not do is read a frame: bytes off the port are `vm-stream`'s
subject. What it owns is that the phrase reaches an agent at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:56:57 +00:00
HermenixandClaude Opus 5 887ed17be2 docs(stream): mcp-v3, the seventh box, and two TODOs the check wrote
`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two
resources, three `session_start` arguments, and the one rule that is not a name
at all -- a connected viewer is the single exception to the idle-clock rule, and
it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is
additive; every v2 name still means what it meant.

README.md leads the stream with the shape of it rather than the options: one
port for the machine, a phrase per session, a browser `<img>` as the entire
client, and the four things worth knowing before switching one on -- that it is
per session and off by default, that the phrase survives a restart, that capture
runs only while somebody is connected, and that watching counts as activity.
The phrase is called what it is: the only protection, with no TLS and no second
factor.

ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`,
hanging off the broker by `live.sock` with one port and a browser at the end of
it -- and the counts move to 23 and 10.

Two TODOs, both written by `checks/vm-stream.nix`:

* `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a
  stream after ten consecutive capture failures and the stop is sticky on
  purpose, but `Control._describe` does not pass `stopped` on, so
  `_stream_public` reports `attached: true` for a capture that has permanently
  given up. That is the second place `attached` answers "is a capture running
  right now" wrongly, and a field that is right only when nothing is wrong is
  not worth reading.
* `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The
  module passes grim's store path and this check reads real frames -- which
  immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`.
  What is still open is the other half: the app resolves its capture command by
  name and never checks it, so any deployment that is not this module still
  discovers a broken capture ten failures later.

The plan's status section records Stage 2 and Stage 3 as built, the two
decisions §5 left open (that `start` takes `--stream`, and that the default rate
is the daemon's), and what Stage 2 deliberately did not do -- §6's restart
re-attachment, which has its own TODO.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:54:26 +00:00
HermenixandClaude Opus 5 9d33639c04 fix(sessions): start --stream answers with the daemon's stream, not the record's
`start`'s reply was `Session.public()`, which reports what was *stored* -- and a
`url` is never stored, because naming one is the daemon's (CONTRACT-sessions.md
§3.5) and a URL on disk is a URL that lies the first time the listener moves.

So a successful `start --stream` handed back a stream with a phrase and no URL,
which no caller could tell from a stream that failed to open: the CLI printed

    WARNING: the session is running but its stream was not enabled: the
    broker reported no stream

over a stream the daemon had attached a second earlier, and the MCP tool's
summary said `stream: NOT enabled` for the same reason. `stream enable` was
always right, because it answers with `_stream_public` -- only the one-call path
was wrong.

Found by checks/vm-stream.nix's last subtest, which is the only place
`start --stream` runs against a real daemon. The unit test added beside it pins
the seam rather than the symptom: the reply carries a `url`, the record does
not, so anything answering from the record alone has to merge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:53:50 +00:00
HermenixandClaude Opus 5 b4abd085cc test(stream): both ends of live.sock, the broker's verbs, and a real viewer in a guest
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
2026-10-11 22:49:18 +00:00
HermenixandClaude Opus 5 5f5726c02e feat(mcp): the stream, as two tools and two resources
The split mcp-v2 froze, applied to the stream: switching one on is an act, so
it is a tool; what is being published is state, so it is a resource. 23 tools
and 10 resources.

Tools: `session_stream_enable` (returns the URL, takes an optional `phrase` and
`fps`), `session_stream_disable`, and `session_start` gains `stream`,
`stream_phrase` and `stream_fps` -- the last because a stream needs the
container output that starting creates, so one call is the shape an agent
actually wants.

Resources: `hhstream://streams` (every stream, with `available` so "no streams"
is not confused with "no daemon") and `hhstream://sessions/{id}/stream`.

What the descriptions carry is the part that matters here, because an agent
reads them and nothing else:

* **CREDENTIAL.** The phrase in the URL is the stream's only protection. The
  resource descriptions say outright not to put the URL where a session's own
  screen can see it -- an agent that pastes it into the browser it is driving
  has published the desktop.
* **ACTIVITY.** The stream tools do *not* reset the idle clock, but a connected
  viewer does, which is the first exception to that rule this surface has had
  to state. `session_touch` is still the only thing an agent can do about it.
* `session_start`'s summary prints `stream url:` beside the id, and a stream
  that could not be opened is reported loudly as `stream: NOT enabled -- …`,
  because the call succeeded and an agent must not read that as a stream.

`nix/mcp.nix` counts the new surface in `entryPointCheckPhase` (23 and 10),
which is the only place those numbers are asserted against the *wrapped* binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:45 +00:00
HermenixandClaude Opus 5 ca5dbfb2ea feat(nix): the hhstream-live unit, and the two things it has to be handed
`services.hyprland-headless-stream.sessions.stream.enable` (default **false**)
runs `hhstream-live` and hands the broker `/run/hhstream/live.sock`. Running it
still turns nothing on: a stream exists only for the sessions
`hhstream session stream enable` was run on, which is the plan's rule that a
stream is never on for all sessions at all times.

A fourth unit rather than a flag on an existing one, for the pointer driver's
reason: `grim` blocks tens to hundreds of milliseconds, so the capture 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.

Two things the unit must be handed, both of them MEASURED failures rather than
precautions:

1. **The capture command, spelled out, with grim's store path.** A unit's
   `PATH` has no `grim`
   (`docs/TODO/capture-binary-and-the-unit-path.md`), and the symptom is a
   stream that answers with an empty frame area and says why only in the
   daemon's journal. Every word is passed as `--capture-command=<word>` and not
   `--capture-command <word>`, because grim's last word is a bare `-` and
   argparse reads a lone dash as an option prefix rather than a value -- a unit
   crash-looping with "expected one argument", which is how that form was
   chosen.
2. **The compositor's session.** `XDG_RUNTIME_DIR` on the unit plus `execLive`,
   which discovers whichever `wayland-N` the compositor actually bound and
   exports it -- `execServer`'s trick, for `execServer`'s reason: the name is
   only known once the compositor is up, so it cannot be an `Environment=`
   line. Without it 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 in the environment" until the
   publisher gave up after ten in a row. checks/vm-stream.nix found that on its
   first real run, which is the whole reason that check reads bytes instead of
   asserting a 200.

`SupplementaryGroups` gets the compositor's group for the pointer driver's
reason one step further -- this one has to *capture*, not merely find the
socket -- and there is deliberately no `RuntimeDirectory=`: a second one on
/run/hhstream would delete the broker's control socket when this unit stopped,
which the plan names as the Stage 3 risk.

`sessions.stream.fps` is the daemon's own default and nothing else sends one, so
the option changes what actually happens; the port and bind address are the
daemon's too, and the broker learns the URL from it.

`nix/package.nix` names `hhstream_live.control` and `hhstreamd.live` in
`pythonImportsCheck`: they are the one pair in this package that has to agree
with each other across two processes, so an import error in either is worth
finding at build time rather than the first time an operator enables a stream.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:22 +00:00
HermenixandClaude Opus 5 850f9caa1d feat(cli): session stream and start --stream
The operator's side of the four verbs: `hhstream session stream
enable|disable|list|status`, and `start --stream [--stream-phrase]
[--stream-fps]` for the one-call case.

`stream enable` prints the URL on **stdout and nothing else**, with the detail
on stderr, so `url=$(hhstream session stream enable ID)` works -- the same shape
`start` already has for the session id. `start --stream` prints the id and then
the URL, two lines, because a caller who asked for both should not have to run
a second verb for the second one.

The phrase is a credential, and the two renderers disagree on purpose:

* `render_streams` (`stream list`) does **not** show it. A listing is what ends
  up in a shared terminal, a paste or a screenshot, so what it shows is enough
  to recognise and manage a stream -- session, output, rate, viewers, `LIVE` --
  and not enough to watch one. It also prints the daemon's reachability, because
  "two records and no daemon" is a different situation from "two records and two
  captures" and the rows alone cannot say which.
* `render_stream` (`stream status ID`) does show the URL. That question was
  asked about one session by name, which is what somebody about to watch it
  does, and making them reach for `--json` for the thing the verb is for would
  be the worse trade.

When the daemon is not publishing, `status` says so and prints no URL -- the
phrase is kept, so re-enabling restores the same one.

`start --stream` that starts the session but cannot open the stream exits 0 and
says `WARNING: the session is running but its stream was not enabled: …` on
stderr. Loudly, because the exit code is the session's and a caller who asked
for a stream must not read a 0 as one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:00 +00:00
HermenixandClaude Opus 5 7d8ca6191b feat(sessions)!: the four stream verbs, schema 4, and the viewer sweep
The broker half of sessions-v4: `stream.enable`, `stream.disable`,
`stream.list`, `stream.status`, `start`'s three new arguments, and the one rule
that is genuinely new rather than additive -- a connected viewer is activity.

The decisions worth reading the diff for:

**A stream never falls back to the main output.** `_stream_output` refuses when
a session has no container, and the refusal is stronger than the pointer's for a
reason the hint states: the main output carries *every other session*, so a
fallback would put somebody else's desktop on a phone behind a phrase that was
issued for this one.

**The phrase lives in the record, so re-enabling returns the same URL.** A
different `--phrase` on an already-enabled session is `stream_busy` (exit 8),
not a silent rotation: rotating under a caller who is holding the old URL is the
one outcome neither answer can be mistaken for. `disable` then `enable` is how
it rotates, which is explicit.

**`_checked_phrase` raises the shape and never the value**, with `from None`, for
`control._phrase_of`'s reason: `phrase.validate` names what it rejected, and
this value is a password on its way into an error reply and a log.

**`fps` is only sent when a caller named one** (`_checked_fps` returns `None`
otherwise), which is what makes the daemon's own default authoritative instead
of decorative. The broker holds the daemon to the frozen cap before sending, so
a nonsense rate is exit 2 from the verb rather than a surprise from the socket.

**`attached` is its own field and is not folded into `enabled`.** A record can
say the operator asked for a stream while the daemon is down, and those are two
different facts; `url` and `viewers` are *absent* rather than stale when it is
false, because a URL that no longer serves anything is worse than no URL.
`stream.list` also reports `available`, so "no streams" is distinguishable from
"no daemon" without parsing an error.

**The viewer sweep** (`_sweep_streams`, every `STREAM_SWEEP_S = 60`s) asks the
daemon for viewer counts and stamps `touch` on every session somebody is
watching. It is the only thing in this daemon that treats an observation as an
intention, and it exists for one failure: an operator watching a long job on his
phone and losing the session at three hours *because* watching was all he was
doing. It cannot hold a session open by itself -- an enabled stream with no
viewer runs no `grim` and stamps nothing -- which is why it is safe to run
unconditionally.

**Teardown detaches before it destroys the container.** The other order makes
every capture fail against a removed output, which is a stream that gives up
ten frames later and a log that blames `grim`.

`start` takes `stream`, `stream_phrase` and `stream_fps` and reports a stream it
could not open in `stream_error` beside a session that *did* start, because the
exit code is 0 and a caller who asked for a stream must not read that as one.

Registry schema 3 -> 4: the record gains `stream`, older records migrate to
`null` rather than being refused, and the viewer count is deliberately not
stored -- a viewer count on disk is a number that is wrong the moment it is
written.

No new exit numbers: `stream_busy` -> 8, `stream_budget` -> 6,
`stream_unavailable` -> 10. The last one is 10 for `driver_refused`'s reason --
the session keeps running, and a caller that read an unreachable stream as a
dead session would kill an application over a web page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:47:43 +00:00
HermenixandClaude Opus 5 8c99518a62 feat(live): live.sock, both ends
The socket CONTRACT-sessions.md §3.5 freezes, implemented on both sides and by
nobody else: `hhstream_live.control` answers it, `hhstreamd.live` asks it.

`control.Control` is the four ops and nothing more -- attach, detach, list,
viewers -- with the decisions the daemon is allowed to make and no others. It
owns the two things only this process knows: how to build a capture for an
output (the capture command, from this unit's argv) and what a URL looks like
(the bound port). Both are injected as callables by `__main__.control_server`,
which is also why `attach` replies with a URL rather than letting the broker
assemble one from a port it was told about once.

`attach` is idempotent on the phrase and returns the existing stream, so a
re-`enable` after a broker restart cannot double the `grim` rate on an output.
The same phrase aimed at a *different* output is `invalid_argument`, because
that is a mistake and not a request.

Two details that are the point rather than polish:

* `_phrase_of` holds a caller's phrase to the generated shape and raises a
  shape-only message, with `from None`. `phrase.validate` names the value it
  rejected, which is correct for a library and wrong here: this value is a
  password, and the refusal travels back over a socket and into a log.
* `ControlServer.serve_forever` reads `self._sock` into a local before using
  it. `close()` runs on the main thread while this one is in `accept()`, and
  the attribute it was reading can be gone by the time it is dereferenced.

`hhstreamd.live` is the broker's client: one op at a time behind a lock, a
2-second timeout, `LiveUnavailable` for "could not be reached or did not answer
intelligibly" and `LiveRejected` carrying the `kind` the broker maps to an exit
code -- the pointer driver's client, verb for verb, because the broker already
knows how to hold one of those. `Attachment.parse` refuses a malformed reply
rather than defaulting its way past one.

`fps` is omitted from an `attach` unless a caller named one, which is what makes
`sessions.stream.fps` on the daemon's unit authoritative instead of decorative.
And `_safe()` renders a phrase as `<phrase:5 tokens>` for the one log line that
mentions a stream at all: the shape, never the words.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:47:16 +00:00
HermenixandClaude Opus 5 0f2810afaa docs(sessions)!: sessions-v4, the per-session live stream
`docs/CONTRACT-sessions.md` goes to sessions-v4 with a change table at the top,
for the reason mcp-v2 got one: everything in it is an addition, and a reader who
learned v3 should be told what moved rather than diff it.

The new §3.5 is the interface that needed freezing most, because it is the only
one in this build that two *processes* have to agree on: `/run/hhstream/live.sock`,
`LiveStreams.attach/detach/list/viewers`, the four JSON ops on the wire, and the
`Attachment` the broker gets back. Its shape is §3.4's deliberately -- the broker
holds the decision (which session streams, under which phrase), the daemon holds
the capture -- so a reader who knows the pointer driver already knows this.

Four rules in §3.5 are written out because each one is a thing a reasonable
implementation would get wrong:

* the daemon holds no session state and no idle clock; `viewers` is a reading,
  and what the broker does with it is the broker's;
* `fps` is optional and omitting it is normal -- the default is the daemon's,
  from its own unit's argv, for the same reason the port is. A broker that sent
  its own default on every attach would turn `sessions.stream.fps` into a
  setting that changed nothing, which is the failure `--xkb-layout` exists to
  avoid;
* `attach` is idempotent on the phrase, so a re-`enable` after a broker restart
  does not double the `grim` rate on one output;
* the phrase is never logged by either side. It is the stream's only credential.

§4 gains four verbs, the three `start` arguments, and the one genuinely new rule
in this version: **a connected viewer is activity**. That is the first exception
to "`touch` is the only mark of activity" since that rule was written, and it is
there for one failure -- an operator watching a long job on his phone, saying
nothing to the broker, and losing the session at three hours *because* watching
was all he was doing. It cannot hold a session open by itself: an enabled stream
with no viewer runs no `grim` and stamps nothing.

No new exit numbers. The three error names map onto codes the frozen table
already has (`stream_unavailable` -> 10, `stream_busy` -> 8, `stream_budget` ->
6), because no new *kind* of failure appeared: no container output is a
compositor-side failure, a phrase collision is a busy, a viewer cap is a budget.

§6 records schema 3 -> 4 (the record gains `stream`, older records migrate to
`null`), and §5 names the socket, the unit and port 9988 beside the other frozen
paths.

What v4 deliberately withholds from the broker is the port, the bind address and
the capture command. The broker learns the URL prefix *from* the daemon, in the
`attach` reply -- a URL it assembled itself from a port it was told about once
is a URL that lies the first time an operator moves the listener.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:46:54 +00:00
HermenixandClaude Opus 5 e636472106 docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it
`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because
v1 lasted a day and an agent that learned it deserves to be told what moved
rather than to discover it. The new §4 freezes the resource surface: the eight
URIs, their bodies, their query parameters, and the five rules the layer keeps
(a read never writes; only declared parameters; a literal route beats a
template; a frame's media type comes from its bytes; no subscriptions). §6
gains the other half of the error mapping -- for a resource read every exit
code arrives as `-32602` with the remedy in `message` and the structured object
in `data`, because `ReadResourceResult` has no `isError` to use instead.

§2 records what `--toolsets` is and is not: there is no grouping primitive in
MCP, the `Tool` object has nowhere to put a family, and tools are a flat list
in the specification too -- so the only lever is which tools the server lists,
decided by whoever spawns it.

README.md leads with the split rather than with a tool count, since that is the
thing a reader has to understand before any of the names make sense, and shows
the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth
box grows its second half and says why `shot` is on both sides.

A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit
that cost the most: `Server.get_capabilities` hardcodes
`ResourcesCapability(subscribe=False, …)`, so registering a
`subscribe_resource` handler changes nothing and a client is correctly told not
to try. Subscriptions would have been the principled answer to the missing
`logs --follow` -- it is the one place this design wanted a capability the SDK
will not advertise -- so the file names the one-line local override, says what
it risks, and recommends upstreaming the real fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:50:12 +00:00
HermenixandClaude Opus 5 56493721f0 test(mcp): the resource routing, the toolsets, and the guest check for both
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
2026-10-11 11:50:12 +00:00
HermenixandClaude Opus 5 0a63c9b7fc feat(mcp)!: state as resources, acts as tools, and --toolsets for the rest
BREAKING: `status`, `session_list`, `session_status`, `session_logs` and
`pointer_state` are no longer tools. They are `hhstream://…` resources. 26
tools became 21, and eight resources appeared beside them.

The reason is the split the protocol itself draws, which the first cut ignored.
A resource is **application**-controlled context: the host decides what to put
in front of the model, and "what is on this machine right now" is the host's
question. A tool is **model**-controlled: an act the model chooses to perform.
Nothing in those five verbs acts. So the line between the halves is *who
decides*, not what a call costs.

    hhstream://status                     text, the units and the frame socket
    hhstream://sessions          {?all}   the broker's own list object
    hhstream://pointer                    the lease holder, buttons and keys
    hhstream://containers                 every container, plus the orphans
    hhstream://screen                     a frame, as an image blob
    hhstream://sessions/{id}     {?events}
    hhstream://sessions/{id}/logs {?lines}
    hhstream://outputs/{name}             one output's frame, as a blob

What did *not* move is the interesting part. `shot` and `record` stay tools
though neither changes the desktop: capturing is an act at a moment, and an
agent in a loop has to be able to decide to look *now* -- in many clients a
resource is something a person attaches rather than something a model can
fetch. The same frames are readable as `hhstream://screen` and
`hhstream://outputs/{name}` as well, for a host that wants one in context
itself. `session_container` stays a tool for a harder reason: with an id the
CLI runs `container.reconcile`, which writes the record back, so it is not a
read at all. Only the no-id listing is a resource. **A resource read must never
write**, and `resources.py` says so where it would be tempting.

Three consequences worth naming:

* A refusal cannot be content. `ReadResourceResult` has no `isError`, so a CLI
  refusal is raised as `-32602` with the same remedy text in `message` and the
  same `{ok, exit_code, error, reason, hint, remedy}` in `data`. Returning the
  broker's failure object as the *body* would make "no such session" read as a
  successful read of a session.
* Arguments become query parameters, and only declared ones are accepted -- for
  the reason every tool schema sets `additionalProperties: false`. A parameter
  silently ignored is a read that answered a different question.
* A v1 tool name is told where it went: `session_list` comes back with "It is a
  RESOURCE now ... read hhstream://sessions instead". "No such tool" alone
  reads as a broken server rather than a moved surface.

`--toolsets frames,sessions,pointer,keyboard` lands with it, because 21 flat
tools is the same problem one size smaller. There is **no grouping primitive in
MCP** -- `Tool` carries name, title, description, inputSchema, outputSchema,
icons, annotations, _meta and execution, and nowhere to put a family -- so the
only honest lever is which tools the *server* lists, chosen at launch. An
unknown name is argparse's exit 2, never a silently empty server, and a tool
outside the selection is unreachable rather than merely unlisted. Resources are
deliberately not filtered by it: they are the host's context, not the model's
budget.

`--list-resources` joins `--list-tools`; both are in the package's own
entry-point check, with `--toolsets` beside them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:49:46 +00:00
HermenixandClaude Opus 5 6a40c7e2e4 docs(mcp): freeze the tool surface, and record what the in-process seam costs
`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:33:07 +00:00
HermenixandClaude Opus 5 fea55eecde test(mcp): the argv each tool builds, the mapping, and the server in a guest
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
2026-10-11 06:32:55 +00:00
HermenixandClaude Opus 5 549c73e8ae feat(nix): hhstream-mcp as its own derivation, and an option to install it
`packages.hhstream-mcp` (`nix/mcp.nix`), separate from `packages.hhstream` and
the separation is the point: the frame socket, the CLI and the broker are
stdlib-only by policy, the MCP SDK is a third-party dependency, and
`packages.hhstream` runs as the compositor's own units. Verified: the hhstream
closure gains no `mcp`, no `pydantic` and no `httpx`, and `hhstream_mcp` is not
in its site-packages.

The join to `hhstream` is a *library* one -- `toPythonModule`, because the
tools call `hhstream.cli`'s handlers in process. `grim` and `ffmpeg` are
prefixed onto the wrapper's PATH, because the CLI spawns them and the server is
launched by an MCP client whose PATH is not ours to predict.

The entry point is smoke-tested with `--list-tools` in a `postPhases` phase,
not `postInstall`: the script is wrapped in `fixupPhase`, so any earlier and
the check runs against a script with no PYTHONPATH and tests the wrong thing.
(`installCheckPhase` is no use either -- `buildPythonPackage` does not include
that phase at all.)

`services.hyprland-headless-stream.mcp.enable` (default false) puts the binary
on the system PATH, which is the whole of the option: the server is stdio and
spawned per client, so there is no unit, no socket and no state directory.
`mcp.package` defaults to this flake's build against `cfg.package`, so the
server and the CLI it runs are one build. A warning, not an assertion, when it
is enabled with `sessions.enable` off: 22 of the 26 tools then answer exit 5,
but the four frame tools are genuinely useful alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:32:34 +00:00
HermenixandClaude Opus 5 ca5e309e51 feat(mcp): the hhstream CLI as Model Context Protocol tools
`hhstream_mcp` serves the whole `hhstream` surface -- the four frame verbs, the
ten session verbs, the eight pointer verbs and the four keyboard verbs -- as 26
MCP tools over stdio, so an agent drives this desktop through typed tools
instead of writing command lines.

It is a shim and nothing more. Each tool builds the argv list the CLI's own
parser takes, hands it to the CLI's own handler **in this process**, and maps
what came back. The idle clock, the pointer lease, the allowlist, the exit-code
table and every refusal message stay where they already were.

Four decisions worth stating, each argued at length where it lives:

* **One tool per verb**, not one per family with an `action` enum. The
  arguments do not rhyme, the two rules an agent gets wrong have to be on the
  tool it gets wrong, and `readOnlyHint` is a real per-verb distinction here --
  `session_container` with an id runs `container.reconcile`, so it is not
  marked read-only.
* **In process, not as a subprocess.** `hhstream.cli`'s parser already takes an
  argv list and its handlers already return a code from the frozen table. Two
  of its paths cannot be called here and both end in an `exec` that would
  replace this server: `main`'s `sg` re-exec, and `cmd_run`'s `execvpe`. The
  first is therefore unavailable and said out loud (`access_hint`); the second
  is why `run` goes through `posix_spawn` into its own session.
* **The transport leaves file descriptor 1.** The CLI prints, and `record`
  spawns an `ffmpeg` whose output it does not capture. `claim_transport` takes
  a private duplicate of stdin and stdout at start-up and points fd 1 at the
  log, so a stray write is a log line and never a corrupted JSON-RPC stream.
* **No state, and the lease is an argument.** The CLI caches a lease id between
  invocations because its surface is flagless; this passes `--lease` on every
  call and never reads that cache. A cached lease is a lease an agent cannot
  see.

Refusals come back as tool errors -- never as a success -- carrying the remedy
sentence, the CLI's own `error`/`reason`/`hint`, everything it said, and the
frozen exit code in `structuredContent`. Exits 8 and 9 are held apart by a
test, because an agent that sees 8 must wait and one that sees 9 must acquire.

The root pyproject excludes `hhstream_mcp*` from package discovery: without
that, `packages.hhstream` would ship a module whose first import line fails.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:32:23 +00:00
ari f3ac9ada27 Merge pull request 'Keyboard input for sessions: typing on the compositor's one seat' (#1) from feat/keyboard-input into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/1
2026-10-11 05:10:29 +00:00
HermenixandClaude Opus 5 443efd8da8 docs(dev): register vm-keyboard and vm-keyboard-de where a reader looks
The keyboard checks were in `README.dev.md`'s `checks/` layout listing and
nowhere else: not in the table of what each check proves, and not in the
one-at-a-time `nix build -L` list that the same section tells you to use
instead of `nix flake check`. So the two checks this branch adds were
invisible exactly where someone goes to find out what is gated and how to
run it, while `vm-stream-firewall` (from main) was in all three places.

Four lines, no behaviour. The table rows state what each run actually
asserts, taken from `checks/vm-keyboard.nix`'s header and its
`expectations` attrset rather than paraphrased:

  * `vm-keyboard` -- the uploaded keymap reaching a real compositor,
    `pointer acquire` leaving the aimed window holding the keyboard and
    not merely the cursor, and `hhs-keyboard-target` decoding `hello`
    from the keymap it was forwarded. The mutation is named, because it
    is the point of the victim decoding rather than counting keycodes: a
    driver that stopped uploading a keymap leaves every key arriving as
    `sym=?`.

  * `vm-keyboard-de` -- why one file is exposed twice, which is that
    `sessions.keyboard.layout` reaches the keymap only through
    `--xkb-layout` on the driver unit and a single-layout run cannot
    tell that path from a hardcoded `us`. The three differences it
    pins: keysym `y`'s evdev code (21 against 44), the forwarded
    `symbols=` name, and `ü` going from exit 2 to `udiaeresis`.

Both rows say `yes` under "Needs a VM", and the build lines sit between
`vm-pointer` and `vm-stream-firewall` so the list keeps the order the
layout listing and `checks/default.nix` already use.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 03:06:08 +00:00
HermenixandClaude Opus 5 5f94833a76 Merge origin/main into feat/keyboard-input: keep both the stream and the
keyboard sides

origin/main brought the session live-stream feature (stage 1): the
`hhstream_live` router, its phrase generator and wordlist, the
`sessions.stream.*` module options with their loopback-vs-openFirewall
assertion and the one firewall port, the `vm-stream-firewall` check, and
`tests/live/`. This branch adds keyboard input: the `key`/`type` ops, the
uploaded XKB keymap, `sessions.keyboard.{layout,model,variant,options}`
and the four `--xkb-*` flags on the driver unit, `vm-keyboard` and
`vm-keyboard-de`, and their docs.

The two features are independent, so every conflict wanted both sides.
Four files, resolved as follows.

checks/default.nix -- both the header list and the attribute set take all
three new checks: `vm-keyboard`, `vm-keyboard-de` (the same file with
`keyboardLayout = "de"`, because the layout reaches the keymap only
through the driver unit's argv) and `vm-stream-firewall`, which stays a
non-`sessionArgs` consumer with main's comment saying why. Neither side's
check list is reduced; the flake now exposes ten.

nix/package.nix -- one `pythonImportsCheck` list with both sides' entries:
`hhstream_pointer.keymap` and the vendored
`virtual_keyboard_unstable_v1` from here, `hhstream_live.server` from
main. The surrounding hunks were not in conflict, so the branch's
xkbcommon dependency and main's wordlist `postFixup` both survive, and
both ran in this merge's `checks.unit` build (`wordlist ok: 7772 words`).

nix/module.nix -- the sole conflict was textual: both sides open a new
sub-option block immediately after `sessions.pointer`. Both blocks are
kept, `keyboard` then `stream`, each with its own closing. Everything
else in the file merged cleanly, so `loopbackBinds`, the
openFirewall-on-loopback assertion and
`networking.firewall.allowedTCPPorts` are present alongside the driver
unit's `--xkb-layout`/`--xkb-model`/`--xkb-variant`/`--xkb-options`.

README.dev.md -- the `checks/` layout listing keeps both entries in the
file's existing order, `vm-keyboard.nix` then `vm-stream-firewall.nix`.

Verified: `nix flake check --no-build` evaluates every output green, and
`nix build .#checks.x86_64-linux.unit` passes -- 977 passed, 2 skipped,
0 failed, over both sides' suites. The VM checks were not run (they boot
a software-rendered compositor and must run one at a time).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 02:57:55 +00:00
ari c6cfd02bf3 Merge pull request 'Session live stream: one port, a router, and a phrase per session (stage 1)' (#2) from feat/session-live-stream-webapp into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/2
2026-10-11 02:42:39 +00:00
ari 4461660c6d Merge branch 'main' into feat/session-live-stream-webapp 2026-10-11 02:42:25 +00:00
Hermenix 4fefb448ac docs(todo): the capture binary needs an absolute path under a unit
Found on the deployment machine on 2026-10-11, the first time `hhstream-live`
was run **as a unit** rather than from a login shell: a systemd unit's PATH has
no system profile, so the capture command `grim` is not found, ten times, and
the stream gives up. It answers on its port, serves the landing page and
reports `"stopped": true, "failures": 10` while showing nothing -- the quiet
half of the failure is what makes it worth a file.

The module already solves this for `sessions.apps` by requiring an absolute
store path; the stream's unit has to do the same (or set PATH, which is what
made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and
named as a risk on stage 3 of the plan, which is the stage that turns this from
an experiment into the only path.
2026-10-11 02:31:52 +00:00
Hermenix 7141900070 module: declare the stream's port, and the one hole it needs
`sessions.stream { port, bind, openFirewall }` -- the piece of stage 3 that
does not need the broker. It exists because 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 still runs by hand, and a
bare `networking.firewall.allowedTCPPorts` line in one machine's config is the
wrong place for a fact about this flake.

- `openFirewall` defaults false and is deliberately not implied by
  `sessions.enable`: a live view of the desktop is readable by anyone who can
  reach the port, the phrase in the URL is its only credential, and there is no
  TLS. It opens exactly one port -- the one the option names.
- `bind` defaults to loopback and is *checked*: `openFirewall = true` beside a
  loopback bind is refused, because that is a hole with no service behind it.
- `checks/vm-stream-firewall.nix` boots the module with a configured port that
  is not the module's default, puts listeners on that port and on a neighbour,
  and asserts from a second machine on the same VLAN that the peer reaches the
  configured port and is refused on the other -- while both answer on loopback
  inside the guest, so the refusal is the firewall's doing and not an empty
  socket. The peer is a second machine because a probe from the test driver
  proves nothing: the driver is not on the test VLAN.

Nothing here turns a stream on -- no unit, no phrases, no `session stream`
verbs, which stay stage 2+3 -- and docs/plans/2026-10-04-session-stream-webapp.md
now records which part of its stage 3 landed and why out of order.
2026-10-11 02:22:00 +00:00
ari 934774f15e fixing a test 2026-10-09 11:32:42 -04:00
HermenixandClaude Opus 5 db7aaf8276 build(nix): prove the wordlist is actually installed
`pythonImportsCheck` only imports, and `hhstream_live.phrase` reads its
wordlist lazily, so a wheel that dropped `wordlist.txt` sailed past the
check and would have failed at the first `enable` instead. The package now
reads the list from the installed tree and mints a phrase through
`validate`, which is the only place the packaged data is exercised --
`doCheck = false`, the suite runs in the flake's `checks`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:20:00 +00:00
HermenixandClaude Opus 5 bd3ca2e644 fix(live): hhstream-live with no subcommand serves, and SIGTERM stops it
`cmd_serve` read `args.capture_command`, which only exists on the `serve`
subparser, so a bare `hhstream-live` died with an `AttributeError`. The word
`serve` is now inserted before parsing rather than defaulted afterwards: the
top-level parser would otherwise reject `hhstream-live --port 9999` for an
unknown option before anything could be filled in. `--help` is left alone so
it still shows the program's own help. `--log-level` gained a copy on each
subparser, defaulting to `SUPPRESS` so that naming the subcommand does not
reset it.

SIGTERM had no handler, so the default action killed the process and
`server.stop()` never ran -- the exit status was a signal, not a 0. The
handler is installed before the listener is bound, so a supervisor's first
signal is never the fatal one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:20:00 +00:00
HermenixandClaude Opus 5 a9299682d2 fix(live): bound connections, a delimited stream, and a quiet access log
Four things the HTTP side owed.

A connection had no read timeout, so a client that connected and sent
nothing held a handler thread in `readline` for ever -- and on the MJPEG
route it also held a viewer slot, which keeps grim running for nobody.
Handlers now carry a 15 s header timeout, cleared once the MJPEG headers
are out because from there the wait is on frames, not on the client. TCP
keepalive covers the other half: a black-holed viewer that never closes.

The MJPEG response had no `Content-Length`, no chunked encoding and no
`Connection: close` -- `close_connection = True` was set after
`end_headers()`, so it never became a header. An intermediary was entitled
to buffer the whole thing waiting for an EOF that never comes.

`log_message` formatted the request line, which is the phrase, at debug
level; so did the client-error line. Both now log the method, the status
and the peer, never the path.

`RateLimiter` pruned only the key it was asked about, so every source
address that ever missed stayed in the table for the life of the process --
a leak any LAN host could drive. The sweep now covers the table.

Finally, `LiveServer` says where it is really bound: `address` still
returns something dialable, and `describe_bind` is what names `0.0.0.0` as
all interfaces.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:19:50 +00:00
HermenixandClaude Opus 5 19338af17c fix(live): a phrase is four plain words and a tail, and nothing weaker
Two holes in the one credential a stream has.

The wordlist has four hyphenated entries (`drop-down`, `felt-tip`,
`t-shirt`, `yo-yo`). A phrase drawn from one is six tokens --
`abacus-drop-down-lantern-harbor-7k2qp` -- and a listener cannot hear where
the tail starts. `words()` now keeps only `^[a-z]+$`; 7772 words costs
0.003 bits, so the ~77.5-bit figure is unchanged. The shape test asserted
over 50 draws, which caught this about a tenth of the time; the property is
now asserted over the whole list.

`validate` accepted `a-b-c`. It is what an operator-supplied `--phrase` is
checked against, so everything it accepts is a password someone can choose
for a LAN-facing stream. The floor is now exactly what `generate` produces:
four `[a-z]{3,}` words and a five-character `[a-z0-9]` tail. The router
still looks phrases up without validating, so an unknown phrase is the same
empty 404 it was.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:19:41 +00:00
HermenixandClaude Opus 5 52e3786bfb fix(live): a dead output stops the stream even after a good frame
The failure cap read `consecutive_failures >= FAILURE_LIMIT and captured ==
0`, so it could only ever fire on a cold start. An output removed while
someone was watching -- grim answering "unknown output" to every grab from
then on -- kept the loop retrying twice a second for as long as the viewer
held the page open. That is the busy loop the cap exists to stop, so the
count is now of failures in a row and nothing else. Giving up stays sticky:
a removed output does not come back, and re-enabling the session is how it
returns.

While here, the capture thread is named for its output and the give-up is
logged by output. The phrase is the stream's only credential, and
faulthandler, `threading.excepthook` and any sampling profiler all print
thread names.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:19:32 +00:00
Hermenix 9744d35945 feat(live): one port, a router, and a phrase per session (stage 1)
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase. Off by default, so a stream
exists only for the sessions it was enabled on.

  src/hhstream_live/phrase.py     four EFF-large words + a 5-char base-36 tail
                                  (~77.5 bits); the phrase is the password
  src/hhstream_live/publisher.py  one capture thread + one frame slot per
                                  output; one slot/no queue; capture paused at
                                  zero viewers
  src/hhstream_live/server.py     the router: /, /<phrase>/, /stream.mjpg,
                                  /frame.jpg, /status.json; unknown phrase is
                                  an empty 404, rate-limited
  src/hhstream_live/pages.py      the built-in dark pages (no CDN, no build)
  src/hhstream_live/__main__.py   hhstream-live serve|phrase, standalone

The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Transport is MJPEG (multipart/x-mixed-replace), reusing
the JPEG grim already produces. Not yet wired to the broker -- that is
stage 2. Tests: tests/live (51).
2026-10-06 13:32:00 +00:00
HermenixandClaude Opus 5 561e0c28f5 Stage 2 fixes: the two tests the review named, and the docs drift
From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2
done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only
things standing before merge.

(A) REPLAY, THROUGH THE SINK. What existed was
    `test_every_keyboard_verb_is_cached_for_the_same_reason`, which
    asserts the two verbs are in MUTATING_VERBS -- and the verification
    doc had already named that as the false pass: "asserting
    `deduplicated` and not the sink. A handler that types and then sets
    the flag stays green." Two integration tests now, modelled on
    `test_a_retried_click_with_the_same_request_id_clicks_once`:

      test_a_retried_type_with_the_same_request_id_types_once
        `keyboard.type` of "ab" twice with request_id="retry-me".
        Asserts `deduplicated`, chars == 2 on both, and that the sink
        still has exactly 4 key events -- two characters, a down and an
        up each -- so a replay that typed again is caught by the count
        and not by the flag.

      test_a_retried_unmappable_type_stays_refused_and_types_nothing
        `café` twice with one id. Both refusals are `invalid_argument`,
        the second carries `deduplicated` (a recorded failure is
        replayed as the failure it was), and the sink is empty after
        both -- there is no partial type on either call.

    Mutation-checked rather than assumed: removing `keyboard.key` and
    `keyboard.type` from MUTATING_VERBS fails both.

(B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls
    `_drop_lease_for` directly, so it proves that helper lifts keys and
    says nothing about whether `kill` still calls it. The integration
    kill test now holds `Shift_L` before the kill and asserts the SINK
    saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease
    forgetting a key is not the compositor being told it came up, and
    only the second matters to the application. Code 42 because `type`
    never emits it, so the release cannot be a leftover.

    Mutation-checked: stubbing out the `_drop_lease_for` call in
    `kill()` fails it. Before this it stayed green.

(C) DOCS. The plan's stage table and risk paragraph still said acquire
    is one warp and that `focuswindow` was unbuilt Stage 4 work. The
    contract (v3 §4) describes what shipped; the plan did not. Rewritten
    so they agree, and the plan now says outright that the contract wins
    where they differ:

      * risk 1 marked RESOLVED, describing the two warps, the pinned
        `follow_mouse_threshold`, and `focuswindow` as the
        nudge-failure fallback selecting on `address:` (not
        `stable_id`, which is not a Hyprland selector)
      * Stage 3 marked Done; Stage 4 struck as not existing -- the
        answer to Stage 0 was the second warp, not a focus dispatch
      * the top banner, the §5 VM assertion list and open question 2
        no longer say "one warp"
      * verification §B3 subtest 1 amended: it is a live assertion
        rather than an expected red, and the check additionally requires
        `focus == "warp"` so the fallback is not accepted as success

    Also amended one sentence the review did not list, because leaving
    it would contradict the edit above inside the same document:
    verification §"Warp does not guarantee wl_keyboard.enter" predicted
    `focuswindow` was "likely mandatory". It was not; the second warp
    was.

    Written down rather than smoothed over: the `focuswindow` branch
    itself has no test, and if both mechanisms fail acquire still
    returns ok with `focus="none"` -- a lease whose first key may go to
    the previously focused window.

(D) The tap docstring claimed the `up` is sent even if the `down` was
    refused after sending. The next lines return early on `not ok`, and
    that early return is right: a refusal means the key was never
    pressed, so an `up` would ask the compositor to release something it
    never had. Sentence replaced with why the early return is correct
    and what actually covers a lost reply (the broker's `release_all`,
    not the CLI, which cannot know whether the request arrived).

Not done, and not claimed: findings 4, 6 and 7 (the broker chord test
checking first/last mask rather than the key; the at-cap test not
looking at the sink; the module-defaults test being a substring match).
The review rates all three as not holes in the claim, and the driver
tests are the locks for the first two.

  nix develop -c python -m pytest tests -q
    907 passed in 67.71s
  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
    605 passed in 27.16s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-05 04:43:56 +00:00
HermenixandClaude Opus 5 54dd109dde checks(vm-pointer): the two-warp acquire invalidated a premise, not a property
Found by running vm-pointer after fixing the helper derivation, which is
the only reason it could be found: the heredoc bug meant this check had
not run, so nothing noticed that Stage 2 had broken it. Two bugs hiding
each other.

The subtest "the cursor reaches a session that does not hold focus"
needed the lease holder and the focused window to be different sessions,
and used to get that for free -- the second session's window took focus
when it opened, and `acquire` left it there, because one warp moves the
cursor and not keyboard focus. `pointer acquire` now takes the keyboard
too, so after the acquire the focused window IS the holder's and the
precondition assertion fired:

  this subtest needs the OTHER session focused; ['hh-target-epoqmb'] is

The property is still worth proving, so it is still proved: the premise
is now arranged with one `hyprctl dispatch focuswindow` on the other
session. That is SETUP and not the thing under test -- what is measured
is which client the compositor hands the warp to, which is unaffected by
how focus came to be where it is. Asserting "acquire takes focus" here
as well would make the subtest about the acquire rather than about
routing, and vm-keyboard already asserts that against both layouts.

Re-run, and the discriminator is intact:

  nix build --no-link -L .#checks.x86_64-linux.vm-pointer
    test script finished in 181.53s   (12/12, exit 0)

  the compositor's focused window belongs to: ['hh-target-qnly47']
  aimed at target-awyant: it reports [..., (747.0, 267.0)]
  focused is  target-qnly47: it reports []

The warp went to the session it was aimed at and the focused one was
told nothing, which is what this check exists to catch.

One behavioural consequence of the two-warp acquire, visible in that
same log and worth knowing: the focus nudge is delivered to the client
as a real motion. `[(299.0, 521.88), (299.0, 519.0), ...]` is the nudge
and then the target, about 3 px apart, so an application sees a small
cursor jiggle on every acquire.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-05 01:32:58 +00:00
HermenixandClaude Opus 5 a6a4094e6a Stage 3: vm-keyboard, and the helper derivation that never built
The keyboard's only purpose is that a client receives symbols, so a unit
suite alone was testing the shape of a request nobody answered --
docs/TODO/scroll-has-no-compositor-proof.md is the precedent. This is
the compositor proof: two nixosTests, 16 subtests each, real time, no
injected clock.

  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard
    test script finished in 281.06s   (16/16, exit 0)
  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard-de
    test script finished in 278.15s   (16/16, exit 0)

The victim, checks/lib/keyboard_target.py, decodes every keysym from the
keymap the COMPOSITOR forwarded rather than from a table of its own.
That is the mutation rule PLAN §14 asks for: a driver that stopped
uploading leaves the client with nothing to decode with, every key
arrives as `sym=?`, and the character assertions go red. A victim with
its own keymap would decode `hello` either way and the check would be
asserting that the check can spell.

What the client actually reported, which is the point of reading back
the application's state rather than the broker's intention:

  type A        [(30, 1, 'A'), (30, 0, 'A')]   masks [1, 1, 0, 0]
                -- evdev 30 decoded as A, so the mask arrived BEFORE the
                   key, and no code 42 anywhere
  key Return    [(28, 1, 'Return'), (28, 0, 'Return')]
  TTL expiry    [(42, 1, 'Shift_L'), (42, 0, 'Shift_L')] masks [1,1,0,0]
                -- lifted by the sweeper alone, mask cleared with it
  chord         depressed mask [4, 4] while Control held, still held
                   after the type returned

It runs TWICE because `sessions.keyboard.layout` reaches the uploaded
keymap through exactly one path -- `--xkb-layout` on the driver unit's
argv -- and one layout cannot tell that path from a hardcoded `us`:

  us:  symbols=pc_us_inet(evdev)  bytes=35572
       type y -> [(21, 1, 'y')]   type z -> [(44, 1, 'z')]
       type cafü -> exit 2, "scalar 3 (U+00FC) is not typeable", and the
                    client reported [] -- no prefix typed
  de:  symbols=pc_de_inet(evdev)  bytes=37532
       type y -> [(44, 1, 'y')]   type z -> [(21, 1, 'z')]   (swapped)
       type cafü -> {'chars': 4, 'ok': True}
                    client decoded ['c', 'a', 'f', 'udiaeresis']

Hyprland's own input:kb_layout is left at `us` in BOTH runs, so a client
that ignored our keymap would decode the us answer on the de machine.

The decisive subtest is "acquire takes the KEYBOARD as well as the
cursor". With session B holding keyboard focus because its window mapped
last, acquire on A delivered wl_pointer.enter AND wl_keyboard.enter to A
and wl_keyboard.leave to B, with focus == "warp". A check that asserted
only pointer delivery would have gone green while A had the cursor, B
had the keys, and the first keystroke of the lease went to B -- which is
exactly what one warp does. §B3's "one warp" and the Stage 0 review's
"do not assert enter on acquire" are superseded by the two-warp acquire,
and the header says so.

One deviation from §B3, with reasons in the header: its subtest 4 says
`type y` decodes to sym `z`, which is wrong for a victim that decodes
from the forwarded keymap -- the same paragraph requires that. `type y`
resolves keysym y against the uploaded layout and sends that layout's
code; the client decodes it back to `y`. The sym is `y` on both layouts
by construction. What differs is the CODE, the symbols name, and whether
ü is typeable at all, and those are what this asserts.

── AND A PRE-EXISTING BUG THE FIRST RUN EXPOSED ──────────────────────

checks/lib/session-tools.nix opened a heredoc with `<<EOF` and closed it
with an INDENTED `  EOF`. A delimiter has to be at column zero, so it
never closed: it swallowed the rest of the builder -- both `install`
lines and every self-test -- into the shim's own text. The derivation
built anyway, with `hhs-ipc-watch` alone in $out/bin:

  $ ls /nix/store/wy3lp3...-hhstream-session-tools/bin/
  hhs-ipc-watch

So hhs-pointer-target has NEVER existed in that derivation either.
vm-pointer execs that absolute path, and vm-keyboard failed the same
way: the broker reported `target exited immediately (exit code 127)`,
which is true about a path that was never created and says nothing about
why. hhs-ipc-watch's own first line was `  #!...`, indented, which is
not a shebang, so vm-ipc is affected too. The build-time self-tests that
exist to catch exactly this had themselves become heredoc text. The
unquoted delimiter also expanded the swallowed text, so the builder ran
`hhstreamd.ipc` as a command.

The shim is a writeTextFile now -- no delimiter to indent wrong -- and
`test -x` on all three programs is the guard that would have caught it.

NOT DONE, and it needs doing: vm-pointer and vm-ipc have not been
re-run. checks/default.nix says one VM at a time on this two-core box
and I did not want to perturb the keyboard runs. That they WOULD have
failed is read off the store listing above, not off a run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 20:23:14 +00:00
HermenixandClaude Opus 5 7890315cf6 checks(unit): xkbcommon in the suite's env, and the two-warp acquire
Two gaps found by running more than the gate command.

`checks/unit.nix` builds its own `python3.withPackages` and had only
pytest and pywayland in it, so `nix build .#checks.unit` would have
collected tests/pointer/test_keymap.py and failed on the import. The
dev shell has xkbcommon through nix/package.nix and the gate command
therefore never noticed. It is not an optional dependency: that file
compiles a real `us` keymap and a real `de` one, because only xkbcommon
can say `é` is unmappable on `us` and that `@` on `de` needs a
level-three mask.

And two integration tests asserted acquire's single warp, which is now
two. They are the whole-gesture trace and the bookmark-survives-a-
restart case, and both now assert the pair -- with the restored
position as the SECOND warp, since the bookmark is where the cursor is
left and the reverse order would restore every session a few pixels
off.

  nix develop -c python -m pytest tests -q
  905 passed in 65.91s

  nix build --no-link .#checks.x86_64-linux.unit
  903 passed, 2 skipped in 73.24s
  unit suite: 905 collected, 903 executed, 0 failed, 0 errored, 2 skipped

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 04:16:46 +00:00
HermenixandClaude Opus 5 e6f4c3bb3f Stage 1 review fixes, and Stage 2: the broker, the CLI and the module
The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:

(1) HIGH, and reproduced before fixing: `key` resolved the action and
    then used only its `code`. So `keyboard key A` sent a bare code 30
    and the window received `a`; on `de`, `at` lost its level-three mask
    and typed `q`. `type` was the only path that used the mask, which is
    why every `type` test stayed green. `key` now sends
    modifiers(baseline | mask) before the down and restores the baseline
    on the up -- the one-character `type` sequence -- and `Shift_L`
    keeps its key-then-mask order, which is the other path on purpose.

    The same hole aliased two names onto one keycode: `down A` then
    `down a` recorded both and pressed 30 twice, Hyprland dropped the
    second, and the held set lied until the lease ended. A second name
    for a code already down is now refused.

(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
    input:virtualkeyboard:release_pressed_on_close. It did not. The line
    is there now, with the note that it releases keys and still never
    clears a mask -- which is why release_all zeroes the mask on every
    path we control rather than relying on it.

(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
    `main` that connected and listened without uploading passed every
    test in the tree. Now asserted on the real sink: uploaded once,
    before `listen` (one shared ordering log across both stand-ins), the
    payload NUL-terminated with `size == len(utf8) + 1` read back
    through the fd, format 1, one terminator not two, and modifiers(0)
    straight after.

(4) LOW: `key` up now forgets the name only after a successful send,
    like `button` -- otherwise a raise between the two leaves us
    believing a key is up that the compositor still has down, and
    release_all will not try again.

(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
    newlines silently), and an empty layout is refused -- xkbcommon
    compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
    configured and typed `us`.

Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.

Stage 2 proper:

  * broker verbs keyboard.key / keyboard.type, both in the mutation set,
    both through _refresh (so they refresh the lease and, like every
    pointer verb, do NOT count as activity)
  * the driver's `kind` token mapped: a bad keysym or character is
    invalid_argument (exit 2), a missing keyboard global stays
    driver_refused (exit 10). The 4096-scalar cap and the shape checks
    are broker-side, because only a broker-side invalid_argument is 2
  * keys[] on pointer.state, keys_lifted[] on pointer.release and on
    pointer_lease_timeout, one release_all for both halves
  * CLI `session keyboard type|key|down|up`, reusing the pointer lease
    and its cache; `type` takes one raw argument and interprets nothing;
    the audit records a character count and never the text
  * sessions.keyboard.{layout,model,variant,options} on the unit's argv,
    layout defaulting to "us" with a type that refuses a comma. NO
    [keyboard] TOML table: hhstreamd reads that file and the driver is a
    different unit, so it would be a setting with no effect
  * CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
    vm-pointer.nix's header corrected (both still said the conf ships
    follow_mouse = 0 and that the keyboard work would choose)

And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  605 passed in 27.11s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 04:11:24 +00:00
HermenixandClaude Opus 5 b1f2744cf0 Stage 0 review: correct what the log does not say, and edit the plan
The Stage 0 review (docs/reviews/2026-10-04-stage0-review.md, verdict
yes-with-fixes) found that the measurements were sound and the write-up
was not. All four of its high and medium defects, verified against the
committed transcript before fixing:

(1) 19e484b's README claimed a verbatim excerpt and printed serial=336
    while the run's (a2) enter was serial 371. It also claimed six
    reproductions with one transcript, and cited a `keys=[42, 0, 0, 0]`
    enter from a run whose log was never kept -- every enter in the
    committed file is `keys=[]`. The excerpt is now copied from the log
    with line numbers to check it against, the reproduction claim is
    gone, and the Shift observation is named as not-in-this-log.

(2) THE (a) CONCLUSION WAS WRONG, and it is the one that matters. The
    first idle warp onto the unfocused window gave wl_pointer.enter and
    NO keyboard enter; the leave/enter arrived on the LATER motion. So
    it is not "enter, one warp late" -- the first warp's delta is set to
    0, the threshold is 0.0, and the second motion's own non-zero delta
    is what focused. Two corollaries the old text got backwards: a
    second warp to the SAME point returns before mouseMoveUnified
    touches the delta and proves nothing, and waiting longer does not
    help. The probe now prints both targets and the measured gap
    (0.401s) instead of hardcoding the word "immediately", and its
    ANSWER string says the mechanism.

    Consequence, now stated everywhere it belongs: `pointer acquire` is
    one warp, so the first key of a lease can land on whatever was
    already focused. Stage 3's enter subtest must not be designed from
    acquire's single warp, and must not be made to pass by warping twice
    to the same bookmark.

(3) d07a1fd did not edit the plan -- `git diff 14b3f69 HEAD --
    docs/plans/2026-10-03-keyboard-input.md` was empty, so anyone told
    to follow the plan still had the contradicted text. All eight
    pre-code changes are now folded into that file, each marked
    [SUPERSEDED], plus a banner at the top. Changes 5 and 7 were the
    ones that had survived intact in four places: the [keyboard] TOML
    table (dropped -- the broker reads that file and the driver is a
    different unit, so it would have been a setting with no effect) and
    "if it repeats, the help text says so" (now unconditional). The four
    closed open questions and the stage table are updated with what
    Stage 0 measured, including that Stage 4 is no longer contingent.

(4) mask_cleared=no was reported as a held mask surviving destroy. The
    held key was a letter, so the mask was 0 throughout; the README now
    says destroy emitted no key-up and no modifiers event, and that the
    reason release_all still sends modifiers(0,0,0,0) is
    VirtualKeyboard.cpp's releasePressed, not this line. The real
    poison evidence is promoted: onKeyboardKey drops a release whose
    code is not in m_pressed, so the cleanup's `key code=30 state=0`
    arriving from a brand-new keyboard proves 30 was still in that set.

The transcript is a fresh run of the corrected probe, so the file and
the claims about it agree line for line.

19e484b's message carries defect (2)'s wrong causality. It is corrected
here rather than by rewriting that commit, so the hashes the reviewer
cites keep resolving.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:46:53 +00:00
HermenixandClaude Opus 5 f931858f30 Stage 1: the driver learns to type
`zwp_virtual_keyboard_v1`, spoken by the process that already speaks
`zwlr_virtual_pointer_v1`. One device for the seat, one keymap uploaded
once, keysym names on our socket and evdev codes only on the Wayland
request -- the division buttons.py already draws.

keymap.py is the new seam, and it holds the three decisions that have a
wrong version which looks right:

  * A capital is the MASK, not a synthetic Shift keycode. Hyprland's
    virtual keyboard never runs updateXkbStateWithKey, so a virtual
    KEY_LEFTSHIFT changes no modifier state at all -- and sending both
    is how a toolkit applies Shift twice.
  * A modifier is whatever the keymap says is one, measured by pressing
    each key in a throwaway xkb state. Not a name list: `@` on `de` is a
    level-three symbol, and a Shift-only special case types the wrong
    character. (The measured set is also smaller than the canonical one,
    because no keycode on us/pc105 carries Meta or Hyper.)
  * A lock is not a modifier. Caps_Lock reports a *locked* mask, so
    `type` refuses while it is held rather than guessing the case.

The whole string resolves before anything is emitted, and every refusal
names the scalar INDEX, never the character: these messages reach the
driver's log and the string is a password as often as not.

Folding in the review's changes 1, 2, 3 and 6:

  1 a Rejected now carries a `kind`. A bad keysym or an unmappable
    character is `invalid_argument`; a missing keyboard global is
    `refused`. Without the token the broker would have to tell exit 2
    from exit 10 by reading English, and _drive maps every `ok: false`
    to driver_refused today.
  2 the keymap `size` on the wire includes the trailing NUL, and the fd
    outlives a roundtrip rather than a flush. Hyprland mmaps exactly
    that many bytes and hands the pointer to xkb_keymap_new_from_string.
  3 release_all lifts buttons, then keys in press order, then zeroes the
    mask -- and the mask only if something set it, so a compositor with
    no keyboard global still gets its buttons lifted. One release_all is
    the whole of expiry; an exception in the key half would abandon it.
  6 `key` and `type` never call _aimed(). A keyboard has no output, and
    one test deliberately never warps so that stays true.

Also: `--xkb-layout/-model/-variant/-options`, compiled BEFORE any
Wayland call so a bad layout is exit 2 rather than exit 10; a comma in
the layout refused outright, because v1 always sends group 0 and
xkbcommon would hand back a second group nothing could reach; the
keymap uploaded after connect and before listen, with one
modifiers(0,0,0,0) after it; and xkbcommon as a hard, non-optional
dependency -- an optional one would let test_keymap.py skip, and the
unmappable-character path is the one that must not rot.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  549 passed in 25.70s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:39:00 +00:00
HermenixandClaude Opus 5 19e484b388 Stage 0: measure the compositor instead of reading its source
A throwaway client against the live /run/hypr-stream that answers the
four open questions. It touches no broker, no lease and no session; it
opens two windows of its own and moves the one cursor, because keyboard
focus cannot be measured without doing both, and it refuses to send a
key until it sees wl_keyboard.enter on a surface it owns.

What it found, with the transcript beside it:

  1  zwp_virtual_keyboard_manager_v1 is present at version 1. The gate
     the plan hangs on holds against the running binary, not just
     against §6.7's [RAN] claim.

  a  ONE IDLE WARP DOES NOT MOVE KEYBOARD FOCUS. A second warp
     immediately after does. Measured with an unfocused fullscreen
     window under a focused floating one, warping into the margin that
     belongs to the first alone -- and `pointer acquire` is one warp, so
     the first key of a lease can land in the previously focused
     window. Neither plan permits building the fallback here, so this
     branch does not; it is the objection in the final report.

  b  destroy with a key down releases nothing and clears no mask
     (release_pressed_on_close is 0 and unset). An earlier run proved it
     by accident: it exited with Shift_L down and the NEXT run's first
     enter carried keys=[42, 0, 0, 0].

  c  one held key is one wl_keyboard.key, with repeat_info 25/600. The
     flood is the client's repeat, not ours -- which is why `down` warns
     unconditionally rather than only if the probe saw repeats.

The XML both plans name does not exist in this nixpkgs: not in
wayland-protocols 1.49, not in wlr-protocols, not in wlroots. Hyprland's
own copy is the only one, so that is what is used -- and because it
names keymap_format and key_state without defining them, both are
written down as cited constants instead of read off an enum.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:21:14 +00:00
HermenixandClaude Opus 5 d07a1fd045 docs(plan): fold in the independent review of the keyboard plan
An adversarial read of 2026-10-03-keyboard-input.md against this tree and
against Hyprland v0.56.2. Its verdict is "safe to build on, not safe to
implement as written", and its §"Changes required before code" is the list
Stages 0-2 are built to rather than the original plan where the two differ:

  1 exit 2 vs driver_refused -- _drive maps every `ok: false` to
    driver_refused (exit 10), so the plan's "exit 2 for a bad keysym"
    needs a token the broker can map to invalid_argument
  2 the keymap `size` must include the trailing NUL
  3 release_all must no-op its key half with no keyboard object, and
    must end with modifiers(0, 0, 0, 0)
  4 input:virtualkeyboard:release_pressed_on_close defaults to false
  5 the layout reaches the keymap only as --xkb-layout on the driver
    unit; a [keyboard] table in the broker TOML would be a false pass
  6 the modifier-keysym set has to be written down; no Shift special case
  7 Stage 0 expectations, including a two-window probe
  8 acquire's stderr, and an index rather than the string in logs

It also writes the test specs for Stages 1-3, including the false pass
beside each assertion, which is the part the unit tests are written from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:21:01 +00:00
Hermenix 14b3f691c4 docs(plan): keyboard input for sessions — approach and open questions 2026-10-03 23:55:44 +00:00