Commit Graph
7 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 549c73e8ae feat(nix): hhstream-mcp as its own derivation, and an option to install it
`packages.hhstream-mcp` (`nix/mcp.nix`), separate from `packages.hhstream` and
the separation is the point: the frame socket, the CLI and the broker are
stdlib-only by policy, the MCP SDK is a third-party dependency, and
`packages.hhstream` runs as the compositor's own units. Verified: the hhstream
closure gains no `mcp`, no `pydantic` and no `httpx`, and `hhstream_mcp` is not
in its site-packages.

The join to `hhstream` is a *library* one -- `toPythonModule`, because the
tools call `hhstream.cli`'s handlers in process. `grim` and `ffmpeg` are
prefixed onto the wrapper's PATH, because the CLI spawns them and the server is
launched by an MCP client whose PATH is not ours to predict.

The entry point is smoke-tested with `--list-tools` in a `postPhases` phase,
not `postInstall`: the script is wrapped in `fixupPhase`, so any earlier and
the check runs against a script with no PYTHONPATH and tests the wrong thing.
(`installCheckPhase` is no use either -- `buildPythonPackage` does not include
that phase at all.)

`services.hyprland-headless-stream.mcp.enable` (default false) puts the binary
on the system PATH, which is the whole of the option: the server is stdio and
spawned per client, so there is no unit, no socket and no state directory.
`mcp.package` defaults to this flake's build against `cfg.package`, so the
server and the CLI it runs are one build. A warning, not an assertion, when it
is enabled with `sessions.enable` off: 22 of the 26 tools then answer exit 5,
but the four frame tools are genuinely useful alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:32:34 +00:00
HermenixandClaude Opus 5 f931858f30 Stage 1: the driver learns to type
`zwp_virtual_keyboard_v1`, spoken by the process that already speaks
`zwlr_virtual_pointer_v1`. One device for the seat, one keymap uploaded
once, keysym names on our socket and evdev codes only on the Wayland
request -- the division buttons.py already draws.

keymap.py is the new seam, and it holds the three decisions that have a
wrong version which looks right:

  * A capital is the MASK, not a synthetic Shift keycode. Hyprland's
    virtual keyboard never runs updateXkbStateWithKey, so a virtual
    KEY_LEFTSHIFT changes no modifier state at all -- and sending both
    is how a toolkit applies Shift twice.
  * A modifier is whatever the keymap says is one, measured by pressing
    each key in a throwaway xkb state. Not a name list: `@` on `de` is a
    level-three symbol, and a Shift-only special case types the wrong
    character. (The measured set is also smaller than the canonical one,
    because no keycode on us/pc105 carries Meta or Hyper.)
  * A lock is not a modifier. Caps_Lock reports a *locked* mask, so
    `type` refuses while it is held rather than guessing the case.

The whole string resolves before anything is emitted, and every refusal
names the scalar INDEX, never the character: these messages reach the
driver's log and the string is a password as often as not.

Folding in the review's changes 1, 2, 3 and 6:

  1 a Rejected now carries a `kind`. A bad keysym or an unmappable
    character is `invalid_argument`; a missing keyboard global is
    `refused`. Without the token the broker would have to tell exit 2
    from exit 10 by reading English, and _drive maps every `ok: false`
    to driver_refused today.
  2 the keymap `size` on the wire includes the trailing NUL, and the fd
    outlives a roundtrip rather than a flush. Hyprland mmaps exactly
    that many bytes and hands the pointer to xkb_keymap_new_from_string.
  3 release_all lifts buttons, then keys in press order, then zeroes the
    mask -- and the mask only if something set it, so a compositor with
    no keyboard global still gets its buttons lifted. One release_all is
    the whole of expiry; an exception in the key half would abandon it.
  6 `key` and `type` never call _aimed(). A keyboard has no output, and
    one test deliberately never warps so that stays true.

Also: `--xkb-layout/-model/-variant/-options`, compiled BEFORE any
Wayland call so a bad layout is exit 2 rather than exit 10; a comma in
the layout refused outright, because v1 always sends group 0 and
xkbcommon would hand back a second group nothing could reach; the
keymap uploaded after connect and before listen, with one
modifiers(0,0,0,0) after it; and xkbcommon as a hard, non-optional
dependency -- an optional one would let test_keymap.py skip, and the
unmappable-character path is the one that must not rot.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  549 passed in 25.70s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:39:00 +00:00
Hermenix 1ce39ba210 examples: agent-eyes-demo.py -- drive a browser on the headless screen and film it 2026-09-30 18:47:24 +00:00
Hermenix a77eaa96d3 devShell: add chromium and the hhstream client for the eyes demo 2026-09-30 18:44:58 +00:00
HermenixandClaude Opus 5 75a05cd72f tests: checks.{unit,vm-basic,vm-hyprland} + the harness behind them
Wires a `checks` output into the flake, one file per check under checks/,
all three asserting docs/CONTRACT.md rather than the implementation:

- unit: pytest over tests/unit/ in the build sandbox, against the
  nix/package.nix build. Refuses an empty suite -- pytest exits 0 when
  every test was skipped or deselected, so checks/lib/check_report.py
  parses the JUnit report and fails on zero collected or zero executed.
- vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py,
  which emits one fixed deterministic PNG. Because the image never changes,
  "two frames arrived and they are the same bytes" is an assertion about
  the framing rather than a coincidence.
- vm-hyprland: the same machine with no captureCommand override, so grim
  captures the real compositor. Deliberately impatient -- bounded timeouts,
  no retry loops, and a full diagnostics dump (compositor log, hyprctl
  monitors, both journals) before any failure propagates.

tests/assert_stream.py is a second, independent reader of the contract: it
shares no code with hhstream.client, so a framing bug present in both the
server's writer and the shipped client's reader still fails. The unit
suite's negative tests use a `rejects` fixture instead of
pytest.raises(Exception), which an unimplemented stub's
NotImplementedError would otherwise satisfy.

Three defects found in code this branch does not own, recorded in
README.dev.md rather than worked around:
- nix/module.nix has no config side, so neither unit exists and both VM
  checks fail at their first wait;
- services.hyprland-headless-stream.package is declared with no default,
  against docs/CONTRACT.md;
- src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz
2026-09-28 05:25:37 +00:00
Hermenix c0a59f5673 flake: devShell with python/pytest/tmux/hyprland/grim 2026-09-28 05:04:06 +00:00
Hermenix 8993f026d3 buzz: initial mirror 2026-09-28 05:01:41 +00:00