Commit Graph
5 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 6a40c7e2e4 docs(mcp): freeze the tool surface, and record what the in-process seam costs
`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:33:07 +00:00
Hermenix 4fefb448ac docs(todo): the capture binary needs an absolute path under a unit
Found on the deployment machine on 2026-10-11, the first time `hhstream-live`
was run **as a unit** rather than from a login shell: a systemd unit's PATH has
no system profile, so the capture command `grim` is not found, ten times, and
the stream gives up. It answers on its port, serves the landing page and
reports `"stopped": true, "failures": 10` while showing nothing -- the quiet
half of the failure is what makes it worth a file.

The module already solves this for `sessions.apps` by requiring an absolute
store path; the stream's unit has to do the same (or set PATH, which is what
made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and
named as a risk on stage 3 of the plan, which is the stage that turns this from
an experiment into the only path.
2026-10-11 02:31:52 +00:00
Hermenix cbf58f6443 docs: two TODO items closed, and the cursor question answered
Closed: containers-do-not-bind and pointer-needs-a-container-or-a-screen. Both
were the same defect seen from two sides, and both are fixed by assigning
windows by pid -- two sessions now hold two outputs with a real browser on each,
and the pointer aims at a desk that has something in it.

The cursor item is rewritten with the answer rather than the speculation: the
compositor draws no cursor image for a virtual pointer, so no capture setting
can make one appear. The evidence is in the file, including the three wrong
answers that came before it and the boring measurement that settled it.

New item: killing a session left two browsers alive, found by counting windows
rather than sessions.
2026-10-03 19:45:42 +00:00
Hermenix 336474793f docs: the pointer is unusable while containers are off
Found live while trying to demonstrate the scroll verb that was just deployed:
every cursor verb resolves its target through _pointer_output, which requires a
container output, and no session has one -- because containers are off. So the
verb exists and cannot be used, and the acceptance video's missing cursor was
never a capture artefact: nothing could have moved it.

Recorded with the routes out (aim at the shared output when a session owns no
container; or fix the binding first and leave this alone), the cost of the
quick one, and the misleading hint that blames the compositor for a switched-off
feature.
2026-10-03 19:19:24 +00:00
HermenixandClaude Opus 5 6b395305e0 scroll: one verb, two axes, and the sign carries the direction
A session could move a cursor and press it, but not scroll. The protocol
already had the request -- zwlr_virtual_pointer_v1.axis(time, axis, value) --
it had simply never been implemented, in the driver or the broker.

  hhstream session pointer scroll <id> --axis vertical --amount 3

Positive is down (vertical) or right (horizontal): the protocol's direction,
not a choice of ours, which is why direction travels in the sign and there is
deliberately no up/down vocabulary layered over it. The output is whatever the
last warp aimed at, exactly like a button, so scrolling somewhere else is a
warp first -- and the lease is what keeps the whole gesture atomic. Bounded at
100 wheel clicks per request on both sides, because a decimal-point slip should
be a refusal rather than a session scrolled somewhere unrecoverable.

The resume point is re-stamped, not moved: the cursor did not go anywhere, so
the coordinates are re-affirmed and only the stamp advances. Recorded in the
contract as an amendment to the frozen op set, because adding an op to a frozen
interface should be visible rather than implied.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-10-03 19:05:39 +00:00