# 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 │ │ the stream phrases │ a └──────────────────────────┘ └────────────┬────────┬─────┘ private socket │ │ ┌──────────────────────────┐ │ └─────────────▶│ hhstream-live.service │ │ live.sock │ one port (9988) │ │ │ grim ─▶ MJPEG per │ │ │ phrase, while watched │ │ └───────────┬──────────────┘ │ │ HTTP │ a browser ┘ // │ AF_UNIX control.sock, mode 0660 ▼ hhstream session ... (the CLI an agent drives) ▲ │ in-process: argv in, exit code out │ ┌────────────┴──────────────┐ │ hhstream-mcp │ stdio: spawned per client │ 23 tools (the acts) │◀─── an MCP client's JSON-RPC │ 10 resources (the state)│ http: one unit, one port, └───────────────────────────┘ a bearer token per request ``` Six pieces, deliberately separate, and a seventh 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. 6. **The stream daemon** (`hhstream-live`) publishes one session's output as MJPEG on one port, behind a four-word phrase, while somebody is connected. A third executor on the pointer driver's pattern and for its reasons: `grim` blocks tens to hundreds of milliseconds so it 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 owns the *decision* (which session, under which phrase, in the record); the daemon owns the port, the capture and the URL. It knows nothing about sessions or idle clocks — it publishes what it is told to publish, and reports a viewer count the broker chooses to read as activity. And the seventh, which is a *shim* and not a layer: 7. **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. It is the only component with **two transports**, and the only one that authenticates anything. Over stdio it does not, because there is nothing there to authenticate: the client spawns the process, so it has already passed a filesystem permission check and holds the `0660` control socket either way — unix permissions are the gate, and a token checked by a process the caller started guards a lock whose key is in the same pocket. Over HTTP (`mcp.http.enable`) it is a unit on a port, the caller passed no such check, and a bearer token is then the only gate there is. That asymmetry is the whole of why the credential exists, and it is also why this shim has a state directory of its own (`mcp.stateDir`) while owning no state about the desktop: the authorization table is about *callers*, not about sessions, and it has no business in the broker's `0700` directory beside the audit trail. ## 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-` 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.