From 5f5726c02efad6b1f1e1ed750d27915635e6df82 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 22:48:45 +0000 Subject: [PATCH] feat(mcp): the stream, as two tools and two resources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE --- nix/mcp.nix | 6 +- src/hhstream_mcp/resources.py | 38 ++++++++ src/hhstream_mcp/tools.py | 163 +++++++++++++++++++++++++++++++++- 3 files changed, 200 insertions(+), 7 deletions(-) diff --git a/nix/mcp.nix b/nix/mcp.nix index a876b06..fd7f6e6 100644 --- a/nix/mcp.nix +++ b/nix/mcp.nix @@ -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" diff --git a/src/hhstream_mcp/resources.py b/src/hhstream_mcp/resources.py index 43ce2f9..40a9654 100644 --- a/src/hhstream_mcp/resources.py +++ b/src/hhstream_mcp/resources.py @@ -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", diff --git a/src/hhstream_mcp/tools.py b/src/hhstream_mcp/tools.py index 1eed94c..8c83df0 100644 --- a/src/hhstream_mcp/tools.py +++ b/src/hhstream_mcp/tools.py @@ -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",