Commit Graph
10 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 10176356b6 docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 18:00:05 +00:00
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 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 4b5cb5197a docs+examples: log the cursor marker as open, and film each desk on its own
The marker is now written up as the *open* item rather than a research note: it
is not implemented, the video went out without it, and everything else about the
pointer is exact and readable.

proof-video.py is rewritten for desks, one command, no arguments. It films the
session's own output with `record --output` instead of the published socket --
with desks, the socket carries every output stitched together, so a viewer would
watch two thirds wallpaper. The scrolling beats are real pointer axis events,
down twice and back up once, so the movement cannot be mistaken for a page that
merely loaded a different part of itself.
2026-10-03 19:54:08 +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
Hermenix 7e0544ed70 docs: point the known-gaps list at the TODO folder, and un-stale its first item
Item 1 said the broker reads none of the container or pointer configuration.
That was true and is not: the settings are parsed beside Policy and a switched-off
container host reports itself unavailable with the key named. The item now
records what actually matters about it -- that containers are off on the
deployment machine because no window can be put in one -- and the section links
docs/TODO/, where each open problem has its impact written down.

The TODO folder itself landed in the previous commit by accident (a `git add -A
docs` swept it in with the scroll work); this commit only makes it findable.
2026-10-03 19:06:17 +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