Commit Graph
7 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 887ed17be2 docs(stream): mcp-v3, the seventh box, and two TODOs the check wrote
`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two
resources, three `session_start` arguments, and the one rule that is not a name
at all -- a connected viewer is the single exception to the idle-clock rule, and
it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is
additive; every v2 name still means what it meant.

README.md leads the stream with the shape of it rather than the options: one
port for the machine, a phrase per session, a browser `<img>` as the entire
client, and the four things worth knowing before switching one on -- that it is
per session and off by default, that the phrase survives a restart, that capture
runs only while somebody is connected, and that watching counts as activity.
The phrase is called what it is: the only protection, with no TLS and no second
factor.

ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`,
hanging off the broker by `live.sock` with one port and a browser at the end of
it -- and the counts move to 23 and 10.

Two TODOs, both written by `checks/vm-stream.nix`:

* `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a
  stream after ten consecutive capture failures and the stop is sticky on
  purpose, but `Control._describe` does not pass `stopped` on, so
  `_stream_public` reports `attached: true` for a capture that has permanently
  given up. That is the second place `attached` answers "is a capture running
  right now" wrongly, and a field that is right only when nothing is wrong is
  not worth reading.
* `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The
  module passes grim's store path and this check reads real frames -- which
  immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`.
  What is still open is the other half: the app resolves its capture command by
  name and never checks it, so any deployment that is not this module still
  discovers a broken capture ten failures later.

The plan's status section records Stage 2 and Stage 3 as built, the two
decisions §5 left open (that `start` takes `--stream`, and that the default rate
is the daemon's), and what Stage 2 deliberately did not do -- §6's restart
re-attachment, which has its own TODO.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:54:26 +00:00
HermenixandClaude Opus 5 e636472106 docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it
`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because
v1 lasted a day and an agent that learned it deserves to be told what moved
rather than to discover it. The new §4 freezes the resource surface: the eight
URIs, their bodies, their query parameters, and the five rules the layer keeps
(a read never writes; only declared parameters; a literal route beats a
template; a frame's media type comes from its bytes; no subscriptions). §6
gains the other half of the error mapping -- for a resource read every exit
code arrives as `-32602` with the remedy in `message` and the structured object
in `data`, because `ReadResourceResult` has no `isError` to use instead.

§2 records what `--toolsets` is and is not: there is no grouping primitive in
MCP, the `Tool` object has nowhere to put a family, and tools are a flat list
in the specification too -- so the only lever is which tools the server lists,
decided by whoever spawns it.

README.md leads with the split rather than with a tool count, since that is the
thing a reader has to understand before any of the names make sense, and shows
the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth
box grows its second half and says why `shot` is on both sides.

A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit
that cost the most: `Server.get_capabilities` hardcodes
`ResourcesCapability(subscribe=False, …)`, so registering a
`subscribe_resource` handler changes nothing and a client is correctly told not
to try. Subscriptions would have been the principled answer to the missing
`logs --follow` -- it is the one place this design wanted a capability the SDK
will not advertise -- so the file names the one-line local override, says what
it risks, and recommends upstreaming the real fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:50:12 +00:00
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 e8b3855a05 move every live default to /run/hypr-stream, and resolve the slices' contract gaps
Slice A renamed the runtime directory in the module, but the old path was still
live in the code and checks it does not own, so the VM gates pointed at a
directory the module no longer creates. This moves the 21 remaining live
occurrences (client/server defaults, the unit tests that pin them, all three VM
checks, the diagnostics script, both READMEs) and deliberately leaves the three
mentions that are history rather than configuration: the plan's problem
statement, module.nix's note about the previous name, and cli.py's explanation
for spelling its default out.

Also here: docs/CONTRACT-sessions.md is now v2 with every gap the four slices
reported resolved as a decision (Monitor.id, stable_id, pid -1, Event.data,
mark(), the quarantine argv type, the corrected wlr XML path, and the state
dir/frame socket rows), and docs/CONTRACT.md is v2 because its documented socket
default moved -- wire format unchanged.

Two comments that stated the old, wrong diagnosis (a 'misnamed' IPC socket) now
state the measured one: the event socket did not fit in sun_path.
2026-10-02 18:11:46 +00:00
Hermenix bfb333e9ff examples: document the demo; strip ffmpeg metadata so Blossom accepts the mp4 2026-09-30 19:15:33 +00:00
HermenixandClaude Opus 5 6510e315d4 module: make outputs monitor rules for real connectors, and own the seat flag
A machine running this module has a GPU. aquamarine's headless backend has
no allocator of its own -- `CHeadlessBackend::drmFD()` returns -1 and
`CBackend::start()` takes the allocator from the first backend with a drm fd
-- so the session always rides on the DRM backend and always has the host's
own connectors. `HEADLESS-1` is a name no connector will ever have, which
made the shipped default a monitor rule Hyprland silently ignored, and made
`vm-hyprland`'s assertion on that name unsatisfiable.

`outputs` now means "monitor rules applied to whatever outputs the machine
has". `name` is a regex against the real connector names and defaults to the
empty string -- Hyprland's own wildcard form, as in its shipped
`monitor=,preferred,auto,1` -- so `enable = true` alone gives a session at a
known size on any host. Nothing else about the option changed.

SEATD_VTBOUND=0 moves from checks/lib/gpu-session.nix into the compositor
unit, where it belongs: libseat finds no seatd socket and no logind session
for a system service, falls back to its embedded seatd, and that seat is
VT-bound by default -- so it opens /dev/tty0, which the service user cannot,
and every device open is refused. That is true on any host, not just in the
test. gpu-session.nix keeps only the two things that really are the test
machine's business: a render node and Mesa.

vm-hyprland now asserts over `hyprctl -j monitors` that at least one monitor
exists at the configured mode, with no monitor name anywhere in the check.
It also gains a wallpaper, because `--reject-blank` could not otherwise mean
anything: the session the module configures by default is a flat black
field, which grim captures as an all-zero 1280x720 RGBA PNG of exactly 3653
bytes -- `blank_png_size()` to the byte. Runs that passed that assertion were
reading Hyprland's startup notification overlay, which expires after about
fifteen seconds. With `misc:force_default_wallpaper` on, the frame is 85267
bytes with all 921600 pixels non-zero and is byte-identical at +15s, +30s and
+60s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r
2026-09-28 21:51:24 +00:00
Hermenix 8993f026d3 buzz: initial mirror 2026-09-28 05:01:41 +00:00