the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.
CLI (src/hhstream/cli.py, src/hhstream_session/**)
session container [ID], session reconcile [ID], and the seven pointer verbs
from PLAN §9. `start` still prints the bare session id and nothing else.
`list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
genuinely unknown rather than a blank that reads as zero -- the POINTER
column needs a second, read-only `pointer.state` call because the `list`
reply carries no lease state.
The lease id is cached in `hhstream_session.lease` (under
$XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
override it, and a `no_lease` refusal drops the stale entry.
Exit codes are the contract's: a gesture with no lease is 9 and never
reaches the broker, and a compositor failure is 10 with a message that says
the session is still running. `kill` now warns about
`session.container_survivors` -- windows the compositor still shows -- and
distinguishes `null` ("could not ask") from `[]`.
`shot`/`record --output NAME` capture one container through `grim -o`; the
frame socket publishes the main output only, so it cannot do it.
Module (nix/module.nix)
sessions.containers.{enable,max,mode,workspaceBase},
sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
TOML with §10's key names. hhstream-pointer.service: the operator's account,
supplementary group hhstream, After=/BindsTo= the compositor,
Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
without which restarting the broker deletes the driver's socket out from
under it. The runtime-directory length assertion is untouched.
And ExecStartPost on the compositor, opening its IPC directory to its own
group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
different account by design -- could not reach the request or event socket
at all, and degraded silently exactly as it is built to.
Checks (checks/**)
vm-ipc: both sockets at their frozen names, measured against sun_path's 108
bytes, and a socket2 subscriber that receives an openwindow for a window the
test creates. The subscriber is the shipped HyprlandIPC, not a second
implementation: this check exists to prove that this client hears this
compositor.
vm-containers: one hh-* output per session at the container mode, the window
on it, a second window of the same application beside it, an unmatched
window quarantined, grim -o isolating one container, teardown removing the
output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
create headless` works.
vm-pointer: a version-2 virtual pointer, a warp and a click whose
coordinates the *application* reports, BUSY naming the holder, an expired
lease swept with its held button lifted, and a broker restart that leaves
the lock free, the bookmark intact and the driver reachable.
checks/lib gains the guest the three share, their test-script helpers (no
assertions live there), an event-socket subscriber and a Wayland client that
says where it was clicked -- nothing in nixpkgs both honours
$HHSTREAM_APP_ID and reports pointer events.
Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
This commit is contained in:
1 parent
57fdd4f636
commit
de408e4b7f
19 files changed
+4304
-98
No files matched your search
+70
-14
@@ -6,21 +6,35 @@
|
||||
│ Hyprland 0.56.2, no physical monitor │
|
||||
│ private XDG_RUNTIME_DIR, as `user` │
|
||||
│ outputs come from `outputs[]` │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ Wayland session
|
||||
▼
|
||||
┌──────────────────────────────────────────┐
|
||||
│ hyprland-headless-stream.service │
|
||||
│ hhstream-server │
|
||||
│ capture ──▶ one "latest frame" slot │
|
||||
│ accept ──▶ a thread per client │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ AF_UNIX, mode 0660
|
||||
▼
|
||||
many clients ── hhstream-client / any socket reader
|
||||
│ + 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)
|
||||
```
|
||||
|
||||
Three pieces, deliberately separate:
|
||||
Five pieces, deliberately separate:
|
||||
|
||||
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
|
||||
outputs. It knows nothing about frames on a socket.
|
||||
@@ -29,6 +43,35 @@ Three pieces, deliberately separate:
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
@@ -71,7 +114,20 @@ So the requirements are:
|
||||
| `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.
|
||||
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.
|
||||
Reference in new issue
Block a user