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
2026-10-09 11:32:42 -04:00
2026-09-28 05:01:41 +00:00
2026-09-28 05:01:41 +00:00

hyprland-headless-stream-plugin

A Nix flake that runs a headless Hyprland session and publishes its frames on a persistent Unix socket, so any process that can open a socket can see the screen without owning a display.

Two parts:

  • NixOS module — services.hyprland-headless-stream: starts Hyprland with no physical monitor, and a small frame server beside it.
  • Package — hhstream — the frame server (publishes frames) and its client (reads them). Pure Python standard library.
{
  inputs.hhstream.url = "git+https://<host>/git/<owner>/hyprland-headless-stream-plugin.git";

  # in your host config
  imports = [ inputs.hhstream.nixosModules.default ];
  services.hyprland-headless-stream = {
    enable = true;
    # Optional: the default is one 1280x720@30 rule with an empty name, which
    # is Hyprland's wildcard and applies to whatever outputs the GPU has.
    outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
  };
}

Then any consumer:

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.

Document What it is
docs/CONTRACT.md the wire protocol and the module surface — the interface other people build against
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

Status: work in progress — the module and the test suite are being built.

S
Description
No description provided
Readme
2.8 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 81.7%
Nix 18.1%
Shell 0.2%