Files
hyprland-headless-stream-pl…/docs/ARCHITECTURE.md
T
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

11 KiB

Architecture

                     ┌──────────────────────────────────────────┐
                     │ hyprland-headless.service                │
                     │   Hyprland 0.56.2, no physical monitor   │
                     │   private XDG_RUNTIME_DIR, as `user`     │
                     │   outputs come from `outputs[]`          │
                     │   + one headless output per session      │
                     └───┬───────────┬───────────────┬──────────┘
                         │           │               │
       IPC: request /    │           │ Wayland       │ Wayland
       event sockets     │           │ session       │ (virtual pointer)
                         │           ▼               │
                         │  ┌────────────────────────┴─────────┐
                         │  │ hyprland-headless-stream.service │
                         │  │   hhstream-server                │
                         │  │     capture ──▶ one frame slot   │
                         │  │     accept  ──▶ thread per client│
                         │  └───────────────┬──────────────────┘
                         │                  │ AF_UNIX, mode 0660
                         │                  ▼
                         │   many clients ── hhstream-client / any reader
                         │
            ┌────────────┴──────────────┐      ┌──────────────────────────┐
            │ hhstream-sessions.service │─────▶│ hhstream-pointer.service │
            │   hhstreamd               │      │   one Wayland connection │
            │   registry, containers,   │ JSON │   one virtual pointer    │
            │   the pointer lease       │ over │   per output             │
            └────────────┬──────────────┘ a    └──────────────────────────┘
                         │          private socket
                         │ 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, 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.
  2. The frame server (hhstream) captures, holds exactly one frame, and publishes it. It owns the socket, the framing and the drop policy.
  3. The client is any process that can open a Unix socket and read the contract's byte format. The shipped hhstream-client is a convenience, not a requirement.
  4. The session broker (hhstreamd) starts allowlisted applications as tracked sessions, gives each one its own headless output and workspace (a container), reads the compositor back over its own IPC, and owns the pointer lease. It is the only part that keeps state across a restart.
  5. The pointer driver (hhstream-pointer) is a Wayland client of the same session that creates one zwlr_virtual_pointer_v1 per output. It holds no lease and no session state: the broker decides, the driver executes. It is 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:

  1. 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 two consequences are the reason:

  • grim -o hh-<id> captures exactly one session, so one agent's screenshot cannot contain another's window;
  • zwlr_virtual_pointer_manager_v1 version 2 creates a pointer bound to an output, so a warp to (0.5, 0.5) is the middle of that session's screen and not the middle of the desktop. Version 1 is refused rather than used, because its coordinates are global and every click would land somewhere plausible and wrong.

The cursor itself is singular — there is one seat — so pointer access is serialised by a broker-wide lease: one holder, a TTL the broker enforces with its own sweeper, and buttons lifted on release or expiry. The lease disciplines these sessions; it does not enforce against a hostile client, which can create its own virtual pointer (that is what sandboxing, not the lease, would fix).

Why one frame, not a queue

The server keeps a single slot holding the most recent frame. Each client thread sends whatever is in that slot when it is ready. A client that cannot keep up therefore misses frames instead of forcing the server to buffer them: memory use does not grow with the number of stalled clients, and a stalled client cannot delay the others. See docs/CONTRACT.md for exactly what a client observes.

Capture

Capturing is a separate program (by default grim, a wlr-screencopy client) run inside the compositor's session and pointed at stdout. That choice is what keeps hhstream free of Wayland and GPU code — the awkward part lives in a tool that already exists and is already tested — and it is why the capture command is a module option: tests inject a fake, and a future backend (a native screencopy client, a hardware encoder) is a command-line swap rather than a rewrite.

The hardware requirement, stated plainly

Hyprland 0.56.2 asks aquamarine for its headless backend as mandatory (src/Compositor.cpp) and does not accept the DRM backend if it is unavailable. Aquamarine's headless backend still needs an EGL/GBM render node; there is no software-only path that works without one. Consequently a host with no graphics device at all (/dev/dri missing) cannot run this, and Pyprland fails with CBackend::create() failed! before any of its managers come up.

So the requirements are:

  • a render node, i.e. /dev/dri/renderD* — from a real GPU, a virtual GPU (virtio-gpu, virtio-gpu-gl, QXL) or a NixOS test VM's own QEMU display;
  • the video/render groups for whichever user runs it (the module sets them).

Testing, and what each layer proves

Layer Proves
tests/unit the framing, the capture wrapper and the server's client handling, with no compositor and no GPU
checks.vm-basic the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program
checks.vm-hyprland the real thing: headless Hyprland comes up in the VM and grim captures a frame of the configured size
checks.vm-sessions the session broker side: a real application runs as a tracked session on the compositor, the compositor's IPC sees its window, the idle reaper fires for real (and does not fire when the session is touched), and a broker restart adopts its sessions back
checks.vm-ipc both IPC sockets exist at the names the contract freezes and fit in sun_path; hyprctl answers; and a subscriber on the event socket receives an openwindow for a window the test creates — the one assertion that can tell a working event socket from a silently truncated one
checks.vm-containers one hh-* output per session at the container mode, the application's window on it, a second window of the same application beside the first, an unmatched window quarantined instead of landing on whoever had focus, grim -o isolating one container, and teardown removing the output and releasing its workspace slot
checks.vm-pointer the driver binds a version-2 virtual pointer; acquire warps into the container and restores from the bookmark; a click arrives at the application, which reports the coordinates it was delivered at; a second acquire is BUSY naming the holder; an expired lease is swept and its held button lifted; a broker restart leaves the lock free, the bookmark intact and the driver reachable

The three session checks share one guest (checks/lib/session-machine.nix) and one set of test-script helpers (checks/lib/session-prelude.nix); the helpers contain no assertions, so each check's script is still a complete account of what it proves.

vm-hyprland is the only check that can fail for reasons outside this repo, so it is kept separate from vm-basic on purpose: when it fails, the compositor's log is the answer and the other two layers are already known good.

Run the VM checks one at a time. Each boots a guest with a software-rendered compositor; two at once on a two-core machine make the timing-sensitive assertions flake, and a flaky green is worth less than a slow one.