diff --git a/README.dev.md b/README.dev.md index 37073f0..4c854ff 100644 --- a/README.dev.md +++ b/README.dev.md @@ -152,7 +152,7 @@ What the dump contains, and where it comes from in the guest: |---|---| | `units` | `systemctl list-units --all 'hyprland*'` | | per-unit `status` / `journalctl` | `hyprland-headless.service` and `hyprland-headless-stream.service`, 200 lines each | -| `socket and runtime directories` | `/run/hyprland-headless-stream`, `/run/user/*` | +| `socket and runtime directories` | `/run/hypr-stream`, `/run/user/*` | | `hyprland logs` | every `hyprland*.log` found under `/run`, `/var/log`, `/tmp`, `/home` | | `hyprctl monitors` | run once per instance found, with the right `XDG_RUNTIME_DIR` and `HYPRLAND_INSTANCE_SIGNATURE` | | `processes` | `ps aux` filtered to `hypr`, `hhstream`, `grim` | diff --git a/README.md b/README.md index 80901b1..e750c12 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Two parts: Then any consumer: ```bash -hhstream-client --socket /run/hyprland-headless-stream/stream.sock --count 1 --out frame.png +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 diff --git a/checks/vm-basic.nix b/checks/vm-basic.nix index 2bac106..b891f1a 100644 --- a/checks/vm-basic.nix +++ b/checks/vm-basic.nix @@ -13,7 +13,7 @@ width ? 1280, height ? 720, fps ? 30, - socketPath ? "/run/hyprland-headless-stream/stream.sock", + socketPath ? "/run/hypr-stream/stream.sock", }: testers.runNixOSTest { name = "hhstream-vm-basic"; diff --git a/checks/vm-hyprland.nix b/checks/vm-hyprland.nix index a85af35..a69617b 100644 --- a/checks/vm-hyprland.nix +++ b/checks/vm-hyprland.nix @@ -20,7 +20,7 @@ width ? 1280, height ? 720, fps ? 30, - socketPath ? "/run/hyprland-headless-stream/stream.sock", + socketPath ? "/run/hypr-stream/stream.sock", }: testers.runNixOSTest { name = "hhstream-vm-hyprland"; @@ -111,8 +111,8 @@ testers.runNixOSTest { # compositor's IPC socket even though it belongs to `hhstream`. HYPRCTL_MONITORS = ( "set -eu; " - "sig=$(ls -1 /run/hyprland-headless-stream/hypr | head -n1); " - "XDG_RUNTIME_DIR=/run/hyprland-headless-stream" + "sig=$(ls -1 /run/hypr-stream/hypr | head -n1); " + "XDG_RUNTIME_DIR=/run/hypr-stream" " HYPRLAND_INSTANCE_SIGNATURE=$sig hyprctl -j monitors" ) @@ -177,8 +177,8 @@ testers.runNixOSTest { # minimal PATH, not the guest's environment.systemPackages. status, out = machine.execute( "systemd-run --pipe --wait --uid=hhstream" - " --setenv=XDG_RUNTIME_DIR=/run/hyprland-headless-stream" - " --setenv=WAYLAND_DISPLAY=$(cd /run/hyprland-headless-stream" + " --setenv=XDG_RUNTIME_DIR=/run/hypr-stream" + " --setenv=WAYLAND_DISPLAY=$(cd /run/hypr-stream" " && ls -1 wayland-* | grep -v '\.lock$' | head -n1)" " sh -c '${grim}/bin/grim -t png - > /tmp/direct.png' 2>&1", timeout=120, diff --git a/checks/vm-sessions.nix b/checks/vm-sessions.nix index fca0bd6..5a84072 100644 --- a/checks/vm-sessions.nix +++ b/checks/vm-sessions.nix @@ -214,7 +214,7 @@ testers.runNixOSTest { CONTROL = "${controlSocket}" CONTROL_DIR = "/run/hhstream" IDLE_TIMEOUT = ${toString idleTimeout}.0 - COMPOSITOR_RUNTIME = "/run/hyprland-headless-stream" + COMPOSITOR_RUNTIME = "/run/hypr-stream" # The module pins the compositor's XDG_RUNTIME_DIR; the instance signature # under it is the only part not known ahead of time. Root may connect to diff --git a/docs/CONTRACT-sessions.md b/docs/CONTRACT-sessions.md index 336f591..ff7e2e8 100644 --- a/docs/CONTRACT-sessions.md +++ b/docs/CONTRACT-sessions.md @@ -9,7 +9,20 @@ 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-v1 (2026-10-01). +Version: sessions-v2 (2026-10-02). v1 was the freeze the four slices built against; +v2 records the decisions their reports asked for. Every v2 change is either a +clarification or an addition — **no v1 signature changed meaning** — so v1 code +stays valid except where noted. Changes: + +| § | Change | Why | +| --- | --- | --- | +| §3.1 | `Monitor` gains `id: int` | `clients -j` reports a client's monitor as a numeric **index**, `Workspace.monitor` as a **name**, so without an id there is no way to join a client to its output. Slice D's aiming is output-local. | +| §3.1 | `Client.stable_id` defined as `":"` (fallback `address`); absent `pid` becomes `-1`; `Event.data` is a per-event field table plus always-present `raw`/`args`; `request_timeout_s` is an overridable class attribute (2 s); `version()` returns the compositor's banner verbatim | What slice B had to decide, now written down instead of re-derived. | +| §3.2 | `quarantine_argv()` replaces `quarantine_plan()`, returning `list[list[str]] \| None` | A quarantine rule is not a container: no output, no numbered workspace, no mode, and `container_plan` refuses a zero size. **Integration updates `containers.py` and its tests to this shape.** | +| §3.3 | `mark()` added; `expire()` precedence documented | §3.3 gave no way to record a position, so `LeaseOutcome.bookmark` could only ever be `None` and `pointer.acquire … restore?` had nothing to restore. | +| §3.4 | Vendored protocol is permitted, and the XML path is corrected | The v1 path was wrong (`share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml`). | +| §5 | The broker state dir is stated as an *option default* with this machine's override; the frame socket is named | §5's value was the deployed one, not the default, and the frame socket was missing while `docs/CONTRACT.md` still documents the old one. | + --- @@ -57,7 +70,7 @@ class CompositorUnavailable(Exception): @dataclass(frozen=True) class Monitor: - name: str; x: int; y: int; width: int; height: int; scale: float + id: int; name: str; x: int; y: int; width: int; height: int; scale: float active_workspace_id: int | None @dataclass(frozen=True) @@ -103,6 +116,24 @@ Rules: every method raises `CompositorUnavailable` rather than returning a guess. `clients()` parses `clients -j`; `monitors()` parses `monitors -j`; `workspaces()` parses `workspaces -j`. Stdlib only. +Decisions, so they are not re-derived per caller: + +- **A client's monitor is an index, an output's name is a name.** `Client.monitor` + is the numeric index rendered as text (or `None` when the reply said nothing); + join it to a `Monitor` through `Monitor.id`. `Workspace.monitor` is a name. +- **`Client.stable_id`** is `":"`, falling back to + `address`. Hyprland publishes no such key; this is the identity that survives a + remap, and the launcher sets the class per session. +- **An absent `pid` becomes `-1`**, not `0` — no process has pid `-1`. +- **Events are positional on the wire** (`name>>a,b,c`). `Event.data` is built + from a per-event field table, with the last named field absorbing the remaining + commas (titles contain them); `raw` and `args` are always present so an unknown + event is still usable. An event that carries fewer fields than the table names + only what arrived — never invented empties. +- **`request_timeout_s`** is a class attribute (2 s) on `HyprlandIPC` because + `__init__` is frozen. +- **`version()` returns the compositor's banner verbatim**, not a parsed number. + ### 3.2 `hhstreamd/containers.py` (C) **Pure logic. No I/O, no subprocess, no socket, no import of `ipc.py`.** It @@ -139,9 +170,18 @@ def app_id_for(session_id: str) -> str: ... # the bare "hh-" the launcher sets on the app; "^hh-$" # is built in container_plan. -def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None: ... +def quarantine_argv(quarantine_workspace: str) -> list[list[str]] | None: ... # the backstop: every window matching no container goes to - # special:quarantine. Returns the keyword argv, or None if disabled. + # special:quarantine. Returns the keyword argv, or None when the target is + # blank/whitespace (which is how "disabled" is spelled). + # + # Deliberately NOT a ContainerPlan: a quarantine rule has no output, no + # numbered workspace and no mode. The argv shape mirrors the per-session + # rule, with a catch-all class: + # ["hyprctl","keyword","windowrule", + # f"match:initial_class .*, workspace {target}"] + # It must be installed BEFORE any per-session rule, or the catch-all wins. + # That ordering is the caller's, and this module cannot enforce it. class WorkspaceAllocator: def __init__(self, base: int, count: int) -> None: ... @@ -183,6 +223,11 @@ class PointerLease: def acquire(self, session_id: str) -> str: ... # -> lease_id; raises LeaseBusy def refresh(self, session_id: str, lease_id: str) -> None: ... # raises LeaseInvalid def release(self, session_id: str, lease_id: str, reason: str) -> LeaseOutcome: ... + def mark(self, session_id: str, lease_id: str, bookmark: Bookmark) -> None: ... + # records where the cursor was left, called on every move and before + # release. Added in v2: without it LeaseOutcome.bookmark could only ever + # be None, so `pointer.acquire --restore` had nothing to restore. + # raises LeaseInvalid for a non-holder. def state(self) -> dict: ... # {"holder": str|None, "since": float|None, # "lease_id": str|None, "expires_at": float|None} def expire(self) -> LeaseInfo | None: ... @@ -192,6 +237,13 @@ class PointerLease: def unpress(self, session_id: str, button: str) -> list[str]: ... def pressed(self) -> list[str]: ... +**`expire()` carries no bookmark and no lifted buttons** — it returns the lease +that was released, nothing more. The broker therefore has two duties on expiry: +read `pressed()` *before* calling `expire()` if it wants the lease's view of what +was down, and lift those buttons on the driver (`release_all`), because the lease +cannot lift them itself. The bookmark is not `expire()`'s to keep: the broker +already stores it with the session (§1), which is where it belongs. + def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int], monitor: tuple[int, int, int, int]) -> tuple[float, float]: # point is window-local pixels; window is (x, y, w, h) global; monitor is @@ -209,11 +261,14 @@ blocked driver must not stall the broker. - Command line the module will pass, exactly: `hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream` - Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr - virtual pointer XML** from `pkgs.wlr-protocols` - (`share/wayland-protocols/wlr-unstable/zwlr-virtual-pointer-unstable-v1.xml`). - Compile the protocol at build time or vendor the generated module under your - directory — your choice, stated in your report. `pyproject.toml` and - `nix/package.nix` are yours precisely so this is possible. + virtual pointer XML** from `pkgs.wlr-protocols`, which lives at + `share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml` (the v1 + contract had this path wrong: different middle directory, and no `z` prefix on + the filename). **Vendoring the generated module is explicitly permitted** (v2): + generating at build time puts a code generator between a checkout and a runnable + driver, and the dev shell has neither the XML nor a scanner. State which you + did. `pyproject.toml` and `nix/package.nix` are yours precisely so this is + possible. - Binds `zwlr_virtual_pointer_manager_v1` **version 2** and uses `create_virtual_pointer_with_output(seat, output, id)` so coordinates are output-local. If only version 1 is offered, **report it — never silently fall @@ -269,9 +324,10 @@ reset the idle clock. | Compositor runtime dir | `/run/hypr-stream` — **must be ≤ 25 chars** (socket paths must stay under `sun_path`'s 108-byte limit) | | Compositor request socket | `/hypr//.socket.sock` | | Compositor event socket | `/hypr//.socket2.sock` | +| Frame socket (published) | `/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 state dir | `/var/lib/hermes/hhstream-sessions` | +| 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/` | | Container output name | `hh-` | | Container workspace band | `1000 + slot`, allocated from the registry's free list | diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index 9b8ccb1..3448b98 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -1,4 +1,11 @@ -# Wire contract (v1) +# Wire contract (v2) + +**v2 changes nothing on the wire.** The published socket's documented *default* +moved from `/run/hyprland-headless-stream/stream.sock` to +`/run/hypr-stream/stream.sock`: the old runtime directory pushed the compositor's +own IPC *event* socket past `sun_path`'s 108-byte limit, so it never bound (see +`docs/CONTRACT-sessions.md` §5). Message sequence, framing and failure semantics +are unchanged, so a v1 reader is still a correct reader. This file is the interface. Code on either side may change freely; **this document may not**, without bumping the version. @@ -7,7 +14,7 @@ document may not**, without bumping the version. - Transport: `AF_UNIX`, `SOCK_STREAM`. - Path: whatever `services.hyprland-headless-stream.socketPath` says. - Default `/run/hyprland-headless-stream/stream.sock`. + Default `/run/hypr-stream/stream.sock`. - Ownership: the service user (`user` option, default `hhstream`), mode `0660`. - The server accepts **any number of concurrent clients**. Each client gets its own copy of the header and of every subsequent frame. A client disconnecting @@ -78,7 +85,7 @@ Namespace: `services.hyprland-headless-stream` | Option | Type | Default | Meaning | |---|---|---|---| | `enable` | bool | `false` | turn everything on | -| `socketPath` | str | `/run/hyprland-headless-stream/stream.sock` | published socket | +| `socketPath` | str | `/run/hypr-stream/stream.sock` | published socket | | `user` / `group` | str | `hhstream` | owner of the session and the socket | | `frameRate` | int | `30` | capture target, becomes `fps` in Hello | | `format` | enum `png`/`jpeg` | `png` | frame encoding | diff --git a/examples/README.md b/examples/README.md index 29e27c5..e320e91 100644 --- a/examples/README.md +++ b/examples/README.md @@ -93,10 +93,14 @@ Two notes for anyone editing that file: Hyprland draws the error *across the screen*, which lands in the recording. Always check an edit with `Hyprland --verify-config --config ` — it does not need a display, so it costs seconds instead of a rebuild. -- `hyprctl` **cannot connect** to this session: the compositor names its IPC - socket `.socket.so`/`.socket.s` instead of `.socket.sock`, so nothing using the - documented path works. Do not plan on `hyprctl` for window control — measure - what you need from the frames instead. +- `hyprctl` **works** against this session; an older note here claimed the + compositor misnames its IPC socket, which was wrong. The real defect was path + length: `$XDG_RUNTIME_DIR` was `/run/hyprland-headless-stream` (29 chars) and + the event socket `hypr//.socket2.sock` did not fit in `sun_path`, so + the compositor logged `ERR ]: Socket2 path is too long. (2) IPC will not work.` + while the request socket kept answering — which is why the wrong diagnosis + survived. The runtime directory is now `/run/hypr-stream`, and `nix/module.nix` + asserts it stays ≤ 25 characters. ### Posting the result to a chat diff --git a/examples/agent-eyes-demo.py b/examples/agent-eyes-demo.py index 784731c..3098a97 100644 --- a/examples/agent-eyes-demo.py +++ b/examples/agent-eyes-demo.py @@ -50,8 +50,8 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src")) from hhstream import protocol # noqa: E402 (path set above) -DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" -DEFAULT_RUNTIME_DIR = "/run/hyprland-headless-stream" +DEFAULT_SOCKET = "/run/hypr-stream/stream.sock" +DEFAULT_RUNTIME_DIR = "/run/hypr-stream" def log(message: str) -> None: diff --git a/src/hhstream/client.py b/src/hhstream/client.py index 7c6b28e..e661502 100644 --- a/src/hhstream/client.py +++ b/src/hhstream/client.py @@ -11,7 +11,7 @@ from typing import Iterable from . import protocol -DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" +DEFAULT_SOCKET = "/run/hypr-stream/stream.sock" def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]: diff --git a/src/hhstream/server.py b/src/hhstream/server.py index 5518dd0..343ec4b 100644 --- a/src/hhstream/server.py +++ b/src/hhstream/server.py @@ -23,7 +23,7 @@ from typing import Iterable from . import protocol from .capture import CaptureBackend, CommandCapture -DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" +DEFAULT_SOCKET = "/run/hypr-stream/stream.sock" #: Contract: the published socket is mode 0660 (ownership is the unit's job). SOCKET_MODE = 0o660 #: Contract default for `services.hyprland-headless-stream.captureCommand`. diff --git a/tests/hyprland_diagnostics.sh b/tests/hyprland_diagnostics.sh index d0a33c6..9ef1804 100755 --- a/tests/hyprland_diagnostics.sh +++ b/tests/hyprland_diagnostics.sh @@ -42,7 +42,7 @@ ls -l /dev/dri 2>&1 || echo "[no /dev/dri: this machine has no DRM device at all run cat /proc/fb say "socket and runtime directories" -ls -la /run/hyprland-headless-stream 2>&1 || echo "[no /run/hyprland-headless-stream]" +ls -la /run/hypr-stream 2>&1 || echo "[no /run/hypr-stream]" ls -la /run/user 2>&1 || echo "[no /run/user]" for d in /run/user/*; do [ -d "$d" ] && ls -la "$d" 2>&1 @@ -56,7 +56,7 @@ say "wayland socket vs WAYLAND_DISPLAY" systemctl show -p Environment --value "$SERVICE_UNIT" 2>&1 \ | tr ' ' '\n' | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=' \ || echo "[no WAYLAND_DISPLAY/XDG_RUNTIME_DIR in the unit environment]" -for d in /run/hyprland-headless-stream /run/user/*; do +for d in /run/hypr-stream /run/user/*; do [ -d "$d" ] || continue found_sock=$(find "$d" -xdev -maxdepth 1 -name 'wayland-*' ! -name '*.lock' 2>/dev/null) if [ -n "$found_sock" ]; then diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py index 8d844cc..9b3b43c 100644 --- a/tests/unit/conftest.py +++ b/tests/unit/conftest.py @@ -31,7 +31,7 @@ for _path in (str(_HERE), str(_SRC)): from hhstream.server import FrameServer # noqa: E402 (needs sys.path above) #: The path named in docs/CONTRACT.md and in the module's option default. -CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock" +CONTRACT_SOCKET = "/run/hypr-stream/stream.sock" # AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a # confusing OSError instead of the assertion the test is about. diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py index 48778fe..494b5e0 100644 --- a/tests/unit/test_cli.py +++ b/tests/unit/test_cli.py @@ -54,7 +54,7 @@ def wait_for_socket(path: str, proc: subprocess.Popen, timeout: float = 10.0) -> def test_server_defaults_match_the_contract(): args = server.build_parser().parse_args([]) - assert args.socket == "/run/hyprland-headless-stream/stream.sock" + assert args.socket == "/run/hypr-stream/stream.sock" assert (args.fps, args.format, args.capture_command) == (30, "png", None) assert server.DEFAULT_CAPTURE_COMMAND == ["grim", "-t", "png", "-"] diff --git a/tests/unit/test_client.py b/tests/unit/test_client.py index 6fd7241..a54a6f1 100644 --- a/tests/unit/test_client.py +++ b/tests/unit/test_client.py @@ -134,7 +134,7 @@ def test_main_rejects_a_negative_count(sock_path, capsys): def test_default_socket_matches_the_contract(): - assert client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock" + assert client.DEFAULT_SOCKET == "/run/hypr-stream/stream.sock" assert client.build_parser().parse_args([]).socket == client.DEFAULT_SOCKET