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:
1 parent
ca5dbfb2ea
commit
5f5726c02e
3 files changed
+200
-7
No files matched your search
+3
-3
@@ -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"
|
||||
|
||||
@@ -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
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user