Commit Graph
4 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 a61558a0ad docs: the two counts that are prose rather than assertions
`tools.py`'s module docstring and the module's `mcp.enable` warning both state
the size of the surface in words, so neither moved when the stream added to it.
Twenty-three tools, and twenty of them plus seven of the ten resources need the
broker -- counted rather than carried over: the three that do not are `shot`,
`record` and `run`, and `hhstream://status`, `hhstream://screen` and
`hhstream://outputs/{name}` beside them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:59:45 +00:00
HermenixandClaude Opus 5 5f5726c02e feat(mcp): the stream, as two tools and two resources
The split mcp-v2 froze, applied to the stream: switching one on is an act, so
it is a tool; what is being published is state, so it is a resource. 23 tools
and 10 resources.

Tools: `session_stream_enable` (returns the URL, takes an optional `phrase` and
`fps`), `session_stream_disable`, and `session_start` gains `stream`,
`stream_phrase` and `stream_fps` -- the last because a stream needs the
container output that starting creates, so one call is the shape an agent
actually wants.

Resources: `hhstream://streams` (every stream, with `available` so "no streams"
is not confused with "no daemon") and `hhstream://sessions/{id}/stream`.

What the descriptions carry is the part that matters here, because an agent
reads them and nothing else:

* **CREDENTIAL.** The phrase in the URL is the stream's only protection. The
  resource descriptions say outright not to put the URL where a session's own
  screen can see it -- an agent that pastes it into the browser it is driving
  has published the desktop.
* **ACTIVITY.** The stream tools do *not* reset the idle clock, but a connected
  viewer does, which is the first exception to that rule this surface has had
  to state. `session_touch` is still the only thing an agent can do about it.
* `session_start`'s summary prints `stream url:` beside the id, and a stream
  that could not be opened is reported loudly as `stream: NOT enabled -- …`,
  because the call succeeded and an agent must not read that as a stream.

`nix/mcp.nix` counts the new surface in `entryPointCheckPhase` (23 and 10),
which is the only place those numbers are asserted against the *wrapped* binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:45 +00:00
HermenixandClaude Opus 5 0a63c9b7fc feat(mcp)!: state as resources, acts as tools, and --toolsets for the rest
BREAKING: `status`, `session_list`, `session_status`, `session_logs` and
`pointer_state` are no longer tools. They are `hhstream://…` resources. 26
tools became 21, and eight resources appeared beside them.

The reason is the split the protocol itself draws, which the first cut ignored.
A resource is **application**-controlled context: the host decides what to put
in front of the model, and "what is on this machine right now" is the host's
question. A tool is **model**-controlled: an act the model chooses to perform.
Nothing in those five verbs acts. So the line between the halves is *who
decides*, not what a call costs.

    hhstream://status                     text, the units and the frame socket
    hhstream://sessions          {?all}   the broker's own list object
    hhstream://pointer                    the lease holder, buttons and keys
    hhstream://containers                 every container, plus the orphans
    hhstream://screen                     a frame, as an image blob
    hhstream://sessions/{id}     {?events}
    hhstream://sessions/{id}/logs {?lines}
    hhstream://outputs/{name}             one output's frame, as a blob

What did *not* move is the interesting part. `shot` and `record` stay tools
though neither changes the desktop: capturing is an act at a moment, and an
agent in a loop has to be able to decide to look *now* -- in many clients a
resource is something a person attaches rather than something a model can
fetch. The same frames are readable as `hhstream://screen` and
`hhstream://outputs/{name}` as well, for a host that wants one in context
itself. `session_container` stays a tool for a harder reason: with an id the
CLI runs `container.reconcile`, which writes the record back, so it is not a
read at all. Only the no-id listing is a resource. **A resource read must never
write**, and `resources.py` says so where it would be tempting.

Three consequences worth naming:

* A refusal cannot be content. `ReadResourceResult` has no `isError`, so a CLI
  refusal is raised as `-32602` with the same remedy text in `message` and the
  same `{ok, exit_code, error, reason, hint, remedy}` in `data`. Returning the
  broker's failure object as the *body* would make "no such session" read as a
  successful read of a session.
* Arguments become query parameters, and only declared ones are accepted -- for
  the reason every tool schema sets `additionalProperties: false`. A parameter
  silently ignored is a read that answered a different question.
* A v1 tool name is told where it went: `session_list` comes back with "It is a
  RESOURCE now ... read hhstream://sessions instead". "No such tool" alone
  reads as a broken server rather than a moved surface.

`--toolsets frames,sessions,pointer,keyboard` lands with it, because 21 flat
tools is the same problem one size smaller. There is **no grouping primitive in
MCP** -- `Tool` carries name, title, description, inputSchema, outputSchema,
icons, annotations, _meta and execution, and nowhere to put a family -- so the
only honest lever is which tools the *server* lists, chosen at launch. An
unknown name is argparse's exit 2, never a silently empty server, and a tool
outside the selection is unreachable rather than merely unlisted. Resources are
deliberately not filtered by it: they are the host's context, not the model's
budget.

`--list-resources` joins `--list-tools`; both are in the package's own
entry-point check, with `--toolsets` beside them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:49:46 +00:00
HermenixandClaude Opus 5 ca5e309e51 feat(mcp): the hhstream CLI as Model Context Protocol tools
`hhstream_mcp` serves the whole `hhstream` surface -- the four frame verbs, the
ten session verbs, the eight pointer verbs and the four keyboard verbs -- as 26
MCP tools over stdio, so an agent drives this desktop through typed tools
instead of writing command lines.

It is a shim and nothing more. Each tool builds the argv list the CLI's own
parser takes, hands it to the CLI's own handler **in this process**, and maps
what came back. The idle clock, the pointer lease, the allowlist, the exit-code
table and every refusal message stay where they already were.

Four decisions worth stating, each argued at length where it lives:

* **One tool per verb**, not one per family with an `action` enum. The
  arguments do not rhyme, the two rules an agent gets wrong have to be on the
  tool it gets wrong, and `readOnlyHint` is a real per-verb distinction here --
  `session_container` with an id runs `container.reconcile`, so it is not
  marked read-only.
* **In process, not as a subprocess.** `hhstream.cli`'s parser already takes an
  argv list and its handlers already return a code from the frozen table. Two
  of its paths cannot be called here and both end in an `exec` that would
  replace this server: `main`'s `sg` re-exec, and `cmd_run`'s `execvpe`. The
  first is therefore unavailable and said out loud (`access_hint`); the second
  is why `run` goes through `posix_spawn` into its own session.
* **The transport leaves file descriptor 1.** The CLI prints, and `record`
  spawns an `ffmpeg` whose output it does not capture. `claim_transport` takes
  a private duplicate of stdin and stdout at start-up and points fd 1 at the
  log, so a stray write is a log line and never a corrupted JSON-RPC stream.
* **No state, and the lease is an argument.** The CLI caches a lease id between
  invocations because its surface is flagless; this passes `--lease` on every
  call and never reads that cache. A cached lease is a lease an agent cannot
  see.

Refusals come back as tool errors -- never as a success -- carrying the remedy
sentence, the CLI's own `error`/`reason`/`hint`, everything it said, and the
frozen exit code in `structuredContent`. Exits 8 and 9 are held apart by a
test, because an agent that sees 8 must wait and one that sees 9 must acquire.

The root pyproject excludes `hhstream_mcp*` from package discovery: without
that, `packages.hhstream` would ship a module whose first import line fails.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:32:23 +00:00