The plan is the researched design (one compositor, one output+workspace per session, serialised output-bound pointer input under a lease). The contract is the freeze point for a parallel build: file ownership per slice, the exact Python seams, the wire format, and the names and paths nobody may invent. Kept separate from docs/CONTRACT.md, which governs the frame socket and is untouched by this work.
301 lines
14 KiB
Markdown
301 lines
14 KiB
Markdown
# CONTRACT — sessions build (sessions-v1)
|
|
|
|
This file is the interface for the **session** work: the broker, containers,
|
|
compositor IPC and pointer input. It is the sibling of `docs/CONTRACT.md`, which
|
|
freezes the *frame-socket* wire format; that one is untouched by this build.
|
|
|
|
**Immutable without a version bump.** Every slice codes against this and nothing
|
|
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).
|
|
|
|
---
|
|
|
|
## 1. What is being built, in one paragraph
|
|
|
|
A headless Hyprland desktop is driven by an agent. A broker (`hhstreamd`) starts
|
|
allowlisted applications as **sessions** and tracks them. This build gives each
|
|
session its **own output and workspace** (a spatial container), teaches the
|
|
broker to **talk to the compositor** (IPC), and adds **serialised pointer input**
|
|
aimed at one session, under a **lease** whose bookmark is stored with the
|
|
session.
|
|
|
|
Read `docs/PLAN-workspaces-and-pointer.md` only if your brief tells you to. It
|
|
describes the whole system; you are building one part.
|
|
|
|
---
|
|
|
|
## 2. File ownership — the rule that makes four sessions possible
|
|
|
|
| Slice | Owns (only these) |
|
|
| --- | --- |
|
|
| **A — stage0-rename** | `nix/module.nix`, `src/hhstream/cli.py` (the two socket-path defaults only), `examples/agent-eyes` |
|
|
| **B — ipc-client** | `src/hhstreamd/ipc.py`, `tests/ipc/**` |
|
|
| **C — containers** | `src/hhstreamd/containers.py`, `tests/containers/**` |
|
|
| **D — pointer** | `src/hhstreamd/pointer.py`, `src/hhstream_pointer/**`, `tests/pointer/**`, `pyproject.toml`, `nix/package.nix` |
|
|
| **parent (integration)** | `src/hhstreamd/{protocol,registry,manager,launcher,compositor,procmon}.py`, `checks/**`, `docs/**`, `src/hhstream/cli.py` (everything but the path defaults), `nix/module.nix` (after A merges) |
|
|
|
|
Two slices never edit the same file. A shared-file change you believe you need is
|
|
a **report**, not an edit.
|
|
|
|
**Never touch:** `/etc/nixos` (outside this repo), anything under
|
|
`/var/lib/hermes/nixos`, any systemd unit, any running service. Never run
|
|
`nixos-rebuild`, `nixosTest`, `nix build .#checks.*`, or launch a GUI
|
|
application. The parent serialises all of that on a 2-core machine.
|
|
|
|
---
|
|
|
|
## 3. Python seams (exact signatures — code to these)
|
|
|
|
### 3.1 `hhstreamd/ipc.py` (B)
|
|
|
|
```python
|
|
class CompositorUnavailable(Exception):
|
|
"""No request socket, or the compositor refused. Callers degrade, never guess."""
|
|
|
|
@dataclass(frozen=True)
|
|
class Monitor:
|
|
name: str; x: int; y: int; width: int; height: int; scale: float
|
|
active_workspace_id: int | None
|
|
|
|
@dataclass(frozen=True)
|
|
class Workspace:
|
|
id: int; name: str; monitor: str | None; windows: int; is_special: bool
|
|
|
|
@dataclass(frozen=True)
|
|
class Client:
|
|
address: str; pid: int; workspace_id: int | None; monitor: str | None
|
|
class_: str; initial_class: str; title: str; stable_id: str; visible: bool
|
|
|
|
@dataclass(frozen=True)
|
|
class CursorPos:
|
|
x: int; y: int
|
|
|
|
@dataclass(frozen=True)
|
|
class Event:
|
|
name: str # "openwindow", "workspace", "monitorremoved", ...
|
|
data: dict # parsed payload; keys are whatever the event carried
|
|
|
|
class HyprlandIPC:
|
|
@classmethod
|
|
def discover(cls, runtime_dir: Path, signature: str | None = None) -> "HyprlandIPC": ...
|
|
# raises CompositorUnavailable. Signature from the argument, else
|
|
# $HYPRLAND_INSTANCE_SIGNATURE, else the single directory under
|
|
# <runtime_dir>/hypr/. More than one and no signature = CompositorUnavailable.
|
|
|
|
def __init__(self, request_socket: Path, event_socket: Path | None = None) -> None: ...
|
|
|
|
def version(self) -> str: ...
|
|
def monitors(self) -> list[Monitor]: ...
|
|
def workspaces(self) -> list[Workspace]: ...
|
|
def clients(self) -> list[Client]: ...
|
|
def cursorpos(self) -> CursorPos: ...
|
|
def query(self, command: str) -> str: ... # raw request socket, for anything not wrapped
|
|
def events(self) -> Iterator[Event]: ... # blocking; raises CompositorUnavailable on EOF
|
|
def close(self) -> None: ...
|
|
|
|
def parse_event(line: str) -> Event: ... # "name>>a,b,c" -> Event
|
|
```
|
|
|
|
Rules: every method raises `CompositorUnavailable` rather than returning a
|
|
guess. `clients()` parses `clients -j`; `monitors()` parses `monitors -j`;
|
|
`workspaces()` parses `workspaces -j`. Stdlib only.
|
|
|
|
### 3.2 `hhstreamd/containers.py` (C)
|
|
|
|
**Pure logic. No I/O, no subprocess, no socket, no import of `ipc.py`.** It
|
|
computes command lines and parses nothing. Seams are primitives so this module
|
|
stands alone.
|
|
|
|
```python
|
|
@dataclass(frozen=True)
|
|
class ContainerPlan:
|
|
output: str # hh-<session-id>
|
|
workspace: int
|
|
mode: tuple[int, int] # width, height
|
|
create: list[list[str]] # full argv lists, in order, each ["hyprctl", ...]
|
|
teardown: list[list[str]]
|
|
|
|
def output_name(session_id: str) -> str: ...
|
|
# "hh-" + session_id. Ids are already [a-z0-9-]; assert and raise ValueError otherwise.
|
|
|
|
def contains_output(name: str) -> bool: ...
|
|
# True for names this broker creates (prefix "hh-"), so a start-up scan can
|
|
# find orphans.
|
|
|
|
def container_plan(session_id: str, workspace: int, width: int, height: int,
|
|
app_id: str) -> ContainerPlan: ...
|
|
# create: output create headless <name> ["hyprctl","output","create","headless",name]
|
|
# workspace rule ["hyprctl","keyword","workspace",
|
|
# f"{workspace}, monitor:{name}, default:true, persistent:true"]
|
|
# window rule ["hyprctl","keyword","windowrule",
|
|
# f"match:initial_class ^{app_id}$, workspace {workspace}, monitor {name}"]
|
|
# output mode ["hyprctl","keyword","monitor", f"{name},{width}x{height},auto,1"]
|
|
# teardown: output remove <name> ["hyprctl","output","remove",name]
|
|
|
|
def app_id_for(session_id: str) -> str: ...
|
|
# the bare "hh-<session-id>" the launcher sets on the app; "^hh-<session-id>$"
|
|
# is built in container_plan.
|
|
|
|
def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None: ...
|
|
# the backstop: every window matching no container goes to
|
|
# special:quarantine. Returns the keyword argv, or None if disabled.
|
|
|
|
class WorkspaceAllocator:
|
|
def __init__(self, base: int, count: int) -> None: ...
|
|
def allocate(self) -> int: ... # lowest free slot in [base, base+count); raises NoSlots
|
|
def release(self, workspace: int) -> None: ... # unknown id -> KeyError (a bug, not a no-op)
|
|
def in_use(self) -> list[int]: ...
|
|
|
|
class NoSlots(Exception): ...
|
|
```
|
|
|
|
### 3.3 `hhstreamd/pointer.py` (D)
|
|
|
|
Lease state machine + coordinate maths. **No Wayland, no socket, no I/O.** The
|
|
clock is injected so expiry is testable without sleeping.
|
|
|
|
```python
|
|
class LeaseBusy(Exception): # another session holds it
|
|
def __init__(self, holder: str) -> None: ...
|
|
class LeaseInvalid(Exception): # not held, or held by someone else / stale lease_id
|
|
|
|
@dataclass(frozen=True)
|
|
class Bookmark:
|
|
x: float; y: float # 0..1, output-local, normalised
|
|
output: str
|
|
at: str # ISO-8601 UTC
|
|
|
|
@dataclass(frozen=True)
|
|
class LeaseInfo:
|
|
session_id: str; lease_id: str; acquired_at: float; expires_at: float
|
|
hard_deadline: float
|
|
|
|
@dataclass(frozen=True)
|
|
class LeaseOutcome:
|
|
bookmark: Bookmark | None; reason: str; buttons_lifted: list[str]
|
|
|
|
class PointerLease:
|
|
def __init__(self, ttl_s: float = 30.0, max_s: float = 300.0,
|
|
clock: Callable[[], float] = time.monotonic) -> None: ...
|
|
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 state(self) -> dict: ... # {"holder": str|None, "since": float|None,
|
|
# "lease_id": str|None, "expires_at": float|None}
|
|
def expire(self) -> LeaseInfo | None: ...
|
|
# force-release if past ttl or hard cap; returns what was released.
|
|
# The caller (broker) lifts buttons on the driver side.
|
|
def press(self, session_id: str, button: str) -> None: ...
|
|
def unpress(self, session_id: str, button: str) -> list[str]: ...
|
|
def pressed(self) -> list[str]: ...
|
|
|
|
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
|
|
# (x, y, w, h) global. Returns normalised 0..1 in the MONITOR's frame,
|
|
# clamped to [0, 1]. Raises ValueError if the point is outside the window.
|
|
```
|
|
|
|
### 3.4 `src/hhstream_pointer/**` (D) — the driver process
|
|
|
|
A separate process, because a Wayland client needs its own connection and a
|
|
blocked driver must not stall the broker.
|
|
|
|
- Entry point `hhstream-pointer` (add to `pyproject.toml`:
|
|
`hhstream-pointer = "hhstream_pointer.__main__:main"`).
|
|
- 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.
|
|
- 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
|
|
back** to a global pointer, which would break aiming.
|
|
- Private socket protocol with the broker, newline-delimited JSON:
|
|
|
|
```json
|
|
{"op": "warp", "output": "hh-x", "x": 0.42, "y": 0.61} -> {"ok": true}
|
|
{"op": "button", "button": "left", "state": "down"} -> {"ok": true}
|
|
{"op": "frame"} -> {"ok": true}
|
|
{"op": "pressed"} -> {"ok": true, "buttons": ["left"]}
|
|
{"op": "release_all"} -> {"ok": true, "lifted": ["left"]}
|
|
```
|
|
|
|
`{"ok": false, "error": "<text>"}` for anything rejected. The driver holds **no
|
|
lease state** — the broker owns the lease; the driver is an executor that must
|
|
never be trusted to serialise anything.
|
|
|
|
---
|
|
|
|
## 4. Wire format (broker control socket) — B, C and D do not implement this
|
|
|
|
Newline-delimited JSON over `/run/hhstream/control.sock`. Existing verbs are
|
|
unchanged. New verbs (integration implements; listed so slices know what their
|
|
code will be called with):
|
|
|
|
| Verb | Request (beyond `verb`, `request_id`) | Response |
|
|
| --- | --- | --- |
|
|
| `container.list` | — | `containers[]`, `orphans[]` |
|
|
| `container.reconcile` | `id?` | `container`, `diff` |
|
|
| `pointer.acquire` | `id`, `ttl_s?`, `restore?` | `lease_id`, `bookmark` |
|
|
| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` |
|
|
| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` |
|
|
| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` |
|
|
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` |
|
|
| `pointer.state` | — | `holder`, `since`, `lease_id` |
|
|
|
|
### Error codes (extend `ExitCode`, do not renumber)
|
|
|
|
| 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE |
|
|
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
|
|
|
|
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
|
|
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` verb do **not**
|
|
reset the idle clock.
|
|
|
|
---
|
|
|
|
## 5. Names and paths (frozen)
|
|
|
|
| Thing | Value |
|
|
| --- | --- |
|
|
| Compositor runtime dir | `/run/hypr-stream` — **must be ≤ 25 chars** (socket paths must stay under `sun_path`'s 108-byte limit) |
|
|
| Compositor request socket | `<runtime dir>/hypr/<signature>/.socket.sock` |
|
|
| Compositor event socket | `<runtime dir>/hypr/<signature>/.socket2.sock` |
|
|
| Broker control socket | `/run/hhstream/control.sock` |
|
|
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
|
|
| Broker state dir | `/var/lib/hermes/hhstream-sessions` |
|
|
| Session runtime dir | `/run/hhstream/sessions/<session-id>` |
|
|
| Container output name | `hh-<session-id>` |
|
|
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
|
|
| Container mode | `1280x720` |
|
|
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
|
|
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
|
|
| Service account | `hermes`, supplementary group `hhstream` |
|
|
|
|
---
|
|
|
|
## 6. Rules of engagement
|
|
|
|
1. **Only your files** (§2). A shared-file change you need is a report.
|
|
2. **Unit tests only.** `nix develop -c python -m pytest tests/<yours> -q`.
|
|
Nothing that builds a VM, rebuilds the system, or touches a live service.
|
|
3. **Stdlib only**, except slice D which may add `pywayland`.
|
|
4. **Machine style:** module docstrings that say *why*, not what; comments carry
|
|
reasoning; no TODO placeholders; no speculative generality.
|
|
5. **Definition of done:** a commit on your branch; your tests pass; your final
|
|
message states (a) what you built, (b) the exact test command and its result,
|
|
(c) what you could **not** verify, (d) any contract gap you hit. A slice that
|
|
"finishes" without (b) is not done.
|
|
6. **Do not open by reading the whole repo.** Your brief plus this contract is
|
|
your context. Read the two or three files you actually touch.
|
|
7. If the contract is wrong, say so and stop. If your slice turns out to need
|
|
another slice's file, say so and stop. Both are successful outcomes.
|