Compare commits

..
Author SHA1 Message Date
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
45 changed files with 8435 additions and 2429 deletions

No files matched your search

+45 -10
View File
@@ -7,8 +7,8 @@ decides, and if the document is wrong it gets a version bump, not an edit.
## Prerequisites
- Nix with flakes enabled.
- `/dev/kvm` readable, for the six VM checks. They are `nixosTest`s; without
KVM they still run, just slowly enough that the timeouts below get tight.
- `/dev/kvm` readable, for the VM checks. They are `nixosTest`s; without KVM
they still run, just slowly enough that the timeouts below get tight.
- No GPU. Nothing in the test suite needs one — the compositor runs on
Hyprland's headless backend over software rendering.
@@ -21,21 +21,39 @@ socket outside the build sandbox or the test VM.
nix develop
```
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH
and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree
rather than an installed copy.
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH,
plus both packages (`hhstream` and `hhstream-mcp`) and the `mcp` SDK, and sets
`PYTHONPATH=$PWD/src`, so `import hhstream` and `import hhstream_mcp` both pick
up the working tree rather than an installed copy.
## Build
```bash
nix build .#hhstream # the package
ls result/bin # hhstream-server, hhstream-client, hhstream,
# hhstreamd, hhstream-pointer
# hhstreamd, hhstream-pointer, hhstream-live
nix build .#hhstream-mcp # the MCP server, a SEPARATE derivation
ls result/bin # hhstream-mcp
```
Five entry points: the frame server and a reference reader for it, the `hhstream`
front-door CLI (frames, `run`, and the `session` namespace), the session broker,
and the pointer driver.
The first package's entry points: the frame server and a reference reader for
it, the `hhstream` front-door CLI (frames, `run`, and the `session` namespace),
the session broker, the pointer driver and the session-stream web app.
`hhstream-mcp` is its own derivation on purpose. It is the CLI as Model Context
Protocol tools (`docs/CONTRACT-mcp.md`), it depends on the third-party `mcp`
SDK, and `packages.hhstream` is stdlib-only by policy — see the header of
`nix/mcp.nix`. It depends on the `hhstream` package as a *library*: the tools
call `hhstream.cli`'s handlers in process rather than spawning the CLI. The dev
shell has both, plus `python3.pkgs.mcp` so `tests/unit/test_mcp_server.py` can
import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the 21 acting verbs
hhstream-mcp --list-resources # the 8 read-only URIs
```
## The checks
@@ -51,6 +69,7 @@ and the pointer driver.
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads 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** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 21 tools and 8 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
All of them at once:
@@ -75,6 +94,7 @@ nix build -L .#checks.x86_64-linux.vm-pointer
nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
@@ -97,7 +117,17 @@ warning.
pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at
what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on
purpose, so this is the only place the suite runs in a build).
purpose, so this is the only place the suite runs in a build). `nix/mcp.nix`'s
output is on that path beside it, and `mcp` is in the test environment, because
`tests/unit/test_mcp_*.py` import `hhstream_mcp` and one of them imports the SDK
— not optionally: a file that skipped when the SDK was absent would be green in
exactly the build where a malformed tool schema mattered.
The MCP suite is four files, split along what each can be tested without:
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
@@ -230,6 +260,11 @@ checks/
(layout us) and `vm-keyboard-de` -- because the layout
reaches the keymap only through the driver unit's argv
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
JSON-RPC client against the live broker
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
NOT the MCP SDK's -- the SDK on both ends would agree
with itself about a framing neither side had to get right
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share
+84
View File
@@ -35,9 +35,93 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
The socket is a plain file descriptor: the server serves every client that
connects, and keeps running when one disconnects.
## Driving it from an agent: the MCP server
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
Protocol](https://modelcontextprotocol.io) surface, so an agent can look at this
desktop, put an application on it, and aim its one pointer and keyboard at that
application without writing command lines. The interface is frozen in
`docs/CONTRACT-mcp.md`.
It is split the way the protocol splits things:
- **Resources are the state** — eight of them, read by URI, and reading one
changes nothing. `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
an application's own output, `hhstream://pointer` is who holds the input
lease, `hhstream://screen` is a frame of the screen.
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
`session_start` puts an application on the screen, `pointer_acquire` takes the
input lease, `keyboard_type` types, `session_kill` ends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why `shot` is still a tool
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
It is a thin wrapper and nothing more: every tool and every resource builds the
argv list the CLI's own parser takes, runs the CLI's own handler, and maps what
came back. The idle clock, the pointer lease, the allowlist and the exit-code
table all stay where they were.
Install it with the module — off by default, because it is the surface through
which a language model starts processes on this machine:
```nix
services.hyprland-headless-stream = {
enable = true;
sessions.enable = true; # the session, pointer and keyboard tools need the broker
mcp.enable = true; # puts `hhstream-mcp` on the system PATH
};
```
Then register it with a client. The transport is **stdio** — one process per
client, spawned by the client, no port and no daemon — so the whole
configuration is a command and an environment:
```json
{
"mcpServers": {
"hhstream": {
"command": "hhstream-mcp",
"env": {
"HHSTREAM_SOCKET": "/run/hhstream/control.sock",
"HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock"
}
}
}
}
```
Both variables are the CLI's own and both are shown at their defaults, so they
can be left out unless this machine moved a socket. The account the client runs
as needs what the CLI needs: membership of the compositor's group (`hhstream`)
to read the frame socket, and of the broker's to reach the control socket. The
server cannot recover that for itself the way the CLI does — see
`docs/CONTRACT-mcp.md` §5 — so if `shot` reports it cannot read the socket, the
answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an
account in the group.
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
exit, which is the quickest way to check an install.
If twenty-one tools is more than a client has room for, `--toolsets` narrows
what is offered to whichever families are wanted — `frames`, `sessions`,
`pointer`, `keyboard`:
```json
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
```
Resources are deliberately *not* narrowed by it: they are the host's context,
not the model's tool budget. Nothing else about the server is configurable — it
holds no state and caches no lease, and the pointer lease is an explicit
argument on every gesture tool for exactly that reason.
| Document | What it is |
|---|---|
| `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against |
| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease |
| `docs/CONTRACT-mcp.md` | the MCP surface: the resource URIs, the tool names, their arguments and the error mapping |
| `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client |
| `README.dev.md` | how to build, test and hack on it |
| `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` |
+8 -1
View File
@@ -1,6 +1,7 @@
# The flake's `checks` output. One file per check; this is only the wiring.
#
# unit -- pytest over tests/, against the nix/package.nix build
# vm-mcp -- the MCP server over stdio, against a live broker
# vm-basic -- nixosTest with a fake capture backend: module + wire contract
# vm-hyprland -- nixosTest with the real compositor and grim
# vm-sessions -- nixosTest with the real compositor and the session broker
@@ -32,6 +33,7 @@
}:
let
hhstream = self.packages.${system}.hhstream;
hhstream-mcp = self.packages.${system}.hhstream-mcp;
hhsModule = self.nixosModules.default;
testTools = pkgs.callPackage ./lib/test-tools.nix { };
# The session checks take the same arguments; naming them once keeps a new
@@ -42,7 +44,7 @@ let
};
in
{
unit = pkgs.callPackage ./unit.nix { inherit hhstream; };
unit = pkgs.callPackage ./unit.nix { inherit hhstream hhstream-mcp; };
vm-basic = pkgs.callPackage ./vm-basic.nix {
inherit hhstream hhsModule testTools;
@@ -73,4 +75,9 @@ in
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
# The session machine again, plus `mcp.enable`, driven over stdio by a
# JSON-RPC client the check writes itself. `sessionArgs` plus the one package
# the others have no reason to carry.
vm-mcp = pkgs.callPackage ./vm-mcp.nix (sessionArgs // { inherit hhstream-mcp; });
}
+223
View File
@@ -0,0 +1,223 @@
#!/usr/bin/env python3
"""``hhs-mcp-call`` -- drive an MCP server over stdio from a shell.
What `checks/vm-mcp.nix` uses to talk to `hhstream-mcp` in the guest, and
deliberately **not** the MCP SDK's own client: the SDK on both ends would agree
with itself about a framing neither side had to get right. This is raw
JSON-RPC, newline-delimited, written against the specification -- the same
choice, and for the same reason, as `tests/assert_stream.py` being a second
implementation of the frame contract.
One server process per invocation, which means every call re-does the
`initialize` handshake. That is a feature here: the handshake is one of the
things under test, and a client that did it once would prove it once.
hhs-mcp-call --initialize the handshake's own result
hhs-mcp-call --list every tool, as JSON
hhs-mcp-call --resources every resource and template
hhs-mcp-call --read hhstream://sessions one resources/read
hhs-mcp-call session_gc one call, no arguments
hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON
``--server-arg`` is passed through to the server, which is how a check drives
``--toolsets`` without a second program.
Always exits 0 when the server answered, whatever the answer was: a refusal is
a result the test asserts on, not this program's failure. Exit 2 is "the
server did not answer" -- it died, it timed out, or it sent something that is
not JSON-RPC -- which is the one outcome no assertion should be able to mistake
for a reply.
"""
from __future__ import annotations
import argparse
import json
import signal
import subprocess
import sys
from typing import Any
#: The protocol version this client speaks. Named rather than negotiated: a
#: server that answers a different one is a thing the test should see.
PROTOCOL_VERSION = "2025-06-18"
def fail(message: str) -> None:
print(f"hhs-mcp-call: {message}", file=sys.stderr)
raise SystemExit(2)
class Server:
"""One ``hhstream-mcp`` process, spoken to over its stdin and stdout."""
def __init__(self, command: list[str], timeout: int) -> None:
self.timeout = timeout
# stderr is left alone on purpose: the server logs there, and in a
# nixosTest that ends up in the build log beside the assertion that
# failed, which is where it is wanted.
self.process = subprocess.Popen(
command,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
text=True,
bufsize=1,
)
self.next_id = 0
def send(self, message: dict[str, Any]) -> None:
assert self.process.stdin is not None
self.process.stdin.write(json.dumps(message) + "\n")
self.process.stdin.flush()
def read(self) -> dict[str, Any]:
assert self.process.stdout is not None
# An alarm rather than a poll loop: a server that never answers must
# fail the check, not hang the test driver until its global timeout.
signal.alarm(self.timeout)
try:
line = self.process.stdout.readline()
except KeyboardInterrupt: # pragma: no cover -- the alarm handler
fail(f"no answer within {self.timeout}s")
raise
finally:
signal.alarm(0)
if not line:
fail(f"the server closed its stream (exit {self.process.poll()})")
try:
return json.loads(line)
except json.JSONDecodeError:
# The failure a stray `print` on stdout produces, named as such:
# the tools run the CLI in process, and this is what it looks like
# when something it printed reached the transport.
fail(f"not JSON-RPC on the server's stdout: {line!r}")
raise AssertionError("unreachable")
def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
self.next_id += 1
wanted = self.next_id
self.send(
{"jsonrpc": "2.0", "id": wanted, "method": method, "params": params or {}}
)
answer = self.read()
if answer.get("id") != wanted:
fail(f"answer for id {answer.get('id')!r}, expected {wanted}")
if "error" in answer:
# Printed as the result and exited 3, not `fail`ed: a resource read
# has no `isError`, so a refusal arrives here -- and the checks
# assert on *which* refusal. Exit 3 keeps it distinguishable from
# exit 2, which is "the server did not answer at all".
print(json.dumps({"error": answer["error"]}, indent=2, sort_keys=True))
raise SystemExit(3)
return answer["result"]
def initialize(self) -> dict[str, Any]:
result = self.request(
"initialize",
{
"protocolVersion": PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "hhs-mcp-call", "version": "0"},
},
)
self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
return result
def close(self) -> int:
assert self.process.stdin is not None
self.process.stdin.close()
try:
return self.process.wait(timeout=self.timeout)
except subprocess.TimeoutExpired: # pragma: no cover
self.process.kill()
return -1
def _alarm(signum, frame): # pragma: no cover -- raises into read()
raise KeyboardInterrupt
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="hhs-mcp-call", description=__doc__)
parser.add_argument(
"--server",
default="hhstream-mcp",
help="the MCP server to spawn (default: %(default)s, from PATH)",
)
parser.add_argument(
"--server-arg",
action="append",
default=[],
metavar="ARG",
help="an argument for the server itself; repeatable",
)
parser.add_argument("--timeout", type=int, default=120, metavar="SECONDS")
parser.add_argument("--initialize", action="store_true", help="print the handshake result")
parser.add_argument("--list", action="store_true", help="print the tool listing")
parser.add_argument(
"--resources",
action="store_true",
help="print the resource listing and the templates, as one object",
)
parser.add_argument("--read", metavar="URI", help="read one resource")
parser.add_argument("tool", nargs="?", help="the tool to call")
parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON")
args = parser.parse_args(argv)
signal.signal(signal.SIGALRM, _alarm)
try:
arguments = json.loads(args.arguments)
except json.JSONDecodeError as exc:
fail(f"arguments are not JSON: {exc}")
return 2
if not isinstance(arguments, dict):
fail("arguments must be a JSON object")
server = Server([args.server, *args.server_arg], args.timeout)
try:
handshake = server.initialize()
if args.initialize:
print(json.dumps(handshake, indent=2, sort_keys=True))
return 0
if args.list:
print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True))
return 0
if args.resources:
# Both listings as one object, because they are two halves of one
# question and a check that asked twice would pay two handshakes.
print(
json.dumps(
{
"resources": server.request("resources/list")["resources"],
"resourceTemplates": server.request(
"resources/templates/list"
)["resourceTemplates"],
},
indent=2,
sort_keys=True,
)
)
return 0
if args.read:
print(
json.dumps(
server.request("resources/read", {"uri": args.read}),
indent=2,
sort_keys=True,
)
)
return 0
if not args.tool:
fail("name a tool, or pass --list, --resources, --read or --initialize")
result = server.request(
"tools/call", {"name": args.tool, "arguments": arguments}
)
print(json.dumps(result, indent=2, sort_keys=True))
return 0
finally:
server.close()
if __name__ == "__main__":
raise SystemExit(main())
+20 -2
View File
@@ -16,6 +16,7 @@
runCommand,
python3,
hhstream,
hhstream-mcp,
}:
let
# `xkbcommon` beside `pywayland`, and it is not optional: `tests/pointer/
@@ -24,7 +25,19 @@ let
# needs a level-three mask rather than Shift. A suite that could skip those
# would let the unmappable-character path rot, which is the path that decides
# whether a bad string types a prefix.
pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ps.xkbcommon ]);
#
# `mcp` beside them, for `tests/unit/test_mcp_server.py`. That file imports
# the SDK on purpose and is not allowed to skip: the tool table itself is
# stdlib-only and tested without it, but the step that turns the table into
# `mcp.types.Tool` objects is where a malformed schema or a name the spec
# refuses would show up, and a file that skipped when the SDK was absent
# would be green in exactly the build where that mattered.
pytestEnv = python3.withPackages (ps: [
ps.pytest
ps.pywayland
ps.xkbcommon
ps.mcp
]);
# Only the suite itself, so an editor's droppings or a local .pytest_cache
# cannot change the derivation's hash.
@@ -61,11 +74,16 @@ runCommand "hhstream-unit"
# point PYTHONPATH at what nix/package.nix installed. Importing it here rather
# than letting pytest do it makes a packaging problem distinguishable from a
# test failure.
export PYTHONPATH=${hhstream}/${python3.sitePackages}
export PYTHONPATH=${hhstream}/${python3.sitePackages}:${hhstream-mcp}/${python3.sitePackages}
export PYTHONDONTWRITEBYTECODE=1
export HOME=$PWD
python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)'
python3 -c 'import hhstreamd.ipc, hhstream_pointer; print("broker ipc client + pointer driver import")'
# The second distribution, on the path beside the first. `tests/unit`'s
# conftest adds `../src` to sys.path, which does not exist in this sandbox --
# so here, as for `hhstream`, the import comes from what Nix installed, and a
# packaging mistake is distinguishable from a test failure.
python3 -c 'import hhstream_mcp.tools as t; print("mcp tool table:", len(t.TOOLS), "tools")'
set +e
pytest suite \
+537
View File
@@ -0,0 +1,537 @@
# checks.<system>.vm-mcp -- the MCP server over stdio, in a guest, against a
# live broker and a real compositor.
#
# The same machine the other session checks use (`lib/session-machine.nix`),
# plus `services.hyprland-headless-stream.mcp.enable = true` -- which is also
# the first thing asserted, because "installing it" is the whole of that
# option. Then `hhs-mcp-call` (`lib/mcp_client.py`) spawns `hhstream-mcp` as the
# operator account and talks raw JSON-RPC to it: initialize, tools/list,
# tools/call.
#
# WHAT THIS PROVES, AND WHAT IT DOES NOT.
#
# It proves the *surface*, both halves of it: the handshake completes over a
# real pipe, all twenty-one tools and all eight resources are listed, a tool
# call reaches the broker and comes back with the broker's own protocol object,
# a resource read reaches it the same way, an image arrives as a blob with the
# geometry the module configured, `--toolsets` actually narrows what is
# offered, and a refusal arrives as a tool error (or, for a resource, a
# protocol error) carrying the frozen exit code rather than as a success.
#
# It does not prove the compositor behaviour the other checks own, and it must
# not be read as doing so. `vm-pointer` is where a click is shown to land in the
# window it was aimed at; `vm-keyboard` is where a typed symbol is shown to be
# decoded by a client from the keymap the driver uploaded. Here the victim is
# `foot`, which ignores `$HHSTREAM_APP_ID` and so matches no container rule
# (README.dev.md, known gap 4) -- so what the pointer and keyboard subtests
# below assert is that the lease was granted and the driver accepted the
# injection, which is the part the MCP layer is responsible for.
#
# The client is not the MCP SDK's, deliberately: the SDK on both ends would
# agree with itself about a framing neither side had to get right. Same choice
# as `tests/assert_stream.py` being a second implementation of the frame
# contract, and for the same reason.
#
# Habits copied from the other session checks: every wait is bounded, each
# subtest asserts once, and a failure dumps the compositor's diagnostics and
# the broker's journal before it propagates.
{
testers,
hhstream,
hhstream-mcp,
hhsModule,
testTools,
hyprland,
foot,
jq,
grim,
procps,
coreutils,
dejavu_fonts,
width ? 1280,
height ? 720,
sessionUser ? "hermes",
}:
testers.runNixOSTest (
{ pkgs, ... }:
let
tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; };
guest = import ./lib/session-machine.nix {
inherit
hhsModule
hhstream
hyprland
testTools
foot
jq
procps
grim
coreutils
dejavu_fonts
;
sessionTools = tools;
};
prelude = import ./lib/session-prelude.nix {
inherit hhstream coreutils sessionUser;
};
# The client, with a plain python3: it speaks JSON-RPC over a pipe and
# imports nothing but the standard library, which is what makes it a second
# implementation rather than the SDK talking to itself.
client = pkgs.runCommandLocal "hhs-mcp-call" { } ''
install -Dm755 ${./lib/mcp_client.py} $out/bin/hhs-mcp-call
sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-call
$out/bin/hhs-mcp-call --help > /dev/null
# It must refuse to invent a request rather than printing nothing: a
# client that exits 0 having done nothing would make every subtest below
# vacuous.
if $out/bin/hhs-mcp-call --server ${coreutils}/bin/true; then
echo "hhs-mcp-call succeeded against a server that says nothing" >&2
exit 1
fi
'';
in
{
name = "hhstream-vm-mcp";
globalTimeout = 1800;
nodes.machine = {
imports = [
(guest {
inherit width height sessionUser;
pointer = true;
apps.foot = {
exec = "${foot}/bin/foot";
# The broker refuses unlisted arguments and this check passes none:
# `foot` with no argv opens a window, which is all the victim has
# to do.
argsAllow = [ ];
};
})
];
# The option under test. Installing the package IS the option, so the
# first subtest asserts the binary is on PATH and nothing else had to
# happen.
services.hyprland-headless-stream.mcp = {
enable = true;
package = hhstream-mcp;
};
environment.systemPackages = [ client ];
};
testScript =
prelude
+ ''
import base64
import shlex
MCP = "${client}/bin/hhs-mcp-call"
WIDTH = ${toString width}
HEIGHT = ${toString height}
def mcp(argv, timeout=180):
"""`hhs-mcp-call …` as USER, parsed. Fails loudly if it printed no JSON."""
out = machine.succeed(as_user(f"{MCP} {argv}"), timeout=timeout)
try:
return json.loads(out)
except json.JSONDecodeError:
raise AssertionError(f"not JSON from `hhs-mcp-call {argv}`: {out!r}")
def call(tool, arguments=None, timeout=180):
"""One tools/call. Returns the CallToolResult as a dict."""
payload = json.dumps(arguments or {})
return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout)
def read(uri, timeout=180):
"""One resources/read that must succeed. Returns its contents list."""
return mcp(f"--read {shlex.quote(uri)}", timeout=timeout)["contents"]
def read_refused(uri, timeout=180):
"""One resources/read that must NOT succeed. Returns the error object.
A resource read has no `isError`, so a refusal is a protocol error
and the client exits 3 for it -- which is deliberately a different
status from the 2 it uses for "the server did not answer", so this
cannot pass because the server died.
"""
status, out = machine.execute(
as_user(f"{MCP} --read {shlex.quote(uri)}"), timeout=timeout
)
assert status == 3, f"expected a refusal (3) for {uri}, got {status}: {out}"
return json.loads(out)["error"]
def text_of(result):
"""The text part of a CallToolResult, which is where the CLI's own
output and (on a refusal) the remedy live."""
for block in result.get("content") or []:
if block.get("type") == "text":
return block["text"]
raise AssertionError(f"no text content in {result!r}")
def succeeded(tool, arguments=None, timeout=180):
"""A call that must not be an error, with the reason printed if it is."""
result = call(tool, arguments, timeout=timeout)
if result.get("isError"):
print(f"----- {tool} returned an error -----")
print(text_of(result))
assert not result.get("isError"), f"{tool} failed: {text_of(result)}"
return result
start_all()
bring_up("the compositor and broker")
with subtest("the as-user wrapper propagates exit status"):
# Every assertion below reads machine.succeed through it, so a
# wrapper that swallowed the status would make them all vacuous.
machine.succeed(as_user(TRUE), timeout=120)
machine.fail(as_user(FALSE), timeout=120)
with subtest("mcp.enable put the server on the system PATH"):
# The whole of the module option: no unit, no socket, no state dir.
path = machine.succeed(as_user("/run/current-system/sw/bin/sh -c 'command -v hhstream-mcp'")).strip()
print(f"hhstream-mcp resolves to {path}")
assert path.startswith("/run/current-system/sw/bin"), path
machine.fail("systemctl is-active hhstream-mcp.service")
with subtest("the stdio handshake completes and names this server"):
try:
handshake = mcp("--initialize")
print(json.dumps(handshake, indent=2)[:600])
assert handshake["serverInfo"]["name"] == "hhstream", handshake
assert handshake["capabilities"].get("tools") is not None, handshake
# The two rules, in the instructions a client is handed once.
instructions = handshake["instructions"]
assert "`session_touch` is the ONLY" in instructions
assert "POINTER lease" in instructions
except Exception:
dump("the mcp handshake")
raise
with subtest("tools/list carries every acting verb, with its annotations"):
listed = mcp("--list")["tools"]
names = sorted(tool["name"] for tool in listed)
print(f"{len(names)} tools: {', '.join(names)}")
assert len(names) == 21, names
for expected in (
"shot", "record", "run",
"session_start", "session_touch", "session_kill",
"pointer_acquire", "pointer_click", "keyboard_type",
):
assert expected in names, f"{expected} is missing from the listing"
# The read-only verbs are resources now and must not be here.
for moved in ("status", "session_list", "session_status",
"session_logs", "pointer_state"):
assert moved not in names, f"{moved} is a resource, not a tool"
by_name = {tool["name"]: tool for tool in listed}
assert by_name["shot"]["annotations"]["readOnlyHint"] is True
assert by_name["session_kill"]["annotations"]["destructiveHint"] is True
# The rules have to be on the tool, not only in the instructions.
assert "session_touch" in by_name["session_gc"]["description"]
assert "POINTER lease" in by_name["keyboard_type"]["description"]
with subtest("resources/list and the templates carry the read-only half"):
both = mcp("--resources")
uris = sorted(r["uri"] for r in both["resources"])
templates = sorted(t["uriTemplate"] for t in both["resourceTemplates"])
print(f"resources: {', '.join(uris)}")
print(f"templates: {', '.join(templates)}")
assert uris == [
"hhstream://containers",
"hhstream://pointer",
"hhstream://screen",
"hhstream://sessions",
"hhstream://status",
], uris
assert templates == [
"hhstream://outputs/{name}",
"hhstream://sessions/{id}/logs{?lines}",
"hhstream://sessions/{id}{?events}",
], templates
by_uri = {r["uri"]: r for r in both["resources"]}
assert by_uri["hhstream://status"]["mimeType"] == "text/plain"
assert by_uri["hhstream://sessions"]["mimeType"] == "application/json"
# The idle-clock rule is on the reads it applies to.
assert "does NOT reset" in by_uri["hhstream://sessions"]["description"]
with subtest("a resource read reaches the broker and returns its object"):
try:
contents = read("hhstream://sessions")
assert len(contents) == 1, contents
assert contents[0]["mimeType"] == "application/json"
# The body is the CLI's own `--json` output, unmodified.
listing = json.loads(contents[0]["text"])
assert listing["ok"] is True, listing
assert "sessions" in listing, listing
except Exception:
dump("reading hhstream://sessions")
raise
with subtest("the status resource answers without the broker's help"):
# It reads the compositor's units and the frame socket, not the
# control socket -- which is why it is the thing to read first.
contents = read("hhstream://status")
assert contents[0]["mimeType"] == "text/plain"
report = contents[0]["text"]
print(report)
assert "hyprland-headless.service" in report
assert "frame:" in report
with subtest("a session started over mcp is the broker's own session"):
try:
started = succeeded("session_start", {"app": "foot"}, timeout=300)
session_id = started["structuredContent"]["id"]
print(f"started {session_id}")
assert text_of(started).startswith(f"session id: {session_id}")
# The broker is the authority on whether that happened, so it
# is asked directly rather than through the server under test.
listing = cli_json("list --json")
assert session_id in [s["id"] for s in listing["sessions"]], listing
except Exception:
dump("session_start over mcp")
raise
with subtest("reading a session does not reset its clock; touching it does"):
# The rule the whole surface repeats, measured rather than asserted
# about: two reads of the resource, then the tool, and the deadline
# has to move only for the tool.
try:
def expires_in():
body = json.loads(read(f"hhstream://sessions/{session_id}")[0]["text"])
return body["session"]["expires_in_s"]
first = expires_in()
second = expires_in()
assert second <= first, (
f"reading hhstream://sessions/{session_id} reset the idle "
f"clock: {first} -> {second}"
)
touched = succeeded("session_touch", {"id": session_id})
assert (
touched["structuredContent"]["session"]["expires_in_s"] >= second
), touched
except Exception:
dump("the idle clock over mcp", session_id)
raise
with subtest("a session's logs read through its template, with a query"):
try:
contents = read(f"hhstream://sessions/{session_id}/logs?lines=5")
body = json.loads(contents[0]["text"])
assert body["ok"] is True, body
assert "lines" in body, body
print(f"{len(body['lines'])} line(s) of {session_id}'s own output")
except Exception:
dump("reading a session's logs", session_id)
raise
with subtest("shot returns image content, sized as the publisher serves it"):
# MEASURED, and not what this check first assumed: the frame is
# 2560x720 on a guest configured for 1280x720. The publisher's
# default capture is `grim -t png -` with no `-o`, which takes the
# whole compositor layout -- and with containers on (the module's
# default) a session's own output sits beside the main one, so one
# session doubles the width. The geometry the module configures is
# the geometry of an *output*, which is what the next subtest
# captures by name.
try:
shot = succeeded("shot", timeout=300)
kinds = [block["type"] for block in shot["content"]]
assert kinds == ["text", "image"], kinds
image = shot["content"][1]
frame = base64.b64decode(image["data"])
print(f"{image['mimeType']}, {len(frame)} bytes: {text_of(shot)}")
assert image["mimeType"] in ("image/png", "image/jpeg")
# The media type is read off the bytes, never off the extension
# this server asked the CLI for -- so the two must agree.
magic = {"image/png": b"\x89PNG", "image/jpeg": b"\xff\xd8\xff"}
assert frame.startswith(magic[image["mimeType"]]), frame[:8]
reported = shot["structuredContent"]
assert reported["height"] == HEIGHT, reported
assert reported["width"] >= WIDTH, reported
assert reported["bytes"] == len(frame), reported
assert len(frame) > 1024, "a frame that small is not a desktop"
except Exception:
dump("shot over mcp", session_id)
raise
with subtest("the container is listed as a resource and reconciled as a tool"):
# The pair that has to stay split: the LIST only reads the record,
# so it is a resource; asking where the window is *now* re-reads the
# compositor and writes the answer back, so it is a tool. Both are
# asked here, and they have to agree about the output's name.
try:
listed = json.loads(read("hhstream://containers")[0]["text"])
assert listed["ok"] is True, listed
from_resource = [
c["output"] for c in (listed.get("containers") or [])
]
print(f"containers resource reports: {from_resource}")
assert f"hh-{session_id}" in from_resource, listed
reconciled = succeeded("session_container", {"id": session_id})
output = reconciled["structuredContent"]["container"]["output"]
assert output == f"hh-{session_id}", reconciled
except Exception:
dump("the container, both ways", session_id)
raise
with subtest("one output's frame reads as a blob, at exactly its own size"):
# The resource that is an image, and the one place the configured
# geometry is the geometry: `hhstream://screen` is the whole layout.
try:
output = f"hh-{session_id}"
contents = read(f"hhstream://outputs/{output}", timeout=300)
assert len(contents) == 1, contents
blob = contents[0]
assert blob["mimeType"] in ("image/png", "image/jpeg"), blob
assert "text" not in blob, "an image must not arrive as text"
frame = base64.b64decode(blob["blob"])
print(f"{output}: {blob['mimeType']}, {len(frame)} bytes")
assert frame[:4] in (b"\x89PNG", b"\xff\xd8\xff\xe0")
assert len(frame) > 1024, "a frame that small is not a desktop"
# And the tool agrees about the size, which is what makes the
# pointer's normalised coordinates meaningful.
framed = succeeded("shot", {"output": output}, timeout=300)
reported = framed["structuredContent"]
print(text_of(framed))
assert (reported["width"], reported["height"]) == (WIDTH, HEIGHT), reported
except Exception:
dump("reading an output's frame", session_id)
raise
with subtest("the pointer lease is granted, used and given back"):
try:
acquired = succeeded("pointer_acquire", {"id": session_id})
lease = acquired["structuredContent"]["lease_id"]
print(f"lease {lease}: {text_of(acquired).splitlines()[0]}")
assert text_of(acquired).startswith(f"lease_id: {lease}")
# Every gesture takes the lease as an explicit argument: the
# server caches nothing, which is what makes a transcript of
# tool calls readable.
succeeded("pointer_move", {"id": session_id, "lease": lease, "to": [0.5, 0.5]})
succeeded("pointer_click", {"id": session_id, "lease": lease})
succeeded("keyboard_type", {"id": session_id, "lease": lease, "text": "hello"})
typed = succeeded(
"keyboard_key", {"id": session_id, "lease": lease, "name": "Return"}
)
assert typed["structuredContent"]["ok"] is True, typed
released = succeeded("pointer_release", {"id": session_id, "lease": lease})
assert released["structuredContent"]["ok"] is True, released
# And the broker agrees that nobody holds it now.
assert cli_json("pointer state --json")["holder"] is None
except Exception:
dump("the pointer lease over mcp", session_id)
raise
with subtest("a gesture after the release is exit 9 and says to acquire"):
# The frozen NO_LEASE code, arriving as a tool error an agent can
# act on rather than as a success with a sad message in it.
refused = call("pointer_click", {"id": session_id, "lease": lease})
assert refused["isError"] is True, refused
assert refused["structuredContent"]["exit_code"] == 9, refused
said = text_of(refused)
print(said.splitlines()[0])
assert "exit 9 (NO_LEASE)" in said
assert "pointer_acquire" in said
with subtest("an unknown session is exit 3 from a tool, not a success"):
refused = call("session_touch", {"id": "no-such-session"})
assert refused["isError"] is True, refused
assert refused["structuredContent"]["exit_code"] == 3, refused
assert "hhstream://sessions" in text_of(refused)
with subtest("a refused read is a protocol error carrying the same remedy"):
# A resources/read has no `isError`, so this is the one place the
# refusal has to travel as an error -- with the exit code intact,
# or an agent cannot tell "no such session" from "broker down".
error = read_refused("hhstream://sessions/no-such-session")
print(error["message"].splitlines()[0])
assert error["data"]["exit_code"] == 3, error
assert error["data"]["error"] == "no_such_session", error
assert "exit 3 (NO_SUCH_SESSION)" in error["message"]
with subtest("a uri this server does not serve is refused without running anything"):
error = read_refused("hhstream://nonsense")
assert "no resource at" in error["message"], error
# And an undeclared query parameter, which the routing refuses for
# the reason every tool schema sets additionalProperties: false.
error = read_refused("hhstream://pointer?id=x")
assert "accepts: none" in error["message"], error
with subtest("an argument the schema refuses never reaches the broker"):
# No `lease`, so the server's own schema refuses before an argv list
# exists. The CLI is not run at all, which is the point.
refused = call("keyboard_type", {"id": session_id, "text": "x"})
assert refused["isError"] is True, refused
assert "lease" in text_of(refused), refused
with subtest("--toolsets narrows the tools and leaves the resources alone"):
# The flag exists because a tool listing is a budget. What it must
# not do is take the host's context away with it.
narrowed = json.loads(
machine.succeed(
as_user(f"{MCP} --server-arg=--toolsets=keyboard --list"),
timeout=180,
)
)["tools"]
names = sorted(tool["name"] for tool in narrowed)
print(f"--toolsets keyboard offers: {', '.join(names)}")
assert names == [
"keyboard_down", "keyboard_key", "keyboard_type", "keyboard_up",
], names
still_there = json.loads(
machine.succeed(
as_user(f"{MCP} --server-arg=--toolsets=keyboard --resources"),
timeout=180,
)
)
assert len(still_there["resources"]) == 5, still_there
assert len(still_there["resourceTemplates"]) == 3, still_there
# And a tool outside the selection must be unreachable, not merely
# unlisted, or the flag is cosmetic.
refused = json.loads(
machine.succeed(
as_user(
f"{MCP} --server-arg=--toolsets=keyboard session_kill "
+ shlex.quote(json.dumps({"id": session_id}))
),
timeout=180,
)
)
assert refused["isError"] is True, refused
assert "without its toolset" in text_of(refused), refused
with subtest("kill over mcp ends the session the broker was tracking"):
try:
killed = succeeded("session_kill", {"id": session_id}, timeout=300)
print(text_of(killed))
assert killed["structuredContent"]["ok"] is True, killed
live = [s["id"] for s in cli_json("list --json")["sessions"]]
assert session_id not in live, live
except Exception:
dump("session_kill over mcp", session_id)
raise
'';
}
)
+33 -1
View File
@@ -32,9 +32,18 @@
│ AF_UNIX control.sock, mode 0660
▼
hhstream session ... (the CLI an agent drives)
▲
│ in-process: argv in, exit code out
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│
└───────────────────────────┘
```
Five pieces, deliberately separate:
Five pieces, deliberately separate, and a sixth that is deliberately not a
piece at all:
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
outputs. It knows nothing about frames on a socket.
@@ -53,6 +62,29 @@ Five pieces, deliberately separate:
a separate process because a Wayland client needs its own connection and a
driver blocked on the compositor must not stall session lifecycle.
And the sixth, which is a *shim* and not a layer:
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
Model Context Protocol surface on it, so an agent reads state by URI and
acts by calling tools instead of writing command lines. It is drawn above
the CLI rather than beside the broker because that is where it sits: every
tool and every resource builds the argv list the CLI's parser takes and runs
the CLI's own handler **in the same process**, and it is the one component
here that owns no state at all — not even the pointer lease, which is an
explicit argument on every gesture tool. Add it to the diagram's list of
things that can go wrong and nothing new appears: every failure it reports
is the CLI's or the broker's, carrying their exit code.
The split between its two halves is *who decides*, not what it costs. A
resource is the host's to include (`hhstream://sessions` is state anyone may
want in context); a tool is the model's to call (`session_kill` is a
decision). That is why `shot` is both — a tool because deciding to look is
an act, and `hhstream://screen` because a frame is also just state.
It is also the only part with a third-party dependency (the `mcp` SDK),
which is why it is a separate derivation (`nix/mcp.nix`) and why
`packages.hhstream` — the compositor's own units — keeps the closure it had.
## Why containers are outputs
A session's container is a headless **output**, not just a workspace, and the
+382
View File
@@ -0,0 +1,382 @@
# CONTRACT — the MCP server (mcp-v2)
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
the arguments each takes, what comes back, and which of the CLI's exit codes
arrives as which kind of MCP error. It is the sibling of `docs/CONTRACT.md` (the
frame socket's wire format) and `docs/CONTRACT-sessions.md` (the broker, the
containers and the input lease).
**Immutable without a version bump.** An agent that has learned these names and
these argument shapes is a consumer like any other, and renaming a tool breaks
it exactly as renaming a wire verb would.
Version: mcp-v2 (2026-10-11). v1 was the first freeze and lasted one day.
**v2 is a breaking change, and the only one: the verbs that merely read are
resources now, not tools.**
| § | Change | Why |
| --- | --- | --- |
| §3, §4 | `status`, `session_list`, `session_status`, `session_logs` and `pointer_state` are **removed from the tool list** and are `hhstream://…` resources instead. 26 tools became 21. | The protocol's own split. 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. Nothing in those five acts. |
| §4 | Eight resources: five fixed, three templates, with query parameters for the arguments the verbs took. | A resource read takes nothing but a URI, so `--lines` becomes `?lines=`. Only declared parameters are accepted. |
| §5 | A refused resource read is a **protocol error** carrying the same remedy a tool error would have. | `CallToolResult` has `isError`; `ReadResourceResult` has nothing. Returning the broker's failure object as the body would make "no such session" read as a successful read of a session. |
| §3 | `--toolsets` selects which families are listed as tools. | A tool listing is a budget. MCP has no grouping primitive — the `Tool` object has nowhere to put one — so the only lever is which tools the *server* lists, chosen at launch. |
What did **not** move, and the reasons are the interesting part:
* **`shot` and `record` are still tools**, though neither changes the desktop.
Capturing is an act at a moment: an agent in a loop has to be able to decide
to look *now*, and in many clients a resource is something a person attaches
rather than something a model can fetch on its own initiative. The same frames
are *also* readable as `hhstream://screen` and `hhstream://outputs/{name}`,
for a host that wants to put one in context itself.
* **`session_container` is still a tool**, for a harder reason: with an id the
CLI runs `container.reconcile`, which re-reads the compositor and writes the
record back. It is not a read at all. Only the no-id form is a resource
(`hhstream://containers`). A resource read must never write.
## 0. What this is, and what it is not
It is a **shim**. Each tool and each resource builds the argv list the `hhstream`
CLI's own parser takes, hands it to the CLI's own handler **in this process**,
and maps what came back. Nothing in it decides anything:
| Rule | Whose it is |
| --- | --- |
| the idle clock, and that only `touch` resets it | the broker |
| the pointer lease: who holds it, its TTL, what it lifts | the broker |
| the allowlist, and which arguments an app may be given | the broker's policy |
| the exit-code table | `docs/CONTRACT-sessions.md` §4 |
| the refusal messages (`reason`, `hint`) | the CLI and the broker |
| coordinate normalisation, the scroll bound, the type cap | the broker and the driver |
What this layer owns is the argv list, the routing of a URI to one of them, the
mapping of a result to MCP content, and one sentence of *remedy* per exit code —
the "what to do next" that the CLI says to a human in the words of a command
line and an agent needs in the words of tools and resources.
In process, not as a subprocess: `hhstream.cli` is importable Python whose
parser already takes an argv list and whose handlers already return a code from
the frozen table. Two of its paths cannot be called here, and both are
documented in `hhstream_mcp.invoke`: `cli.main`'s `sg` re-exec, and `cmd_run`'s
`execvpe`. Consequences of the first are in §5.
## 1. Transport
**stdio, and only stdio.** One process per client, spawned by the client; no
port, no daemon, no socket of its own. There is already a daemon in this system
and it owns all the state.
The protocol is **not on file descriptor 1** once the server is running: the
tools run the CLI in process, the CLI prints, and `record` spawns an `ffmpeg`
whose output the CLI does not capture. The server takes a private duplicate of
stdin and stdout at start-up, then points fd 1 at its log and fd 0 at
`/dev/null`. A stray write is therefore a log line and never a corrupted
stream.
## 2. Configuration
There is no `--socket` flag. The sockets are the CLI's own environment, read by
the CLI:
| Variable | What it names | Default |
| --- | --- | --- |
| `HHSTREAM_SOCKET` | the broker's control socket | `/run/hhstream/control.sock` |
| `HHSTREAM_FRAME_SOCKET` | the published frame socket | `/run/hypr-stream/stream.sock` |
Set them in the MCP client's `env` block. One place to configure them is one
place for them to be wrong.
The server's own command line:
| flag | what it does |
| --- | --- |
| `--toolsets NAMES` | comma-separated families to offer as **tools**: `frames`, `sessions`, `pointer`, `keyboard`. Omitted, every tool is offered. An unknown name is argparse's exit 2, never a silently empty server. **Resources are not filtered by it** — they are the host's context, not the model's tool budget, and making `hhstream://sessions` conditional on the session *tools* would couple two decisions that are not the same decision. |
| `--list-tools` | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
| `--list-resources` | print the resource URIs and templates and exit. |
`$HHSTREAM_MCP_LOG` sets the log level on stderr. Nothing else affects
behaviour; in particular the server holds no state and caches no lease.
**There is no grouping primitive in MCP**, and `--toolsets` is not pretending to
be one. The `Tool` object carries `name`, `title`, `description`,
`inputSchema`, `outputSchema`, `icons`, `annotations`, `_meta` and `execution` —
nowhere to put a family. Tools are a flat list in the specification too. So the
only honest lever is which tools the *server* lists, decided by whoever spawns
it, and the families below are the grouping that is left: a prefix in the name
and a line in this table.
## 3. The tool surface
**One tool per CLI verb that acts**, named after it, with `_` where the CLI has
a space. Twenty-one tools, in four families. The granularity rationale — and
the alternative that was rejected, one tool per family with an `action` enum —
is in `hhstream_mcp.tools`' docstring.
Every schema sets `additionalProperties: false`, so an argument this server
would not pass through is refused by the schema rather than dropped on the way
to an argv list.
| family | tools |
| --- | --- |
| `frames` | `shot`, `record`, `run` |
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
Every tool is in exactly one family — asserted by a unit test, because a tool in
none of them would be one `--toolsets` could never offer.
### Frames
| Tool | Arguments | Returns |
| --- | --- | --- |
| `shot` | `output?` | **image content** (PNG or JPEG, by the bytes' own magic) plus text naming the geometry, the media type and the byte count |
| `record` | `seconds?`, `out?`, `output?`, `fps?`, `work_dir?`, `keep?` | the artefact's **path** and the *measured* rate — never the video |
| `run` | `argv`, `settle_s?` | the application's pid, and that it is unmanaged |
`shot` captures to a temporary file and reads it back, because that is the CLI's
only output shape. The media type comes from the bytes and not from the
extension: the publisher serves `image/jpeg` on some machines and `hhstream
shot` writes the payload it was given verbatim.
`record` hands back a path because an mp4 of a 720p desktop is megabytes and a
tool reply is a message in a model's context. The rate is the one the capture
measured, read off the CLI's own line.
`run` is spawned with `posix_spawn` into its own session and not waited for.
`settle_s` (default 1.5) is how long the server watches it before reporting the
pid: a launch that fails — no Wayland socket, no such executable — fails inside
that window and comes back as an error, one that survives it comes back as
running.
### Session lifecycle
| Tool | Arguments |
| --- | --- |
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
| `session_touch` | `id` |
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
| `session_gc` | `request_id?` |
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` |
| `session_container` | `id` |
| `session_reconcile` | `id?`, `request_id?` |
Every one of these runs with `--json`, so what comes back is the broker's own
protocol object: in the text part verbatim, and in `structuredContent` parsed.
The human rendering is a table for a terminal; scraping it would be inventing a
second wire format.
`home` and `ephemeral_home` are mutually exclusive, and the schema says so —
the CLI's argparse group, moved forward to where the refusal is free.
`session_container` is **not** marked read-only, and that is not an oversight:
with an `id` the CLI runs `container.reconcile`, which writes the record back.
That is also why it is a tool rather than a resource. The no-id listing, which
only reads, is `hhstream://containers`.
### Input — the pointer lease is an argument, never a cache
| Tool | Arguments |
| --- | --- |
| `pointer_acquire` | `id`, `ttl?`, `no_restore?` |
| `pointer_move` | `id`, `lease`, exactly one of `to` / `by` (each `[x, y]`) |
| `pointer_click` | `id`, `lease`, `button?` |
| `pointer_scroll` | `id`, `lease`, `axis?`, `amount?` |
| `pointer_down` | `id`, `lease`, `button?` |
| `pointer_up` | `id`, `lease`, `button?` |
| `pointer_release` | `id`, `lease` |
| `keyboard_type` | `id`, `lease`, `text` |
| `keyboard_key` | `id`, `lease`, `name` |
| `keyboard_down` | `id`, `lease`, `name` |
| `keyboard_up` | `id`, `lease`, `name` |
**`lease` is required on every gesture.** The CLI caches the lease id between
invocations (`hhstream_session.lease`) because its surface is flagless and it is
one process per verb; this server passes `--lease` explicitly on every call and
so never reads that cache. The reason is worth stating in full: a cached lease
is a lease an agent cannot see, and the failure it
produces — a gesture that went to a lease the agent did not know it held — is
not one a transcript can explain.
`pointer_acquire`'s reply puts `lease_id` on the first line of the text part,
because that is what the next call needs.
Who *holds* the lease is a read, so it is `hhstream://pointer` rather than a
tool. That is the resource to read after an exit 8.
Durations (`ttl`, `idle_timeout`, `wait_ready`, `grace`) are **strings** in the
CLI's own vocabulary: `30s`, `5m`, `3h`, `2d`, or a bare number of seconds.
They are passed through untouched, so the parsing and the refusal are the CLI's.
### Flag form
Every option value is passed as one `--name=value` token, and a literal `--`
precedes every positional. Not a style choice: `--by -0.1,0.5` and a `text`
beginning with a dash are both values argparse reads as option strings, and one
uniform rule is one fewer thing to get wrong per flag.
## 4. The resource surface
Five fixed resources and three templates, all under one scheme, because they
are all views of one machine's one desktop. Every one of them runs the same CLI
verb a tool would have, with `--json` where the verb has it.
| URI | Body | Query |
| --- | --- | --- |
| `hhstream://status` | `text/plain` — the CLI's own report: both compositor units, the frame socket's path and whether this server can read it, the Wayland socket, one probe frame. `hhstream status` has no JSON form, so neither does this. | — |
| `hhstream://sessions` | `application/json` — the broker's `list` object | `?all=true` includes tombstones |
| `hhstream://pointer` | `application/json` — the holder, since when, and the buttons and **keys** held | — |
| `hhstream://containers` | `application/json` — every container plus the orphan `hh-*` outputs. The **listing** only; see §3. | — |
| `hhstream://screen` | the published main output as an image blob. With containers on this is the whole compositor layout, so it is **wider than any single output's configured size**. | — |
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
Rules this surface keeps:
* **A read never writes.** That is what excludes `session container <id>`.
* **Only declared query parameters are accepted.** An unknown one is refused,
for the reason every tool schema sets `additionalProperties: false`: a
parameter silently ignored is a read that answered a different question from
the one asked. A parameter given twice is refused too.
* **A literal route beats a template.** `hhstream://sessions` is the listing,
not a session whose id happened to be empty.
* **The media type of a frame is read off the bytes**, never off the extension
the server asked the CLI for. The entry's declared `mimeType` is a hint; the
`ReadResourceContents` carries the answer.
* **No subscriptions.** `Server.get_capabilities` in the pinned SDK hardcodes
`ResourcesCapability(subscribe=False, …)` — it never advertises `subscribe`
even if a handler is registered. So resource subscription is *not* available
as the answer to the missing `logs --follow`, which is a shame, because it
would have been the right one. Read it again instead.
## 5. What is deliberately absent
| Not exposed | Why |
| --- | --- |
| `session logs --follow` | it polls until interrupted, and a tool call that never returns hangs the client that made it. Read `hhstream://sessions/{id}/logs` again. Resource *subscriptions* would have been the principled fix; see §4. |
| `session start --no-container` | the CLI's flag exists in order to *refuse*: the broker's `start` verb carries no such field (`docs/CONTRACT-sessions.md` §4), so the CLI exits 2 and names the disagreement. A tool argument whose only possible outcome is a refusal is a trap. |
| `hhstream --frame-socket` / `session --socket` | §2: the environment configures them, in one place. |
| a per-call timeout | §6. |
| `session keyboard` with no verb | it prints help and exits 2. There is nothing for a tool to do with that. |
## 6. Error mapping
Every refusal the CLI produces on a **tool call** comes back as a tool error —
`CallToolResult` with `isError: true` — carrying:
- the remedy sentence, first, naming the code: `exit 9 (NO_LEASE): …`;
- the CLI's own `error`, `reason` and `hint` when it printed a protocol object;
- everything it said, verbatim, under `hhstream said:`;
- `structuredContent` with `ok: false`, `exit_code`, `remedy`, and the
protocol object's own fields.
`isError` and not a JSON-RPC error, for tools, throughout. A JSON-RPC error
reaches the client's log; "another session holds the lease" is something the
calling agent has to read and act on. (The SDK's `call_tool` handler also
converts anything raised into `isError`, so this is the only channel there is in
practice.)
On a **resource read** it is the other way round, and not by preference:
`ReadResourceResult` has no `isError`, so a refusal is raised as a JSON-RPC
error with code `-32602` (`INVALID_PARAMS`), its `message` carrying the same
remedy-then-the-CLI's-own-words text and its `data` carrying the same
`{ok, exit_code, error, reason, hint, remedy}` object. Returning the broker's
failure object as the resource's *body* would make "no such session" read as a
successful read of a session, which is the one outcome a contract has to
forbid. The same error is raised for a URI that names nothing and for an
undeclared query parameter — in both cases before the CLI is reached at all.
"Arrives as" below is for a tool call; on a resource read every one of them is
the protocol error above, with the same remedy.
| Exit | Name | Arrives as | The remedy an agent is given |
| --- | --- | --- | --- |
| 0 | OK | a result | — |
| 1 | *not in the frozen table* | tool error | the frame verbs' own failure: no frame published, or `grim`/`ffmpeg` missing from the server's PATH. Also what an uncaught exception in a handler becomes, with its traceback — which is what a CLI process would have done. |
| 2 | USAGE | tool error | fix the arguments; a retry fails identically |
| 3 | NO_SUCH_SESSION | tool error | read `hhstream://sessions` to see which ids exist |
| 4 | BAD_STATE | tool error | read `hhstream://sessions/<id>` to see which state |
| 5 | DAEMON_UNREACHABLE | tool error | an operator problem; the three frame tools and `hhstream://status` may still work |
| 7 | TIMEOUT | tool error | read the state back, then retry with the same `request_id` |
| 6 | POLICY | tool error | a configuration decision; no retry changes it |
| 8 | BUSY | tool error | read `hhstream://pointer` for the holder; wait. **Never** "acquire one" |
| 9 | NO_LEASE | tool error | `pointer_acquire`, then pass the new `lease_id` |
| 10 | COMPOSITOR | tool error | the session is **not** lost; it is degraded |
8 and 9 must never read alike, and a unit test holds them apart: an agent that
sees 8 must wait, one that sees 9 must acquire.
Two failures are not the CLI's verdict and are reported in the same channel
anyway, because the agent holding the tool is the one who has to say so:
- a tool name that does not exist — the reply names the ones that do;
- an argument the schema rejects — the SDK refuses before an argv list exists,
so the CLI is never reached.
**The `sg` re-exec is not available here.** `hhstream` recovers from an
unreadable frame socket by re-executing itself through the setuid `sg` wrapper
to join the compositor's group. That is an `exec`, and performing it would
replace this server and drop the client's connection. So a frame verb that
cannot reach the socket fails with the CLI's own message plus a sentence saying
what the CLI would have done and how to avoid needing it: run the server as a
member of that group (`sg hhstream -c hhstream-mcp` in the client's spawn
command, or add the account to the group). The hint is added only when the
condition is actually true, asked of the CLI's own predicate, and only for the
verbs it could be true of.
**There is no per-call timeout.** In process there is nothing to kill: a thread
cannot be interrupted. The deadlines are therefore the ones that already exist
— the session client's 60 s socket timeout, the broker's per-verb deadline, and
the frame socket's own `--timeout` — and a call that outlives all of them
outlives this server too. A subprocess design could have killed it; that is the
one thing given up by calling the CLI in process.
## 7. Concurrency
Tool calls are **serialised**. The CLI prints to a process-global `sys.stdout`,
so two concurrent calls would interleave their output into each other's reply.
One lock around the whole call is the honest fix, and costs nothing a caller
would notice: the broker already serialises every mutation, and the CLI was one
process per verb anyway. The event loop stays free, so a `ping` is answered
while a `record` runs.
## 8. The two rules, which every relevant tool and resource repeats
These are `hhstream_session.ACTIVITY_NOTE` and `KEYBOARD_LEASE_NOTE` restated
in terms of this surface. They are on the individual tools and resources and
not only in the server instructions, because a client shows a thing's own
description at the point of use:
1. **`session_touch` is the only thing that resets a session's idle clock.**
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
session being driven is still a session nobody has said they want kept. The
three resources it applies to say so in their own descriptions, because a
description is what a host shows beside the thing it describes.
2. **Every keyboard tool needs the pointer lease, and holds only while it
holds.** There is no keyboard lease: one compositor seat means one keyboard
focus. A held non-modifier key floods the window until it is lifted or the
lease expires, because the *application* does the repeating — measured at 25
a second after 600 ms — and this server cannot rate-limit what it does not
generate.
`tests/unit/test_mcp_tools.py` asserts both notes are present on every tool they
apply to and holds the CLI's own constants as a tripwire against drift;
`tests/unit/test_mcp_resources.py` does the same for the five reads the first
rule applies to.
## 9. Packaging
`packages.hhstream-mcp` (`nix/mcp.nix`), a separate derivation from
`packages.hhstream` because `mcp` is a third-party dependency and the frame
socket, the CLI and the broker are stdlib-only by policy. `packages.hhstream`
must not grow that dependency; the root `pyproject.toml` excludes
`hhstream_mcp*` from its package discovery so it cannot acquire it by accident.
`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the
binary on the system PATH. That is the whole of the option: there is no unit, no
socket and no state directory, because the server is spawned per client over
stdio.
+162 -11
View File
@@ -1,4 +1,4 @@
# CONTRACT — sessions build (sessions-v3)
# CONTRACT — sessions build (sessions-v4)
This file is the interface for the **session** work: the broker, containers,
compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which
@@ -9,11 +9,31 @@ else. If something here is wrong or missing, **stop and report it in your final
message** — the parent edits this file, not you. Do not widen your slice to work
around a gap.
Version: sessions-v3 (2026-10-04). v1 was the freeze the four slices built
Version: sessions-v4 (2026-10-11). v1 was the freeze the four slices built
against; v2 recorded the decisions their reports asked for; v3 adds the
keyboard. Every change in both has been an addition or a clarification — **no
v1 or v2 signature changed meaning** — so earlier code stays valid except where
noted.
keyboard; v4 adds the **per-session live stream**. Every change in all of them
has been an addition or a clarification — **no v1, v2 or v3 signature changed
meaning** — so earlier code stays valid except where noted.
v4 changes, all of them the stream
(`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2):
| § | Change | Why |
| --- | --- | --- |
| §3.5 | New: `hhstreamd/live.py`, the broker's end of `/run/hhstream/live.sock`, and that socket's wire format. | The stream is captured by `hhstream-live`, a third executor beside the pointer driver. `grim` blocks tens to hundreds of milliseconds, so it must not run in the broker, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. The broker therefore *tells* a process what to publish, exactly as it tells the driver where to warp. |
| §4 | Verbs `stream.enable`, `stream.disable`, `stream.list`, `stream.status`. `enable` and `disable` are in the mutation set; `list` and `status` are not. | `enable` mints or rotates a phrase and opens a capture — a retried `enable` that minted a second phrase would invalidate the URL somebody is already holding. |
| §4 | `start` gains `stream?`, `stream_phrase?` and `stream_fps?`. | A stream needs the session's container output, which `start` creates; sequencing "start, then enable" in a *caller* means every caller repeats the ordering and the failure handling. One request, one answer, and the phrase comes back with the session. |
| §4 | **A connected viewer is activity.** The broker asks the daemon for viewer counts about once a minute and stamps `touch` when any is non-zero. | The one new way the idle clock moves, and the only exception to "`touch` is the only mark of activity" since that rule was written. A session an operator is watching on his phone must not be reaped at three hours *because* watching is all he is doing. An enabled stream with **no** viewer runs no `grim` and keeps nothing alive, so this cannot hold a session open by itself. |
| §4 | Error names `stream_unavailable` (exit 10), `stream_busy` (exit 8), `stream_budget` (exit 6). **No new exit numbers.** | The failures are the ones the table already has: no container is a compositor-side failure, a phrase collision is a busy, a viewer cap is a policy budget. |
| §5 | `/run/hhstream/live.sock`, the unit `hhstream-live`, and the stream port 9988. | Named here with the other frozen paths, because two processes have to agree on them. |
| §6 | Registry **schema 3 → 4**: the record gains `stream`. | A phrase has to survive a broker restart and a re-enable, so it lives in the record. Older records migrate to `stream: null` and are adopted, not refused. |
v4 deliberately does **not** give the broker the port, the bind address or the
capture command. Those are the daemon's, from its own unit's argv, for the
reason the keyboard layout is the driver's: the broker's TOML is read by
`hhstreamd`, and a setting an operator could change in it while the listener
stayed where it was would be worse than no setting at all. The broker learns
the URL prefix *from* the daemon, in the `attach` reply.
v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as
amended by `docs/plans/2026-10-04-keyboard-verification.md`):
@@ -375,6 +395,79 @@ the lease; a real-compositor case is still missing — see
lease state** — the broker owns the lease; the driver is an executor that must
never be trusted to serialise anything.
### 3.5 `hhstreamd/live.py` (v4) — the broker's end of the stream daemon
A third executor beside the pointer driver, and the same shape as §3.4: the
broker holds the *decision* (which session streams, under which phrase) and the
daemon holds the *capture*. `hhstream-live` owns the port, the bind address and
the capture command, from its own unit's argv; the broker never passes them and
never reads them from its own TOML.
```python
class LiveUnavailable(Exception):
"""The stream daemon could not be reached, or did not answer intelligibly."""
class LiveRejected(Exception):
"""The daemon refused. `kind` maps to an exit code, as the driver's does."""
def __init__(self, message: str, *, kind: str | None = None) -> None: ...
@dataclass(frozen=True)
class Attachment:
phrase: str; output: str; fps: int; session: str | None
url: str # the daemon's own prefix, e.g. http://127.0.0.1:9988/<phrase>/
viewers: int
class LiveStreams:
def __init__(self, socket_path: Path | str, *, timeout_s: float = 2.0) -> None: ...
def attach(self, *, phrase: str, output: str, fps: int,
session: str | None = None, label: str = "") -> Attachment: ...
def detach(self, phrase: str) -> bool: ... # False if it was not attached
def list(self) -> list[Attachment]: ...
def viewers(self) -> dict[str, int]: ... # phrase -> connected viewers
def close(self) -> None: ...
```
Private socket protocol, newline-delimited JSON, the driver's conventions
exactly — `{"ok": true, …}` or `{"ok": false, "error": "…", "kind": "…"}`:
```json
{"op": "attach", "phrase": "amber-otter-lantern-harbor-7k2qp", "output": "hh-x",
"session": "x", "label": "chromium", "fps": 5} // fps is OPTIONAL
-> {"ok": true, "stream": {"phrase": "…", "output": "hh-x",
"fps": 5, "session": "x", "url": "http://…/", "viewers": 0}}
{"op": "detach", "phrase": "…"} -> {"ok": true, "detached": true}
{"op": "list"} -> {"ok": true, "streams": [ {…}, … ]}
{"op": "viewers"} -> {"ok": true, "viewers": {"<phrase>": 2}}
```
Four rules that are not interchangeable:
- **The daemon holds no session state and no idea of an idle clock.** It
publishes what it was told to publish. `viewers` is a *reading*, and what the
broker does with it (§4) is the broker's.
- **`fps` is optional, and omitting it is the normal case.** The default rate is
the daemon's, from its own unit's argv (`sessions.stream.fps`), for the same
reason the port is. The broker sends one only when a caller named one, or
when re-attaching a stream that already had one. A broker that sent its own
default on every attach would make the operator's option a setting that
changed nothing — the same failure `--xkb-layout` (§3.4) exists to avoid.
- **`attach` is idempotent on the phrase.** Re-attaching the same phrase to the
same output returns the existing stream rather than starting a second
capture, because a re-`enable` after a broker restart must not double the
`grim` rate on one output. The same phrase aimed at a *different* output is
`{"kind": "invalid_argument"}`.
- **The phrase is never logged by either side.** It is the stream's only
credential. The daemon logs the output and the viewer count; the broker's
audit log records the session and the output (§4), and neither records the
phrase.
`url` comes back from the daemon rather than being built by the broker, for the
reason the port is the daemon's: a URL the broker assembled from a port it was
told about once is a URL that silently lies the first time an operator moves
the listener.
---
---
## 4. Wire format (broker control socket) — B, C and D do not implement this
@@ -395,6 +488,44 @@ code will be called with):
| `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` |
| `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` |
| `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` |
| `stream.enable` (v4) | `id`, `phrase?`, `fps?` | `stream` |
| `stream.disable` (v4) | `id` | `stream`, `detached` |
| `stream.list` (v4) | — | `streams[]`, `available` |
| `stream.status` (v4) | `id?` | `stream` \| `streams[]` |
**v4, the stream.** `stream.enable` and `stream.disable` are in the
`request_id` mutation set; `stream.list` and `stream.status` are not.
`start` additionally accepts `stream?` (bool), `stream_phrase?` and
`stream_fps?`, and when `stream` is true its reply's session carries the same
`stream` object `stream.enable` would have returned.
The `stream` object is the record's, with the daemon's `url` and `viewers`
merged in when it could be asked:
```json
{"enabled": true, "phrase": "amber-otter-lantern-harbor-7k2qp",
"output": "hh-x", "fps": 5, "port": 9988,
"url": "http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/",
"viewers": 0, "enabled_at": "2026-10-11T…Z", "attached": true}
```
`attached` is its own field and is **not** folded into `enabled`: a record may
say a session is enabled while the daemon is down, and "the operator asked for
this stream" and "a capture is running right now" are two different facts. A
caller that wants the second one reads `attached`; `url` and `viewers` are
absent when it is false, rather than stale.
**`stream.enable` requires the session's container output.** Without one it is
`stream_unavailable` (exit 10). A stream never falls back to the main output:
that output carries every other session, and putting it on a phone is the one
mistake this feature must not make. Re-enabling an enabled session returns the
same phrase; a `phrase` that differs from the stored one is `stream_busy`
(exit 8). `disable` then `enable` rotates it.
**Teardown order is load-bearing.** `kill` detaches the stream *before*
`hyprctl output remove`, because a capture aimed at a removed output fails every
time and the daemon's own failure budget would close the viewers with
"unknown output" instead of "the session ended".
**v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is
no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard
@@ -417,10 +548,26 @@ explicitly rather than inheriting.
| 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE |
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` **and
`keyboard.*`** verb do **not** reset the idle clock. A session being typed into
is still a session nobody has said they want kept.
**v4 adds error names and no numbers.** `stream_unavailable` → 10 (no
container, or the daemon is unreachable — the session itself is fine either
way), `stream_busy` → 8 (a `phrase` that is not this session's), `stream_budget`
→ 6 (the daemon's viewer or stream cap). A bad `fps` is `invalid_argument` → 2,
as every other bad argument is.
Activity accounting is load-bearing and has **one** exception as of v4:
**`touch` is the only mark of activity a caller can make**; `list`, `status`,
`logs`, `gc`, every `pointer.*` **and `keyboard.*`** verb, and every
`stream.*` verb do **not** reset the idle clock. A session being typed into is
still a session nobody has said they want kept.
The exception is **a connected viewer**. About once a minute the broker asks
the daemon for viewer counts and stamps `touch` on every session whose stream
has at least one; the audit entry names the session, the output and the count,
never the phrase. This is not a caller's verb and cannot be invoked — it is the
broker observing that a person is *looking*, which is the one form of "still
wanted" that does not come down the control socket. It cannot hold a session
open on its own: an enabled stream with no viewer runs no `grim` and stamps
nothing.
The *lease* clock is a different one, and v3 widens it: every `pointer.*` and
`keyboard.*` gesture verb refreshes the lease's idle deadline, because they all
@@ -438,14 +585,18 @@ go through the same gate. `pointer acquire`'s own stderr says so.
| Frame socket (published) | `<runtime dir>/stream.sock` — default `/run/hypr-stream/stream.sock`. Also frozen in `docs/CONTRACT.md`, which v1 of this file left disagreeing with it. |
| Broker control socket | `/run/hhstream/control.sock` |
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
| Broker↔stream socket | `/run/hhstream/live.sock` (v4) |
| Stream port | **option default** `9988` (`sessions.stream.port`), fixed and single — no range, no fallback. The daemon owns it; the broker learns the URL from the daemon (§3.5). |
| Stream bind | **option default** `127.0.0.1` (`sessions.stream.bind`) |
| Broker state dir | **option default** `/var/lib/hhstream`; this machine sets `/var/lib/hermes/hhstream-sessions` (`sessions.stateDir`). v1 listed the deployed value, which read as a contradiction of the module. |
| Session runtime dir | `/run/hhstream/sessions/<session-id>` |
| Container output name | `hh-<session-id>` |
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
| Container mode | `1280x720` |
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer`, `hhstream-live` (v4) |
| Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. |
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer`, `hhstream-live` |
| Registry schema | **4** (v4; 3 → 4 adds `stream`, migrating to `null`) |
| Service account | `hermes`, supplementary group `hhstream` |
---
+2
View File
@@ -15,6 +15,8 @@ Each file answers three questions and stops:
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
Closed since this folder was written:
@@ -0,0 +1,67 @@
# The MCP server cannot abandon a call, and cannot re-join the compositor's group
## The issue
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool or a
resource read builds the argv list `hhstream.cli`'s parser takes, and
`hhstream_mcp.invoke.dispatch` runs the handler argparse selected. That is the seam the design asks for — one place
decides the argv, nothing re-implements a rule — and it costs two things a
subprocess would have given for free. Both are consequences of the same fact, so
they are one item.
**1. There is no per-call deadline.** A subprocess can be killed; a Python
thread cannot be interrupted. So the only deadlines are the ones that already
exist inside the CLI: `hhstream_session.client`'s 60 s socket timeout, the
broker's own per-verb deadline, and the frame socket's `--timeout` (10 s by
default, and not currently reachable as a tool argument — it is a *global* CLI
flag, before the verb, and the argv builders emit the verb first).
Measured consequence: nothing in the current surface is known to hang — every
path either talks to the broker under its 60 s timeout or to the frame socket
under its own — but `record` with a large `seconds`, or a `grim` wedged on a
compositor that has stopped answering, would hold the worker thread until it
returns. The event loop stays responsive (a `ping` is answered), and the calls
are serialised by design, so the visible symptom is every *subsequent* tool call
queueing behind one that will not finish.
**2. The `sg` re-exec is unavailable.** `cli.main` recovers from a frame socket
it cannot read by `os.execv`-ing itself through the setuid `sg` wrapper to join
the compositor's group. Performing that here would replace the MCP server
mid-session and drop the client's connection, so `dispatch` deliberately does
not call `cli.main` and the recovery does not happen. `shot` and `record`
instead fail with the CLI's own message plus a sentence naming what the CLI
would have done (`hhstream_mcp.invoke.access_hint`), and the operator is told to
run the server as a member of the group instead.
## Ideas
1. **Leave (1) as it is and make the frame-socket timeout reachable.** *(recommended
for (1))* The honest small fix: let `shot` and `record` take a `timeout`
argument, and `hhstream://status` and the frame resources a `?timeout=`,
emitted as a global flag *before* the verb — which `hhstream_mcp.tools.argv`
cannot express today. That hands the one knob the CLI already has to the
caller, and does not pretend this layer can enforce a deadline it cannot.
2. **Run each call in a forked child after all.** Restores a killable deadline,
at the cost of a process per tool call and of re-introducing the two `exec`
paths this design avoids. Worth it only if a hang is observed in practice.
3. **For (2): a `--sg-group` flag on the server** that re-execs itself through
`sg` *once, before claiming the transport*, so the group is joined while
there is still no client to drop. *(recommended for (2))* It keeps the
recovery the CLI has, in the one moment it is safe, and is strictly better
than asking every client's configuration to spell `sg hhstream -c
hhstream-mcp`.
4. **For (2): accept it and document only.** What ships today. Correct, and the
message says what to do — but it makes a working CLI and a failing tool out
of the same machine, which is exactly the kind of difference an agent cannot
diagnose.
## Why it matters
(2) is the one an operator meets first: the CLI works from their shell, the
`shot` tool does not, and the two differ only in a recovery that is invisible
from either side. The message carries the answer, which is why this is medium
and not high.
(1) is latent. It becomes real the first time a compositor stops answering while
an agent is driving it: the agent's next tool call waits behind the stuck one
with no way to give up, where a CLI user would have pressed ctrl-C.
@@ -0,0 +1,65 @@
# A resource cannot be followed, because the SDK will not advertise subscriptions
## The issue
`hhstream://sessions/{id}/logs` is the right shape for watching an application:
a URI whose content changes, which is exactly what MCP resource
**subscriptions** are for (`resources/subscribe`, then
`notifications/resources/updated`). An agent waiting for a build to finish, or
for a page to load, would subscribe once instead of reading in a loop.
It is not available. `mcp.server.lowlevel.Server.get_capabilities` computes the
resource capability like this (mcp 1.29.0, `server/lowlevel/server.py`):
```python
if types.ListResourcesRequest in self.request_handlers:
resources_capability = types.ResourcesCapability(
subscribe=False, listChanged=notification_options.resources_changed
)
```
`subscribe=False` is hardcoded. Registering a `@server.subscribe_resource()`
handler does not change it, so a client is told the server cannot be subscribed
to and correctly never tries. The handlers exist on the `Server` class and are
unreachable through the advertised capability.
This is why `docs/CONTRACT-mcp.md` §4 says there is no following, and why the
`session-logs` resource's own description tells the reader to read it again. It
is also the reason the CLI's `session logs --follow` has no equivalent anywhere
in this surface: the tool form would hang the client, and the resource form is
switched off upstream.
## Ideas
1. **Set the capability after construction.** *(recommended)*
`create_initialization_options()` returns the computed capabilities, and the
server is handed them by `serve()` -- so one line in
`hhstream_mcp.server.serve` could set `capabilities.resources.subscribe =
True` before `server.run`, with `subscribe_resource`/`unsubscribe_resource`
handlers behind it. Small, local, and reversible when the SDK grows the
knob. The cost is that it reaches past the SDK's own computation, which is
the kind of thing that breaks on an upgrade without saying so -- so it wants
a unit test asserting the advertised capability, not just the handler.
2. **Poll on the server's side and notify.** Keep `subscribe=False`, and have
the server itself re-read and send `notifications/resources/updated`. Does
not work: a client that was told `subscribe=False` has no reason to have
subscribed, so there is nobody to notify.
3. **Upstream it.** The hardcoded `False` looks like an oversight rather than a
decision; a patch that derives it from whether a `subscribe_resource`
handler was registered would match how every other capability on that method
is computed. Slowest, and the right long-term answer.
4. **Leave it, and say so.** What ships today, in the contract and in the
resource's own description.
## Why it matters
It is the difference between an agent that waits and an agent that polls. Every
read is a CLI call in process, so a loop that reads a session's logs every
second is a `hhstream session logs` every second, serialised against every other
call this server makes -- which is exactly the contention the other TODO in this
folder describes. Subscriptions would remove the loop rather than make it
cheaper.
Medium rather than high because reading again *works*, and because the one
caller who really needs to follow output can run `hhstream session logs
--follow` in a terminal, which is what it is for.
+19 -2
View File
@@ -15,6 +15,12 @@
in {
packages = forAllSystems (pkgs: rec {
hhstream = pkgs.callPackage ./nix/package.nix {};
# The MCP server. Its own derivation, not another entry point on
# `hhstream`: it depends on the `mcp` SDK and `hhstream` is stdlib-only by
# policy (nix/mcp.nix says why at length). `packages.hhstream` therefore
# keeps the closure it had, which is the property `checks.unit` and
# `nix build .#hhstream` are expected to hold.
hhstream-mcp = pkgs.callPackage ./nix/mcp.nix {inherit hhstream;};
default = hhstream;
});
@@ -28,7 +34,9 @@
checks = forAllSystems' ({ pkgs, system }:
import ./checks { inherit pkgs self system; });
devShells = forAllSystems (pkgs: {
devShells = forAllSystems (pkgs: let
hhstream = pkgs.callPackage ./nix/package.nix {};
in {
default = pkgs.mkShell {
packages = with pkgs; [
python3
@@ -44,7 +52,16 @@
# pywayland and xkbcommon, which `tests/pointer` imports directly --
# `test_keymap.py` compiles a real `us` keymap rather than stubbing
# one, because a stub cannot tell you that `é` is unmappable.
(callPackage ./nix/package.nix { })
hhstream
# The MCP server, so `hhstream-mcp` can be run (and handed to an MCP
# client) straight out of `nix develop`.
(callPackage ./nix/mcp.nix {inherit hhstream;})
# The SDK itself, because `tests/unit/test_mcp_server.py` imports it
# directly: the tool table is stdlib-only and testable without it, but
# the wiring that turns the table into `mcp.types.Tool` objects is not,
# and a suite that could skip that file would stop noticing a schema
# the SDK rejects.
python3.pkgs.mcp
# `websocket-client` drives Chromium over the DevTools protocol, which
# is how the demo types into the page and reads the result back.
python3.pkgs.websocket-client
+114
View File
@@ -0,0 +1,114 @@
# `hhstream-mcp` -- the MCP server, as its own derivation.
#
# Separate from `nix/package.nix` on purpose, and the separation is the point:
# the frame socket, the CLI and the broker are stdlib-only by policy
# (`pyproject.toml`, `docs/CONTRACT-sessions.md` §6 rule 3), the MCP SDK is a
# third-party dependency, and `packages.hhstream` runs as the compositor's own
# units. So the dependency lives here, in a package nothing else imports, and
# `packages.hhstream` keeps the closure it had.
#
# `hhstream` is a *library* dependency here and not a binary one: the tools call
# `hhstream.cli`'s handlers in process (see that module's docstring), so what
# this package needs is the import path. `toPythonModule` is what makes an
# application's site-packages visible to a dependent, which a bare
# `buildPythonApplication` output is not.
#
# `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them --
# `shot --output` and `record` are two of the twenty-one tools, and the server
# is launched by an MCP client whose PATH is not ours to predict. `--prefix`
# and not `--set`, so a deployment that wants its own ahead of these puts them
# on PATH and wins.
{
lib,
python3,
hhstream,
grim,
ffmpeg,
makeWrapper,
}:
python3.pkgs.buildPythonApplication {
pname = "hhstream-mcp";
version = "0.1.0";
pyproject = true;
# The package directory is the project root: its own pyproject.toml lives
# there and maps the package name onto `.`. See the comment in that file for
# why it is not at the repository root.
src = ../src/hhstream_mcp;
build-system = [ python3.pkgs.setuptools ];
dependencies = [
python3.pkgs.mcp
python3.pkgs.anyio
# An application is not importable by a dependent until this converts it,
# and `hhstream_mcp.invoke` imports `hhstream.cli` directly.
(python3.pkgs.toPythonModule hhstream)
];
nativeBuildInputs = [ makeWrapper ];
makeWrapperArgs = [
"--prefix"
"PATH"
":"
"${lib.makeBinPath [
grim
ffmpeg
]}"
];
# The suite lives in `tests/` at the repository root and runs in the flake's
# `checks.unit`, which is also where `mcp` reaches it. Same choice as
# nix/package.nix, for the same reason.
doCheck = false;
# Cheap proof that both tables build and the SDK wiring imports: `tools` and
# `resources` construct every entry at import time, and `server` is the only
# module that touches `mcp`. A missing SDK, a schema that is not a dict, or a
# tool named twice all fail here rather than at an agent's first call.
pythonImportsCheck = [
"hhstream_mcp.tools"
"hhstream_mcp.resources"
"hhstream_mcp.server"
];
# `pythonImportsCheck` proves the modules load; it does not prove the script
# Nix wrapped can run, and the script is what an MCP client spawns.
# `--list-tools` and `--list-resources` are the two code paths that exercise
# argument parsing and both whole tables without opening stdio, so together
# they are the honest smoke test. `--toolsets` is in it because a selection
# that silently served everything would be the failure nobody notices.
#
# A `postPhases` entry and not `postInstall`, because the script is wrapped in
# `fixupPhase`: run any earlier and it has no PYTHONPATH, so `import mcp`
# fails and the check tests the wrong thing. `installCheckPhase` is no use
# either -- `buildPythonPackage` does not include that phase at all.
postPhases = [ "entryPointCheckPhase" ];
entryPointCheckPhase = ''
echo "checking the wrapped entry point..."
tools=$($out/bin/hhstream-mcp --list-tools)
echo "$tools"
test "$(echo "$tools" | wc -l)" -eq 21
resources=$($out/bin/hhstream-mcp --list-resources)
echo "$resources"
test "$(echo "$resources" | wc -l)" -eq 8
narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l)
echo "--toolsets keyboard offers $narrowed tools"
test "$narrowed" -eq 4
# An unknown toolset must be argparse's exit 2, not a server with no tools.
if $out/bin/hhstream-mcp --list-tools --toolsets nonsense; then
echo "an unknown toolset was accepted" >&2
exit 1
fi
'';
meta = {
description = "Drive a headless Hyprland session over the Model Context Protocol";
license = lib.licenses.mit;
mainProgram = "hhstream-mcp";
};
}
+237 -7
View File
@@ -46,6 +46,7 @@ let
brokerRuntimeDir = "/run/${brokerRuntimeDirName}";
controlSocket = "${brokerRuntimeDir}/control.sock";
pointerSocket = "${brokerRuntimeDir}/pointer.sock";
liveSocket = "${brokerRuntimeDir}/live.sock";
# Addresses that mean "this listener answers on loopback only". The spelling
# `localhost` is included because it is what a person writes; it is not a
@@ -164,6 +165,35 @@ let
done
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
'';
# The same problem, for the stream daemon, one step worse.
#
# `grim` is an ordinary Wayland client: it needs XDG_RUNTIME_DIR *and* the
# name of the socket the compositor actually bound, and that name is only
# known once the compositor is up -- so, exactly as above, it cannot be an
# `Environment=` line.
#
# MEASURED, in checks/vm-stream.nix, which is the check that exists to find
# this: with the group but without the environment, the unit came up
# `active (running)`, the broker attached, `stream status` said
# `attached: true`, and every capture failed with
#
# grim: error: XDG_RUNTIME_DIR is invalid or not set in the environment.
#
# until the publisher gave up after ten in a row. A viewer with the right
# phrase got a page and no frames, and nothing in the session's own state
# said why -- the sibling failure to
# docs/TODO/capture-binary-and-the-unit-path.md, and the reason this unit
# spells out the whole capture command *and* hands it a session.
execLive = pkgs.writeShellScript "hhstream-exec-live" ''
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
if [ -S "$candidate" ]; then
export WAYLAND_DISPLAY="''${candidate##*/}"
break
fi
done
exec ${lib.getExe' cfg.package "hhstream-live"} "$@"
'';
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
inherit lib;
inherit (cfg) outputs extraConfig;
@@ -701,15 +731,57 @@ in {
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
# (`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2 and 3).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
# `enable` runs the unit and hands the broker `/run/hhstream/live.sock`,
# over which `hhstream session stream enable <id>` switches one stream
# on. Everything else here is the *reach* of it: the port every stream
# shares, the address it binds, and whether that port is opened in the
# firewall.
#
# Running it still turns nothing on. A stream exists only for the
# sessions it was enabled on — a stream is switched on per session, never
# for all of them — so `enable = true` is a listener serving one form
# until somebody asks for a session.
stream = {
enable = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Run `hhstream-live`, the web app that publishes one session's
screen at a URL whose path is a spoken phrase, and give the broker
the socket it switches streams on over
(`/run/hhstream/live.sock`).
Off by default, and running it turns **nothing** on: a stream
exists only for the sessions `hhstream session stream enable` was
called on, and until then this is a listener serving one form.
That is deliberate — a live view of a desktop is readable by
anyone who can reach the port and guess the phrase, so switching
one on is a per-session act and never a consequence of the service
being up.
Needs {option}`sessions.enable`: the phrase lives in the session
record, and there are no sessions without the broker.
'';
};
fps = lib.mkOption {
type = lib.types.ints.positive;
default = 5;
description = ''
Frames a second a stream captures at when nobody says otherwise.
Five is one frame per ~200 ms plus a ~46 ms `grim`, measured rather
than guessed; the daemon's own hard cap is 10, because this box is
also running the compositor and the main frame publisher. Capture
happens **only while somebody is connected**, so an enabled stream
nobody is watching costs nothing at any rate.
`hhstream session stream enable --fps N` overrides it per stream.
'';
};
port = lib.mkOption {
type = lib.types.port;
default = 9988;
@@ -772,6 +844,48 @@ in {
'';
};
};
# The Model Context Protocol server -- `hhstream-mcp`, the `hhstream` CLI
# as typed tools, so an agent drives this desktop without shelling out.
#
# Its own top-level block rather than one under `sessions`, because it is
# not the broker's: four of its tools (`status`, `shot`, `record`, `run`)
# are frame-socket verbs that work with the broker switched off. It is also
# not a unit. The transport is stdio, one process per client, spawned by
# whichever client wants it -- so "installing" it means exactly putting the
# binary on PATH, and anything that started a daemon here would be
# inventing a second thing to supervise.
mcp = {
enable = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Put `hhstream-mcp` on the system PATH, so an MCP client on this
machine can spawn it.
Off by default, and deliberately not implied by
{option}`sessions.enable`: this is the surface through which a
language model starts applications, clicks and types on this desktop,
and whether that is wanted is a decision, not a consequence of the
broker being up. Installing it starts nothing — the server is stdio
and short-lived, spawned per client — and it grants no access the
`hhstream` CLI does not already grant to whoever runs it.
The client configures the sockets through the CLI's own environment,
`HHSTREAM_SOCKET` and `HHSTREAM_FRAME_SOCKET`; see the README section
on registering it.
'';
};
package = lib.mkOption {
type = lib.types.package;
description = ''
The MCP server package. Defaults to this flake's `hhstream-mcp`,
built against {option}`package` so the server and the CLI it drives
are the same build.
'';
};
};
};
config = lib.mkIf cfg.enable {
@@ -863,6 +977,31 @@ in {
services.hyprland-headless-stream.package =
lib.mkDefault (pkgs.callPackage ./package.nix {});
# Built against `cfg.package`, so the server and the CLI it runs are one
# build: the tools are argv lists against that CLI's parser, and a server
# paired with a different one would refuse flags for reasons no agent could
# read. `mkDefault` for the same reason as above.
services.hyprland-headless-stream.mcp.package =
lib.mkDefault (pkgs.callPackage ./mcp.nix { hhstream = cfg.package; });
# Installing it IS the whole of `mcp.enable`: the server is spawned by a
# client over stdio, so there is no unit, no socket and no state directory
# to declare.
environment.systemPackages = lib.mkIf cfg.mcp.enable [ cfg.mcp.package ];
# A warning and not an assertion: eighteen of the twenty-one tools and six
# of the eight resources need the broker, and an agent handed them against
# a machine where it is off gets exit 5 from every one of them -- which is
# a true answer, badly timed. The frame tools are genuinely useful on their
# own, so this is a thing worth saying rather than a thing worth refusing.
warnings = lib.optional (cfg.mcp.enable && !cfg.sessions.enable) ''
services.hyprland-headless-stream.mcp.enable is on while sessions.enable
is off: the MCP server's session, pointer and keyboard tools, and every
resource but hhstream://status and hhstream://screen, will fail because
the broker is unreachable (exit 5). Only shot, record, run and those two
resources will work.
'';
# The broker's state directory and the moved socket directory are two
# different reasons to write a tmpfiles entry, and this option takes one
# definition — so they are merged here rather than assigned twice (which
@@ -1169,5 +1308,96 @@ in {
];
};
};
# The stream daemon. A third executor beside the pointer driver, and the
# split is the driver's: `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 (docs/CONTRACT-sessions.md §3.5).
systemd.services.hhstream-live = lib.mkIf (cfg.sessions.enable && cfg.sessions.stream.enable) {
description = "Per-session live stream for the headless Hyprland desktop";
wantedBy = ["multi-user.target"];
after = ["hyprland-headless.service"];
# `BindsTo` for the pointer driver's reason: this process captures from
# that compositor's outputs through `grim`, so when the compositor goes
# it has nothing left to capture. The broker reports such a stream as
# `attached: false` rather than pretending, and re-enabling re-attaches.
bindsTo = ["hyprland-headless.service"];
environment = {
PYTHONUNBUFFERED = "1";
# The compositor's session, not this unit's own: `grim` has to find the
# Wayland socket in here. `WAYLAND_DISPLAY` is set by `execLive` at
# start, because the socket's name is only known once the compositor
# has bound it. HOME is deliberately NOT redirected here the way the
# frame server's is -- this unit runs as the operator's account, and
# the compositor's runtime directory is not writable by it.
XDG_RUNTIME_DIR = runtimeDir;
};
serviceConfig = {
Type = "simple";
User = cfg.sessions.user;
# The compositor's runtime directory is 0750 and owned by this group,
# and `grim` is a Wayland client of it -- same reason the pointer
# driver needs the group, one step further: this one has to *capture*,
# not merely find the socket.
SupplementaryGroups = [cfg.sessions.group];
# No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and
# to the tmpfiles entry above, and a second RuntimeDirectory= on the
# same path would delete the broker's control socket when this unit
# stopped. The plan calls this out by name as the Stage 3 risk.
WorkingDirectory = brokerRuntimeDir;
UMask = "0007";
Restart = "on-failure";
RestartSec = 1;
NoNewPrivileges = true;
KillMode = "process";
# `grim` is NOT on a unit's PATH, and the symptom of leaving it off is
# a stream that serves an empty frame area without saying why --
# docs/TODO/capture-binary-and-the-unit-path.md, found the first time
# the capture ran as a unit rather than from a login shell. So the
# whole capture command is spelled out here, with grim's store path.
#
# `--capture-command=<word>` and not `--capture-command <word>`:
# MEASURED, as a unit crash-looping with
#
# hhstream-live serve: error: argument --capture-command: expected
# one argument
#
# because grim's last word is a bare `-` (its "write to stdout"), and
# argparse reads a lone dash as an option prefix rather than a value.
# The `=` form is unambiguous for every word, so it is used for every
# word rather than only the one that needs it.
# Same second line of defence as the frame server's: `BindsTo=` stops
# this unit when the compositor goes, but the compositor is only
# *ready* once its socket is bound, and `execLive` has to find that
# socket to export its name.
ExecStartPre = "${findSession} >/dev/null";
ExecStart = lib.escapeShellArgs (
[
execLive
"serve"
"--control-socket=${liveSocket}"
"--bind=${cfg.sessions.stream.bind}"
"--port=${toString cfg.sessions.stream.port}"
"--fps=${toString cfg.sessions.stream.fps}"
]
++ map (word: "--capture-command=${word}") [
(lib.getExe pkgs.grim)
"-c" # include the cursor
"-t"
"jpeg"
"-q"
"80"
"-" # write to stdout
]
);
};
};
};
}
+7
View File
@@ -38,6 +38,13 @@ python3.pkgs.buildPythonApplication {
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
# stdlib-only, and they are named here because 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.
"hhstream_live.control"
"hhstreamd.live"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
+9
View File
@@ -34,6 +34,15 @@ hhstream-live = "hhstream_live.__main__:main"
[tool.setuptools.packages.find]
where = ["src"]
# `hhstream_mcp` lives under src/ beside the others -- so the dev shell's
# PYTHONPATH reaches it and the tests import it the same way they import
# everything else -- but it is a *different distribution*
# (src/hhstream_mcp/pyproject.toml, built by nix/mcp.nix) because it depends on
# the MCP SDK. Without this exclusion `find` would sweep it into this wheel,
# and `packages.hhstream` would ship a module whose first import line fails:
# the dependency policy above would be intact and the package would still be
# broken.
exclude = ["hhstream_mcp*"]
# The phrase generator reads this at runtime, so it has to be *installed*, not
# just present in the checkout: a wheel (and the Nix build) that dropped it
@@ -1 +0,0 @@
/target
File diff suppressed because it is too large. Load diff
@@ -1,16 +0,0 @@
[package]
name = "grimrs-capture"
version = "0.1.0"
edition = "2021"
publish = false
description = "Long-lived grim-rs capture producer for the frozen HARNESS.md contract"
[[bin]]
name = "grimrs-capture"
path = "src/main.rs"
[dependencies]
# Exact: the raw-mode stop point depends on what 0.2.0 does inside capture_*.
grim-rs = "=0.2.0"
libc = "0.2"
serde_json = { version = "1", features = ["preserve_order"] }
@@ -1,53 +0,0 @@
#!/bin/sh
# Eight measured cells, still screen, two runs each.
# Stdout of each cell is one JSON line. Progress goes to runs/progress.log.
# Does not set XDG_RUNTIME_DIR. The caller must export WAYLAND_DISPLAY to the
# absolute socket path.
set -u
cd "$(dirname "$0")"
if [ "${WAYLAND_DISPLAY:-}" != "/run/hypr-stream/wayland-1" ]; then
echo "WAYLAND_DISPLAY must be /run/hypr-stream/wayland-1" >&2
exit 2
fi
if [ "${XDG_RUNTIME_DIR:-}" = "/run/hypr-stream" ]; then
echo "refusing XDG_RUNTIME_DIR=/run/hypr-stream" >&2
exit 2
fi
OUTPUT=${1:?usage: run-cells.sh OUTPUT_NAME}
BIN=./target/release/grimrs-capture
if [ ! -x "$BIN" ]; then
echo "missing $BIN; build with nix-shell --run 'cargo build --release'" >&2
exit 2
fi
mkdir -p runs
LOG=runs/progress.log
: > "$LOG"
# The frame server is a system unit. Do not stop it. Record that it was
# capturing during the run so the numbers are not read as an idle compositor.
ps -eo pid,user,cmd > runs/ps-at-start.txt
echo "BEGIN runner $(date -Is) WAYLAND_DISPLAY=$WAYLAND_DISPLAY XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR-}" >> "$LOG"
fail=0
run() {
name=$1
shift
echo "BEGIN $name $(date -Is)" >> "$LOG"
start=$(date +%s)
"$BIN" "$@" > "runs/$name.stdout" 2> "runs/$name.stderr"
rc=$?
end=$(date +%s)
echo "END $name rc=$rc elapsed=$((end - start)) $(date -Is)" >> "$LOG"
if [ "$rc" -ne 0 ]; then
echo "CELL_FAIL $name rc=$rc" >> "$LOG"
fail=1
fi
}
run output-raw-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-raw-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-jpeg-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run output-jpeg-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run all-raw-1 --all --frames 300 --warmup 10 --mode raw --json
run all-raw-2 --all --frames 300 --warmup 10 --mode raw --json
run all-jpeg-1 --all --frames 300 --warmup 10 --mode jpeg --json
run all-jpeg-2 --all --frames 300 --warmup 10 --mode jpeg --json
echo "ALL_DONE fail=$fail $(date -Is)" >> "$LOG"
exit "$fail"
@@ -1,13 +0,0 @@
# Spike-local toolchain for route 001a. Rust stays out of the repository flake
# on purpose: this shell is the only place this spike gets rustc and cargo.
#
# Do not set WAYLAND_DISPLAY or XDG_RUNTIME_DIR here. The run commands in
# README.md set WAYLAND_DISPLAY to the absolute socket path. Pointing
# XDG_RUNTIME_DIR at /run/hypr-stream makes libwayland reject the runtime dir.
{ pkgs ? import <nixpkgs> { } }:
pkgs.mkShell {
packages = with pkgs; [
rustc # 1.98 from the machine's nixpkgs
cargo
];
}
@@ -1,641 +0,0 @@
//! Long-lived capture producer for the frozen measurement contract.
//!
//! One Wayland connection (`Grim::new_wlr`, so the crate cannot pick
//! `ext-image-copy-capture-v1`), then warmup frames, then N measured frames.
//! Stdout is exactly one JSON object, on the last line. Everything else goes
//! to stderr.
use std::env;
use std::io::{self, Write};
use std::process::ExitCode;
use std::time::Instant;
use grim_rs::Grim;
const ROUTE: &str = "grim-rs";
const JPEG_QUALITY: u8 = 80;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Mode {
Raw,
Jpeg,
}
impl Mode {
fn as_str(self) -> &'static str {
match self {
Mode::Raw => "raw",
Mode::Jpeg => "jpeg",
}
}
}
#[derive(Clone, Debug)]
enum Target {
Output(String),
All,
}
impl Target {
fn label(&self) -> &str {
match self {
Target::Output(name) => name,
Target::All => "all",
}
}
}
struct Args {
target: Target,
frames: u32,
warmup: u32,
mode: Mode,
}
struct Held {
width: u32,
height: u32,
/// JPEG byte length. `None` in raw mode.
jpeg_len: Option<usize>,
/// Pixel or JPEG bytes. Kept alive until the caller drops it, so the
/// frame timer can stop when the bytes are complete and not when they
/// are freed.
bytes: Vec<u8>,
}
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(err) => {
eprintln!("grimrs-capture: {err}");
ExitCode::from(1)
}
}
}
fn run() -> Result<(), String> {
let args = parse_args(env::args().skip(1))?;
// Absolute WAYLAND_DISPLAY is required. Leaving XDG_RUNTIME_DIR alone is
// also required: this process does not own /run/hypr-stream.
match env::var("WAYLAND_DISPLAY") {
Ok(value) if !value.is_empty() => {}
_ => {
return Err(
"WAYLAND_DISPLAY is empty. Set it to the absolute socket \
path /run/hypr-stream/wayland-1 and do not set \
XDG_RUNTIME_DIR=/run/hypr-stream"
.to_string(),
);
}
}
if env::var("XDG_RUNTIME_DIR").ok().as_deref() == Some("/run/hypr-stream") {
return Err(
"XDG_RUNTIME_DIR=/run/hypr-stream is set. Unset it; libwayland \
refuses a runtime dir the caller does not own"
.to_string(),
);
}
// Force zwlr-screencopy. Grim::new() prefers ext-image-copy-capture-v1,
// which is the dma-buf-capable path this machine must not take.
let mut grim = Grim::new_wlr().map_err(|err| {
format!(
"Grim::new_wlr failed ({err}). Refusing to fall back to \
ext-image-copy-capture-v1"
)
})?;
let outputs = grim.get_outputs().map_err(|err| err.to_string())?;
if outputs.is_empty() {
return Err("compositor advertised no outputs".to_string());
}
let layout = describe_outputs(&outputs);
if let Target::Output(name) = &args.target {
if !outputs.iter().any(|output| output.name() == name) {
return Err(format!(
"output {name:?} not found. Outputs: {layout}"
));
}
}
eprintln!(
"grimrs-capture: route {ROUTE} protocol zwlr-screencopy-v1 \
mode {} target {} warmup {} frames {}",
args.mode.as_str(),
args.target.label(),
args.warmup,
args.frames
);
eprintln!("grimrs-capture: outputs {layout}");
let mut last_warmup_nonzero: Option<u64> = None;
let mut last_warmup_jpeg_ok = true;
for i in 0..args.warmup {
let held = grab(&mut grim, &args.target, args.mode)?;
if args.mode == Mode::Jpeg && !held.bytes.starts_with(&[0xFF, 0xD8]) {
last_warmup_jpeg_ok = false;
}
last_warmup_nonzero = Some(count_nonzero(&held.bytes));
eprintln!(
"grimrs-capture: warmup {}/{} {}x{} bytes {} nonzero {}",
i + 1,
args.warmup,
held.width,
held.height,
held.bytes.len(),
last_warmup_nonzero.unwrap_or(0)
);
}
if args.mode == Mode::Jpeg && !last_warmup_jpeg_ok {
return Err(
"warmup JPEG did not start with FF D8; refusing to measure"
.to_string(),
);
}
let cpu_before = process_cpu_ms()?;
let wall_start = Instant::now();
let mut samples_ms: Vec<f64> = Vec::with_capacity(args.frames as usize);
let mut jpeg_sizes: Vec<u64> = Vec::new();
let mut geometry: Option<(u32, u32)> = None;
for _ in 0..args.frames {
let tick = Instant::now();
let held = grab(&mut grim, &args.target, args.mode)?;
// Touch the length so the buffer is complete before the clock stops.
// Do not read pixels: the contract puts stride and checksum outside
// the measurement.
std::hint::black_box(held.bytes.len());
let ms = tick.elapsed().as_secs_f64() * 1000.0;
match geometry {
None => geometry = Some((held.width, held.height)),
Some((w, h)) if w != held.width || h != held.height => {
return Err(format!(
"geometry changed during the run: {w}x{h} then {}x{}",
held.width, held.height
));
}
Some(_) => {}
}
if let Some(len) = held.jpeg_len {
jpeg_sizes.push(len as u64);
}
samples_ms.push(ms);
// Free between frames, outside the frame timer. wall_ms includes it.
drop(held);
}
let wall_ms = wall_start.elapsed().as_secs_f64() * 1000.0;
let cpu_after = process_cpu_ms()?;
let (width, height) = geometry.ok_or("no measured frames")?;
let cpu_ms_per_frame = match (cpu_before, cpu_after) {
(Some(before), Some(after)) if after >= before => {
Some((after - before) / f64::from(args.frames))
}
_ => None,
};
let mut notes = format!(
"grim-rs 0.2.0 via Grim::new_wlr(); copy target is a wl_shm buffer \
created inside each capture_* call, not a dma-buf the producer \
imports. Cursor not overlaid (the frozen argv has no cursor flag; \
hhstream-live's grim command passes -c). JPEG is Grim::to_jpeg, \
quality {JPEG_QUALITY}, the crate default and the live-stream \
setting. Raw timer stops when capture_* returns, which is after \
the crate copies the mapping into a Vec and swizzles XRGB/ARGB to \
RGBA (and applies any output transform or y-invert). The public \
API does not expose the mapped buffer before that, so raw includes \
work the contract says to leave outside the timer. Percentiles are \
linear interpolation on the sorted samples. cpu_ms_per_frame is \
getrusage(RUSAGE_SELF) utime+stime over the measured loop only, \
divided by frames. Frame buffers are freed between frames; that \
free is inside wall_ms and outside frame_ms. Outputs: {layout}. \
No GPU on this machine; dma-buf was not used and is not claimed. \
This process does not move the pointer and does not start or stop \
a session; the pixels are whatever the compositor is already \
showing."
);
if let Some(nonzero) = last_warmup_nonzero {
notes.push_str(&format!(
" Last warmup frame nonzero bytes: {nonzero}."
));
if nonzero == 0 {
notes.push_str(" WARNING: last warmup frame was all zeros.");
}
}
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: args.target.label().to_string(),
geometry: [width, height],
mode: args.mode.as_str(),
warmup: args.warmup,
frames: args.frames,
frame_ms: summarize(&samples_ms),
fps_sustained: sustained_fps(&samples_ms),
wall_ms,
cpu_ms_per_frame,
bytes_p50: if args.mode == Mode::Jpeg {
Some(percentile_u64(&jpeg_sizes, 0.50))
} else {
None
},
persistent: true,
notes,
};
let line = serde_json::to_string(&report.to_json())
.map_err(|err| err.to_string())?;
let mut stdout = io::stdout().lock();
writeln!(stdout, "{line}").map_err(|err| err.to_string())?;
stdout.flush().map_err(|err| err.to_string())?;
Ok(())
}
fn grab(grim: &mut Grim, target: &Target, mode: Mode) -> Result<Held, String> {
let captured = match target {
Target::Output(name) => grim.capture_output(name),
Target::All => grim.capture_all(),
}
.map_err(|err| err.to_string())?;
let width = captured.width();
let height = captured.height();
if width == 0 || height == 0 {
return Err(format!("capture returned {width}x{height}"));
}
match mode {
Mode::Raw => Ok(Held {
width,
height,
jpeg_len: None,
bytes: captured.into_data(),
}),
Mode::Jpeg => {
let jpeg = grim
.to_jpeg_with_quality(captured.data(), width, height, JPEG_QUALITY)
.map_err(|err| err.to_string())?;
let jpeg_len = jpeg.len();
Ok(Held {
width,
height,
jpeg_len: Some(jpeg_len),
bytes: jpeg,
})
}
}
}
fn describe_outputs(outputs: &[grim_rs::Output]) -> String {
let mut ordered: Vec<_> = outputs.iter().collect();
ordered.sort_by(|a, b| {
let ag = a.geometry();
let bg = b.geometry();
ag.x()
.cmp(&bg.x())
.then(ag.y().cmp(&bg.y()))
.then(a.name().cmp(b.name()))
});
ordered
.into_iter()
.map(|output| {
let geometry = output.geometry();
format!(
"{}@{},{} {}x{} scale {}",
output.name(),
geometry.x(),
geometry.y(),
geometry.width(),
geometry.height(),
output.scale()
)
})
.collect::<Vec<_>>()
.join("; ")
}
fn count_nonzero(bytes: &[u8]) -> u64 {
bytes.iter().filter(|byte| **byte != 0).count() as u64
}
fn process_cpu_ms() -> Result<Option<f64>, String> {
let mut usage: libc::rusage = unsafe { std::mem::zeroed() };
let rc = unsafe { libc::getrusage(libc::RUSAGE_SELF, &mut usage) };
if rc != 0 {
return Ok(None);
}
Ok(Some(timeval_ms(usage.ru_utime) + timeval_ms(usage.ru_stime)))
}
fn timeval_ms(value: libc::timeval) -> f64 {
value.tv_sec as f64 * 1000.0 + value.tv_usec as f64 / 1000.0
}
struct Summary {
min: f64,
p50: f64,
mean: f64,
p95: f64,
max: f64,
}
fn summarize(samples: &[f64]) -> Summary {
let mut sorted = samples.to_vec();
sorted.sort_by(|a, b| a.total_cmp(b));
let sum: f64 = sorted.iter().sum();
Summary {
min: sorted[0],
p50: percentile_linear(&sorted, 0.50),
mean: sum / sorted.len() as f64,
p95: percentile_linear(&sorted, 0.95),
max: *sorted.last().expect("at least one sample"),
}
}
fn sustained_fps(samples: &[f64]) -> f64 {
let sum = samples.iter().sum::<f64>();
if sum <= 0.0 {
return 0.0;
}
samples.len() as f64 / (sum / 1000.0)
}
/// Linear interpolation between closest ranks. `samples` must be sorted and
/// non-empty. This is the same definition as numpy's default percentile.
fn percentile_linear(sorted: &[f64], p: f64) -> f64 {
if sorted.len() == 1 {
return sorted[0];
}
let rank = p * (sorted.len() - 1) as f64;
let lo = rank.floor() as usize;
let hi = rank.ceil() as usize;
let frac = rank - lo as f64;
sorted[lo] * (1.0 - frac) + sorted[hi] * frac
}
fn percentile_u64(samples: &[u64], p: f64) -> f64 {
let as_f64: Vec<f64> = samples.iter().map(|value| *value as f64).collect();
let mut sorted = as_f64;
sorted.sort_by(|a, b| a.total_cmp(b));
percentile_linear(&sorted, p)
}
struct Report {
route: &'static str,
language: &'static str,
protocol: &'static str,
output: String,
geometry: [u32; 2],
mode: &'static str,
warmup: u32,
frames: u32,
frame_ms: Summary,
fps_sustained: f64,
wall_ms: f64,
cpu_ms_per_frame: Option<f64>,
bytes_p50: Option<f64>,
persistent: bool,
notes: String,
}
impl Report {
fn to_json(&self) -> serde_json::Value {
serde_json::json!({
"route": self.route,
"language": self.language,
"protocol": self.protocol,
"output": self.output,
"geometry": self.geometry,
"mode": self.mode,
"warmup": self.warmup,
"frames": self.frames,
"frame_ms": {
"min": round3(self.frame_ms.min),
"p50": round3(self.frame_ms.p50),
"mean": round3(self.frame_ms.mean),
"p95": round3(self.frame_ms.p95),
"max": round3(self.frame_ms.max),
},
"fps_sustained": round3(self.fps_sustained),
"wall_ms": round3(self.wall_ms),
"cpu_ms_per_frame": self.cpu_ms_per_frame.map(round3),
"bytes_p50": self.bytes_p50.map(round3),
"persistent": self.persistent,
"notes": self.notes,
})
}
}
fn round3(value: f64) -> f64 {
(value * 1000.0).round() / 1000.0
}
fn parse_args(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
let args: Vec<String> = args.into_iter().collect();
let mut output: Option<String> = None;
let mut all = false;
let mut frames: Option<u32> = None;
let mut warmup: Option<u32> = None;
let mut mode: Option<Mode> = None;
let mut json = false;
let mut index = 0;
while index < args.len() {
let arg = &args[index];
match arg.as_str() {
"--json" => {
if json {
return Err("repeated --json".to_string());
}
json = true;
}
"--all" => {
if all {
return Err("repeated --all".to_string());
}
all = true;
}
"--output" => {
output = Some(need_value(&args, &mut index, "--output")?);
}
"--frames" => {
frames = Some(parse_u32(&need_value(&args, &mut index, "--frames")?, "--frames")?);
}
"--warmup" => {
warmup = Some(parse_u32(&need_value(&args, &mut index, "--warmup")?, "--warmup")?);
}
"--mode" => {
let value = need_value(&args, &mut index, "--mode")?;
mode = Some(match value.as_str() {
"raw" => Mode::Raw,
"jpeg" => Mode::Jpeg,
other => {
return Err(format!(
"--mode must be raw or jpeg, got {other:?}"
))
}
});
}
"--help" | "-h" => {
return Err(usage());
}
other => {
return Err(format!("unknown argument {other}. {}", usage()));
}
}
index += 1;
}
if !json {
return Err(format!("--json is required. {}", usage()));
}
if all && output.is_some() {
return Err("--all and --output are mutually exclusive".to_string());
}
let target = if all {
Target::All
} else if let Some(name) = output {
if name.is_empty() {
return Err("--output name is empty".to_string());
}
Target::Output(name)
} else {
return Err(format!("one of --output or --all is required. {}", usage()));
};
let frames = frames.ok_or_else(|| format!("--frames is required. {}", usage()))?;
if frames == 0 {
return Err("--frames must be at least 1".to_string());
}
let warmup = warmup.ok_or_else(|| format!("--warmup is required. {}", usage()))?;
let mode = mode.ok_or_else(|| format!("--mode is required. {}", usage()))?;
Ok(Args {
target,
frames,
warmup,
mode,
})
}
fn need_value(args: &[String], index: &mut usize, flag: &str) -> Result<String, String> {
let next = index.checked_add(1).and_then(|i| args.get(i));
match next {
Some(value) if !value.starts_with("--") => {
*index += 1;
Ok(value.clone())
}
_ => Err(format!("{flag} needs a value")),
}
}
fn parse_u32(value: &str, flag: &str) -> Result<u32, String> {
value
.parse::<u32>()
.map_err(|_| format!("{flag} must be a non-negative integer, got {value:?}"))
}
fn usage() -> String {
"usage: grimrs-capture (--output NAME | --all) --frames N --warmup W \
--mode raw|jpeg --json"
.to_string()
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(line: &str) -> Result<Args, String> {
parse_args(line.split_whitespace().map(str::to_string))
}
#[test]
fn accepts_the_contract_forms() {
let output = parse(
"--output hh-chromium-yrfadn --frames 300 --warmup 10 --mode raw --json",
)
.unwrap();
assert!(matches!(output.target, Target::Output(name) if name == "hh-chromium-yrfadn"));
assert_eq!(output.frames, 300);
assert_eq!(output.warmup, 10);
assert_eq!(output.mode, Mode::Raw);
let all = parse("--all --frames 300 --warmup 10 --mode jpeg --json").unwrap();
assert!(matches!(all.target, Target::All));
assert_eq!(all.mode, Mode::Jpeg);
}
#[test]
fn rejects_mixed_targets_and_missing_json() {
assert!(parse("--all --output x --frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode raw").is_err());
assert!(parse("--output x --frames 0 --warmup 0 --mode raw --json").is_err());
assert!(parse("--frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode png --json").is_err());
}
#[test]
fn percentile_matches_linear_interpolation() {
let samples = [1.0, 2.0, 3.0, 4.0];
assert_eq!(percentile_linear(&samples, 0.50), 2.5);
assert_eq!(percentile_linear(&samples, 0.0), 1.0);
assert_eq!(percentile_linear(&samples, 1.0), 4.0);
// rank = 0.95 * 3 = 2.85 -> 3.0 * 0.15 + 4.0 * 0.85
let p95 = percentile_linear(&samples, 0.95);
assert!((p95 - 3.85).abs() < 1e-9);
}
#[test]
fn sustained_fps_uses_the_sum_of_frame_times() {
// Two frames of 100 ms -> 2 / 0.2 = 10 fps.
let fps = sustained_fps(&[100.0, 100.0]);
assert!((fps - 10.0).abs() < 1e-9);
}
#[test]
fn json_object_has_the_contract_keys() {
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: "hh-chromium-yrfadn".to_string(),
geometry: [1280, 720],
mode: "jpeg",
warmup: 10,
frames: 300,
frame_ms: Summary {
min: 1.0,
p50: 2.0,
mean: 3.0,
p95: 4.0,
max: 5.0,
},
fps_sustained: 10.0,
wall_ms: 20.0,
cpu_ms_per_frame: None,
bytes_p50: Some(100.5),
persistent: true,
notes: "n".to_string(),
};
let value = report.to_json();
for key in [
"route",
"language",
"protocol",
"output",
"geometry",
"mode",
"warmup",
"frames",
"frame_ms",
"fps_sustained",
"wall_ms",
"cpu_ms_per_frame",
"bytes_p50",
"persistent",
"notes",
] {
assert!(value.get(key).is_some(), "missing {key}");
}
assert!(value["cpu_ms_per_frame"].is_null());
assert_eq!(value["bytes_p50"], 100.5);
assert_eq!(value["persistent"], true);
assert_eq!(value["geometry"][0], 1280);
}
}
+55 -3
View File
@@ -88,6 +88,13 @@ def build_parser() -> argparse.ArgumentParser:
serve.add_argument("--stream", action="append", default=[], type=parse_stream,
metavar="PHRASE=OUTPUT",
help="enable a stream on this output; repeatable")
serve.add_argument(
"--control-socket",
metavar="PATH",
help="serve the broker's control socket here (CONTRACT-sessions.md "
"§3.5), so `hhstream session stream enable` can attach a stream. "
"Omitted, the app is standalone and only --stream puts anything on it.",
)
serve.add_argument("--capture-command", action="append", default=None,
metavar="WORD",
help="capture argv word; repeat (a repeated flag is the "
@@ -139,6 +146,7 @@ def cmd_serve(args: argparse.Namespace) -> int:
capture_base = args.capture_command or DEFAULT_CAPTURE
registry = make_registry(args.stream, capture_base, args.fps)
server = LiveServer(registry, host=args.bind, port=args.port)
control = control_server(args, registry, server, capture_base)
# A service is stopped with SIGTERM, not with Ctrl-C: without a handler the
# default action kills the process outright and `server.stop` never runs, so
@@ -159,14 +167,25 @@ def cmd_serve(args: argparse.Namespace) -> int:
try:
server.start() # raises OSError loudly if the port is taken
if control is not None:
# After the listener, because `attach` replies with a URL and the
# URL has no answer until the port is bound -- a requested port of
# 0 least of all.
control.listen()
threading.Thread(
target=control.serve_forever,
name="hhstream-live.control",
daemon=True,
).start()
print(f"control socket: {control.socket_path}", file=sys.stderr)
# Printed after `start`, because a requested port of 0 only has an answer
# once it is bound. `describe_bind` names the real bind, so `0.0.0.0` is
# not reported as loopback just because that is the address you click.
print(server.describe_bind(), file=sys.stderr)
print(f"landing page: http://{server.address}:{server.port}/", file=sys.stderr)
if not args.stream:
print("no --stream given; only the landing page will answer",
file=sys.stderr)
if not args.stream and control is None:
print("no --stream and no --control-socket; only the landing page "
"will answer", file=sys.stderr)
for phrase in registry.phrases():
print(server.url_for(phrase))
sys.stdout.flush()
@@ -177,10 +196,43 @@ def cmd_serve(args: argparse.Namespace) -> int:
finally:
if previous is not None:
signal.signal(signal.SIGTERM, previous)
if control is not None:
# Before the HTTP listener: the broker's next `attach` should fail
# to connect rather than be accepted by a process on its way out.
control.close()
server.stop()
return 0
def control_server(
args: argparse.Namespace,
registry: StreamRegistry,
server: LiveServer,
capture_base: list[str],
) -> "ControlServer | None":
"""The broker's control socket, or ``None`` for a standalone run.
The two things only this process knows are injected here and nowhere else:
how to build a capture for an output (the capture command, from this unit's
argv) and how to name a URL (the bound port). That is the whole reason
`attach` replies with a URL instead of letting the broker assemble one.
"""
if not getattr(args, "control_socket", None):
return None
from .control import Control, ControlServer
from hhstream.capture import CommandCapture
control = Control(
registry,
capture_for=lambda output: CommandCapture(capture_argv(capture_base, output)),
url_for=server.url_for,
default_fps=args.fps,
)
return ControlServer(args.control_socket, control)
def main(argv: list[str] | None = None) -> int:
args = parse_args(argv)
logging.basicConfig(
+317
View File
@@ -0,0 +1,317 @@
"""``/run/hhstream/live.sock`` — the broker tells this process what to publish.
The daemon's end of `docs/CONTRACT-sessions.md` §3.5. Four ops (`attach`,
`detach`, `list`, `viewers`) over newline-delimited JSON, in the shape the
pointer driver's socket already uses, because a second convention for the same
job would be a second thing to remember.
**This process decides nothing about sessions.** It does not know what an idle
clock is, which application a session runs, or whether a stream *should* be on.
It is told a phrase, an output and a rate, and it publishes. `viewers` is a
counter read; what it means is the broker's business
(`docs/CONTRACT-sessions.md` §4).
**It does own the port, the bind address and the capture command**, from its own
unit's argv — which is why `attach` replies with the URL rather than letting the
broker assemble one. A URL built from a port somebody was told about once is a
URL that lies the first time the listener moves.
**`attach` is idempotent on the phrase.** The same phrase aimed at the same
output returns the running stream instead of starting a second capture: the
broker re-attaches after a restart, and doubling the ``grim`` rate on one output
because of a reconnect would be a self-inflicted load problem. The same phrase
aimed somewhere *else* is refused — a phrase is a credential for one view, and
silently re-pointing it would show a person a desktop they were not given.
**The phrase is never logged**, here or in the broker. Every line below names
the output and the session.
"""
from __future__ import annotations
import json
import logging
import os
import socket
import threading
from pathlib import Path
from typing import Any, Callable
from . import phrase as phrase_mod
from .publisher import DEFAULT_FPS, FPS_CAP, StreamRegistry, StreamSpec
log = logging.getLogger("hhstream.live.control")
#: Matches ``hhstreamd.protocol.MAX_LINE_BYTES`` and the pointer driver's.
MAX_LINE_BYTES = 1 << 20
LISTEN_BACKLOG = 8
#: A rejection the broker maps to exit 2 rather than exit 10 -- the caller's
#: mistake, not a failure of this process. Same vocabulary as the driver's.
INVALID = "invalid_argument"
class Control:
"""The op handler. Holds the registry and the two things only this process knows.
``capture_for`` turns an output name into a capture object, and ``url_for``
turns a phrase into this listener's URL. Both are injected rather than
built here so the tests can drive the whole protocol without a compositor
and without binding a port.
"""
def __init__(
self,
registry: StreamRegistry,
*,
capture_for: Callable[[str], Any],
url_for: Callable[[str], str],
default_fps: int = DEFAULT_FPS,
) -> None:
self.registry = registry
self.capture_for = capture_for
self.url_for = url_for
#: The rate an `attach` with no `fps` gets. This process's, from its
#: own argv, because it is the one that has to keep up with it -- and
#: so an operator's `sessions.stream.fps` reaches every stream rather
#: than only the ones somebody named a rate for.
self.default_fps = int(default_fps)
self._lock = threading.Lock()
# -- the ops ----------------------------------------------------------
def handle(self, request: Any) -> dict[str, Any]:
if not isinstance(request, dict):
return _no(f"request is not an object: {type(request).__name__}", INVALID)
op = request.get("op")
handler = {
"attach": self._attach,
"detach": self._detach,
"list": self._list,
"viewers": self._viewers,
}.get(op if isinstance(op, str) else "")
if handler is None:
return _no(f"unknown op: {op!r}", INVALID)
# One op at a time: `attach` reads the registry and then mutates it, and
# two brokers (or a broker and a restart sweep) must not interleave
# there and start two captures for one phrase.
with self._lock:
try:
return handler(request)
except Rejected as refused:
return _no(str(refused), refused.kind)
except (ValueError, TypeError) as exc:
# The registry's own validation (`fps must be a positive int`,
# `phrase ... is already enabled`) surfaces here. It is the
# caller's mistake, so it is exit 2 and not a daemon failure.
return _no(str(exc), INVALID)
def _attach(self, request: dict[str, Any]) -> dict[str, Any]:
phrase = _phrase_of(request)
output = _text(request, "output")
fps = _fps(request, self.default_fps)
session = request.get("session")
session = None if session is None else str(session)
label = str(request.get("label") or "")
existing = self.registry.get(phrase)
if existing is not None:
if existing.spec.output != output:
raise Rejected(
f"that phrase is already publishing output "
f"{existing.spec.output!r}, not {output!r}; disable it first",
INVALID,
)
# Idempotent: the running stream, with whatever rate it was started
# at. A new `fps` is deliberately NOT applied here -- changing the
# rate under a connected viewer is a `disable`/`enable`, which is
# one record write and one obvious act, rather than a silent
# re-rate that no log line would explain.
log.info("re-attached output %s for %s", output, session or "a standalone stream")
return {"ok": True, "stream": self._describe(existing)}
spec = StreamSpec(
phrase=phrase, output=output, fps=fps, session=session, label=label or output
)
stream = self.registry.add(spec, self.capture_for(output))
log.info(
"attached output %s for %s at %s fps",
output,
session or "a standalone stream",
fps,
)
return {"ok": True, "stream": self._describe(stream)}
def _detach(self, request: dict[str, Any]) -> dict[str, Any]:
phrase = _phrase_of(request)
stream = self.registry.remove(phrase)
if stream is None:
# Not an error. `disable` on a session whose daemon restarted since
# `enable` is the ordinary case, and the broker has to clear its
# record either way.
return {"ok": True, "detached": False}
log.info(
"detached output %s for %s",
stream.spec.output,
stream.spec.session or "a standalone stream",
)
return {"ok": True, "detached": True}
def _list(self, request: dict[str, Any]) -> dict[str, Any]:
return {"ok": True, "streams": [self._describe(s) for s in self.registry.all()]}
def _viewers(self, request: dict[str, Any]) -> dict[str, Any]:
return {
"ok": True,
# `Stream.viewers` is a property, not a method.
"viewers": {s.spec.phrase: s.viewers for s in self.registry.all()},
}
def _describe(self, stream: Any) -> dict[str, Any]:
public = dict(stream.spec.public())
public["url"] = self.url_for(stream.spec.phrase)
public["viewers"] = stream.viewers
return public
class Rejected(Exception):
"""A refusal with a ``kind`` the broker maps to an exit code."""
def __init__(self, message: str, kind: str | None = None) -> None:
super().__init__(message)
self.kind = kind
def _no(error: str, kind: str | None = None) -> dict[str, Any]:
reply: dict[str, Any] = {"ok": False, "error": error}
if kind:
reply["kind"] = kind
return reply
def _text(request: dict[str, Any], field: str) -> str:
value = request.get(field)
if not isinstance(value, str) or not value.strip():
raise Rejected(f"{field} must be a non-empty string", INVALID)
return value.strip()
def _phrase_of(request: dict[str, Any]) -> str:
"""The request's phrase, held to the generated shape.
``phrase.validate`` and not a looser check, for the reason it exists: the
phrase is this stream's only credential, so anything that reaches the
registry has to be a password rather than ``a-b-c``. The refusal never
echoes the phrase back.
"""
value = request.get("phrase")
if not isinstance(value, str):
raise Rejected("phrase must be a string", INVALID)
try:
return phrase_mod.validate(value)
except ValueError:
# Not `{exc}`: the validator names the value it refused, and this
# message travels back over the socket into the broker's log. The
# shape, never the phrase.
raise Rejected(
"the phrase given is not of the expected shape: four words of at "
"least three letters plus a five-character tail",
INVALID,
) from None
def _fps(request: dict[str, Any], default: int) -> int:
value = request.get("fps")
if value is None:
return default
if isinstance(value, bool) or not isinstance(value, int):
raise Rejected(f"fps must be an int, got {type(value).__name__}", INVALID)
if value <= 0 or value > FPS_CAP:
raise Rejected(f"fps must be between 1 and {FPS_CAP}, got {value}", INVALID)
return value
class ControlServer:
"""The accept loop for ``live.sock``. One connection at a time.
The same shape as ``hhstream_pointer.server.PointerServer``: the broker is
the only peer, the ops are one small line each, and an async server would
buy nothing but a way to interleave two attaches.
"""
def __init__(
self,
socket_path: Path | str,
control: Control,
*,
socket_mode: int = 0o660,
) -> None:
self.socket_path = Path(socket_path)
self.control = control
self.socket_mode = socket_mode
self._sock: socket.socket | None = None
self.ready = threading.Event()
def listen(self) -> None:
"""Bind and listen. A stale socket file is replaced, not refused:
a crashed daemon leaves one behind and the unit must still start."""
self.socket_path.parent.mkdir(parents=True, exist_ok=True)
if self.socket_path.is_socket():
self.socket_path.unlink()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.bind(str(self.socket_path))
os.chmod(self.socket_path, self.socket_mode)
sock.listen(LISTEN_BACKLOG)
self._sock = sock
self.ready.set()
log.info("control socket listening on %s", self.socket_path)
def serve_forever(self) -> None:
assert self._sock is not None, "listen() first"
while True:
# Read into a local first. `close()` runs on another thread and
# sets `_sock` to None, so reading the attribute twice can find a
# socket and then find nothing -- measured, as an AttributeError
# out of a daemon thread at shutdown rather than the clean return
# this loop is supposed to make.
sock = self._sock
if sock is None:
return
try:
conn, _ = sock.accept()
except OSError:
# The other way `close()` shows up: the listener was closed
# while this thread was blocked in `accept`.
return
with conn:
self._serve_connection(conn)
def close(self) -> None:
sock, self._sock = self._sock, None
if sock is not None:
sock.close()
self.socket_path.unlink(missing_ok=True)
self.ready.clear()
def _serve_connection(self, conn: socket.socket) -> None:
with conn.makefile("rwb") as stream:
while True:
line = stream.readline(MAX_LINE_BYTES + 1)
if not line:
return
if len(line) > MAX_LINE_BYTES:
_write(stream, _no("request line too long", INVALID))
return
try:
request = json.loads(line)
except json.JSONDecodeError as exc:
_write(stream, _no(f"malformed JSON: {exc}", INVALID))
continue
_write(stream, self.control.handle(request))
def _write(stream, response: dict[str, Any]) -> None:
stream.write(json.dumps(response, separators=(",", ":")).encode() + b"\n")
stream.flush()
+43
View File
@@ -0,0 +1,43 @@
"""``hhstream-mcp`` -- the ``hhstream`` CLI, as Model Context Protocol tools.
A **shim**, and deliberately the thinnest one that can be honest: every 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. No behavioural rule lives
here. The idle clock, the pointer lease, the container policy, the allowlist,
the exit-code table and the refusal messages are all the CLI's and the broker's,
and this package's one job is to not get between an agent and them.
In process, and not as a subprocess: ``hhstream.cli`` is importable Python, its
``main`` already takes an argv list and returns an exit code from the frozen
table, and spawning a Python interpreter per tool call to re-parse arguments
this process just built would be paying for an isolation nobody asked for. The
seam that matters is the *argv list* -- the thing this layer actually decides --
and that is identical either way. :mod:`hhstream_mcp.invoke` says which two of
the CLI's paths cannot be called in process, and what is done about them.
Why a separate distribution from ``hhstream`` rather than one more entry point
in ``pyproject.toml``: the frame socket, the CLI and the broker are stdlib-only
by policy (``pyproject.toml``, ``docs/CONTRACT-sessions.md`` §6 rule 3), and the
MCP SDK is a third-party dependency. Growing ``packages.hhstream`` an ``mcp``
dependency to serve a shim would put that dependency on the compositor's own
units. So the code lives beside the others under ``src/`` -- the dev shell's
``PYTHONPATH`` reaches it for free -- and ``nix/mcp.nix`` builds it as its own
derivation, with its own pyproject, that *depends on* the ``hhstream`` package.
The interface is frozen in ``docs/CONTRACT-mcp.md``: the tool names, their
arguments, and which exit code arrives as which MCP error. The modules split
along the one line that matters for testing -- :mod:`hhstream_mcp.invoke`,
:mod:`hhstream_mcp.media` and :mod:`hhstream_mcp.tools` are standard library
only, so the argv each tool builds, the parsing of what the CLI printed and the
error mapping are all testable without the SDK and without a live socket. Only
:mod:`hhstream_mcp.server` imports ``mcp``.
"""
from __future__ import annotations
__version__ = "0.1.0"
#: What the server calls itself in the ``initialize`` handshake. The same name
#: an MCP client configuration block is expected to use for it, so a log line
#: and a config entry can be matched up by eye.
SERVER_NAME = "hhstream"
+8
View File
@@ -0,0 +1,8 @@
"""``python -m hhstream_mcp`` — the same entry point as the ``hhstream-mcp`` script."""
from __future__ import annotations
from .server import main
if __name__ == "__main__":
raise SystemExit(main())
+499
View File
@@ -0,0 +1,499 @@
"""Run the CLI's own functions, in this process. Standard library only.
No subprocess. A tool builds the same argv list the CLI's parser takes, this
module hands it to ``hhstream.cli``'s parser, runs the handler argparse
selected, and reports what that handler printed and returned. The behavioural
rules stay exactly where they were -- the idle clock, the lease, the exit-code
table, the allowlist and every refusal message are the CLI's and the broker's --
and what is saved is a process spawn per tool call and a ``PATH`` to get wrong.
**Why not ``hhstream.cli.main``.** Two of its paths end in an ``exec``, and in
a CLI that is correct while here it would replace the MCP server mid-session and
the client would see its connection die:
1. ``main`` calls ``ensure_access`` before the four frame verbs, which re-execs
the whole process through the setuid ``sg`` wrapper when the frame socket is
out of reach.
2. ``cmd_run`` ends in ``os.execvpe`` -- that *is* the verb. ``run`` therefore
spawns instead; see :meth:`Runner.launch`.
So the parser is the CLI's (``cli.build_parser``), the handler is the one
argparse selected, and the exit code is that handler's own return value. What
this module adds is the dispatch line between them, the capture, and the remedy
sentence per exit code.
**The one capability lost with the ``sg`` re-exec**, stated plainly because it
is a real difference from running the CLI: a process that cannot read the frame
socket does not recover here. ``shot`` and ``record`` fail with the CLI's own
message plus a hint, where the CLI would have rejoined the group and succeeded.
The remedy is to give the server the group in the first place -- see the README
section on registering it.
**Serialised.** The CLI prints to process-global ``sys.stdout``, so two
concurrent calls would interleave their output into each other's reply. One
lock around the whole call is the honest fix, and costs nothing a caller would
notice: the broker already serialises every mutation, and the CLI was one
process per verb anyway.
"""
from __future__ import annotations
import contextlib
import dataclasses
import io
import json
import os
import shutil
import sys
import tempfile
import threading
import time
import traceback
from typing import Any, Callable, Iterator
from hhstream import cli
from hhstreamd.protocol import ExitCode
#: Exit 1 is not in the frozen table: it is what the *frame* verbs return when
#: the publisher sent no frame or a tool they need is missing, and what this
#: module reports for an exception no handler caught.
GENERIC_FAILURE = 1
#: The three frame verbs' handlers, by the name the CLI's parser gives them.
#: `run` is deliberately absent -- it is the one that execs -- and the session
#: namespace needs no entry, because argparse sets `func` for it.
FRAME_VERBS: dict[str, Callable[[Any], int]] = {
"status": cli.cmd_status,
"shot": cli.cmd_shot,
"record": cli.cmd_record,
}
#: One CLI call at a time. See the module docstring.
_ONE_AT_A_TIME = threading.Lock()
@dataclasses.dataclass(frozen=True)
class Outcome:
"""One completed CLI call, exactly as it ended."""
argv: list[str]
returncode: int
stdout: str
stderr: str
@property
def ok(self) -> bool:
return self.returncode == 0
def payload(self) -> dict[str, Any] | None:
"""The protocol object a ``--json`` verb printed, wherever it printed it.
stdout on success and **stderr on failure** -- that is the CLI's own
split (``hhstream_session._finish``), not a guess: an error always goes
to stderr whatever the output mode, because that is what an agent
branches on. Both streams are searched in both cases anyway, because a
verb that grows a warning on the happy path should not take the parsing
with it.
"""
for text in (self.stdout, self.stderr):
found = first_json_object(text)
if found is not None:
return found
return None
def first_json_object(text: str) -> dict[str, Any] | None:
"""The first JSON *object* in ``text``, or ``None``.
A scan rather than ``json.loads`` on the whole stream: ``session start``
prints the bare id above its object, and a verb that one day prints a line
above one should not stop being parseable.
"""
decoder = json.JSONDecoder()
index = text.find("{")
while index != -1:
try:
value, _ = decoder.raw_decode(text, index)
except ValueError:
index = text.find("{", index + 1)
continue
if isinstance(value, dict):
return value
index = text.find("{", index + 1)
return None
# ── what each exit code means to an agent ──────────────────────────────────
#: The sentence a calling agent needs after a refusal: not what went wrong --
#: the CLI's own ``reason`` says that better than any table could -- but what to
#: do about it. Keyed by the frozen exit codes of
#: ``docs/CONTRACT-sessions.md`` §4, so a new code is a missing key here and
#: not a silently generic message.
REMEDY: dict[int, str] = {
ExitCode.USAGE: (
"The call was rejected before anything happened: an argument is "
"missing, malformed, or names something this build does not support. "
"Fix the arguments; retrying the same call will fail the same way."
),
ExitCode.NO_SUCH_SESSION: (
"No session (or process) by that id. Read `hhstream://sessions` to see "
"which ids exist; a reaped session is gone and has to be started again."
),
ExitCode.BAD_STATE: (
"The session exists but is not in a state this verb can act on -- it "
"is still starting, or it has already exited, been killed or been "
"reaped. Read `hhstream://sessions/<id>` to see which."
),
ExitCode.DAEMON_UNREACHABLE: (
"The session broker (`hhstreamd`) could not be reached on its control "
"socket. Nothing was done. This is an operator problem, not an "
"argument problem: the daemon is down, or $HHSTREAM_SOCKET points "
"somewhere else. The frame tools (`shot`, `record`, `run`) and "
"`hhstream://status` do not need the broker and may still work."
),
ExitCode.POLICY: (
"Refused by policy. The application is not on the broker's allowlist, "
"or an argument is not one the allowlist permits, or a budget (session "
"cap, workspace band) is full. No retry will change it; this is a "
"configuration decision."
),
ExitCode.TIMEOUT: (
"The broker accepted the request and did not finish in time. Whether "
"it took effect is unknown -- read the state back "
"(`hhstream://sessions`, `hhstream://sessions/<id>`, "
"`hhstream://pointer`) before retrying, and retry with the same "
"`request_id` so a mutation cannot happen twice."
),
ExitCode.BUSY: (
"Something else holds what this call needs -- for the pointer and "
"keyboard verbs, another session holds the one pointer lease, and the "
"refusal names the holder. Nothing was injected. Read "
"`hhstream://pointer` to see who holds it, then wait for them to "
"release it or for its TTL to expire. Do NOT try to take it from "
"them; there is no such verb."
),
ExitCode.NO_LEASE: (
"This verb needs the pointer lease and this session does not hold one "
"(never acquired, already released, or expired -- an idle lease is "
"force-released by the broker). Call `pointer_acquire` for this "
"session and pass the `lease_id` it returns as `lease` on every "
"pointer and keyboard call. A lease id that was refused is dead; "
"acquire a new one rather than retrying with it."
),
ExitCode.COMPOSITOR: (
"The compositor or the input driver failed. **The session itself is "
"not lost** -- it keeps running in degraded mode -- so do not treat "
"this as a dead session. The compositor may be down, the container may "
"be gone, or the driver refused the request (an unmappable character, "
"a keysym this layout does not have)."
),
GENERIC_FAILURE: (
"The command failed without one of the broker's classified codes. For "
"the frame tools this is usually the publisher sending no frame (is the "
"compositor up? read `hhstream://status`) or `grim`/`ffmpeg` missing "
"from the "
"server's PATH. The text below is the CLI's own."
),
}
def remedy_for(returncode: int) -> str:
try:
name = ExitCode(returncode).name
except ValueError:
name = "UNCLASSIFIED"
advice = REMEDY.get(
returncode,
"The CLI exited with a code this server does not know. Treat it as a "
"failure and read the output below; do not assume anything happened.",
)
return f"exit {returncode} ({name}): {advice}"
# ── capture ────────────────────────────────────────────────────────────────
@contextlib.contextmanager
def captured() -> Iterator[tuple[io.StringIO, io.StringIO]]:
"""Redirect the CLI's ``print``s into a pair of buffers.
Python-level only, and that is enough **because the protocol is not on file
descriptor 1 any more**: :func:`hhstream_mcp.server.claim_transport` takes a
private duplicate of stdout at start-up and points fd 1 at the log. So a
stray write from a grandchild (``ffmpeg``, which the CLI does not capture)
lands in the server's log rather than in the client's stream, and this
context manager only has to collect what the handler itself printed.
"""
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
yield out, err
def dispatch(argv: list[str]) -> int:
"""Parse ``argv`` with the CLI's own parser and run the handler it selects.
The CLI's ``main`` minus its two ``exec`` paths; see the module docstring.
"""
parser = cli.build_parser()
args = parser.parse_args(argv)
if args.command is None:
parser.print_help(sys.stderr)
return int(ExitCode.USAGE)
handler = FRAME_VERBS.get(args.command)
if handler is not None:
return int(handler(args))
# The session namespace: argparse already chose the handler when it parsed.
return int(getattr(args, "func")(args))
def access_hint(argv: list[str]) -> str:
"""The sentence the ``sg`` re-exec would otherwise have made unnecessary.
Added to a failure only when the diagnosis is actually true, and only for
the verbs it could be true of. The predicate is the CLI's own, asked about
the CLI's own resolved socket path; the verb list is the one ``cli.main``
guards, because the frame socket has nothing to do with why a session verb
failed and an explanation that does not apply is worse than none.
"""
try:
# Inside the capture, because an argv argparse refuses makes it print
# usage -- and this runs *after* the call, so that print would reach
# the log rather than the reply, saying the same thing twice in the
# wrong place.
with captured():
args = cli.build_parser().parse_args(argv)
if args.command not in FRAME_VERBS and args.command != "run":
return ""
socket_path = getattr(args, "frame_socket", None)
if socket_path and not cli.have_access(socket_path):
return (
f"\n\nThis process cannot read {socket_path}. The hhstream CLI "
"would have re-joined the compositor's group through the "
"setuid 'sg' wrapper at this point; this server cannot, "
"because that is an exec which would replace it and drop the "
"client's connection. Run it as a member of that group "
"instead -- `sg hhstream -c hhstream-mcp` in the client's "
"spawn command, or add the account to the group."
)
except SystemExit:
# A parse that fails here fails identically in the call itself, and
# that failure is the one worth reporting.
return ""
return ""
# ── the runner ─────────────────────────────────────────────────────────────
@dataclasses.dataclass(frozen=True)
class Spawned:
"""A process that was started and deliberately not waited for."""
argv: list[str]
pid: int
exited: bool
stdout: str
stderr: str
class Runner:
"""Calls the CLI. Holds the entry point and nothing else.
No lease, no session id, no last reply. The server is a shim
(``docs/CONTRACT-mcp.md`` §3), and the moment it remembers a lease an agent
can no longer see which lease its call used.
``entry`` exists so the tests can put a recorder where the CLI goes: what
this layer decides is the argv list, and a test that cannot see the argv
list is testing nothing. There is no second production value for it.
"""
def __init__(self, entry: Callable[[list[str]], int] | None = None) -> None:
self.entry = entry or dispatch
def run(self, argv: list[str]) -> Outcome:
"""One call, start to finish. Never raises for a CLI failure."""
with _ONE_AT_A_TIME:
with captured() as (out, err):
try:
code = int(self.entry(list(argv)))
except SystemExit as exc:
# argparse's own refusals, and the handlers' `sys.exit` for
# an unreachable compositor or a grim that is not there.
code = _exit_status(exc)
except BaseException: # noqa: BLE001 -- a CLI process would
# have died here with a traceback on stderr and status 1;
# reproducing that is more honest than letting it reach the
# protocol as a transport error.
traceback.print_exc(file=sys.stderr)
code = GENERIC_FAILURE
stdout, stderr = out.getvalue(), err.getvalue()
if code != 0:
stderr += access_hint(list(argv))
return Outcome(argv=list(argv), returncode=code, stdout=stdout, stderr=stderr)
def launch(self, command: list[str], *, settle: float) -> Spawned:
"""``run``: put an application on the screen and do not wait for it.
``cli.cmd_run`` is two lines -- the environment a Wayland client needs,
then ``os.execvpe`` -- and the second of them is why it cannot be
called here: it would turn this server into the application. So the
environment comes from the CLI's own
:func:`hhstream.cli.env_for_session` and the exec is done by
``posix_spawn``:
* ``posix_spawn`` and not ``fork`` because this runs on a worker thread.
A ``fork`` from a threaded process can inherit a lock another thread
was holding, and Python warns about exactly that; ``posix_spawn``
leaves no Python running between the clone and the exec.
* ``setsid`` puts the application in its own session, so a client that
kills this server's process group does not take the desktop with it.
That, plus not waiting, is what "launch and forget" means.
* The executable is resolved *here*, so "no such command" is a refusal
an agent can read rather than a child exiting 127 into a log.
* A reaper thread waits on the pid, so a long-lived application that
eventually exits does not sit in this process's table as a zombie.
"""
# The frame socket the CLI would have resolved -- its flag default, or
# $HHSTREAM_FRAME_SOCKET -- read out of its own parser rather than
# re-derived, because `run` takes the compositor's runtime directory
# from it and a second opinion about that path is a second bug.
frame_socket = cli.build_parser().parse_args(["status"]).frame_socket
runtime_dir = os.path.dirname(frame_socket)
try:
environment = dict(os.environ)
environment.update(cli.env_for_session(runtime_dir))
except SystemExit as exc:
# `env_for_session` refuses with `sys.exit(message)` when the
# compositor has bound no Wayland socket. The message is the CLI's
# own and is handed on verbatim.
return Spawned(
argv=command, pid=0, exited=True, stdout="", stderr=str(exc.code)
)
resolved = shutil.which(command[0], path=environment.get("PATH"))
if resolved is None:
return Spawned(
argv=command,
pid=0,
exited=True,
stdout="",
stderr=f"hhstream-mcp: no executable {command[0]!r} on PATH",
)
return _spawn_detached(resolved, command, environment, settle)
def _exit_status(exc: SystemExit) -> int:
"""``SystemExit`` as a status. A message is status 1, as in a real process."""
if exc.code is None:
return 0
if isinstance(exc.code, int):
return exc.code
return GENERIC_FAILURE
def _spawn_detached(
resolved: str, command: list[str], environment: dict[str, str], settle: float
) -> Spawned:
"""Start the application in its own session and report its pid."""
with tempfile.TemporaryDirectory(prefix="hhstream-mcp-run-") as scratch:
capture = os.path.join(scratch, "output")
# Its stdin must not be the protocol stream, and its first complaint is
# worth handing back to the agent rather than mixing into the server's
# log -- so both of its output descriptors go to one file, which this
# directory takes away afterwards. An application that keeps writing
# writes to a deleted inode and leaves nothing behind.
file_actions = [
(os.POSIX_SPAWN_OPEN, 0, os.devnull, os.O_RDONLY, 0o666),
(
os.POSIX_SPAWN_OPEN,
1,
capture,
os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
0o600,
),
(os.POSIX_SPAWN_DUP2, 1, 2),
]
pid = os.posix_spawn(
resolved, command, environment, file_actions=file_actions, setsid=True
)
exited = _watch(pid, settle)
if not exited:
_reap_later(pid)
try:
with open(capture, encoding="utf-8", errors="replace") as fh:
said = fh.read()
except OSError: # pragma: no cover -- the spawn created it
said = ""
return Spawned(
argv=command,
pid=pid,
exited=exited,
stdout="" if exited else said,
stderr=said if exited else "",
)
#: How often to look at a launched process while the settle window runs.
_WATCH_INTERVAL_S = 0.05
def _watch(pid: int, settle: float) -> bool:
"""``True`` if the process is gone before ``settle`` seconds are up.
``waitpid`` with ``WNOHANG``, so an application that fails at once is both
detected and reaped here.
"""
deadline = time.monotonic() + max(0.0, settle)
while True:
try:
reaped, _ = os.waitpid(pid, os.WNOHANG)
except ChildProcessError: # pragma: no cover -- already reaped
return True
if reaped == pid:
return True
if time.monotonic() >= deadline:
return False
time.sleep(_WATCH_INTERVAL_S)
def _reap_later(pid: int) -> None:
"""Wait on a surviving application, on a thread that does nothing else.
Without this the application sits in this process's table as a zombie from
the moment it exits until the server does. A thread blocked in ``waitpid``
is the cheapest way to not have that, and a daemon one so it never delays
shutdown.
"""
def wait() -> None:
try:
os.waitpid(pid, 0)
except (ChildProcessError, OSError): # pragma: no cover
pass
threading.Thread(target=wait, name=f"hhstream-mcp-reap-{pid}", daemon=True).start()
def temp_name(prefix: str, suffix: str) -> str:
"""A unique filename for an artefact, in the system temporary directory.
Used for ``record``'s default destination, which is the one artefact a tool
hands back by *path*: it has to outlive the call, so it cannot live in a
directory this process cleans up.
"""
directory = os.path.join(tempfile.gettempdir(), "hhstream-mcp")
os.makedirs(directory, exist_ok=True)
stamp = time.strftime("%Y%m%d-%H%M%S")
return os.path.join(directory, f"{prefix}-{stamp}-{os.getpid()}{suffix}")
+115
View File
@@ -0,0 +1,115 @@
"""Read back what ``shot`` and ``record`` produced. Standard library only.
Two small readers, and both are deliberately readers rather than deciders.
``shot`` writes a file and prints its path; ``record`` writes an mp4 and prints
the path with the rate it measured. The geometry and the rate are facts those
artefacts already carry, and an agent that gets a picture without its
dimensions has to guess at the coordinate space it is about to aim the pointer
in -- so they are parsed out and put in the text part of the reply.
Nothing here re-derives anything the CLI decided. The frame rate is the CLI's
own measured number, read off its output; the dimensions come from the image's
header, not from the configured output size, because the configured size is
what the compositor was *asked* for.
"""
from __future__ import annotations
import dataclasses
import re
import struct
PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
JPEG_MAGIC = b"\xff\xd8"
#: The SOFn markers that carry a JPEG's dimensions. Everything except DHT
#: (c4), DAC (cc) and the RSTn range (d0-d7), which share the 0xffc_ block.
_JPEG_SOF = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
@dataclasses.dataclass(frozen=True)
class Image:
media_type: str
width: int
height: int
size: int
def sniff(data: bytes) -> Image | None:
"""The media type and pixel size of one captured frame, or ``None``.
By magic bytes and not by the extension this server asked for. The frame
socket publishes whatever format the module configured -- ``image/png`` by
default, ``image/jpeg`` on the deployment machine -- and ``hhstream shot``
writes the payload it was given to the ``--out`` path verbatim, so a file
called ``.png`` holds a JPEG whenever the publisher is serving one. An
agent told the wrong media type gets an image its client cannot decode.
"""
if data.startswith(PNG_MAGIC):
return _png(data)
if data.startswith(JPEG_MAGIC):
return _jpeg(data)
return None
def _png(data: bytes) -> Image | None:
# IHDR is required to be the first chunk: 8 bytes of signature, a 4-byte
# length, the type, then width and height.
if len(data) < 24 or data[12:16] != b"IHDR":
return None
width, height = struct.unpack(">II", data[16:24])
return Image("image/png", width, height, len(data))
def _jpeg(data: bytes) -> Image | None:
index = 2
end = len(data)
while index + 3 < end:
if data[index] != 0xFF:
index += 1
continue
marker = data[index + 1]
if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
index += 2
continue
if marker == 0xD9 or marker == 0xDA: # end of image, or start of scan
return None
(length,) = struct.unpack(">H", data[index + 2 : index + 4])
if marker in _JPEG_SOF:
if index + 9 > end:
return None
height, width = struct.unpack(">HH", data[index + 5 : index + 9])
return Image("image/jpeg", width, height, len(data))
index += 2 + length
return None
#: What ``hhstream record`` prints on success, which is the only place the
#: *measured* rate exists: a software-rendered compositor tops out well under
#: the advertised fps, so the encoded rate is the one it counted, and an agent
#: reading the mp4 later cannot recover how long the capture actually took.
RECORD_LINE = re.compile(
r"^(?P<path>.+?) \((?P<frames>\d+) frames in (?P<seconds>[\d.]+)s -> (?P<fps>\d+) fps\)\s*$",
re.MULTILINE,
)
@dataclasses.dataclass(frozen=True)
class Recording:
path: str
frames: int
seconds: float
fps: int
def recording(stdout: str) -> Recording | None:
match = RECORD_LINE.search(stdout)
if match is None:
return None
return Recording(
path=match["path"],
frames=int(match["frames"]),
seconds=float(match["seconds"]),
fps=int(match["fps"]),
)
+46
View File
@@ -0,0 +1,46 @@
# The second distribution in this repository, and the only one with a
# third-party runtime dependency.
#
# It sits *inside* the package directory rather than at the repository root
# because the root `pyproject.toml` is `hhstream`'s and a project has one. The
# alternatives were worse: a second source tree would duplicate nothing but a
# directory level, and adding `hhstream-mcp` to the root project would put the
# `mcp` dependency on the compositor's own units -- which is the one thing
# `docs/CONTRACT-sessions.md` §6 rule 3 and the root pyproject's own comment
# forbid. The root project excludes `hhstream_mcp*` from its package discovery
# for the same reason; see the note there.
#
# `package-dir` maps the package name onto this directory, so the layout stays
# `src/hhstream_mcp/` -- which is what puts it on the dev shell's
# `PYTHONPATH=$PWD/src` beside every other package here, with no second path to
# set and no second place for a test to import from.
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "hhstream-mcp"
version = "0.1.0"
description = "Drive a headless Hyprland session over the Model Context Protocol"
requires-python = ">=3.11"
# `mcp` is the official Python SDK and the whole reason this is a separate
# distribution. `anyio` is declared rather than taken for granted through the
# SDK: `server.py` calls `anyio.run` and `anyio.to_thread` directly, and a
# dependency used by name belongs in the metadata.
#
# `hhstream` is NOT listed, and it is not optional either: this package imports
# `hhstream.cli`, `hhstreamd.protocol` and `hhstream_session` and does not work
# without them. It is absent because `hhstream` is not a wheel anyone installs
# from an index -- it is this repository's other derivation, and `nix/mcp.nix`
# is where the two are joined. A dependency naming a version nobody can
# resolve would be worse than the comment you are reading.
dependencies = ["mcp>=1.9", "anyio>=4"]
[project.scripts]
# Stdio only. One process per client, spawned by the client; no port, no daemon.
hhstream-mcp = "hhstream_mcp.server:main"
[tool.setuptools]
packages = ["hhstream_mcp"]
package-dir = { "hhstream_mcp" = "." }
+436
View File
@@ -0,0 +1,436 @@
"""The read-only half of the surface: state as resources. Standard library only.
Every verb of the CLI that only *reads* is addressed by URI here rather than
called as a tool, because that is the split the protocol draws. 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 business. A
tool is **model**-controlled: an act the model chooses to perform, and every one
left in :mod:`hhstream_mcp.tools` either changes something or costs something.
So the line is not "cheap here, expensive there" -- it is *who decides*.
``hhstream://sessions`` is state a host may always include; ``session_kill`` is
a decision only the model can make.
Two things this module is careful about:
* **A resource read must not write.** That rules out ``session container <id>``,
which looks like a read and is not: with an id the CLI runs
``container.reconcile`` and brings the record up to the compositor's answer.
Only the no-id form (``container.list``) is here, as ``hhstream://containers``;
the reconciling form stays the ``session_container`` tool.
* **A refusal must not arrive as content.** There is no ``isError`` on a
resource read, so a CLI refusal is *raised* and carries the same remedy
sentence a tool error would have. Returning the broker's failure object as
the body would make "this session does not exist" look like a successful read
of a session.
Arguments become query parameters, because a resource read takes nothing but a
URI. Only the declared ones are accepted -- an unknown parameter is refused
rather than dropped, for the reason every tool schema sets
``additionalProperties: false``: an argument silently ignored is a read that
answered a different question than the one asked.
"""
from __future__ import annotations
import dataclasses
import urllib.parse
from typing import Any, Callable
from . import media, tools
from .invoke import Outcome, Runner, remedy_for
#: The scheme every resource here lives under. One, because they are all views
#: of one machine's one desktop.
SCHEME = "hhstream"
JSON = "application/json"
TEXT = "text/plain"
class ReadRefused(Exception):
"""The CLI refused, or the URI names nothing. Raised, never returned.
Carries what a tool error would have carried, so a host that surfaces the
message gives its model the same remedy a tool call would have given it.
"""
def __init__(self, message: str, detail: dict[str, Any] | None = None) -> None:
super().__init__(message)
self.message = message
self.detail = detail or {}
@dataclasses.dataclass(frozen=True)
class Reading:
"""What one resource read produced. Text or bytes, never both."""
media_type: str
text: str | None = None
blob: bytes | None = None
Read = Callable[[Runner, dict[str, str]], Reading]
@dataclasses.dataclass(frozen=True)
class Entry:
"""One resource, or one family of them.
``route`` is the URI after the scheme, as segments: a literal matches
itself, ``{name}`` captures exactly one segment. An entry with a capture is
a *template*; there is no second class for it, because the only thing that
differs is whether ``resources/list`` or ``resources/templates/list``
mentions it.
"""
route: tuple[str, ...]
name: str
title: str
description: str
media_type: str
read: Read
#: Query parameters this read accepts, by the name an agent puts in the
#: URI. What each becomes on the command line is :data:`_FLAGS`' business,
#: so that translation lives in one place rather than once per entry.
parameters: tuple[str, ...] = ()
@property
def captures(self) -> tuple[str, ...]:
return tuple(s[1:-1] for s in self.route if s.startswith("{"))
@property
def is_template(self) -> bool:
return bool(self.captures)
@property
def uri(self) -> str:
"""The concrete URI. Only meaningful for an entry with no captures."""
return f"{SCHEME}://" + "/".join(self.route)
@property
def uri_template(self) -> str:
"""RFC 6570, including the query parameters it accepts."""
base = f"{SCHEME}://" + "/".join(self.route)
if not self.parameters:
return base
return base + "{?" + ",".join(sorted(self.parameters)) + "}"
def match(self, segments: tuple[str, ...]) -> dict[str, str] | None:
"""The captured values, or ``None`` if this entry is not the one."""
if len(segments) != len(self.route):
return None
captured: dict[str, str] = {}
for pattern, value in zip(self.route, segments):
if pattern.startswith("{"):
if not value:
return None
captured[pattern[1:-1]] = value
elif pattern != value:
return None
return captured
# ── parsing a URI ──────────────────────────────────────────────────────────
def split(uri: str) -> tuple[tuple[str, ...], dict[str, str]]:
"""``hhstream://sessions/s-1/logs?lines=5`` -> ``(("sessions","s-1","logs"), {...})``.
The authority and the path are one route: ``urlsplit`` puts the first
segment in ``netloc`` for a ``scheme://a/b`` URI, which is an artefact of
the form rather than a distinction worth preserving.
"""
parsed = urllib.parse.urlsplit(uri)
if parsed.scheme != SCHEME:
raise ReadRefused(
f"not a {SCHEME} resource: {uri!r}. Every resource this server "
f"serves is {SCHEME}://… — call resources/list for the set."
)
joined = parsed.netloc + parsed.path
segments = tuple(s for s in joined.split("/") if s)
if not segments:
raise ReadRefused(f"{uri!r} names no resource; call resources/list")
query: dict[str, str] = {}
for key, value in urllib.parse.parse_qsl(parsed.query, keep_blank_values=True):
if key in query:
raise ReadRefused(
f"{key!r} is given more than once in {uri!r}; each parameter "
"takes one value"
)
query[key] = value
return segments, query
def resolve(uri: str) -> tuple[Entry, dict[str, str]]:
"""The entry for ``uri``, with its captures and validated query merged.
Literal routes are tried before templates, so ``hhstream://sessions`` is the
listing and not a session whose id happens to be absent.
"""
segments, query = split(uri)
for entry in sorted(ENTRIES, key=lambda e: len(e.captures)):
captured = entry.match(segments)
if captured is None:
continue
unknown = set(query) - set(entry.parameters)
if unknown:
accepted = ", ".join(sorted(entry.parameters)) or "none"
raise ReadRefused(
f"{entry.name} does not accept "
f"{', '.join(repr(u) for u in sorted(unknown))}; it accepts: {accepted}"
)
return entry, {**captured, **query}
raise ReadRefused(
f"no resource at {uri!r}. Call resources/list for the fixed ones and "
"resources/templates/list for the rest."
)
# ── turning a CLI call into a reading ──────────────────────────────────────
def _checked(outcome: Outcome, what: str) -> Outcome:
"""The outcome, or a refusal carrying the CLI's own words and the remedy."""
if outcome.ok:
return outcome
payload = outcome.payload() or {}
said = (outcome.stderr or outcome.stdout).strip()
raise ReadRefused(
f"could not read {what}: {remedy_for(outcome.returncode)}"
+ (f"\n\n{said}" if said else ""),
{
"ok": False,
"exit_code": outcome.returncode,
"error": payload.get("error"),
"reason": payload.get("reason"),
"hint": payload.get("hint"),
"remedy": remedy_for(outcome.returncode),
},
)
#: Query parameter -> the flag it becomes on the command line. One table, not
#: one entry per resource: the name an agent puts in a URI and the flag the CLI
#: takes are allowed to differ, and a per-entry copy would be a per-entry
#: chance for them to disagree.
_FLAGS = {"all": "all", "events": "events", "lines": "lines"}
#: Of those, the ones that are switches and not values -- so `?all=true` is
#: `--all` and `?all=false` is no flag at all, rather than `--all=false`, which
#: the CLI would refuse.
_SWITCHES = {"all"}
_FALSE = {"false", "0", "no", "off", ""}
def _flag_for(name: str, value: str) -> list[str]:
flag = _FLAGS[name]
if name in _SWITCHES:
return [] if value.strip().lower() in _FALSE else [f"--{flag}"]
return [tools.flag(flag, value)]
def _json_read(verb: list[str], what: str) -> Read:
"""A ``--json`` verb's protocol object, verbatim, as the resource's body.
Verbatim because that object is what the broker actually said, and a
resource that reshaped it would be a second wire format for the same facts.
"""
def read(runner: Runner, arguments: dict[str, str]) -> Reading:
options = ["--json"]
for name in sorted(arguments):
if name in _FLAGS:
options.extend(_flag_for(name, arguments[name]))
positionals = [arguments["id"]] if "id" in arguments else []
outcome = _checked(runner.run(tools.argv(verb, options, positionals)), what)
return Reading(media_type=JSON, text=outcome.stdout.strip())
return read
def _status(runner: Runner, arguments: dict[str, str]) -> Reading:
"""``hhstream status``: the one verb with no ``--json``, so it stays text."""
outcome = _checked(runner.run(["status"]), "the session's status")
return Reading(media_type=TEXT, text=outcome.stdout.strip())
def _frame(runner: Runner, arguments: dict[str, str]) -> Reading:
"""One captured frame as bytes.
Serves both the whole screen and one named output: ``hhstream://screen``
captures with no ``--output`` and ``hhstream://outputs/{name}`` captures
with one, which is the same CLI call with one flag more.
The media type is read off the bytes, never assumed: the publisher serves
`image/jpeg` on some machines and the CLI writes the payload it was given
verbatim, so the entry's declared `mimeType` is a hint and this is the
answer.
"""
named = arguments.get("name")
what = f"output {named!r}" if named else "the screen"
outcome, frame = tools.capture(runner, named)
_checked(outcome, what)
if frame is None:
raise ReadRefused(
f"hhstream shot reported success but wrote no readable file for {what}"
)
image = media.sniff(frame)
return Reading(
media_type=image.media_type if image else "application/octet-stream",
blob=frame,
)
# ── the table ──────────────────────────────────────────────────────────────
#: Appended to the three descriptions whose verb the CLI's own note names.
_NOT_ACTIVITY = (
" Reading this does NOT reset the session's idle clock -- only the "
"`session_touch` tool does."
)
ENTRIES: tuple[Entry, ...] = (
Entry(
route=("status",),
name="status",
title="Is the desktop up",
description=(
"Whether the headless Hyprland session is running and reachable: "
"each unit's state, the frame socket's path and whether this "
"server can read it, the Wayland socket the compositor bound, and "
"one probe frame's size. Read this first when something else "
"fails in a way that smells like the desktop being down. It says "
"nothing about the session broker -- an unreachable broker shows "
"up as exit 5 from a session tool or a failed read of "
"`hhstream://sessions`."
),
media_type=TEXT,
read=_status,
),
Entry(
route=("sessions",),
name="sessions",
title="Every tracked session",
description=(
"The broker's list: every session it is tracking, with its state, "
"pid and idle deadline. `?all=true` includes the tombstones of "
"ended ones." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "list"], "the session list"),
parameters=("all",),
),
Entry(
route=("pointer",),
name="pointer",
title="Who holds the pointer",
description=(
"Who holds the one pointer lease, since when, and which buttons "
"and KEYS are held down. This is what to read after a tool "
"returns exit 8 (BUSY): it names the holder. There is one cursor, "
"so there is one of these." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "pointer", "state"], "the pointer lease"),
),
Entry(
route=("containers",),
name="containers",
title="Every container, and the orphans",
description=(
"Each session's output, workspace and mode, plus the `hh-*` "
"outputs no live session claims. The output names here are what "
"`hhstream://outputs/{name}` and the `record` tool take.\n\n"
"This is the LIST, which only reads the record. Asking where a "
"session's window is *now* re-reads the compositor and writes the "
"answer back, so it is the `session_container` tool and not a "
"resource." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "container"], "the container list"),
),
Entry(
route=("screen",),
name="screen",
title="One frame of the screen",
description=(
"The published main output, as an image. This is the whole "
"compositor layout: with containers on, each session's own output "
"sits beside the main one, so the frame is wider than any single "
"output's configured size. For one container alone, read "
"`hhstream://outputs/{name}`."
),
media_type="image/png",
read=_frame,
),
Entry(
route=("sessions", "{id}"),
name="session",
title="One session, in detail",
description=(
"One session: its state, pid, container, idle deadline, and the "
"most recent entries from the broker's audit trail. `?events=N` "
"sets how many of those to include. The audit events are where a "
"session that died for a reason its own logs do not show explains "
"itself." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "status"], "that session"),
parameters=("events",),
),
Entry(
route=("sessions", "{id}", "logs"),
name="session-logs",
title="A session's captured output",
description=(
"The tail of the application's own stdout and stderr, as the "
"broker captured it -- the first place to look when an "
"application started and then did nothing. `?lines=N` sets how "
"much to tail.\n\n"
"There is no following here and there cannot be: this SDK does "
"not advertise resource subscriptions, and the CLI's `--follow` "
"polls until interrupted. Read it again instead." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "logs"], "that session's logs"),
parameters=("lines",),
),
Entry(
route=("outputs", "{name}"),
name="output",
title="One output's frame",
description=(
"One output captured in isolation through `grim` -- a session's "
"container is `hh-<session-id>`, and `hhstream://containers` "
"lists the names. Unlike `hhstream://screen` this is exactly the "
"configured size of that output, which is the coordinate space "
"the pointer tools aim in."
),
media_type="image/png",
read=_frame,
),
)
BY_NAME: dict[str, Entry] = {entry.name: entry for entry in ENTRIES}
#: The fixed ones, for `resources/list`.
FIXED: tuple[Entry, ...] = tuple(e for e in ENTRIES if not e.is_template)
#: The rest, for `resources/templates/list`.
TEMPLATES: tuple[Entry, ...] = tuple(e for e in ENTRIES if e.is_template)
def read(runner: Runner, uri: str) -> Reading:
"""Resolve ``uri`` and read it. Raises :class:`ReadRefused`."""
entry, arguments = resolve(uri)
return entry.read(runner, arguments)
+441
View File
@@ -0,0 +1,441 @@
"""The MCP wiring. The only module here that imports the SDK.
Transport is **stdio** and nothing else: one process per client, spawned by the
client, no port and no daemon. There is already a daemon in this system
(`hhstreamd`) and it owns all the state; a second long-lived process in front of
it would be a second place for a lease to be remembered.
The low-level :class:`mcp.server.Server` rather than FastMCP, for two reasons.
The schemas here are written by hand -- ``pointer_move``'s exclusive ``to``/``by``
pair, ``additionalProperties: false`` on every tool -- and deriving them from
Python type hints would mean writing the signatures that happen to produce them.
And ``shot`` returns image content beside its text, which is a content list, not
a return value.
**The transport does not stay on file descriptor 1**, and that is load-bearing
rather than tidy: the tools run the CLI's handlers *in this process*
(:mod:`hhstream_mcp.invoke`), those handlers ``print``, and ``record`` spawns an
``ffmpeg`` whose output the CLI does not capture. Any one of those writing on
fd 1 would put a line of prose in the middle of a JSON-RPC stream, which a
client reports as a parse failure with no hint of where it came from. So
:func:`claim_transport` takes a private duplicate of stdin and stdout before
anything else runs and then points fd 1 at the log and fd 0 at ``/dev/null``.
After that the protocol is on descriptors nothing else in the process knows
about, and a stray write is a log line.
"""
from __future__ import annotations
import argparse
import io
import logging
import os
import sys
from typing import Any
import anyio
import mcp.types as types
from mcp.server.lowlevel import NotificationOptions, Server
from mcp.server.lowlevel.helper_types import ReadResourceContents
from mcp.server.stdio import stdio_server
from mcp.shared.exceptions import McpError
from pydantic import AnyUrl
from . import SERVER_NAME, __version__, resources, tools
from .invoke import Runner
log = logging.getLogger("hhstream.mcp")
#: Shown by a client that surfaces server instructions, and the one place the
#: whole surface can be introduced at once. The two rules are repeated on the
#: individual tools, because a per-tool description is what a client shows at
#: the point of use.
INSTRUCTIONS = """\
Drive this machine's headless Hyprland desktop: look at it, put applications on
it, and aim its one pointer and keyboard at them.
Everything here is one verb of the `hhstream` CLI and does nothing the CLI would
not. The surface is split the way the protocol splits it:
* **Resources are the state.** `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>` is one of
them with its recent audit events, `hhstream://sessions/<id>/logs` is an
application's own output, `hhstream://pointer` is who holds the input lease,
`hhstream://containers` is each session's output and workspace. Reading any of
them changes nothing.
* **Tools are the acts.** `session_start` puts an allowlisted application on the
screen and returns a session id; `shot` captures the screen now;
`pointer_acquire` gives you the lease every pointer and keyboard tool needs;
`session_kill` ends a session.
Two rules this surface will not let you avoid, because they are the two an agent
gets wrong:
1. `session_touch` is the ONLY thing that resets a session's idle clock.
Reading any resource deliberately does NOT, nor does `session_gc`, nor does
clicking or typing. A session being driven is still a session nobody has said
they want kept, and the broker reaps it on schedule.
2. Every keyboard tool needs the POINTER lease, and holds only while that lease
holds. There is no keyboard lease: one compositor seat means one keyboard
focus. A held non-modifier key floods the window until you lift it or the
lease expires, because the application does the repeating.
Tool failures come back as tool errors carrying the CLI's own exit code, its
machine-readable error name, its reason and what to do next. Exit 8 means
another session holds the pointer lease (read `hhstream://pointer` for the
holder); exit 9 means you need to acquire one. A resource read that the CLI
refuses is raised as an error carrying the same remedy, because a resource has
no way to hand back a failure as content.
"""
def annotations_for(tool: tools.Tool) -> types.ToolAnnotations:
"""Hints, and only honest ones.
``readOnlyHint`` is set from the verb's own behaviour, which is why
``session_container`` does not get it: with a session id that verb runs
``container.reconcile`` and writes the record back. ``openWorldHint`` is
false throughout -- the world here is one desktop on one machine.
"""
return types.ToolAnnotations(
title=tool.title,
readOnlyHint=tool.read_only,
# Meaningful only when `readOnlyHint` is false, and then stated rather
# than left out: the spec's default for it is *true*, so omitting it
# would mark `session_touch` and `record` as possibly destructive.
destructiveHint=None if tool.read_only else tool.destructive,
openWorldHint=False,
)
def describe(tool: tools.Tool) -> types.Tool:
return types.Tool(
name=tool.name,
title=tool.title,
description=tool.description,
inputSchema=tool.schema,
annotations=annotations_for(tool),
)
def listing() -> list[types.Tool]:
return [describe(tool) for tool in tools.TOOLS]
def content_for(result: tools.Result) -> list[types.ContentBlock]:
blocks: list[types.ContentBlock] = [types.TextContent(type="text", text=result.text)]
if result.image is not None and result.media_type:
import base64
blocks.append(
types.ImageContent(
type="image",
data=base64.b64encode(result.image).decode("ascii"),
mimeType=result.media_type,
)
)
return blocks
def call(
runner: Runner,
name: str,
arguments: dict[str, Any],
available: Any = None,
) -> types.CallToolResult:
"""Run one tool. A refusal comes back as a tool error, never as a success.
``isError`` rather than a JSON-RPC error, throughout. That is not only a
preference: the SDK's own ``call_tool`` handler catches whatever this raises
and turns it into an ``isError`` result anyway, and for the CLI's refusals
it is the right channel regardless -- "another session holds the lease" is
something the calling agent has to read and act on, and a JSON-RPC error
reaches the client's log rather than the agent. So the error text is
written for the agent, including for the two cases that are not the CLI's
verdict at all: a tool name that does not exist, and this layer's own bug.
"""
# The *selected* set, not the whole table: a tool `--toolsets` left out is
# not listed, so calling it must fail rather than work anyway. The SDK only
# validates arguments against what `tools/list` returned, so without this a
# client could reach an unlisted tool by name.
offered = tools.BY_NAME if available is None else available
tool = offered.get(name)
if tool is None:
known = ", ".join(sorted(offered)) or "nothing (every toolset is disabled)"
hint = ""
if name in tools.MOVED_TO_RESOURCES:
# The v1 name. Say where it went rather than only that it is gone:
# a caller asking for `session_list` wants the session list, and the
# answer is one `resources/read` away.
hint = (
f" It is a RESOURCE now, not a tool: read "
f"{tools.MOVED_TO_RESOURCES[name]} instead. Reading state is "
"the host's to offer, not the model's to call -- call "
"resources/list for the whole read-only half of this server."
)
elif name in tools.BY_NAME:
hint = (
f" {name!r} exists but this server was started without its "
"toolset, so it is not offered."
)
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=f"no such tool: {name!r}.{hint} This server exposes: {known}",
)
],
structuredContent={"ok": False, "error": "no_such_tool"},
isError=True,
)
try:
result = tool.invoke(runner, arguments)
except (OSError, ValueError, KeyError) as exc:
# `Runner.run` already turns a handler's own exception into exit 1 with
# its traceback, so what reaches here is this layer's own fault -- a
# schema and an argv builder that disagree about a field name. Reported
# to the agent rather than only logged, because an agent that is told
# nothing retries forever.
log.exception("tool %s failed", name)
result = tools.Result(
text=f"the {name} tool failed before the CLI was called: {exc!r}",
data={"ok": False, "error": "tool_failed"},
is_error=True,
)
return types.CallToolResult(
content=content_for(result),
structuredContent=result.data,
isError=result.is_error,
)
# ── resources ──────────────────────────────────────────────────────────────
def describe_resource(entry: resources.Entry) -> types.Resource:
return types.Resource(
uri=AnyUrl(entry.uri),
name=entry.name,
title=entry.title,
description=entry.description,
mimeType=entry.media_type,
)
def describe_template(entry: resources.Entry) -> types.ResourceTemplate:
return types.ResourceTemplate(
uriTemplate=entry.uri_template,
name=entry.name,
title=entry.title,
description=entry.description,
mimeType=entry.media_type,
)
def resource_listing() -> list[types.Resource]:
return [describe_resource(entry) for entry in resources.FIXED]
def template_listing() -> list[types.ResourceTemplate]:
return [describe_template(entry) for entry in resources.TEMPLATES]
def read(runner: Runner, uri: str) -> list[ReadResourceContents]:
"""One resource read. A refusal is an error, because there is no other way.
A ``CallToolResult`` can say ``isError``; ``ReadResourceResult`` cannot. So
a URI that names nothing, or a CLI that refused, is raised as a JSON-RPC
error carrying the remedy a tool error would have carried. Handing back the
broker's failure object as the resource's *body* would make "no such
session" read as a successful read of a session.
"""
try:
reading = resources.read(runner, uri)
except resources.ReadRefused as refused:
raise McpError(
types.ErrorData(
code=types.INVALID_PARAMS,
message=refused.message,
data=refused.detail or None,
)
) from refused
body = reading.blob if reading.blob is not None else (reading.text or "")
return [ReadResourceContents(content=body, mime_type=reading.media_type)]
def build(runner: Runner, toolsets: Any = None) -> Server:
server: Server = Server(
SERVER_NAME, version=__version__, instructions=INSTRUCTIONS
)
available = tools.selected(toolsets)
by_name = {tool.name: tool for tool in available}
@server.list_tools()
async def _list() -> list[types.Tool]:
return [describe(tool) for tool in available]
@server.list_resources()
async def _list_resources() -> list[types.Resource]:
return resource_listing()
@server.list_resource_templates()
async def _list_templates() -> list[types.ResourceTemplate]:
return template_listing()
@server.read_resource()
async def _read_resource(uri: AnyUrl) -> list[ReadResourceContents]:
# Off the event loop for the reason a tool call is: this runs the CLI,
# which blocks. `str(uri)` because the route is parsed here, not by
# pydantic -- see `resources.split`.
return await anyio.to_thread.run_sync(lambda: read(runner, str(uri)))
# `validate_input` left on: the schemas are the first refusal, and they
# refuse before an argv list exists.
@server.call_tool()
async def _call(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
# The CLI call is blocking and can take seconds (`record`, a `start`
# with a readiness budget), so it goes to a worker thread: the event
# loop stays free to answer a ping and to read the next request. The
# calls themselves are serialised inside `Runner.run`, because the CLI
# prints to a stdout this process shares.
return await anyio.to_thread.run_sync(lambda: call(runner, name, arguments, by_name))
return server
def claim_transport() -> tuple[Any, Any]:
"""Take stdin and stdout for the protocol, then make fd 0 and 1 harmless.
Returns the pair of streams to hand to ``stdio_server``. After this call
the process's own ``sys.stdout`` writes to the log beside ``sys.stderr``,
and nothing that reads stdin can eat a request: both are the right answer
for a server whose tools run a CLI in-process.
"""
stdin = anyio.wrap_file(
io.TextIOWrapper(os.fdopen(os.dup(0), "rb"), encoding="utf-8", errors="replace")
)
stdout = anyio.wrap_file(
io.TextIOWrapper(os.fdopen(os.dup(1), "wb"), encoding="utf-8")
)
sys.stdout.flush()
# The literal descriptor 2, not `sys.stderr.fileno()`: what is wanted is
# "whatever the log is at the file-descriptor level", so that a grandchild
# which never heard of `sys` writes there too.
os.dup2(2, 1)
null = os.open(os.devnull, os.O_RDONLY)
try:
os.dup2(null, 0)
finally:
os.close(null)
return stdin, stdout
async def serve(server: Server, transport: tuple[Any, Any] | None = None) -> None:
stdin, stdout = transport if transport is not None else claim_transport()
async with stdio_server(stdin, stdout) as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
server.create_initialization_options(NotificationOptions()),
)
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="hhstream-mcp",
description=(
"Serve the hhstream CLI as Model Context Protocol tools over stdio. "
"Spawned by an MCP client; it speaks JSON-RPC on stdin/stdout and "
"logs to stderr."
),
epilog=(
"There is no --socket flag here, deliberately: the sockets are the "
"CLI's own environment -- $HHSTREAM_FRAME_SOCKET for the frame "
"socket and $HHSTREAM_SOCKET for the broker's control socket -- and "
"a second place to configure them is a second place for them to "
"disagree. Set them in the MCP client's `env` block."
),
)
parser.add_argument(
"--toolsets",
metavar="NAMES",
help="comma-separated families to offer as tools: "
+ ", ".join(tools.TOOLSETS)
+ ". Omitted, every tool is offered. Resources are NOT filtered by "
"this -- they are the host's context, not the model's tool budget.",
)
parser.add_argument(
"--list-tools",
action="store_true",
help="print the tool names and exit, without serving. Honours "
"--toolsets, so it is also how to see what a selection would offer.",
)
parser.add_argument(
"--list-resources",
action="store_true",
help="print the resource URIs and templates and exit, without serving.",
)
return parser
def chosen_toolsets(raw: str | None) -> list[str] | None:
"""``--toolsets`` as a list, or ``None`` for every tool."""
if raw is None:
return None
names = [part.strip() for part in raw.split(",") if part.strip()]
if not names:
raise tools.UnknownToolset(
"--toolsets was given no names. Omit the flag for every tool, or "
f"name some of: {', '.join(tools.TOOLSETS)}"
)
return names
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
# stderr, never stdout: stdout is the transport, and one stray print on it
# is a protocol error the client reports as a parse failure.
logging.basicConfig(
level=os.environ.get("HHSTREAM_MCP_LOG", "WARNING").upper(),
stream=sys.stderr,
format="%(levelname)s %(name)s: %(message)s",
)
try:
toolsets = chosen_toolsets(args.toolsets)
offered = tools.selected(toolsets)
except tools.UnknownToolset as exc:
# argparse's own exit code for a bad argument, because that is what
# this is: `choices=` cannot express a comma-separated subset.
parser.error(str(exc))
return int(2) # pragma: no cover -- parser.error exits
if args.list_tools:
for tool in offered:
print(f"{tool.name}\t{tool.title}")
return 0
if args.list_resources:
for entry in resources.FIXED:
print(f"{entry.uri}\t{entry.title}")
for entry in resources.TEMPLATES:
print(f"{entry.uri_template}\t{entry.title}")
return 0
log.info(
"serving %d tools and %d resources over stdio",
len(offered),
len(resources.ENTRIES),
)
# The transport is claimed before the event loop starts, so no coroutine can
# have written to fd 1 by the time it moves.
transport = claim_transport()
anyio.run(serve, build(Runner(), toolsets), transport)
return 0
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())
File diff suppressed because it is too large. Load diff
+252
View File
@@ -38,6 +38,9 @@ The verb tree, beyond the original eight:
session keyboard type ID TEXT one argument, raw UTF-8, no escapes
session keyboard key ID NAME tap: down then up
session keyboard down/up ID NAME
session stream enable ID publish ID's screen behind a spoken phrase
session stream disable ID stop publishing, and forget the phrase
session stream list/status what is being published, and who is watching
The pointer *and keyboard* verbs share one precondition — the pointer lease —
and the lease id lives in :mod:`hhstream_session.lease` between invocations,
@@ -187,6 +190,27 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
help="deduplication token: retrying a start with the same id returns the "
"original reply instead of launching a second application",
)
start.add_argument(
"--stream",
action="store_true",
help="also enable a live stream for this session and print its URL. "
"Needs the session's container output, which this creates — which is "
"why it is a flag here rather than a second command you have to "
"sequence yourself.",
)
start.add_argument(
"--stream-phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one (four words and a "
"five-character tail). It is the stream's only credential, so it is "
"held to exactly that shape.",
)
start.add_argument(
"--stream-fps",
type=int,
metavar="N",
help="frames per second for the stream (default: the broker's)",
)
start.add_argument(
"--no-container",
action="store_true",
@@ -303,6 +327,9 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
# ---- keyboard ----------------------------------------------------
_build_keyboard(verbs, common)
# ---- stream ------------------------------------------------------
_build_stream(verbs, common)
#: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored
#: here rather than imported: this module's whole integration promise is that it
@@ -627,6 +654,136 @@ def _build_keyboard(verbs: Any, common: argparse.ArgumentParser) -> None:
sub.add_argument("name", help="XKB keysym name, e.g. Control_L, Shift_L")
#: Printed under `stream --help` and under `enable`. The two facts an operator
#: gets wrong about this group, and they pull in opposite directions: the
#: phrase is a password, and *watching* is the one thing besides `touch` that
#: keeps a session alive.
STREAM_NOTE = (
"CREDENTIAL: the phrase in the URL is the stream's only protection — no "
"TLS, no second factor. Anyone who can reach the port and guess four "
"words can watch. It is never written to the audit log, and it is not "
"echoed by 'list' unless you ask for --json.\n\n"
"ACTIVITY: 'stream enable|disable|list|status' do NOT reset the idle "
"clock, like every pointer and keyboard verb. But A CONNECTED VIEWER "
"DOES: about once a minute the broker stamps 'touch' on any session "
"somebody is watching, so a session you are watching on a phone is not "
"reaped at three hours. An enabled stream with nobody watching captures "
"nothing and keeps nothing alive."
)
def _build_stream(verbs: Any, common: argparse.ArgumentParser) -> None:
"""``session stream <verb>`` — a live view of one session, behind a phrase.
A nested namespace for the reason ``pointer`` is one: these four verbs
share a precondition nothing else here has. It is the session's **container
output** — a stream never falls back to the main output, because that one
carries every other session.
"""
namespace = verbs.add_parser(
"stream",
parents=[common],
help="publish one session's screen on the LAN, behind a spoken phrase",
description=(
"A live view of one session, in a browser, at a URL whose path is "
"four words and a five-character tail. Off by default and per "
"session: a session does not stream because it exists, it streams "
"because it was switched on.\n\n"
"What is published is the session's own container output, never "
"the main one — that output carries every other session, and "
"putting it behind one session's phrase is the mistake this "
"refuses to make (exit 10 with no container).\n\n"
"The transport is MJPEG over HTTP: a browser <img> is the whole "
"client. Capture runs only while somebody is connected."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
streams = namespace.add_subparsers(dest="stream_verb", metavar="VERB")
namespace.set_defaults(
func=_cmd_stream_list, hhstream_session_handler=_cmd_stream_list, json=False
)
def add_stream_verb(name: str, handler, **kwargs: Any):
sub = streams.add_parser(name, parents=[common], **kwargs)
sub.set_defaults(func=handler, hhstream_session_handler=handler)
sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout")
return sub
enable = add_stream_verb(
"enable",
_cmd_stream_enable,
help="switch a session's stream on and print its URL",
description=(
"Mint a phrase, open a capture, and print the URL on stdout — so "
"$(hhstream session stream enable ID) is the URL and nothing "
"else. The phrase is kept in the session's record, so it survives "
"a broker restart and a re-enable: somebody you read it out to "
"keeps the URL you gave them.\n\n"
"Re-enabling an enabled session prints the same URL. A --phrase "
"that differs from the stored one is exit 8 rather than a silent "
"rotation, because rotating under a caller holding the old URL is "
"the one outcome neither answer can be mistaken for. 'disable' "
"then 'enable' rotates it."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
enable.add_argument("id", help="session id")
enable.add_argument(
"--phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one. Held to exactly the "
"generated shape (four words of 3+ letters, then a five-character "
"tail): it is a password, and a looser check would accept 'a-b-c'.",
)
enable.add_argument(
"--fps",
type=int,
metavar="N",
help="frames per second (default: the broker's; the daemon caps it)",
)
disable = add_stream_verb(
"disable",
_cmd_stream_disable,
help="switch a session's stream off and forget its phrase",
description=(
"Close the capture, drop the route, and clear the record. The "
"phrase is gone: a later 'enable' mints a new one, which is how a "
"phrase is rotated.\n\n"
"Disabling a stream the daemon has already forgotten is not an "
"error — that is the ordinary case after the daemon restarts, and "
"the record has to be cleared either way. 'detached' says which "
"happened."
),
)
disable.add_argument("id", help="session id")
add_stream_verb(
"list",
_cmd_stream_list,
help="every session with a stream (does NOT count as activity)",
description=(
"Every session a stream was enabled on, with its output, rate and "
"connected viewer count. The phrase is shown only under --json: "
"this listing is the kind of thing that ends up in a terminal "
"somebody is sharing, and the phrase is the credential.\n\n"
"'available' is whether the stream daemon could be asked at all, "
"so 'no streams' is distinguishable from 'no daemon' without "
"parsing an error."
),
)
status = add_stream_verb(
"status",
_cmd_stream_status,
help="one session's stream (does NOT count as activity)",
)
status.add_argument("id", nargs="?", help="session id; omit for all of them")
def _button_help() -> str:
return f"one of: {', '.join(BUTTONS)} (default: left)"
@@ -749,6 +906,9 @@ def _cmd_start(args: argparse.Namespace) -> int:
home=args.home,
ephemeral_home=args.ephemeral_home or None,
request_id=args.request_id,
stream=args.stream or None,
stream_phrase=args.stream_phrase,
stream_fps=args.stream_fps,
)
if not reply.get("ok"):
# A failed start may still have created a session (it exited at once, or
@@ -778,6 +938,27 @@ def _cmd_start(args: argparse.Namespace) -> int:
"(the only mark of activity; list/status/logs/gc do not count)",
file=sys.stderr,
)
if args.stream:
stream = session.get("stream") or {}
error = session.get("stream_error")
if stream.get("url"):
# stdout, beside the id: the URL is the other thing a caller asked
# for, and `$(... --stream)` giving the id and the URL on two lines
# is more useful than making them run a second verb for it.
print(stream["url"])
print(
f"watching it counts as activity; stop it with: hhstream "
f"session stream disable {session_id}",
file=sys.stderr,
)
else:
# The session started. Saying so loudly, because the exit code is
# 0 and a caller who asked for a stream must not read that as one.
print(
f"WARNING: the session is running but its stream was not "
f"enabled: {error or 'the broker reported no stream'}",
file=sys.stderr,
)
return int(ExitCode.OK)
@@ -1312,6 +1493,77 @@ def _cmd_keyboard_hold(args: argparse.Namespace) -> int:
return _finish_gesture(args, reply, render, args.id)
# --------------------------------------------------------------------------
# the live stream
# --------------------------------------------------------------------------
@_guard
def _cmd_stream_enable(args: argparse.Namespace) -> int:
reply = _request(
args, "stream.enable", id=args.id, phrase=args.phrase, fps=args.fps
)
if not reply.get("ok"):
return _finish(args, reply, lambda r: "")
if args.json:
fmt.dump_json(reply)
return int(ExitCode.OK)
stream = reply.get("stream") or {}
# stdout is the URL and nothing else, the same shape `start` and `pointer
# acquire` already have: one token a caller passes on, detail on stderr.
print(stream.get("url") or "")
print(
f"{reply.get('id')}: streaming output {stream.get('output')} "
f"at {stream.get('fps')} fps",
file=sys.stderr,
)
print(
"the phrase in that URL is its only protection, and watching it counts "
"as activity; stop it with: hhstream session stream disable "
f"{reply.get('id')}",
file=sys.stderr,
)
if not stream.get("attached"):
# `enable` cannot normally get here -- it had to attach to succeed --
# but a reply without it means the daemon answered and then went away,
# and a printed URL that serves nothing is worse than a warning.
print(
"WARNING: the broker recorded this stream but the daemon did not "
"confirm it is attached; the URL may not answer",
file=sys.stderr,
)
return int(ExitCode.OK)
@_guard
def _cmd_stream_disable(args: argparse.Namespace) -> int:
reply = _request(args, "stream.disable", id=args.id)
def render(r: dict[str, Any]) -> str:
detached = r.get("detached")
return (
f"{r.get('id')}: stream disabled and its phrase forgotten"
+ ("" if detached else "; the daemon had already dropped it")
)
return _finish(args, reply, render)
@_guard
def _cmd_stream_list(args: argparse.Namespace) -> int:
reply = _request(args, "stream.list")
return _finish(args, reply, fmt.render_streams)
@_guard
def _cmd_stream_status(args: argparse.Namespace) -> int:
session_id = getattr(args, "id", None)
reply = _request(args, "stream.status", id=session_id)
if session_id is None:
return _finish(args, reply, fmt.render_streams)
return _finish(args, reply, fmt.render_stream)
# --------------------------------------------------------------------------
# standalone use
# --------------------------------------------------------------------------
+81
View File
@@ -120,6 +120,87 @@ def render_list(
)
def render_streams(reply: dict[str, Any]) -> str:
"""``session stream list``: what is published, and who is watching.
**The phrase is not in this table**, and that is the whole shape of it. A
listing is the kind of thing that ends up in a shared terminal, a paste or
a screenshot, and the phrase is the stream's only credential — so what is
shown is enough to recognise and manage a stream (the session, the output,
the rate, the viewers) and not enough to watch one. ``--json`` carries the
phrase and the URL, because a caller that asked for the object asked for
the credential too.
``available`` is printed even when there are streams: "two records and no
daemon" is a different situation from "two records and two captures", and
the difference is invisible from the rows alone.
"""
rows = []
for row in reply.get("streams") or []:
rows.append(
[
_cell(row.get("id")),
_cell(row.get("app")),
_cell(row.get("output")),
_cell(row.get("fps")),
"yes" if row.get("attached") else "NO",
_cell(row.get("viewers")),
]
)
lines = [
render_table(rows, ["ID", "APP", "OUTPUT", "FPS", "LIVE", "VIEWERS"])
if rows
else "no session has a stream enabled"
]
available = reply.get("available")
lines.append(
"daemon: "
+ (
"answering"
if available
else "NOT REACHABLE — the records below are what was asked for, "
"not what is running"
)
)
if rows:
lines.append(
"the URL (with its phrase) is in --json, or in `stream status <id>`"
)
return "\n".join(lines)
def render_stream(reply: dict[str, Any]) -> str:
"""``session stream status ID``: one session's stream, URL included.
The URL *is* here, unlike in the listing: this was asked about one session
by name, which is what somebody about to watch it does, and making them
reach for ``--json`` to get the thing the verb is for would be a worse
trade than the one the listing makes.
"""
stream = reply.get("stream")
if not stream:
return f"{_cell(reply.get('id'))}: no stream enabled"
lines = [
f"{_cell(reply.get('id'))}: output {_cell(stream.get('output'))} "
f"at {_cell(stream.get('fps'))} fps",
]
if stream.get("attached"):
lines.append(f" url {_cell(stream.get('url'))}")
lines.append(f" viewers {_cell(stream.get('viewers'))}")
else:
# No URL, deliberately: the record's phrase is still there, but a URL
# that no longer serves anything is worse than none. See
# `SessionManager._stream_public`.
lines.append(
" url — (the daemon is not publishing this; the phrase is "
"kept, so re-enabling restores the same URL)"
)
lines.append(f" enabled {_cell(stream.get('enabled_at'))}")
return "\n".join(lines)
def render_containers(reply: dict[str, Any]) -> str:
"""``session container`` with no id: every container, and every orphan.
+301
View File
@@ -0,0 +1,301 @@
"""The broker's end of the stream daemon's socket (CONTRACT-sessions.md §3.5).
`hhstream-live` is a third executor beside the pointer driver, and this module
is the client that talks to it. The split is the driver's, for the driver's
reasons: ``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.
**The broker holds the decision; the daemon holds the capture.** Which session
streams, and under which phrase, is the broker's — it is in the session record
and it survives a restart. The port, the bind address, the capture command and
the URL prefix are the daemon's, from its own unit's argv. So nothing here
passes a port and nothing here builds a URL: :attr:`Attachment.url` comes back
from the daemon, because a URL assembled from a port the broker was told about
once is a URL that lies the first time an operator moves the listener.
**The phrase is never logged.** It is the stream's only credential, in
cleartext in a URL on whatever the bind allows. Every log line here names the
output and the session; `_safe` is what keeps a phrase out of the ones that
would otherwise carry it.
Transport, lifetime and failure semantics are :mod:`hhstreamd.driver`'s, down to
the held connection and the EOF check before each write. One difference in
what a failure *means*: a dropped `release_all` leaves a key down in the
compositor, which is why the driver never retries; a dropped `attach` leaves
nothing behind but an unattached phrase, so `attach` is **idempotent on the
daemon's side** and re-sending it is safe. That is the daemon's guarantee, not
this module's, and it is what makes re-enabling after a restart cheap.
"""
from __future__ import annotations
import dataclasses
import json
import logging
import select
import socket
import threading
from pathlib import Path
from typing import Any
log = logging.getLogger("hhstreamd.live")
#: The daemon answers from memory for every op here -- it does not capture a
#: frame to answer `attach`, and `viewers` is a counter read. This only bounds
#: a daemon that has stopped answering at all.
DEFAULT_TIMEOUT_S = 2.0
#: Matches the daemon's own ceiling.
MAX_LINE_BYTES = 1 << 20
class LiveUnavailable(Exception):
"""The daemon could not be reached, or did not answer intelligibly.
Distinct from :class:`LiveRejected`: this one means nothing is known about
whether the stream is attached, so the caller reports a *degraded* stream
rather than an absent one. The session is unaffected either way -- a
stream that cannot be reached is a stream, not a dead application -- which
is why the manager maps this to exit 10 and never to a session failure.
"""
class LiveRejected(Exception):
"""The daemon refused. ``kind`` decides the exit code, as the driver's does."""
def __init__(self, message: str, *, kind: str | None = None) -> None:
super().__init__(message)
self.kind = kind
@dataclasses.dataclass(frozen=True)
class Attachment:
"""One stream, as the daemon reports it."""
phrase: str
output: str
fps: int
session: str | None
#: The daemon's own prefix, e.g. ``http://127.0.0.1:9988/<phrase>/``.
url: str
viewers: int
@classmethod
def parse(cls, data: Any) -> "Attachment":
if not isinstance(data, dict):
raise ValueError(f"stream is not an object: {type(data).__name__}")
try:
return cls(
phrase=str(data["phrase"]),
output=str(data["output"]),
fps=int(data["fps"]),
session=None if data.get("session") is None else str(data["session"]),
url=str(data.get("url") or ""),
viewers=int(data.get("viewers") or 0),
)
except (KeyError, TypeError, ValueError) as exc:
raise ValueError(f"malformed stream in the daemon's reply: {exc}") from exc
def _safe(phrase: str) -> str:
"""A phrase, for a log line. The shape, never the words.
``amber-otter-lantern-harbor-7k2qp`` becomes ``<phrase:5 tokens>``. A log
is read by whoever can read logs, and this one is a password.
"""
return f"<phrase:{len(phrase.split('-'))} tokens>"
class LiveStreams:
"""A client for one stream daemon's socket. Thread-safe; one op at a time."""
def __init__(self, socket_path: Path | str, *, timeout_s: float = DEFAULT_TIMEOUT_S) -> None:
self.socket_path = Path(socket_path)
self.timeout_s = float(timeout_s)
self._lock = threading.Lock()
self._sock: socket.socket | None = None
self._stream = None
# -- the ops ----------------------------------------------------------
def attach(
self,
*,
phrase: str,
output: str,
fps: int | None = None,
session: str | None = None,
label: str = "",
) -> Attachment:
"""Publish ``output`` under ``phrase``. Idempotent on the phrase.
The daemon returns the existing stream if the same phrase is already
aimed at the same output, rather than starting a second capture: a
re-enable after a broker restart must not double the ``grim`` rate on
one output. The same phrase aimed somewhere else is a rejection.
``fps`` is **omitted** when nobody asked for one, and that is the point:
the default rate 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 make the operator's ``sessions.stream.fps`` a setting that changed
nothing -- which is exactly the failure the keyboard layout's
``--xkb-layout`` comment in this tree is about.
"""
request: dict[str, Any] = {
"op": "attach",
"phrase": phrase,
"output": output,
"session": session,
"label": label,
}
if fps is not None:
request["fps"] = int(fps)
reply = self.request(request)
attachment = Attachment.parse(reply.get("stream"))
log.info(
"attached %s to output %s at %s fps (%s)",
session or "a standalone stream",
output,
attachment.fps,
_safe(phrase),
)
return attachment
def detach(self, phrase: str) -> bool:
"""Stop publishing ``phrase``. ``False`` if it was not attached.
Not an error: ``disable`` on a session whose daemon restarted since
``enable`` is the ordinary case, and the caller's job is to clear the
record either way.
"""
reply = self.request({"op": "detach", "phrase": phrase})
return bool(reply.get("detached"))
def list(self) -> list[Attachment]:
"""Every stream the daemon is publishing, in its own order."""
reply = self.request({"op": "list"})
streams = reply.get("streams")
if not isinstance(streams, list):
raise LiveUnavailable(
f"stream daemon {self.socket_path}: `list` returned "
f"{type(streams).__name__}, not a list"
)
try:
return [Attachment.parse(entry) for entry in streams]
except ValueError as exc:
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
def viewers(self) -> dict[str, int]:
"""Phrase to connected viewers, for the activity sweep (§4).
A reading, and nothing more: what it means for the idle clock is the
manager's, and this module deliberately has no opinion about it.
"""
reply = self.request({"op": "viewers"})
counts = reply.get("viewers")
if not isinstance(counts, dict):
raise LiveUnavailable(
f"stream daemon {self.socket_path}: `viewers` returned "
f"{type(counts).__name__}, not an object"
)
read: dict[str, int] = {}
for phrase, count in counts.items():
try:
read[str(phrase)] = int(count)
except (TypeError, ValueError) as exc:
raise LiveUnavailable(
f"stream daemon {self.socket_path}: viewer count for "
f"{_safe(str(phrase))} is not a number: {exc}"
) from exc
return read
# -- transport --------------------------------------------------------
def request(self, message: dict[str, Any]) -> dict[str, Any]:
"""One request, one reply. Raises rather than returning a guess."""
with self._lock:
try:
return self._exchange(message)
except (OSError, ValueError) as exc:
# The connection is now of unknown state -- a half-written
# request, a partial reply -- so it is dropped rather than
# reused for the next op.
self._disconnect()
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
def close(self) -> None:
with self._lock:
self._disconnect()
def _exchange(self, message: dict[str, Any]) -> dict[str, Any]:
stream = self._connect()
line = json.dumps(message, separators=(",", ":")).encode("utf-8") + b"\n"
stream.write(line)
stream.flush()
reply_line = stream.readline(MAX_LINE_BYTES + 1)
if not reply_line:
raise OSError("the daemon closed the connection without answering")
if len(reply_line) > MAX_LINE_BYTES:
raise ValueError("reply exceeds the frame limit")
reply = json.loads(reply_line)
if not isinstance(reply, dict):
raise ValueError(f"reply is not an object: {type(reply).__name__}")
if not reply.get("ok"):
kind = reply.get("kind")
raise LiveRejected(
str(reply.get("error") or "the stream daemon refused the request"),
kind=kind if isinstance(kind, str) else None,
)
return reply
def _connect(self):
if self._stream is not None and not self._stale():
return self._stream
self._disconnect()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
try:
sock.settimeout(self.timeout_s)
sock.connect(str(self.socket_path))
except OSError:
sock.close()
raise
self._sock = sock
self._stream = sock.makefile("rwb")
log.debug("connected to the stream daemon at %s", self.socket_path)
return self._stream
def _stale(self) -> bool:
"""True if the held connection has died since the last op.
The daemon never speaks unsolicited, so a readable socket can only be
at EOF. One non-blocking ``select``, and it is what makes reconnecting
safe: a request is written only to a connection that was alive when it
was written.
"""
sock = self._sock
if sock is None:
return True
try:
readable, _, _ = select.select([sock], [], [], 0)
except (OSError, ValueError):
return True
return bool(readable)
def _disconnect(self) -> None:
stream, self._stream = self._stream, None
sock, self._sock = self._sock, None
for closeable in (stream, sock):
if closeable is None:
continue
try:
closeable.close()
except OSError:
pass
+468 -4
View File
@@ -57,6 +57,7 @@ from .container_host import (
ContainerHost,
)
from .driver import DriverRejected, DriverUnavailable, PointerDriver
from .live import Attachment, LiveRejected, LiveStreams, LiveUnavailable
from .ipc import CompositorUnavailable
from .launcher import Launcher
from .pointer import Bookmark, LeaseBusy, LeaseInvalid, PointerLease
@@ -70,6 +71,7 @@ from .registry import (
State,
container_record,
pointer_record,
stream_record,
)
from .textio import tail_lines
@@ -110,6 +112,16 @@ READBACK_INTERVAL_S = 0.05
#: as long as nobody asks.
POINTER_SWEEP_S = 1.0
#: How often the broker asks the stream daemon for viewer counts, and stamps
#: `touch` on every session that has one (CONTRACT-sessions.md §4).
#:
#: A minute, not a second: this is the one exception to "`touch` is the only
#: mark of activity", and the thing it exists to prevent is a three-hour idle
#: timeout firing under somebody's eyes. Against three hours a minute of
#: granularity is free, and a tighter sweep would be one `grim`-adjacent round
#: trip per second for a fact that changes when a browser tab opens.
STREAM_SWEEP_S = 60.0
#: The workspace band (CONTRACT-sessions.md §5) and how many slots of it this
#: broker will hand out. The real ceiling is a CPU question the plan defers to
#: a measurement (PLAN §5.5); the band is the part that can be enforced here,
@@ -199,8 +211,17 @@ class ManagerConfig:
pointer_ttl_s: float = 30.0
pointer_max_s: float = 300.0
pointer_sweep_s: float = POINTER_SWEEP_S
#: The broker↔stream socket (CONTRACT-sessions.md §3.5). Derived from the
#: runtime dir for the reason `pointer_socket` is: the path is frozen, so a
#: flag for it would be a flag for a value that may not vary.
live_socket: Path | None = None
#: How often the viewer sweep runs. The one thing that moves an idle clock
#: without a caller asking (CONTRACT-sessions.md §4).
stream_sweep_s: float = STREAM_SWEEP_S
def __post_init__(self) -> None:
if self.live_socket is None:
self.live_socket = Path(self.runtime_dir) / "live.sock"
if self.pointer_socket is None:
# `<runtime dir>/pointer.sock` is the frozen path
# (CONTRACT-sessions.md §5: /run/hhstream/pointer.sock), and
@@ -221,6 +242,7 @@ class SessionManager:
audit: AuditLog | None = None,
host: ContainerHost | None = None,
driver: PointerDriver | None = None,
live: LiveStreams | None = None,
) -> None:
self.config = config
self.clock = clock or Clock()
@@ -251,6 +273,10 @@ class SessionManager:
ttl_s=config.pointer_ttl_s, max_s=config.pointer_max_s, clock=self.clock.boottime
)
self.driver = driver
#: The stream daemon's client, or ``None`` with no socket configured --
#: in which case every `stream.*` verb answers `stream_unavailable`
#: (exit 10) rather than pretending there is a stream.
self.live = live
# Per-session asyncio plumbing, never persisted.
self._exited: dict[str, asyncio.Event] = {}
self._watchers: dict[str, asyncio.Task] = {}
@@ -259,6 +285,7 @@ class SessionManager:
#: Held so the loop does not collect a task mid-flight.
self._background: set[asyncio.Task] = set()
self._pointer_sweeper: asyncio.Task | None = None
self._stream_sweeper: asyncio.Task | None = None
#: Set while a lease is held with a caller-supplied TTL, so the default
#: comes back when the lease ends (the frozen ``acquire`` takes no TTL).
self._pointer_ttl_override = False
@@ -339,6 +366,13 @@ class SessionManager:
self._pointer_sweeper = asyncio.create_task(
self._sweep_pointer(), name="hhstreamd.pointer-sweep"
)
# Unconditional, even with no stream enabled anywhere: the sweep's own
# first act is to ask the daemon, and a broker that only started it on
# the first `enable` would be a broker whose adopted records were not
# being watched after a restart.
self._stream_sweeper = asyncio.create_task(
self._sweep_streams(), name="hhstreamd.stream-sweep"
)
return summary
# ------------------------------------------------------------------
@@ -632,11 +666,14 @@ class SessionManager:
"""
await self.reaper.stop()
if self._pointer_sweeper is not None:
self._pointer_sweeper.cancel()
for name in ("_pointer_sweeper", "_stream_sweeper"):
sweeper = getattr(self, name)
if sweeper is None:
continue
sweeper.cancel()
with contextlib.suppress(asyncio.CancelledError, Exception):
await self._pointer_sweeper
self._pointer_sweeper = None
await sweeper
setattr(self, name, None)
for task in list(self._background):
task.cancel()
for task in list(self._background):
@@ -650,6 +687,12 @@ class SessionManager:
with contextlib.suppress(Exception):
await self._release_all_buttons()
self.driver.close()
if self.live is not None:
# Nothing to lift on this one: a stream left attached across a
# broker restart is re-attached by `enable`, and the daemon keeps
# publishing meanwhile -- which is the behaviour an operator
# watching a long job wants.
self.live.close()
for task in list(self._watchers.values()):
task.cancel()
for task in list(self._watchers.values()):
@@ -878,6 +921,9 @@ class SessionManager:
wait_ready_s: float | None = None,
home: str | None = None,
ephemeral_home: bool = False,
stream: bool = False,
stream_phrase: str | None = None,
stream_fps: int | None = None,
) -> dict[str, Any]:
policy = self.config.policy
policy.check_capacity(len(self.registry.live()))
@@ -971,8 +1017,38 @@ class SessionManager:
ready = await self._settle(session, wait_ready)
if session.live:
await self._read_back(session, app_id)
stream_error: str | None = None
if stream and session.live:
# After the read-back, because that is what settles the container's
# output, and a stream has to have one to publish
# (`_stream_output`). Before the record below, so the phrase comes
# back with the session the caller asked for -- which is the whole
# reason `start` takes these arguments instead of making every
# caller sequence "start, then enable" and handle the half-done
# case in between.
#
# A stream that cannot be opened does NOT fail the start. The
# application is on the screen and killing it over a web page would
# be the wrong trade; the refusal is reported on the session's
# `stream_error` and the caller can retry `stream.enable`.
try:
await self.stream_enable(
session.id, phrase=stream_phrase, fps=stream_fps
)
except ManagerError as exc:
log.warning("could not enable %s's stream: %s", session.id, exc.reason)
session.last_error = session.last_error or exc.reason
# A local, not an attribute: two starts can be in flight at
# once and an attribute would hand one of them the other's
# failure.
stream_error = exc.reason
self.reaper.wake()
record = session.public(self.now())
if stream:
# Present whenever a stream was asked for, `None` when it worked:
# a key that appears only on failure is a key every caller has to
# remember to look for.
record["stream_error"] = stream_error
if session.state == State.EXITED:
# The app exited during the settle: surface it rather than handing
# back a healthy-looking id (DESIGN.md §7 #3).
@@ -1235,7 +1311,17 @@ class SessionManager:
# has four values (lease|timeout|crash|kill), and a reap is the
# broker killing the session.
await self._drop_lease_for(session, reason="kill")
# The stream goes BEFORE the output does, and the order is
# load-bearing (CONTRACT-sessions.md §4): a capture aimed at a
# removed output fails every time, so the daemon's own failure
# budget would close the viewers with "unknown output" instead of
# the session simply ending. Never raises -- a daemon that cannot
# be reached must not stop a session being killed.
stream_detached = await self._detach_stream(session)
if (session.stream or {}).get("phrase"):
session.stream = None
container_result = self._destroy_container(session)
container_result["stream_detached"] = stream_detached
if refused is None:
state_now = state
@@ -1929,6 +2015,368 @@ class SessionManager:
# -- lease internals --------------------------------------------------
# ------------------------------------------------------------------
# the live stream (CONTRACT-sessions.md §4, v4)
# ------------------------------------------------------------------
async def stream_enable(
self, session_id: str, *, phrase: str | None = None, fps: int | None = None
) -> dict[str, Any]:
"""Publish this session's container output under a spoken phrase.
**Does not** count as activity, like every `pointer.*` verb: switching
a stream on is not saying the session is wanted. What *is* activity is
somebody watching it, and that is :meth:`_sweep_streams`.
The phrase is minted here and stored in the record, so it survives a
broker restart and a re-enable: an operator who read four words out to
somebody must not have them change because the daemon bounced. A
caller's own `phrase` is held to the generated shape -- it is this
stream's only credential, so anything a caller may set is a password,
and a looser check would accept `a-b-c`.
Re-enabling an enabled session returns the same phrase. A different
`phrase` is `stream_busy` (exit 8) rather than a silent rotation,
because rotating under a caller who is holding the old URL is the one
outcome neither answer can be mistaken for.
"""
session = self._require_live(session_id)
output = self._stream_output(session)
rate = self._checked_fps(fps)
stored = session.stream or {}
wanted = self._checked_phrase(phrase)
if stored.get("phrase") and wanted and wanted != stored["phrase"]:
raise ManagerError(
"stream_busy",
f"session {session.id} already has a stream under a different phrase",
hint="`stream disable` then `stream enable` rotates it; a stream "
"cannot have two phrases, because the old one is a URL somebody "
"may be holding",
id=session.id,
)
settled = stored.get("phrase") or wanted or self._mint_phrase()
# The stored rate wins on a re-enable with no `fps`: a re-attach after a
# restart must not quietly re-rate a stream somebody is watching. With
# neither, the rate is left UNSET and the daemon applies its own
# configured default -- the broker does not have one, on purpose.
rate = rate or stored.get("fps")
attachment = await self._attach_stream(
session, phrase=settled, output=output, fps=None if rate is None else int(rate)
)
record = stream_record(
phrase=settled,
output=output,
fps=attachment.fps,
enabled_at=stored.get("enabled_at") or iso(self.clock.wall()),
)
session.stream = record
# `force=True`: the phrase is the one field here that cannot be
# re-derived, so it is on disk before the caller is told what it is.
self.registry.persist(session, force=True)
# The phrase is NOT in the audit entry (CONTRACT-sessions.md §3.5): the
# log is read by whoever can read logs, and this one is a password.
self.audit.emit(
"stream_enable", id=session.id, output=output, fps=attachment.fps
)
return {"id": session.id, "stream": self._stream_public(record, attachment)}
async def stream_disable(self, session_id: str) -> dict[str, Any]:
"""Stop publishing, and clear the record.
Detaching a stream the daemon has already forgotten is **not** an
error: `disable` after a daemon restart is the ordinary case, and the
record has to be cleared either way. `detached` says which happened.
"""
session = self._require_live(session_id)
stored = session.stream or {}
if not stored.get("phrase"):
raise ManagerError(
"stream_unavailable",
f"session {session.id} has no stream to disable",
hint="`stream enable` first",
id=session.id,
)
detached = await self._detach_stream(session)
session.stream = None
self.registry.persist(session, force=True)
self.audit.emit(
"stream_disable", id=session.id, output=stored.get("output"), detached=detached
)
return {"id": session.id, "stream": None, "detached": detached}
def stream_list(self) -> dict[str, Any]:
"""Every session with a stream, with the daemon's view merged in.
Does not count as activity. ``available`` is whether the daemon could
be asked at all, so a caller can tell "no streams" from "no daemon"
without parsing an error.
"""
attachments, available = self._attachments()
streams = []
for session in self.registry.live():
stored = session.stream or {}
if not stored.get("phrase"):
continue
streams.append(
{
"id": session.id,
"app": session.app,
**self._stream_public(stored, attachments.get(stored["phrase"])),
}
)
return {"streams": streams, "available": available}
def stream_status(self, session_id: str | None = None) -> dict[str, Any]:
"""One session's stream, or every one of them. Not activity."""
if session_id is None:
return self.stream_list()
session = self._require(session_id)
stored = session.stream or {}
if not stored.get("phrase"):
return {"id": session.id, "stream": None}
attachments, _ = self._attachments()
return {
"id": session.id,
"stream": self._stream_public(stored, attachments.get(stored["phrase"])),
}
# -- the pieces the four verbs share ---------------------------------
def _stream_output(self, session: Session) -> str:
"""The output a stream publishes: the session's own container.
Refused rather than defaulted, and the reason is stronger than the
pointer's: the main output carries *every other session*, so falling
back to it would put somebody else's desktop on a phone behind a phrase
that was issued for this one.
"""
output = (session.container or {}).get("output")
if output:
return str(output)
raise ManagerError(
"stream_unavailable",
f"session {session.id} has no container output to publish",
hint="a stream never falls back to the main output -- that one "
"carries every other session. `container.reconcile` once the "
"compositor is reachable, or start the session with containers on",
id=session.id,
container=session.container,
)
def _mint_phrase(self) -> str:
"""A fresh phrase.
From `hhstream_live.phrase`, which owns the wordlist, the shape and the
validator -- one definition, so a phrase the broker mints is one the
daemon will accept and a `--phrase` an operator types is held to the
same bar. Imported here rather than at module scope because this is the
only path that needs it and `hhstreamd` must stay importable without
the web app's wordlist being readable.
"""
from hhstream_live import phrase as phrase_mod
return phrase_mod.generate()
def _checked_phrase(self, phrase: Any) -> str | None:
if phrase is None:
return None
from hhstream_live import phrase as phrase_mod
if not isinstance(phrase, str):
raise ManagerError(
"invalid_argument", "phrase must be a string", id=None
)
try:
return phrase_mod.validate(phrase)
except ValueError:
# The validator's own message names the value it refused, which is
# right for an operator reading their own terminal and wrong here:
# this reason reaches the broker's log and the audit trail, and the
# value is a credential (CONTRACT-sessions.md §3.5). So the shape
# is described and the phrase is NOT interpolated -- deliberately,
# and `from None` so the chained message cannot carry it either.
raise ManagerError(
"invalid_argument",
"the phrase given is not of the expected shape",
hint="four words of at least three letters and a five-character "
"tail, e.g. amber-otter-lantern-harbor-7k2qp; omit it to have "
"one minted",
) from None
def _checked_fps(self, fps: Any) -> int | None:
if fps is None:
return None
if isinstance(fps, bool) or not isinstance(fps, int):
raise ManagerError(
"invalid_argument", f"fps must be an int, got {type(fps).__name__}"
)
if fps <= 0:
raise ManagerError("invalid_argument", f"fps must be positive, got {fps}")
# The ceiling is deliberately NOT checked here. It belongs to the
# daemon (`hhstream_live.publisher.FPS_CAP`), which is the process that
# has to keep up with it, and a second copy of the number here would be
# a second thing to raise when the box gets faster.
return fps
async def _attach_stream(
self, session: Session, *, phrase: str, output: str, fps: int | None
) -> Attachment:
live = self._live_streams()
if live is None:
raise ManagerError(
"stream_unavailable",
"no stream daemon is configured for this broker",
hint="the `hhstream-live` unit is what captures a stream; "
"`sessions.stream` in the module turns it on",
id=session.id,
)
try:
return await asyncio.to_thread(
live.attach,
phrase=phrase,
output=output,
fps=fps,
session=session.id,
label=session.app,
)
except LiveRejected as exc:
# The daemon's own vocabulary, mapped once: its `invalid_argument`
# is the caller's mistake (exit 2) and anything else is a stream
# that could not be opened (exit 10). The same split the driver's
# `kind` already gets.
error = "invalid_argument" if exc.kind == "invalid_argument" else "stream_unavailable"
raise ManagerError(error, str(exc), id=session.id) from exc
except LiveUnavailable as exc:
raise ManagerError(
"stream_unavailable",
f"the stream daemon could not be reached: {exc}",
hint="is hhstream-live running? the session itself is unaffected",
id=session.id,
) from exc
async def _detach_stream(self, session: Session) -> bool:
"""Stop the capture for this session, if there is one.
Never raises. Called from `disable`, which has a record to clear
regardless, and from teardown, where a daemon that cannot be reached
must not stop a session from being killed.
"""
phrase = (session.stream or {}).get("phrase")
live = self._live_streams()
if not phrase or live is None:
return False
try:
return await asyncio.to_thread(live.detach, str(phrase))
except (LiveRejected, LiveUnavailable) as exc:
log.warning(
"could not detach %s's stream on output %s: %s",
session.id,
(session.stream or {}).get("output"),
exc,
)
return False
def _attachments(self) -> tuple[dict[str, Attachment], bool]:
"""The daemon's streams by phrase, and whether it answered.
Synchronous and tolerant: the read verbs report what they can, and a
down daemon turns `attached` false rather than failing a `list` that
has records to show.
"""
live = self._live_streams()
if live is None:
return {}, False
try:
return {a.phrase: a for a in live.list()}, True
except (LiveRejected, LiveUnavailable) as exc:
log.debug("the stream daemon did not answer `list`: %s", exc)
return {}, False
@staticmethod
def _stream_public(
stored: dict[str, Any], attachment: Attachment | None
) -> dict[str, Any]:
"""The record, with the daemon's live view merged in.
``attached`` is its own field and is **not** folded into ``enabled``: a
record may say a session is enabled while the daemon is down, and "the
operator asked for this" and "a capture is running right now" are two
different facts. ``url`` and ``viewers`` are *absent* when it is false,
rather than stale -- a URL that no longer serves anything is worse than
no URL.
"""
public = dict(stored)
public["attached"] = attachment is not None
if attachment is not None:
public["url"] = attachment.url
public["viewers"] = attachment.viewers
public["fps"] = attachment.fps
return public
async def _sweep_streams(self) -> None:
"""Stamp `touch` on every session somebody is watching.
The one exception to "`touch` is the only mark of activity"
(CONTRACT-sessions.md §4), and the only thing in this daemon that
treats an observation as an intention. It exists 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, so a forgotten `enable` is
not a leak -- which is why this is safe to run unconditionally.
"""
while True:
await asyncio.sleep(self.config.stream_sweep_s)
try:
await self._touch_watched()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001 -- a sweep must outlive one failure
log.exception("the stream viewer sweep failed; continuing")
async def _touch_watched(self) -> list[str]:
"""One pass of the sweep. Returns the ids it touched."""
live = self._live_streams()
if live is None:
return []
try:
counts = await asyncio.to_thread(live.viewers)
except (LiveRejected, LiveUnavailable) as exc:
log.debug("the stream daemon did not answer `viewers`: %s", exc)
return []
touched: list[str] = []
for session in self.registry.live():
phrase = (session.stream or {}).get("phrase")
if not phrase:
continue
viewers = counts.get(str(phrase), 0)
if viewers <= 0:
continue
self.registry.touch(session, force_flush=True)
touched.append(session.id)
self.audit.emit(
"stream_viewer_activity",
id=session.id,
output=(session.stream or {}).get("output"),
viewers=viewers,
)
return touched
async def _sweep_pointer(self) -> None:
"""Expire a stale lease even when nobody asks.
@@ -2152,6 +2600,22 @@ class SessionManager:
self.driver = PointerDriver(self.config.pointer_socket)
return self.driver
# -- the stream daemon ------------------------------------------------
def _live_streams(self) -> LiveStreams | None:
"""The stream daemon's client, built on first use.
``None`` rather than raising, unlike :meth:`_pointer_driver`, and the
asymmetry is the point: a pointer verb with no driver is a verb that
cannot do its job, while a *read* of stream state with no daemon has a
true answer -- the records, with ``attached: false``. The write paths
(`_attach_stream`) raise `stream_unavailable` for themselves.
"""
if self.live is None and self.config.live_socket is not None:
self.live = LiveStreams(self.config.live_socket)
return self.live
async def _drive(self, verb: str, *args: Any) -> Any:
"""One driver call, off the event loop.
+21
View File
@@ -102,8 +102,17 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = {
"pointer_busy": ExitCode.BUSY,
# 9 — the lease is required and not held
"no_lease": ExitCode.NO_LEASE,
# 8 — a phrase that is not this session's (v4)
"stream_busy": ExitCode.BUSY,
# 6 — the stream daemon's own cap (v4)
"stream_budget": ExitCode.POLICY,
# 10 — the compositor side failed; the session itself is fine
"compositor": ExitCode.COMPOSITOR,
# The stream could not be reached or has no output to aim at (v4). Exit 10
# for the reason `driver_refused` is: the *session* keeps running, and a
# caller that treated an unreachable stream as a dead session would kill an
# application over a web page.
"stream_unavailable": ExitCode.COMPOSITOR,
"compositor_unavailable": ExitCode.COMPOSITOR,
"no_container": ExitCode.COMPOSITOR,
"driver_unavailable": ExitCode.COMPOSITOR,
@@ -156,6 +165,12 @@ VERBS = (
# warp retargets the keys. So there is no `keyboard.acquire`.
"keyboard.key",
"keyboard.type",
# v4: the per-session live stream. `list` and `status` read; `enable` and
# `disable` are in the mutation set below.
"stream.enable",
"stream.disable",
"stream.list",
"stream.status",
)
#: Verbs whose reply is remembered by ``request_id``, so a caller that died
@@ -185,6 +200,12 @@ MUTATING_VERBS = frozenset(
# nothing, and a cached one would be a stale one.
"keyboard.key",
"keyboard.type",
# v4. `enable` mints or rotates a phrase: a retry that minted a second
# one would invalidate the URL somebody is already holding, and
# `disable` is here for symmetry -- a retried disable after a daemon
# restart must report what the first one did.
"stream.enable",
"stream.disable",
}
)
+57 -6
View File
@@ -23,11 +23,12 @@ from .clock import Clock, iso
log = logging.getLogger("hhstreamd.registry")
#: 3 adds the container, the pointer bookmark and the compositor signature
#: (PLAN §7). The number is read, never written by anyone but this module: a
#: record carrying an older one is **migrated on load** (:func:`migrate`), not
#: refused, because the processes it describes are still running and refusing
#: the record would strand them.
SCHEMA = 3
#: (PLAN §7); 4 adds the live stream (CONTRACT-sessions.md §6, v4). The number
#: is read, never written by anyone but this module: a record carrying an older
#: one is **migrated on load** (:func:`migrate`), not refused, because the
#: processes it describes are still running and refusing the record would
#: strand them.
SCHEMA = 4
#: Tombstones survive this long so a ``status`` after an unexplained failure
#: still answers the question. ``gc`` prunes them.
@@ -138,6 +139,17 @@ class Session:
#: ``{bookmark, last_released_at, released_by}``. Absent (``None``) means
#: the pointer was never aimed here — not that its position is unknown.
pointer: dict[str, Any] | None = None
#: The live stream, or ``None`` for a session nobody switched one on for
#: (CONTRACT-sessions.md §4). ``{enabled, phrase, output, fps, port,
#: enabled_at}``; the daemon's ``url`` and ``viewers`` are merged in by the
#: manager when it could be asked, and are deliberately not stored -- a
#: viewer count on disk is a number that is wrong the moment it is written.
#:
#: The phrase lives here because it has to survive a broker restart and a
#: re-enable: it is the stream's only credential, and an operator who read
#: four words out to somebody must not have them change underneath him
#: because the daemon bounced.
stream: dict[str, Any] | None = None
#: ``HYPRLAND_INSTANCE_SIGNATURE`` of the compositor this session's
#: container lives in, so a restarted broker re-attaches to the same
#: instance instead of picking whichever one is there now.
@@ -234,6 +246,38 @@ def container_record(
}
def stream_record(
*,
phrase: str,
output: str,
fps: int,
enabled_at: str,
) -> dict[str, Any]:
"""One ``stream`` sub-record (CONTRACT-sessions.md §4).
Only what survives a restart. The daemon's ``url`` and ``viewers`` are
merged in by the manager when it could be asked and are deliberately absent
here: a viewer count on disk is wrong the moment it is written, and a URL
assembled from a remembered port is a URL that lies the first time the
listener moves.
``enabled`` is always ``True`` in a stored record. A session that was
never enabled has ``stream: None``, and `disable` clears the field rather
than setting ``enabled: False`` -- "nobody asked for a stream here" and
"somebody asked and then stopped" are the same state as far as anything
downstream is concerned, and two spellings for one state is how a
`if stream:` check starts being wrong.
"""
return {
"enabled": True,
"phrase": phrase,
"output": output,
"fps": fps,
"enabled_at": enabled_at,
}
def pointer_record(
*,
bookmark: dict[str, Any] | None,
@@ -284,7 +328,14 @@ def migrate(data: dict[str, Any]) -> dict[str, Any]:
upgraded = dict(data)
# Only ever *adds* keys. A v2 record that somehow carries a container must
# keep it: the field is new to the schema, not new to the session.
for key in ("container", "pointer", "signature"):
#
# `stream` (schema 4) is `None` for the same reason the others are: a
# session written by a daemon that knew nothing of streams had no stream,
# and "no stream" is a defined value rather than a guess. It must NOT be
# invented as `{"enabled": false}` either -- a record that says it was
# asked about and declined is a different claim from one that was never
# asked.
for key in ("container", "pointer", "signature", "stream"):
upgraded.setdefault(key, None)
upgraded["schema"] = SCHEMA
log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA)
+33
View File
@@ -75,6 +75,10 @@ class ControlServer:
"pointer.state": self._op_pointer_state,
"keyboard.key": self._op_keyboard_key,
"keyboard.type": self._op_keyboard_type,
"stream.enable": self._op_stream_enable,
"stream.disable": self._op_stream_disable,
"stream.list": self._op_stream_list,
"stream.status": self._op_stream_status,
}
# ------------------------------------------------------------------
@@ -264,6 +268,9 @@ class ControlServer:
wait_ready_s=request.get("wait_ready_s"),
home=request.get("home"),
ephemeral_home=bool(request.get("ephemeral_home", False)),
stream=bool(request.get("stream", False)),
stream_phrase=request.get("stream_phrase"),
stream_fps=request.get("stream_fps"),
)
return protocol.ok(id=record["id"], state=record["state"], session=record)
@@ -297,6 +304,32 @@ class ControlServer:
)
return protocol.ok(id=record["id"], state=record["state"], session=record)
async def _op_stream_enable(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.stream_enable(
request.get("id"),
phrase=request.get("phrase"),
fps=request.get("fps"),
)
)
async def _op_stream_disable(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**await self.manager.stream_disable(request.get("id")))
async def _op_stream_list(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.stream_list())
async def _op_stream_status(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.stream_status(request.get("id")))
async def _op_container_list(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
+152
View File
@@ -0,0 +1,152 @@
"""A recording stand-in for the CLI, and two image fixtures, for the MCP tests.
The MCP server calls ``hhstream.cli``'s handlers in this process, so what sits
between a tool and the broker is **the argv list** -- and that list is the only
thing this layer decides. :class:`FakeCli` is therefore an entry point that
records the argv it was given, prints whatever the test told it to, and returns
the exit code the test chose: everything the real entry point is, minus the
broker.
That is also why there is no live socket anywhere in this suite. The broker's
behaviour is `tests/sessions`' subject and the VM checks'; what is left here is
the shim. Two tests in ``test_mcp_invoke.py`` do drive the **real** entry point
against a socket path that does not exist, which is the honest way to prove the
dispatch, the capture and the exit-code mapping without standing a daemon up.
"""
from __future__ import annotations
import json
import pathlib
import struct
import sys
import zlib
from typing import Any
class FakeCli:
"""Where :func:`hhstream_mcp.invoke.dispatch` goes in a test.
Prints through ``sys.stdout``/``sys.stderr`` rather than returning text, so
the capture under test is exercised rather than bypassed.
"""
def __init__(
self,
*,
stdout: str = "",
stderr: str = "",
exit_code: int = 0,
write_png: bytes | None = None,
raises: BaseException | None = None,
) -> None:
self.stdout = stdout
self.stderr = stderr
self.exit_code = exit_code
self.write_png = write_png
self.raises = raises
#: Every argv this was called with, in order.
self.calls: list[list[str]] = []
def __call__(self, argv: list[str]) -> int:
self.calls.append(list(argv))
if self.write_png is not None:
destination = _value_of("--out", argv)
if destination:
pathlib.Path(destination).write_bytes(self.write_png)
if self.stdout:
sys.stdout.write(self.stdout)
if self.stderr:
sys.stderr.write(self.stderr)
if self.raises is not None:
raise self.raises
return self.exit_code
@property
def argv(self) -> list[str]:
"""The single call's argv. Fails loudly if there was not exactly one."""
assert len(self.calls) == 1, f"expected one CLI call, got {self.calls}"
return self.calls[0]
def _value_of(name: str, argv: list[str]) -> str | None:
prefix = f"{name}="
for argument in argv:
if argument.startswith(prefix):
return argument[len(prefix) :]
return None
def reply(**fields: Any) -> str:
"""A protocol object the way the CLI prints one: ``json.dumps(indent=2)``."""
return json.dumps(fields, indent=2, sort_keys=True) + "\n"
def png(width: int = 8, height: int = 4) -> bytes:
"""A minimal valid truecolour PNG of a known size.
Built here rather than shared with the suite's other helper because what is
under test is "the server reports the geometry the file actually has", so
the size has to be the test's to choose.
"""
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
raster = (b"\x00" + b"\x10\x20\x30" * width) * height
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+ chunk(b"IDAT", zlib.compress(raster, 9))
+ chunk(b"IEND", b"")
)
def jpeg(width: int = 6, height: int = 3) -> bytes:
"""Enough of a JPEG to carry a SOF0: magic, APP0, SOF0, EOI.
Not a decodable image, deliberately: what is under test is the header scan
that has to skip a segment it does not care about and find the one it does.
"""
app0 = (
b"\xff\xe0"
+ struct.pack(">H", 16)
+ b"JFIF\x00"
+ b"\x01\x01\x00"
+ b"\x00\x01" * 2
+ b"\x00\x00"
)
sof0 = (
b"\xff\xc0"
+ struct.pack(">H", 11)
+ b"\x08"
+ struct.pack(">HH", height, width)
+ b"\x01\x01\x11\x00"
)
return b"\xff\xd8" + app0 + sof0 + b"\xff\xd9"
def isolate(monkeypatch, tmp_path: pathlib.Path) -> None:
"""Point every path the CLI reads from the environment at ``tmp_path``.
A developer's shell has `$HHSTREAM_SOCKET` set, and the real entry point
reads it -- so without this a test could reach a live broker on the machine
it is running on. The lease directory is redirected for the same reason:
`pointer acquire` writes a cache there, and a test must not touch the one a
real session is using.
"""
monkeypatch.setenv("HHSTREAM_SOCKET", str(tmp_path / "control.sock"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "stream.sock"))
monkeypatch.setenv("HHSTREAM_LEASE_DIR", str(tmp_path / "leases"))
# `$HHSTREAM_LEASE` outranks the cache in `hhstream_session.lease.recall`,
# so an inherited one would hand a gesture a lease it never acquired.
monkeypatch.delenv("HHSTREAM_LEASE", raising=False)
+389
View File
@@ -0,0 +1,389 @@
"""The runner: how the CLI is called in process, decoded, and mapped to a code.
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
the subject is what this layer decides -- the argv list and the mapping. Three
tests drive the **real** entry point, against a control socket that does not
exist: that is the honest way to prove the dispatch, the capture and the
exit-code mapping against the CLI's actual parser without standing a daemon up.
"""
from __future__ import annotations
import contextlib
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, media
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
# ── the call ───────────────────────────────────────────────────────────────
def test_the_argv_reaches_the_entry_point_unchanged():
fake = mcp_fake.FakeCli(stdout="hello\n")
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.ok
assert outcome.stdout == "hello\n"
assert fake.argv == ["session", "list", "--json"]
assert outcome.argv == ["session", "list", "--json"]
def test_a_metacharacter_is_one_argument_and_never_a_statement():
"""There is no shell between a tool and the CLI, and no string either."""
fake = mcp_fake.FakeCli()
nasty = "; rm -rf / #"
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
"""A print on stdout here would be a parse error at the client."""
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
outcome = invoke.Runner(fake).run(["status"])
assert outcome.stdout == "on stdout\n"
assert outcome.stderr == "on stderr\n"
escaped = capsys.readouterr()
assert escaped.out == ""
assert escaped.err == ""
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
fake = mcp_fake.FakeCli(raises=SystemExit(2))
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
# `sys.exit("message")` is status 1 in a real process, and the message is
# the exit code object rather than something printed.
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
fake = mcp_fake.FakeCli(raises=SystemExit(None))
assert invoke.Runner(fake).run(["status"]).returncode == 0
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
"""What a CLI process would have done, rather than a transport error."""
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.returncode == invoke.GENERIC_FAILURE
assert "RuntimeError: boom" in outcome.stderr
assert "Traceback" in outcome.stderr
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
"""BaseException is caught on purpose; the code still says "failed"."""
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
outcome = invoke.Runner(fake).run(["session", "list"])
assert outcome.returncode == invoke.GENERIC_FAILURE
def test_a_call_runs_with_the_serialising_lock_held():
"""The CLI prints to a process-global stdout, so one call at a time.
Asserted from inside the call rather than by racing two threads and hoping
their output interleaves: a race that passes by luck is not a test. The
private name is the point -- what is being asserted is that this specific
lock is held while a handler runs.
"""
def probing(argv):
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
if free:
invoke._ONE_AT_A_TIME.release()
print("free" if free else "held", end="")
return 0
assert invoke.Runner(probing).run(["status"]).stdout == "held"
# ── decoding ───────────────────────────────────────────────────────────────
def test_the_protocol_object_is_read_from_stdout_on_success():
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
def test_the_protocol_object_is_read_from_stderr_on_failure():
"""The CLI's own split: an error goes to stderr whatever the output mode."""
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
fake = mcp_fake.FakeCli(
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
)
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
assert not outcome.ok
assert outcome.payload() == fields
def test_an_object_printed_under_a_bare_line_is_still_found():
"""`session start` prints the id beside its object; parsing must survive it."""
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
"ok": True,
"id": "s-1",
}
def test_no_json_at_all_is_none_rather_than_an_invention():
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
assert invoke.Runner(fake).run(["status"]).payload() is None
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
assert invoke.first_json_object("[1, 2, 3]") is None
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
# ── the real entry point, with nothing listening ───────────────────────────
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.USAGE)
assert "invalid choice" in outcome.stderr
# And nothing escaped onto the real stdout: argparse prints usage there for
# --help and to stderr for an error, and both are captured.
assert outcome.stdout == ""
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
"""No socket, no daemon, no fake: the mapping end to end."""
outcome = invoke.Runner().run(["session", "list", "--json"])
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
payload = outcome.payload()
assert payload is not None
assert payload["error"] == "daemon_unreachable"
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
"""Exit 9 is produced by the CLI before the socket is touched at all."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.NO_LEASE)
assert (outcome.payload() or {}).get("error") == "no_lease"
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
"""The one capability lost by calling the CLI in process, said out loud."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "cannot read" in outcome.stderr
assert "sg hhstream" in outcome.stderr
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
readable = tmp_path / "stream.sock"
readable.write_bytes(b"")
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "sg hhstream" not in outcome.stderr
def test_a_session_verb_never_earns_the_frame_socket_hint():
"""It has nothing to do with the control socket, so it must not be offered."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
["session", "pointer", "acquire", "--json", "--", "s-1"]
)
assert "sg hhstream" not in outcome.stderr
# ── the exit-code table ────────────────────────────────────────────────────
@pytest.mark.parametrize(
"code",
[
ExitCode.USAGE,
ExitCode.NO_SUCH_SESSION,
ExitCode.BAD_STATE,
ExitCode.DAEMON_UNREACHABLE,
ExitCode.POLICY,
ExitCode.TIMEOUT,
ExitCode.BUSY,
ExitCode.NO_LEASE,
ExitCode.COMPOSITOR,
],
)
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
"""A new code in the frozen table must not fall through to a generic line."""
text = invoke.remedy_for(int(code))
assert text.startswith(f"exit {int(code)} ({code.name})")
assert int(code) in invoke.REMEDY
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
busy = invoke.remedy_for(int(ExitCode.BUSY))
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
assert "hhstream://pointer" in busy and "wait" in busy
assert "pointer_acquire" in none_held
# "acquire one" must not be the advice for BUSY: that is the one confusion
# the two codes exist to prevent.
assert "pointer_acquire" not in busy
def test_an_unclassified_code_is_still_a_failure_and_says_so():
text = invoke.remedy_for(42)
assert "exit 42 (UNCLASSIFIED)" in text
assert "do not assume anything happened" in text
def test_generic_failure_is_its_own_case():
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
# ── launch, for `run` ──────────────────────────────────────────────────────
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
"""`run` launches and forgets, and a killed server must not take it along."""
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
try:
assert not spawned.exited
assert spawned.pid > 0
os.kill(spawned.pid, 0)
# Its own session, so a client that kills this server's process group
# does not kill the desktop with it.
assert os.getsid(spawned.pid) == spawned.pid
assert os.getsid(spawned.pid) != os.getsid(0)
finally:
with contextlib.suppress(ProcessLookupError):
os.kill(spawned.pid, signal.SIGTERM)
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
spawned = invoke.Runner().launch(["false"], settle=5.0)
assert spawned.exited
assert spawned.pid > 0
def test_launch_hands_back_what_a_failing_application_said(wayland):
spawned = invoke.Runner().launch(
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
)
assert spawned.exited
assert "cannot open display" in spawned.stderr
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
assert spawned.exited
assert spawned.pid == 0
assert "no executable" in spawned.stderr
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
"""`env_for_session` exits with the message; it is handed on verbatim."""
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
(tmp_path / "empty").mkdir()
spawned = invoke.Runner().launch(["true"], settle=1.0)
assert spawned.exited
assert spawned.pid == 0
assert "no wayland socket" in spawned.stderr
assert "is the compositor up?" in spawned.stderr
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory with something `env_for_session` accepts in it.
A real AF_UNIX socket, because that function checks `is_socket()` -- an
empty file would make it refuse for a reason these tests are not about.
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
address is capped near 108 bytes and pytest's own paths are longer than
that.
"""
import socket
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(str(workdir / "wayland-0"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
yield workdir
listener.close()
# ── artefact readers ───────────────────────────────────────────────────────
def test_a_png_is_sniffed_by_its_header_not_its_extension():
image = media.sniff(mcp_fake.png(width=13, height=7))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
"""The publisher serves `image/jpeg` on the deployment machine."""
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
def test_an_unrecognised_format_is_none_rather_than_a_guess():
assert media.sniff(b"GIF89a\x00\x00") is None
assert media.sniff(b"") is None
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
assert found is not None
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
assert media.recording("/tmp/out.mp4\n") is None
assert media.recording("") is None
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
first = invoke.temp_name("recording", ".mp4")
assert "hhstream-mcp" in first
assert first.endswith(".mp4")
assert str(os.getpid()) in first
+303
View File
@@ -0,0 +1,303 @@
"""The resource table: which URI runs which CLI call, and what comes back.
Same subject as ``test_mcp_tools.py`` and the same stand-in: what this layer
decides is the argv list, and here also the *routing* -- which entry a URI
resolves to, and which query parameters it will accept. Nothing here imports
the MCP SDK; the protocol wiring is ``test_mcp_server.py``.
"""
from __future__ import annotations
import json
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, resources, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def read():
"""`read("hhstream://sessions")` -> (Reading, [argv, ...])."""
def _read(uri, **script):
fake = mcp_fake.FakeCli(**script)
reading = resources.read(invoke.Runner(fake), uri)
return reading, fake.calls
return _read
# ── the table ──────────────────────────────────────────────────────────────
#: Every resource `docs/CONTRACT-mcp.md` §4 freezes, written out rather than
#: derived, for the reason the tool list is.
EXPECTED_FIXED = {
"hhstream://status",
"hhstream://sessions",
"hhstream://pointer",
"hhstream://containers",
"hhstream://screen",
}
EXPECTED_TEMPLATES = {
"hhstream://sessions/{id}{?events}",
"hhstream://sessions/{id}/logs{?lines}",
"hhstream://outputs/{name}",
}
def test_the_whole_surface_is_there_and_nothing_else_is():
assert {entry.uri for entry in resources.FIXED} == EXPECTED_FIXED
assert {entry.uri_template for entry in resources.TEMPLATES} == EXPECTED_TEMPLATES
assert len(resources.ENTRIES) == len(EXPECTED_FIXED) + len(EXPECTED_TEMPLATES)
def test_every_entry_has_a_unique_name_and_a_description():
names = [entry.name for entry in resources.ENTRIES]
assert len(names) == len(set(names))
for entry in resources.ENTRIES:
assert entry.title, entry.name
assert len(entry.description) > 40, entry.name
assert entry.media_type
def test_a_template_is_exactly_an_entry_with_a_capture():
for entry in resources.FIXED:
assert entry.captures == ()
for entry in resources.TEMPLATES:
assert entry.captures
def test_the_three_reads_the_activity_rule_names_say_so_themselves():
"""The rule has to be where it is read, and these are read, not called."""
for name in ("sessions", "session", "session-logs", "pointer", "containers"):
description = resources.BY_NAME[name].description
assert "does NOT reset" in description, name
assert "`session_touch`" in description, name
# ── routing ────────────────────────────────────────────────────────────────
def test_a_literal_route_beats_a_template_that_would_also_match():
"""`hhstream://sessions` is the listing, not a session with a blank id."""
entry, arguments = resources.resolve("hhstream://sessions")
assert entry.name == "sessions"
assert arguments == {}
def test_a_capture_becomes_the_argument_the_cli_takes(read):
_, calls = read("hhstream://sessions/foot-abc", stdout=mcp_fake.reply(ok=True))
assert calls == [["session", "status", "--json", "--", "foot-abc"]]
def test_a_deeper_route_is_its_own_entry(read):
_, calls = read("hhstream://sessions/foot-abc/logs", stdout=mcp_fake.reply(ok=True))
assert calls == [["session", "logs", "--json", "--", "foot-abc"]]
def test_each_fixed_resource_runs_the_verb_it_names(read):
cases = {
"hhstream://status": ["status"],
"hhstream://sessions": ["session", "list", "--json"],
"hhstream://pointer": ["session", "pointer", "state", "--json"],
"hhstream://containers": ["session", "container", "--json"],
}
for uri, argv in cases.items():
_, calls = read(uri, stdout=mcp_fake.reply(ok=True))
assert calls == [argv], uri
def test_the_status_resource_is_text_because_the_verb_has_no_json(read):
reading, calls = read("hhstream://status", stdout="services:\n up\n")
assert calls == [["status"]]
assert reading.media_type == "text/plain"
assert reading.text == "services:\n up"
assert reading.blob is None
def test_a_json_resource_passes_the_protocol_object_through_unchanged(read):
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
reading, _ = read("hhstream://sessions", stdout=json.dumps(reply, indent=2))
assert reading.media_type == "application/json"
assert json.loads(reading.text) == reply
def test_a_scheme_this_server_does_not_serve_is_refused(read):
with pytest.raises(resources.ReadRefused) as caught:
read("file:///etc/passwd")
assert "not a hhstream resource" in str(caught.value)
def test_a_uri_that_names_nothing_is_refused_and_points_at_the_listing(read):
for uri in ("hhstream://nonsense", "hhstream://sessions/a/b/c", "hhstream://"):
with pytest.raises(resources.ReadRefused) as caught:
read(uri)
assert "resources/list" in str(caught.value) or "names no resource" in str(
caught.value
)
def test_nothing_was_run_for_a_uri_that_did_not_resolve(monkeypatch, tmp_path):
"""The routing refuses before the CLI is reached, as a schema would."""
fake = mcp_fake.FakeCli()
with pytest.raises(resources.ReadRefused):
resources.read(invoke.Runner(fake), "hhstream://nonsense")
assert fake.calls == []
# ── query parameters ───────────────────────────────────────────────────────
def test_a_declared_parameter_becomes_the_flag_the_cli_takes(read):
_, calls = read(
"hhstream://sessions/foot-abc/logs?lines=250", stdout=mcp_fake.reply(ok=True)
)
assert calls == [["session", "logs", "--json", "--lines=250", "--", "foot-abc"]]
_, calls = read(
"hhstream://sessions/foot-abc?events=5", stdout=mcp_fake.reply(ok=True)
)
assert calls == [["session", "status", "--json", "--events=5", "--", "foot-abc"]]
def test_a_switch_parameter_is_a_bare_flag_or_nothing(read):
"""`--all=false` is not a thing the CLI takes, so false must omit it."""
_, calls = read("hhstream://sessions?all=true", stdout=mcp_fake.reply(ok=True))
assert calls == [["session", "list", "--json", "--all"]]
for falsey in ("false", "0", "no", "off", ""):
_, calls = read(f"hhstream://sessions?all={falsey}", stdout=mcp_fake.reply(ok=True))
assert calls == [["session", "list", "--json"]], falsey
def test_an_undeclared_parameter_is_refused_rather_than_dropped(read):
"""A parameter silently ignored is a read that answered another question."""
with pytest.raises(resources.ReadRefused) as caught:
read("hhstream://sessions?lines=5")
assert "'lines'" in str(caught.value)
assert "all" in str(caught.value)
def test_a_resource_with_no_parameters_says_so_when_given_one(read):
with pytest.raises(resources.ReadRefused) as caught:
read("hhstream://pointer?id=s-1")
assert "accepts: none" in str(caught.value)
def test_a_parameter_given_twice_is_refused(read):
with pytest.raises(resources.ReadRefused) as caught:
read("hhstream://sessions/s-1/logs?lines=1&lines=2")
assert "more than once" in str(caught.value)
def test_the_template_advertises_the_parameters_it_accepts():
"""So a client can construct a URI without guessing."""
logs = resources.BY_NAME["session-logs"]
assert logs.uri_template == "hhstream://sessions/{id}/logs{?lines}"
assert logs.parameters == ("lines",)
# ── refusals ───────────────────────────────────────────────────────────────
def test_a_cli_refusal_is_raised_and_never_returned_as_the_body(read):
"""A resource has no `isError`; returning the failure object would lie."""
reply = {"ok": False, "error": "no_such_session", "reason": "no session 'nope'"}
with pytest.raises(resources.ReadRefused) as caught:
read(
"hhstream://sessions/nope",
stderr=mcp_fake.reply(**reply),
exit_code=int(ExitCode.NO_SUCH_SESSION),
)
refused = caught.value
assert "exit 3 (NO_SUCH_SESSION)" in refused.message
assert "no session 'nope'" in refused.message
# And the structured detail carries what a tool error would have carried.
assert refused.detail["exit_code"] == int(ExitCode.NO_SUCH_SESSION)
assert refused.detail["error"] == "no_such_session"
assert "hhstream://sessions" in refused.detail["remedy"]
def test_an_unreachable_broker_is_refused_with_the_operator_s_remedy(read):
with pytest.raises(resources.ReadRefused) as caught:
read(
"hhstream://sessions",
stderr=mcp_fake.reply(ok=False, error="daemon_unreachable", reason="no socket"),
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
)
assert "HHSTREAM_SOCKET" in caught.value.message
# ── frames ─────────────────────────────────────────────────────────────────
def test_the_screen_resource_is_the_frame_bytes_with_its_real_media_type(read):
frame = mcp_fake.png(width=320, height=180)
reading, calls = read("hhstream://screen", write_png=frame)
assert calls[0][0] == "shot"
assert calls[0][1].startswith("--out=")
assert len(calls[0]) == 2, "the screen takes no --output"
assert reading.blob == frame
assert reading.text is None
assert reading.media_type == "image/png"
def test_an_output_resource_captures_that_output_alone(read):
frame = mcp_fake.png()
reading, calls = read("hhstream://outputs/hh-foot-abc", write_png=frame)
assert "--output=hh-foot-abc" in calls[0]
assert reading.blob == frame
def test_a_frame_s_media_type_is_sniffed_and_not_assumed(read):
"""The entry declares image/png; a JPEG publisher must still be told truly."""
assert resources.BY_NAME["screen"].media_type == "image/png"
reading, _ = read("hhstream://screen", write_png=mcp_fake.jpeg())
assert reading.media_type == "image/jpeg"
def test_a_capture_that_wrote_no_file_is_refused_rather_than_empty(read):
with pytest.raises(resources.ReadRefused) as caught:
read("hhstream://screen")
assert "no readable file" in str(caught.value)
def test_a_refused_capture_carries_the_cli_s_own_words(read):
with pytest.raises(resources.ReadRefused) as caught:
read(
"hhstream://outputs/hh-gone",
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
exit_code=1,
)
assert "unknown output" in str(caught.value)
assert "hh-gone" in str(caught.value)
# ── the one read that must not be a resource ───────────────────────────────
def test_there_is_no_resource_for_the_reconciling_container_read():
"""`session container <id>` writes. Only the no-id list is a resource."""
assert "hhstream://containers" in EXPECTED_FIXED
for entry in resources.ENTRIES:
assert entry.route[:1] != ("containers",) or entry.captures == ()
# ...and the writing form is still reachable, as a tool.
assert "session_container" in tools.BY_NAME
+530
View File
@@ -0,0 +1,530 @@
"""The SDK wiring: the handshake, the listing, and one call of each shape.
This is the file that imports the MCP SDK, and it does so unconditionally. The
tool table is standard library and tested without it
(``test_mcp_tools.py``); what is left is the part only the SDK can judge --
whether every schema validates, whether every name is one the specification
allows, and whether a refusal arrives as a tool error rather than a success. A
file that skipped when the SDK was absent would be green in exactly the build
where that mattered, which is why ``checks/unit.nix`` puts ``mcp`` in the test
environment rather than making it optional.
The server runs in process, over the SDK's in-memory transport. The stdio
transport itself is proved end to end by ``checks/vm-mcp.nix`` and by the
handshake in the pull request description -- a pair of memory streams cannot
tell you that a stray ``print`` has corrupted stdout.
"""
from __future__ import annotations
import json
import os
import anyio
import jsonschema
import mcp.types as types
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from mcp.shared.memory import create_connected_server_and_client_session
from mcp.shared.tool_name_validation import validate_tool_name
from pydantic import AnyUrl
from hhstream_mcp import SERVER_NAME, __version__, invoke, resources, server, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def session():
"""`session(...)` -> (the recording CLI, a connected client session).
The stand-in is scripted per test, exactly as in the table's own tests;
what is added here is a real client on the other end of a real server, so
`initialize` and the two request types are exercised rather than asserted
about.
"""
def _session(toolsets=None, **script):
fake = mcp_fake.FakeCli(**script)
built = server.build(invoke.Runner(fake), toolsets)
return fake, create_connected_server_and_client_session(
built, raise_exceptions=True
)
return _session
def run(coroutine):
return anyio.run(coroutine)
# ── the handshake ──────────────────────────────────────────────────────────
def test_initialize_names_this_server_and_declares_tools(session):
_, connected = session()
async def go():
async with connected as client:
result = await client.initialize()
return result
initialized = run(go)
assert initialized.serverInfo.name == SERVER_NAME
assert initialized.serverInfo.version == __version__
assert initialized.capabilities.tools is not None
# Resources are half the surface now, so the capability has to be declared
# or a host will never ask for them.
assert initialized.capabilities.resources is not None
# The instructions are where the two rules are said once for the whole
# surface; a client that shows them must be given them.
assert initialized.instructions
assert "`session_touch` is the ONLY" in initialized.instructions
def test_the_instructions_carry_both_rules():
assert "`session_touch` is the ONLY" in server.INSTRUCTIONS
assert "POINTER lease" in server.INSTRUCTIONS
assert "There is no keyboard lease" in server.INSTRUCTIONS
# And the two lease codes an agent has to tell apart.
assert "Exit 8 means" in server.INSTRUCTIONS
assert "9 means you need to acquire one" in server.INSTRUCTIONS
def test_the_instructions_explain_the_split_they_cannot_be_read_without():
"""An agent that does not know state is a resource will look for a tool."""
assert "Resources are the state" in server.INSTRUCTIONS
assert "Tools are the acts" in server.INSTRUCTIONS
for uri in ("hhstream://status", "hhstream://sessions", "hhstream://pointer"):
assert uri in server.INSTRUCTIONS
# ── the listing ────────────────────────────────────────────────────────────
def test_tools_list_returns_every_tool_with_a_title_and_a_description(session):
_, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.list_tools()
listed = run(go).tools
assert {tool.name for tool in listed} == set(tools.BY_NAME)
assert len(listed) == 21
for tool in listed:
assert tool.title, tool.name
assert tool.description and len(tool.description) > 40, tool.name
assert tool.annotations is not None
assert tool.annotations.openWorldHint is False
def test_every_tool_name_is_one_the_specification_allows():
for tool in tools.TOOLS:
result = validate_tool_name(tool.name)
assert result.is_valid, (tool.name, result.warnings)
# Warnings are not failures to the SDK, but a name that earns one is a
# name that will be mangled by some client.
assert result.warnings == [], (tool.name, result.warnings)
def test_every_input_schema_is_a_schema_the_validator_accepts():
"""The SDK validates every call against these; a bad one fails at call time."""
for tool in tools.TOOLS:
jsonschema.Draft202012Validator.check_schema(tool.schema)
def test_the_read_only_hint_is_set_from_the_verb_and_not_from_the_name():
for tool in tools.TOOLS:
described = server.describe(tool)
assert described.annotations.readOnlyHint == tool.read_only
if tool.read_only:
assert described.annotations.destructiveHint is None
else:
assert described.annotations.destructiveHint is tool.destructive
# ── the schemas, through the validator the server actually uses ────────────
def test_move_requires_exactly_one_of_to_and_by():
schema = tools.BY_NAME["pointer_move"].schema
jsonschema.validate({"id": "s", "lease": "L", "to": [0.5, 0.5]}, schema)
jsonschema.validate({"id": "s", "lease": "L", "by": [0.5, 0.5]}, schema)
for bad in (
{"id": "s", "lease": "L"},
{"id": "s", "lease": "L", "to": [0.5, 0.5], "by": [0.1, 0.1]},
{"id": "s", "lease": "L", "to": [0.5]},
{"id": "s", "lease": "L", "to": [0.5, 0.5, 0.5]},
):
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate(bad, schema)
def test_home_and_ephemeral_home_are_refused_together_by_the_schema():
"""The CLI's mutually exclusive group, moved forward to where it is cheaper."""
schema = tools.BY_NAME["session_start"].schema
jsonschema.validate({"app": "foot"}, schema)
jsonschema.validate({"app": "foot", "home": "/tmp/h"}, schema)
jsonschema.validate({"app": "foot", "ephemeral_home": True}, schema)
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate({"app": "foot", "home": "/tmp/h", "ephemeral_home": True}, schema)
def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session):
"""The lease is required, so the schema refuses and no argv is built."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("pointer_click", {"id": "s-1"})
result = run(go)
assert result.isError
assert "lease" in result.content[0].text
# The point of a schema refusal: the CLI was never reached.
assert fake.calls == []
# ── calls ──────────────────────────────────────────────────────────────────
def test_a_successful_call_carries_the_protocol_object_as_structured_content(session):
reply = {"ok": True, "pruned": 0}
fake, connected = session(stdout=json.dumps(reply, indent=2))
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_gc", {})
result = run(go)
assert not result.isError
assert result.structuredContent == reply
assert fake.calls == [["session", "gc", "--json"]]
def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session):
reply = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
_, connected = session(
stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE)
)
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool(
"pointer_click", {"id": "s-1", "lease": "stale"}
)
result = run(go)
assert result.isError is True
assert result.structuredContent["exit_code"] == int(ExitCode.NO_LEASE)
text = result.content[0].text
assert "exit 9 (NO_LEASE)" in text
assert "pointer_acquire" in text
def test_a_frame_arrives_as_image_content_beside_its_geometry(session):
frame = mcp_fake.png(width=64, height=48)
_, connected = session(write_png=frame, stdout="/tmp/ignored.png\n")
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("shot", {})
result = run(go)
assert not result.isError
kinds = [block.type for block in result.content]
assert kinds == ["text", "image"]
text, image = result.content
assert "64x48 image/png" in text.text
assert image.mimeType == "image/png"
import base64
assert base64.b64decode(image.data) == frame
def test_a_v1_tool_name_is_told_which_resource_replaced_it(session):
"""`no such tool` alone reads as a broken server rather than a moved surface."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_list", {})
result = run(go)
assert result.isError is True
text = result.content[0].text
assert "It is a RESOURCE now" in text
assert "hhstream://sessions" in text
assert fake.calls == []
def test_a_tool_that_does_not_exist_names_the_ones_that_do(session):
"""And is an error. The SDK turns a raised McpError into this shape anyway."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_detonate", {})
result = run(go)
assert result.isError is True
assert "no such tool: 'session_detonate'" in result.content[0].text
assert "session_touch" in result.content[0].text
assert fake.calls == []
def test_a_handler_that_raises_is_reported_to_the_agent_and_not_only_logged():
"""A CLI process would have died with a traceback and status 1; so does this."""
fake = mcp_fake.FakeCli(raises=RuntimeError("the broker said something odd"))
result = server.call(invoke.Runner(fake), "session_gc", {})
assert result.isError is True
assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE
assert "the broker said something odd" in result.content[0].text
def test_the_transport_is_moved_off_the_descriptor_the_cli_prints_to():
"""The one thing an in-process CLI call could break, asserted directly."""
read_fd, write_fd = os.pipe()
saved_out, saved_err = os.dup(1), os.dup(2)
log_read, log_write = os.pipe()
try:
os.dup2(write_fd, 1)
os.dup2(log_write, 2)
_, stdout = server.claim_transport()
# After claiming, this process's own stdout is the log (fd 2), not the
# stream the client reads.
assert os.path.sameopenfile(1, 2)
assert not os.path.sameopenfile(1, stdout.wrapped.fileno())
# ...and stdin cannot eat a request.
assert os.readlink(f"/proc/self/fd/0") == os.devnull
finally:
os.dup2(saved_out, 1)
os.dup2(saved_err, 2)
for fd in (saved_out, saved_err, read_fd, write_fd, log_read, log_write):
try:
os.close(fd)
except OSError:
pass
def test_the_listing_is_what_the_entry_point_prints(capsys):
"""`--list-tools` is the package's own install check; keep it honest."""
assert server.main(["--list-tools"]) == 0
printed = capsys.readouterr().out.splitlines()
assert len(printed) == len(tools.TOOLS)
assert printed[0].split("\t")[0] == tools.TOOLS[0].name
def test_the_entry_point_lists_resources_too(capsys):
assert server.main(["--list-resources"]) == 0
printed = capsys.readouterr().out.splitlines()
assert len(printed) == len(resources.ENTRIES)
assert printed[0].split("\t")[0] == "hhstream://status"
def test_the_entry_point_s_listing_honours_a_toolset_selection(capsys):
assert server.main(["--list-tools", "--toolsets", "keyboard"]) == 0
printed = capsys.readouterr().out.splitlines()
assert [line.split("\t")[0] for line in printed] == list(
tools.TOOLSETS["keyboard"]
)
def test_an_unknown_toolset_on_the_command_line_is_argparse_s_exit_two(capsys):
with pytest.raises(SystemExit) as caught:
server.main(["--list-tools", "--toolsets", "mouse"])
assert caught.value.code == 2
assert "no such toolset" in capsys.readouterr().err
def test_an_empty_toolset_list_is_refused_rather_than_read_as_all(capsys):
"""`--toolsets ""` is a mistake, and serving everything would hide it."""
with pytest.raises(SystemExit) as caught:
server.main(["--list-tools", "--toolsets", " , "])
assert caught.value.code == 2
# ── resources, over the protocol ───────────────────────────────────────────
def test_resources_list_returns_the_fixed_ones_with_their_descriptions(session):
_, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.list_resources()
listed = run(go).resources
assert {str(r.uri) for r in listed} == {e.uri for e in resources.FIXED}
for resource in listed:
assert resource.title and resource.description and resource.mimeType
def test_resource_templates_are_listed_separately_with_their_parameters(session):
_, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.list_resource_templates()
listed = run(go).resourceTemplates
assert {t.uriTemplate for t in listed} == {e.uri_template for e in resources.TEMPLATES}
logs = next(t for t in listed if t.uriTemplate.endswith("/logs{?lines}"))
assert logs.name == "session-logs"
def test_reading_a_json_resource_returns_the_broker_s_object(session):
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
fake, connected = session(stdout=json.dumps(reply, indent=2))
async def go():
async with connected as client:
await client.initialize()
return await client.read_resource(AnyUrl("hhstream://sessions"))
result = run(go)
assert len(result.contents) == 1
content = result.contents[0]
assert content.mimeType == "application/json"
assert json.loads(content.text) == reply
assert fake.calls == [["session", "list", "--json"]]
def test_reading_a_template_passes_the_capture_and_the_query_through(session):
fake, connected = session(stdout=mcp_fake.reply(ok=True, lines=[]))
async def go():
async with connected as client:
await client.initialize()
return await client.read_resource(
AnyUrl("hhstream://sessions/foot-abc/logs?lines=7")
)
run(go)
assert fake.calls == [
["session", "logs", "--json", "--lines=7", "--", "foot-abc"]
]
def test_reading_a_frame_resource_returns_a_blob_not_text(session):
frame = mcp_fake.png(width=48, height=24)
_, connected = session(write_png=frame)
async def go():
async with connected as client:
await client.initialize()
return await client.read_resource(AnyUrl("hhstream://screen"))
content = run(go).contents[0]
assert isinstance(content, types.BlobResourceContents)
assert content.mimeType == "image/png"
import base64
assert base64.b64decode(content.blob) == frame
def test_a_refused_read_is_a_protocol_error_carrying_the_remedy(session):
"""A resource read has no `isError`, so the refusal has to be an error."""
from mcp.shared.exceptions import McpError
fake, connected = session(
stderr=mcp_fake.reply(ok=False, error="no_such_session", reason="no session 'nope'"),
exit_code=int(ExitCode.NO_SUCH_SESSION),
)
async def go():
async with connected as client:
await client.initialize()
with pytest.raises(McpError) as caught:
await client.read_resource(AnyUrl("hhstream://sessions/nope"))
return caught.value
error = run(go)
assert "exit 3 (NO_SUCH_SESSION)" in str(error)
assert "no session 'nope'" in str(error)
def test_a_uri_that_names_no_resource_is_a_protocol_error(session):
from mcp.shared.exceptions import McpError
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
with pytest.raises(McpError) as caught:
await client.read_resource(AnyUrl("hhstream://nonsense"))
return caught.value
error = run(go)
assert "no resource at" in str(error)
assert fake.calls == []
# ── toolsets, over the protocol ────────────────────────────────────────────
def test_a_toolset_selection_narrows_the_listing_but_not_the_resources(session):
_, connected = session(toolsets=["keyboard"])
async def go():
async with connected as client:
await client.initialize()
return await client.list_tools(), await client.list_resources()
listed, resource_list = run(go)
assert [t.name for t in listed.tools] == list(tools.TOOLSETS["keyboard"])
# Resources are the host's context, not the model's tool budget.
assert len(resource_list.resources) == len(resources.FIXED)
def test_a_tool_outside_the_selection_cannot_be_called_by_name(session):
"""Unlisted must mean unreachable, or the selection is cosmetic."""
fake, connected = session(toolsets=["keyboard"])
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_kill", {"id": "s-1"})
result = run(go)
assert result.isError is True
text = result.content[0].text
assert "session_kill" in text
assert "without its toolset" in text
assert fake.calls == []
def test_content_for_a_text_only_result_has_no_image_block():
blocks = server.content_for(tools.Result(text="hello"))
assert [block.type for block in blocks] == ["text"]
assert isinstance(blocks[0], types.TextContent)
+603
View File
@@ -0,0 +1,603 @@
"""The tool table: the argv each tool builds, and what it makes of the answer.
The subject is the shim and nothing else. Every test here drives a tool
through :class:`hhstream_mcp.invoke.Runner` with a recording stand-in
(:class:`mcp_fake.FakeCli`) where the CLI goes, and asserts on the argv it was
handed -- which is the only thing this layer actually decides.
Nothing in this file imports the MCP SDK: the table is standard library by
design, so an argv bug is findable without a protocol stack. The SDK wiring is
``test_mcp_server.py``, and the real CLI entry point is exercised in
``test_mcp_invoke.py``.
"""
from __future__ import annotations
import json
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def call():
"""`call("session_touch", {"id": "s-1"})` -> (Result, [argv, ...])."""
def _call(name, arguments, **script):
fake = mcp_fake.FakeCli(**script)
result = tools.BY_NAME[name].invoke(invoke.Runner(fake), arguments)
return result, fake.calls
return _call
# ── the surface is all there ───────────────────────────────────────────────
#: Every tool `docs/CONTRACT-mcp.md` §3 freezes. Written out rather than derived
#: from the table, because a list derived from the thing it checks cannot
#: notice a missing entry.
EXPECTED = {
# frames -- capturing is an act at a moment, so these stay tools
"shot", "record", "run",
# lifecycle. The read-only verbs are resources; see MOVED_TO_RESOURCES.
"session_start", "session_touch", "session_kill", "session_gc",
"session_adopt", "session_container", "session_reconcile",
# pointer
"pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll",
"pointer_down", "pointer_up", "pointer_release",
# keyboard
"keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up",
}
#: Verbs that are resources now and must NOT come back as tools. Named, not
#: merely absent, so re-adding one is a failure rather than a silent widening
#: of the surface mcp-v2 narrowed.
MOVED_TO_RESOURCES = {
"status",
"session_list",
"session_status",
"session_logs",
"pointer_state",
}
def test_the_acting_verbs_are_tools_and_nothing_else_is():
assert set(tools.BY_NAME) == EXPECTED
assert len(tools.TOOLS) == 21
def test_the_read_only_verbs_are_not_tools():
"""They are `hhstream://…` resources: the host's context, not the model's acts."""
assert MOVED_TO_RESOURCES.isdisjoint(set(tools.BY_NAME))
# ...and the table that says where each one went covers exactly those five,
# so a caller holding a v1 name can be told rather than just refused.
assert set(tools.MOVED_TO_RESOURCES) == MOVED_TO_RESOURCES
for uri in tools.MOVED_TO_RESOURCES.values():
assert uri.startswith("hhstream://")
def test_session_container_stayed_a_tool_because_it_writes():
"""With an id the CLI runs `container.reconcile`, so it is not a read."""
assert "session_container" in tools.BY_NAME
assert not tools.BY_NAME["session_container"].read_only
assert "write" in tools.BY_NAME["session_container"].description
def test_the_table_is_ordered_and_has_no_duplicate_names():
names = [tool.name for tool in tools.TOOLS]
assert len(names) == len(set(names))
assert isinstance(tools.TOOLS, tuple)
def test_only_the_verbs_that_read_are_marked_read_only():
"""One left, now that the rest of the reads are resources."""
read_only = {tool.name for tool in tools.TOOLS if tool.read_only}
assert read_only == {"shot"}
# `record` writes a file, so it is not read-only either.
assert not tools.BY_NAME["record"].read_only
assert tools.BY_NAME["session_kill"].destructive
assert [t.name for t in tools.TOOLS if t.destructive] == ["session_kill"]
# ── the two rules an agent gets wrong ──────────────────────────────────────
#: The tools the CLI's own note names as NOT counting as activity. The others
#: it names are resources now, and `test_mcp_resources.py` holds those.
NON_ACTIVITY = {
"session_gc",
"session_container",
"session_reconcile",
}
GESTURES = {
"pointer_move",
"pointer_click",
"pointer_scroll",
"pointer_down",
"pointer_up",
"pointer_release",
"keyboard_type",
"keyboard_key",
"keyboard_down",
"keyboard_up",
}
#: The four families `--toolsets` selects from.
FAMILIES = ("frames", "sessions", "pointer", "keyboard")
def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it():
for name in NON_ACTIVITY | GESTURES | {"session_start", "session_touch", "pointer_acquire"}:
description = tools.BY_NAME[name].description
assert tools.ACTIVITY_NOTE in description, f"{name} does not carry the activity rule"
def test_the_idle_clock_rule_names_touch_as_the_only_mark_of_activity():
assert "`session_touch` is the ONLY thing" in tools.ACTIVITY_NOTE
# It has to name the *resources* now, because that is where reading moved:
# an agent told "listing does not count" cannot act on it if the thing it
# is listing with is no longer called `session_list`.
for named in ("hhstream://sessions", "session_gc", "pointer or keyboard tool"):
assert named in tools.ACTIVITY_NOTE
assert "does NOT count" in tools.ACTIVITY_NOTE
def test_the_cli_still_owns_the_rule_this_wording_restates():
"""A tripwire, not a duplication.
`tools.ACTIVITY_NOTE` and `tools.LEASE_NOTE` are the CLI's two epilogues
said in terms of tools. If the CLI's constants are renamed or stop saying
what they say, these notes have silently become this server's own opinion --
so the originals are asserted to still exist and still carry the rule.
"""
import hhstream_session
assert "ONLY" in hhstream_session.ACTIVITY_NOTE
assert "touch" in hhstream_session.ACTIVITY_NOTE
assert "no 'keyboard acquire'" in hhstream_session.KEYBOARD_LEASE_NOTE
def test_every_keyboard_tool_says_it_needs_the_pointer_lease():
for name in ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"):
description = tools.BY_NAME[name].description
assert tools.LEASE_NOTE in description, f"{name} does not carry the lease rule"
assert "POINTER lease" in tools.LEASE_NOTE
assert "exit 9" in tools.LEASE_NOTE
assert "`pointer_acquire`" in tools.LEASE_NOTE
assert "There is no keyboard lease" in tools.LEASE_NOTE
assert "only while it holds" in tools.LEASE_NOTE
def test_holding_a_non_modifier_is_warned_about_where_it_can_happen():
assert tools.HOLD_NOTE in tools.BY_NAME["keyboard_down"].description
assert "FLOODS THE WINDOW" in tools.HOLD_NOTE
assert "the APPLICATION does the repeating" in tools.HOLD_NOTE
def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached():
for name in GESTURES:
schema = tools.BY_NAME[name].schema
assert "lease" in schema["required"], f"{name} does not require a lease"
# ...and acquire is the one that hands it out, so it must not require one.
assert "lease" not in tools.BY_NAME["pointer_acquire"].schema.get("required", [])
# ── toolsets ───────────────────────────────────────────────────────────────
def test_every_tool_is_in_exactly_one_toolset():
"""Or `--toolsets` would be able to hide a tool nobody could ask for."""
assert tuple(tools.TOOLSETS) == FAMILIES
seen: list[str] = []
for family in FAMILIES:
seen.extend(tools.TOOLSETS[family])
assert len(seen) == len(set(seen)), "a tool is in two toolsets"
assert set(seen) == set(tools.BY_NAME), "a tool is in no toolset"
def test_no_toolset_named_is_every_tool():
"""The default, and what an unconfigured client gets."""
assert tools.selected(None) == tools.TOOLS
def test_a_selection_keeps_the_table_s_own_order():
"""So a listing does not reshuffle because of how the flag was written."""
chosen = [tool.name for tool in tools.selected(["keyboard", "frames"])]
assert chosen == ["shot", "record", "run", "keyboard_type", "keyboard_key",
"keyboard_down", "keyboard_up"]
def test_a_repeated_family_is_not_a_repeated_tool():
assert tools.selected(["frames", "frames"]) == tools.selected(["frames"])
def test_an_unknown_family_is_refused_and_names_the_known_ones():
"""Not skipped: a typo that served nothing would look like an empty server."""
with pytest.raises(tools.UnknownToolset) as caught:
tools.selected(["frames", "mouse"])
assert "'mouse'" in str(caught.value)
for family in FAMILIES:
assert family in str(caught.value)
def test_every_schema_refuses_an_argument_this_server_would_drop():
for tool in tools.TOOLS:
assert tool.schema["additionalProperties"] is False, tool.name
assert tool.schema["type"] == "object"
# ── the argv each tool builds ──────────────────────────────────────────────
def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call):
_, calls = call("session_touch", {"id": "s-1"})
assert calls == [["session", "touch", "--json", "--", "s-1"]]
def test_omitted_arguments_become_no_flag_at_all(call):
"""A flag left off is the broker's own default; this layer must not supply one."""
_, calls = call("session_gc", {})
assert calls == [["session", "gc", "--json"]]
_, calls = call("session_gc", {"request_id": "r-1"})
assert calls == [["session", "gc", "--json", "--request-id=r-1"]]
_, calls = call("session_reconcile", {})
assert calls == [["session", "reconcile", "--json"]]
def test_start_passes_the_application_argv_after_one_separator(call):
_, calls = call(
"session_start",
{
"app": "chromium",
"argv": ["--new-window", "https://example.invalid"],
"idle_timeout": "5m",
"wait_ready": "30s",
"request_id": "req-7",
},
)
assert calls == [
[
"session", "start", "--json",
"--idle-timeout=5m",
"--wait-ready=30s",
"--request-id=req-7",
"--",
"chromium",
"--new-window",
"https://example.invalid",
]
]
def test_an_application_argument_that_looks_like_a_flag_is_not_eaten(call):
"""The `--` is what makes `--new-window` the application's and not the CLI's."""
_, calls = call("session_start", {"app": "foot", "argv": ["--help"]})
assert calls[0] == ["session", "start", "--json", "--", "foot", "--help"]
def test_an_ephemeral_home_is_a_switch_and_a_home_is_a_value(call):
_, calls = call("session_start", {"app": "foot", "ephemeral_home": True})
assert "--ephemeral-home" in calls[0]
_, calls = call("session_start", {"app": "foot", "home": "/tmp/h"})
assert "--home=/tmp/h" in calls[0]
def test_a_coordinate_pair_is_sent_in_the_cli_s_own_x_comma_y_form(call):
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [0.25, 0.75]})
assert calls == [["session", "pointer", "move", "--json", "--lease=L", "--to=0.25,0.75", "--", "s-1"]]
def test_a_negative_delta_stays_one_token_so_argparse_cannot_read_it_as_a_flag(call):
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "by": [-0.1, 0.5]})
assert calls[0][5] == "--by=-0.1,0.5"
def test_a_coordinate_is_not_rounded_on_the_way_through(call):
"""A caller that computed a number deserves the broker's verdict on it."""
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [1 / 3, 0.0]})
assert calls[0][5] == f"--to={1 / 3!r},0.0"
def test_a_negative_scroll_amount_stays_one_token(call):
_, calls = call("pointer_scroll", {"id": "s-1", "lease": "L", "amount": -3, "axis": "horizontal"})
assert calls[0] == [
"session", "pointer", "scroll", "--json",
"--lease=L", "--axis=horizontal", "--amount=-3.0", "--", "s-1",
]
def test_a_typed_string_is_one_positional_after_the_separator(call):
text = "--not-a-flag\nsecond line\twith a tab"
_, calls = call("keyboard_type", {"id": "s-1", "lease": "L", "text": text})
assert calls == [["session", "keyboard", "type", "--json", "--lease=L", "--", "s-1", text]]
def test_a_keysym_name_is_passed_through_untouched(call):
_, calls = call("keyboard_key", {"id": "s-1", "lease": "L", "name": "BackSpace"})
assert calls[0][-1] == "BackSpace"
def test_adopt_sends_the_pid_as_a_flag_because_the_cli_requires_it(call):
_, calls = call("session_adopt", {"pid": 4242, "app": "chromium"})
assert calls == [["session", "adopt", "--json", "--pid=4242", "--app=chromium"]]
def test_container_with_no_id_lists_and_with_an_id_reconciles(call):
_, calls = call("session_container", {})
assert calls == [["session", "container", "--json"]]
_, calls = call("session_container", {"id": "s-1"})
assert calls == [["session", "container", "--json", "--", "s-1"]]
# ── what each tool makes of the answer ─────────────────────────────────────
def test_a_successful_session_verb_passes_the_protocol_object_through(call):
reply = {"ok": True, "pruned": 2, "sessions": [{"id": "s-1"}]}
result, _ = call("session_gc", {}, stdout=json.dumps(reply, indent=2))
assert not result.is_error
assert result.data == reply
# The text is the CLI's own stdout: a shim that re-rendered it would be
# inventing a second format for the same facts.
assert json.loads(result.text) == reply
def test_acquire_puts_the_lease_id_where_the_next_call_will_look(call):
reply = {"ok": True, "id": "s-1", "lease_id": "lease-abc", "bookmark": {"output": "hh-s-1"}}
result, _ = call("pointer_acquire", {"id": "s-1"}, stdout=json.dumps(reply, indent=2))
assert result.data == reply
assert result.text.startswith("lease_id: lease-abc")
assert "pointer_release" in result.text
def test_start_puts_the_new_session_id_first_and_names_the_idle_clock(call):
reply = {"ok": True, "id": "s-9", "state": "running"}
result, _ = call("session_start", {"app": "foot"}, stdout=json.dumps(reply, indent=2))
assert result.text.startswith("session id: s-9")
assert "session_touch" in result.text
def test_a_refusal_is_an_error_and_never_a_success(call):
reply = {
"ok": False,
"error": "no_lease",
"reason": "no pointer lease for s-1 on this socket",
"hint": "run 'pointer acquire s-1' first",
}
result, _ = call(
"pointer_click",
{"id": "s-1", "lease": "stale"},
stderr=json.dumps(reply, indent=2),
exit_code=int(ExitCode.NO_LEASE),
)
assert result.is_error
assert result.data["ok"] is False
assert result.data["exit_code"] == int(ExitCode.NO_LEASE)
# The remedy first, then the broker's own words: an agent needs to know what
# to do before it needs to know what was said.
assert result.text.startswith("exit 9 (NO_LEASE)")
assert "pointer_acquire" in result.text
assert "error: no_lease" in result.text
assert "no pointer lease for s-1" in result.text
def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call):
reply = {"ok": False, "error": "pointer_busy", "reason": "held by s-other"}
result, _ = call(
"pointer_acquire",
{"id": "s-1"},
stderr=json.dumps(reply, indent=2),
exit_code=int(ExitCode.BUSY),
)
assert result.is_error
assert result.text.startswith("exit 8 (BUSY)")
assert "hhstream://pointer" in result.text
assert "s-other" in result.text
def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call):
"""Exit 2 with no JSON anywhere -- argparse wrote prose to stderr."""
result, _ = call(
"pointer_click",
{"id": "s-1", "lease": "L", "button": "left"},
stderr="usage: hhstream session pointer click ...\nerror: argument --button: invalid choice\n",
exit_code=int(ExitCode.USAGE),
)
assert result.is_error
assert result.data["exit_code"] == int(ExitCode.USAGE)
assert "invalid choice" in result.text
def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call):
result, _ = call(
"session_gc",
{},
stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n",
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
)
assert result.is_error
assert "HHSTREAM_SOCKET" in result.text
assert "frame tools" in result.text
# ── shot and record ────────────────────────────────────────────────────────
def test_shot_captures_to_a_file_and_returns_the_bytes_with_the_geometry(call):
frame = mcp_fake.png(width=320, height=180)
result, calls = call("shot", {}, write_png=frame, stdout="/tmp/ignored.png\n")
assert len(calls) == 1
verb, out = calls[0][0], calls[0][1]
assert verb == "shot"
assert out.startswith("--out=")
# The temporary directory is gone, so the file cannot be read twice: the
# bytes are in the reply or they are nowhere.
assert result.image == frame
assert result.media_type == "image/png"
assert "320x180 image/png" in result.text
assert result.data["width"] == 320
def test_shot_of_one_output_names_it_in_the_argv_and_in_the_reply(call):
result, calls = call("shot", {"output": "hh-s-1"}, write_png=mcp_fake.png())
assert "--output=hh-s-1" in calls[0]
assert "output 'hh-s-1'" in result.text
assert result.data["output"] == "hh-s-1"
def test_shot_tells_the_truth_about_a_format_it_cannot_read(call):
result, _ = call("shot", {}, write_png=b"GIF89a-not-an-image")
assert not result.is_error
assert result.image is None
assert "does not recognise" in result.text
def test_shot_does_not_claim_an_image_when_the_cli_wrote_no_file(call):
"""Exit 0 and no artefact is still a failure; the alternative is a lie."""
result, _ = call("shot", {}, stdout="/tmp/somewhere.png\n")
assert result.is_error
assert result.data["error"] == "no_artifact"
def test_shot_passes_a_refusal_through_without_reading_a_file(call):
result, _ = call(
"shot",
{"output": "hh-gone"},
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
exit_code=1,
)
assert result.is_error
assert result.image is None
assert "unknown output" in result.text
def test_record_returns_the_path_and_the_measured_rate_not_the_video(call):
destination = "/tmp/hhstream-mcp/clip.mp4"
result, calls = call(
"record",
{"seconds": 3, "out": destination},
stdout=f"{destination} (28 frames in 3.01s -> 9 fps)\n",
)
assert calls[0] == ["record", f"--out={destination}", "--seconds=3"]
assert result.image is None
assert result.data == {
"ok": True,
"path": destination,
"frames": 28,
"seconds": 3.01,
"fps": 9,
}
assert "measured 9 fps" in result.text
def test_record_without_a_destination_generates_one_and_names_it(call):
result, calls = call("record", {}, stdout="/x (1 frames in 1.00s -> 1 fps)\n")
flag = next(a for a in calls[0] if a.startswith("--out="))
assert "hhstream-mcp" in flag
assert flag.endswith(".mp4")
assert result.data["ok"] is True
def test_record_of_one_output_passes_the_rate_target_through(call):
_, calls = call(
"record",
{"seconds": 2, "output": "hh-s-1", "fps": 4, "keep": True, "work_dir": "/tmp/w"},
stdout="/x (8 frames in 2.00s -> 4 fps)\n",
)
# The generated --out is asserted by the test above; what matters here is
# the order and form of everything after it.
assert calls[0][0] == "record"
assert calls[0][2:] == [
"--seconds=2",
"--output=hh-s-1",
"--fps=4",
"--work-dir=/tmp/w",
"--keep",
]
# ── run ────────────────────────────────────────────────────────────────────
def test_run_reports_the_application_s_pid_and_that_it_is_unmanaged(wayland):
result = tools.BY_NAME["run"].invoke(
invoke.Runner(), {"argv": ["sleep", "30"], "settle_s": 0.3}
)
try:
assert not result.is_error
assert result.data["managed"] is False
assert result.data["pid"] > 0
assert result.data["argv"] == ["sleep", "30"]
# The tool's own words have to point at the managed alternative, or an
# agent reaches for `run` because it is the shorter name.
assert "session_start" in result.text
assert "UNMANAGED" in result.text
finally:
import contextlib
with contextlib.suppress(ProcessLookupError):
os.kill(result.data["pid"], signal.SIGTERM)
def test_run_reports_a_launch_that_failed_immediately_as_an_error(wayland):
result = tools.BY_NAME["run"].invoke(
invoke.Runner(),
{"argv": ["sh", "-c", "echo 'cannot open display' >&2; exit 1"], "settle_s": 5.0},
)
assert result.is_error
assert result.data["error"] == "run_exited"
assert "cannot open display" in result.text
assert "nothing is on" in result.text
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory the CLI's `env_for_session` accepts.
A real AF_UNIX socket, because that function checks `is_socket()`, and the
suite's short-pathed `workdir` because an AF_UNIX address is capped near
108 bytes.
"""
import socket
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(str(workdir / "wayland-0"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
yield workdir
listener.close()