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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 22:48:45 +00:00
1 parent ca5dbfb2ea
commit 5f5726c02e
3 files changed
+200 -7

No files matched your search

+3 -3
View File
@@ -14,7 +14,7 @@
# `buildPythonApplication` output is not.
#
# `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them --
# `shot --output` and `record` are two of the twenty-one tools, and the server
# `shot --output` and `record` are two of the twenty-three tools, and the server
# is launched by an MCP client whose PATH is not ours to predict. `--prefix`
# and not `--set`, so a deployment that wants its own ahead of these puts them
# on PATH and wins.
@@ -89,11 +89,11 @@ python3.pkgs.buildPythonApplication {
echo "checking the wrapped entry point..."
tools=$($out/bin/hhstream-mcp --list-tools)
echo "$tools"
test "$(echo "$tools" | wc -l)" -eq 21
test "$(echo "$tools" | wc -l)" -eq 23
resources=$($out/bin/hhstream-mcp --list-resources)
echo "$resources"
test "$(echo "$resources" | wc -l)" -eq 8
test "$(echo "$resources" | wc -l)" -eq 10
narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l)
echo "--toolsets keyboard offers $narrowed tools"
+38
View File
@@ -359,6 +359,24 @@ ENTRIES: tuple[Entry, ...] = (
media_type=JSON,
read=_json_read(["session", "container"], "the container list"),
),
Entry(
route=("streams",),
name="streams",
title="What is being published, and who is watching",
description=(
"Every session a live stream was enabled on, with its output, "
"rate, URL and connected viewer count -- and `available`, which "
"says whether the stream daemon could be asked at all, so 'no "
"streams' is distinguishable from 'no daemon'.\n\n"
"THE URLS HERE CONTAIN THEIR PHRASES, which are the only thing "
"protecting those streams. Do not put this where a session's own "
"screen can see it." + _NOT_ACTIVITY + " A connected viewer, "
"however, does: that is the one exception, and it is why a "
"session somebody is watching is not reaped."
),
media_type=JSON,
read=_json_read(["session", "stream", "list"], "the stream list"),
),
Entry(
route=("screen",),
name="screen",
@@ -405,6 +423,26 @@ ENTRIES: tuple[Entry, ...] = (
read=_json_read(["session", "logs"], "that session's logs"),
parameters=("lines",),
),
Entry(
route=("sessions", "{id}", "stream"),
name="session-stream",
title="One session's live stream",
description=(
"Whether this session is being published, and if so the URL to "
"watch it at, the output it shows, its frame rate and how many "
"people are connected right now. `null` when no stream was "
"enabled.\n\n"
"`attached` is separate from `enabled` on purpose: a record can "
"say the operator asked for a stream while the daemon is down, "
"and those are two different facts. The URL is absent rather than "
"stale when `attached` is false.\n\n"
"THE URL CONTAINS THE PHRASE that protects it. Switch a stream on "
"with the `session_stream_enable` tool -- reading this never "
"enables one." + _NOT_ACTIVITY
),
media_type=JSON,
read=_json_read(["session", "stream", "status"], "that session's stream"),
),
Entry(
route=("outputs", "{name}"),
name="output",
+159 -4
View File
@@ -104,6 +104,19 @@ HOLD_NOTE = (
"`keyboard_up Control_L`."
)
STREAM_NOTE = (
"CREDENTIAL: the phrase in the stream's URL is its only protection -- no "
"TLS, no second factor. Anyone who can reach the port and guess four "
"words can watch this session's screen. Treat the URL as a password: do "
"not put it anywhere the session's own output goes. It is never written "
"to the broker's audit log.\n\n"
"ACTIVITY: the stream tools do NOT reset the idle clock -- but A "
"CONNECTED VIEWER DOES. About once a minute the broker stamps `touch` on "
"any session somebody is watching, which is the one exception to "
"`session_touch` being the only mark of activity. An enabled stream with "
"nobody watching captures nothing and keeps nothing alive."
)
COORDINATES_NOTE = (
"Coordinates are OUTPUT-NORMALISED 0..1 inside the session's own "
"container: (0,0) is its top-left corner and (1,1) its bottom-right. They "
@@ -516,15 +529,58 @@ def _acquire_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
)
def _start_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
session_id = (payload or {}).get("id") or "(not reported)"
def _stream_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
"""The URL on the first line: it is the whole point of the call."""
stream = (payload or {}).get("stream") or {}
url = stream.get("url")
if not url:
return (
"the broker recorded this stream but the daemon did not confirm "
"it is attached, so there is no URL to hand out yet; read "
"`hhstream://streams` and retry if it stays that way."
f"\n\n{outcome.stdout.strip()}"
)
return (
f"session id: {session_id}\n"
f"Keep it alive with `session_touch` before its idle timeout expires.\n\n"
f"{url}\n"
"Hand that URL to whoever is watching. Its phrase is the only thing "
"protecting it, so do not put it anywhere this session's own screen "
"can see. Somebody watching counts as activity; `session_stream_"
"disable` stops it.\n\n"
f"{outcome.stdout.strip()}"
)
def _start_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
"""The id first, and the stream's URL beside it when one was asked for.
Both on the first lines, because both are what the next step needs: the id
to drive the session, the URL to hand to a person.
"""
session = payload or {}
session_id = session.get("id") or "(not reported)"
lines = [f"session id: {session_id}"]
stream = session.get("stream") or {}
if stream.get("url"):
lines.append(f"stream url: {stream['url']}")
lines.append(
"That URL's phrase is its only protection -- treat it as a "
"password. Somebody watching it counts as activity."
)
elif session.get("stream_error"):
# Loudly, because the call succeeded: a caller that asked for a stream
# must not read a session id as one.
lines.append(
f"stream: NOT enabled -- {session['stream_error']}. The session is "
"running; retry with `session_stream_enable`."
)
lines.append(
"Keep it alive with `session_touch` before its idle timeout expires."
)
return "\n".join(lines) + f"\n\n{outcome.stdout.strip()}"
def build() -> tuple[Tool, ...]:
"""The whole surface. A function, so the table is built once per process."""
@@ -712,6 +768,33 @@ def _session_tools() -> list[Tool]:
"the session ends. Mutually exclusive with `home`."
),
},
"stream": {
"type": "boolean",
"description": (
"also enable a live stream for this session, and "
"return its URL in the reply's `stream.url`. One "
"call rather than start-then-enable, because a "
"stream needs the container output that starting "
"creates. A stream that cannot be opened does NOT "
"fail the start -- the application is on the "
"screen, and `stream_error` says what went wrong."
),
},
"stream_phrase": {
"type": "string",
"description": (
"use this phrase instead of a minted one: four "
"words of at least three letters and a "
"five-character tail, e.g. "
"`amber-otter-lantern-harbor-7k2qp`. Held to "
"exactly that shape, because it is a password."
),
},
"stream_fps": {
"type": "integer",
"minimum": 1,
"description": "frames per second for the stream (default: the broker's)",
},
"request_id": REQUEST_ID,
},
["app"],
@@ -728,6 +811,9 @@ def _session_tools() -> list[Tool]:
*_optional(a, "wait_ready", "wait-ready"),
*_optional(a, "home"),
*_switch(a, "ephemeral_home", "ephemeral-home"),
*_switch(a, "stream"),
*_optional(a, "stream_phrase", "stream-phrase"),
*_optional(a, "stream_fps", "stream-fps"),
*_optional(a, "request_id", "request-id"),
],
positionals=lambda a: [a["app"], *[str(x) for x in a.get("argv") or []]],
@@ -872,6 +958,73 @@ def _session_tools() -> list[Tool]:
positionals=lambda a: [a["id"]] if a.get("id") else [],
),
),
Tool(
name="session_stream_enable",
title="Publish a session's screen",
description=(
"Switch on a live view of this session's screen, in a browser, "
"at a URL whose path is a spoken phrase -- and return that "
"URL. This is how a person watches what an agent is doing.\n\n"
"It publishes the session's own container output, never the "
"main one: that output carries every other session, and "
"putting it behind one session's phrase is the mistake this "
"refuses to make (exit 10 with no container).\n\n"
"Re-enabling an already-enabled session returns the same URL. "
"A `phrase` that differs from the stored one is exit 8 rather "
"than a silent rotation, because rotating under somebody who "
"is holding the old URL is the one outcome neither answer can "
"be mistaken for. Disable then enable to rotate it.\n\n"
"Capture runs only while somebody is connected, so an enabled "
"stream nobody is watching costs nothing.\n\n"
f"{STREAM_NOTE}"
),
schema=obj(
{
"id": SESSION_ID,
"phrase": {
"type": "string",
"description": (
"use this phrase instead of a minted one: four "
"words of at least three letters and a "
"five-character tail. Held to exactly that shape, "
"because it is this stream's only credential."
),
},
"fps": {
"type": "integer",
"minimum": 1,
"description": "frames per second (default: the broker's; the daemon caps it)",
},
},
["id"],
),
invoke=json_verb(
["session", "stream", "enable"],
options=lambda a: [*_optional(a, "phrase"), *_optional(a, "fps")],
positionals=lambda a: [a["id"]],
summary=_stream_summary,
),
),
Tool(
name="session_stream_disable",
title="Stop publishing a session's screen",
description=(
"Close the capture, drop the route, and forget the phrase. "
"Anyone holding the old URL loses it, which is the point: "
"this is also how a phrase is rotated, since the next enable "
"mints a new one.\n\n"
"Disabling a stream the daemon has already forgotten is not an "
"error -- that is the ordinary case after the daemon restarts, "
"and the record is cleared either way. `detached` says which "
"happened.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({"id": SESSION_ID}, ["id"]),
invoke=json_verb(
["session", "stream", "disable"], positionals=lambda a: [a["id"]]
),
destructive=True,
),
]
@@ -1214,6 +1367,8 @@ TOOLSETS: dict[str, tuple[str, ...]] = {
"session_adopt",
"session_container",
"session_reconcile",
"session_stream_enable",
"session_stream_disable",
),
"pointer": (
"pointer_acquire",