Files
hyprland-headless-stream-pl…/src/hhstream_mcp/tools.py
T
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

1427 lines
60 KiB
Python

"""The tool table: one tool per CLI verb that *acts*. Standard library only.
**What is here and what is not.** A tool is model-controlled: an act the model
chooses to perform. The verbs that only read state are not tools -- they are
resources, addressed by URI in :mod:`hhstream_mcp.resources`, because that is
application-controlled context and "what is on this machine right now" is the
host's business. So ``session_kill`` is here and ``hhstream://sessions`` is
there, and the line between them is *who decides* rather than what it costs.
``shot`` and ``record`` stay tools even 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*. The same frames are also readable as ``hhstream://screen`` and
``hhstream://outputs/{name}`` for a host that wants to put 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.
**Granularity, and why.** One tool per verb rather than one tool per family
with an ``action`` enum. Three reasons, in order of weight:
1. The arguments do not rhyme. ``shot`` takes an output name, ``keyboard_type``
takes a string, ``pointer_move`` takes a coordinate pair that is exclusive
with a delta pair. Folded into one schema those become a union of optional
fields that is valid for every combination and correct for almost none, and
the refusal moves from the schema (before anything runs) to the broker
(after a round trip).
2. The two rules an agent gets wrong have to be *on the tool it gets wrong*.
A client shows a tool's own description at the point of use; a family-level
note about the idle clock is not what is read when ``session_touch`` is the
thing being forgotten.
3. ``readOnlyHint`` is per tool and is still a real distinction among what is
left: ``shot`` reads, ``session_kill`` destroys, ``record`` writes a file.
The cost is twenty-three tools in one listing, and :data:`TOOLSETS` is the lever
for a client that cannot afford them all. It is paid back by the names being
the CLI's own: an agent that has read ``hhstream session --help``, or this
repository's README, already knows what ``session_touch`` is, and a transcript
of tool calls can be re-run by hand as a shell session.
**Nothing here decides anything.** Every function below builds an argv list and
hands back what the CLI said; :mod:`hhstream_mcp.invoke` is what runs it. The
one place this layer adds words of its own is the remedy sentence per exit code
(also in that module) and the notes below, which are the CLI's own epilogues
restated in terms of tools rather than command lines.
"""
from __future__ import annotations
import dataclasses
import os
import pathlib
import tempfile
from typing import Any, Callable
# The button and axis vocabularies, from the CLI that owns them. Imported and
# not retyped: `hhstream_session` mirrors the driver's lists with a comment
# saying the driver stays the authority, and a third copy here would be a third
# thing to update when the driver learns a button.
from hhstream_session import AXES, BUTTONS
from . import media
from .invoke import GENERIC_FAILURE, Outcome, Runner, remedy_for, temp_name
# ── the two rules, in an agent's words ─────────────────────────────────────
#
# These are `hhstream_session.ACTIVITY_NOTE` and `KEYBOARD_LEASE_NOTE` said in
# terms of tools instead of command lines. Not imported, because the point of
# both notes is to tell the reader what to *call next*, and "run 'hhstream
# session touch <id>'" is not something an MCP client can do. The CLI's
# constants remain the source of the rule; `tests/unit/test_mcp_tools.py` holds
# these against them so a rule that changes there cannot silently stay here.
ACTIVITY_NOTE = (
"ACTIVITY: `session_touch` is the ONLY thing that resets a session's idle "
"clock. Reading `hhstream://sessions`, `hhstream://sessions/<id>` or its "
"logs does NOT count; neither does `session_gc`, and neither does any "
"pointer or keyboard tool -- if polling kept a session alive, an abandoned "
"session would never be reaped. A session being watched or driven is still "
"a session nobody has said they want kept. If you leave an application "
"running, call `session_touch` before its idle timeout expires or the "
"broker will reap it."
)
LEASE_NOTE = (
"LEASE: this tool needs the POINTER lease and fails with exit 9 (NO_LEASE) "
"until you have called `pointer_acquire` for this session; pass the "
"`lease_id` it returned as `lease`. There is no keyboard lease of its own: "
"the compositor has one seat and one keyboard focus, so a second lease "
"would let another session's pointer warp retarget your keys mid-string. "
"The lease holds only while it holds -- the broker force-releases an idle "
"one on its TTL (30 s by default), and every pointer and keyboard call "
"refreshes that deadline. `pointer_release`, and a timeout, lift held keys "
"as well as held buttons."
)
HOLD_NOTE = (
"HOLDING A NON-MODIFIER FLOODS THE WINDOW. The compositor sends one key "
"event and publishes a repeat rate; the APPLICATION does the repeating, so "
"a held `a` inserts characters until the matching `keyboard_up` or until "
"the lease TTL expires -- measured on this build at 25 a second after "
"600 ms. This server cannot rate-limit it, because it does not generate "
"the repeats. The only safe thing to hold is a modifier, which is what "
"chords are for: `keyboard_down Control_L`, `keyboard_type c`, "
"`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 "
"are not pixels, and not pixels of the image `shot` returned."
)
# ── what a tool hands back ─────────────────────────────────────────────────
@dataclasses.dataclass(frozen=True)
class Result:
"""A tool's outcome, in terms that do not mention MCP.
``server.py`` turns this into content blocks. Keeping the two apart is what
lets the whole table be tested without the SDK installed.
"""
text: str
data: dict[str, Any] | None = None
image: bytes | None = None
media_type: str | None = None
is_error: bool = False
Invoke = Callable[[Runner, dict[str, Any]], Result]
@dataclasses.dataclass(frozen=True)
class Tool:
name: str
title: str
description: str
schema: dict[str, Any]
invoke: Invoke
read_only: bool = False
destructive: bool = False
# ── argv construction ──────────────────────────────────────────────────────
def flag(name: str, value: Any) -> str:
"""``--name=value`` as one token.
The ``=`` form everywhere, not only where it is needed. ``--by -0.1,0.5``
and ``--amount -3`` are values that begin with a dash, which argparse reads
as option strings unless they are a bare negative number; ``--by=-0.1,0.5``
is unambiguous for every value, including the ones an agent sends that
nobody predicted. One rule is also one fewer thing to get wrong per flag.
"""
return f"--{name}={value}"
def argv(verb: list[str], options: list[str], positionals: list[str]) -> list[str]:
"""``verb options -- positionals``.
The literal ``--`` goes in whenever there is a positional, for the same
reason the ``=`` form does: ``keyboard_type`` with a string that starts with
a dash is a reasonable thing to ask for, and without the separator argparse
rejects it before the broker ever sees it.
"""
built = [*verb, *options]
if positionals:
built.append("--")
built.extend(positionals)
return built
def point(pair: Any) -> str:
"""``[x, y]`` as the CLI's ``X,Y``.
``repr`` of a float rather than a format with a width: ``{:g}`` rounds to
six significant digits, and a caller that computed a coordinate deserves to
have the broker refuse or accept the number it actually sent.
"""
x, y = pair
return f"{float(x)!r},{float(y)!r}"
def number(value: Any) -> str:
return repr(float(value))
def _optional(args: dict[str, Any], name: str, as_flag: str | None = None) -> list[str]:
"""The flag for ``name`` if the caller gave one, else nothing.
Omission matters: a flag left off is the CLI's (or the broker's) own
default, and this server must not have an opinion about what that is.
"""
if name not in args or args[name] is None:
return []
return [flag(as_flag or name.replace("_", "-"), args[name])]
def _switch(args: dict[str, Any], name: str, as_flag: str | None = None) -> list[str]:
return [f"--{as_flag or name.replace('_', '-')}"] if args.get(name) else []
# ── result mapping ─────────────────────────────────────────────────────────
Summary = Callable[[Outcome, dict[str, Any] | None], str]
def report(outcome: Outcome, *, summary: Summary | None = None) -> Result:
"""One ``Outcome`` as a ``Result``. A refusal is never a success.
The successful text is the CLI's own stdout, which for every ``--json``
verb *is* the protocol object: passing it through unchanged is the whole
point of a shim, and an agent that wants a field reads the field. A few
tools prepend one line (the lease id, the new session id) because that line
is what the next call needs.
"""
payload = outcome.payload()
if outcome.ok:
text = summary(outcome, payload) if summary else outcome.stdout.strip()
return Result(text=text or "(the command succeeded and printed nothing)", data=payload)
return Result(text=failure_text(outcome, payload), data=failure_data(outcome, payload), is_error=True)
def failure_text(outcome: Outcome, payload: dict[str, Any] | None) -> str:
"""A refusal, in the order an agent needs it: what to do, then what was said."""
lines = [remedy_for(outcome.returncode), ""]
if payload:
for key in ("error", "reason", "hint"):
value = payload.get(key)
if value:
lines.append(f"{key}: {value}")
said = (outcome.stderr or outcome.stdout).strip()
if said:
lines += ["", "hhstream said:", said]
return "\n".join(lines)
def failure_data(outcome: Outcome, payload: dict[str, Any] | None) -> dict[str, Any]:
data: dict[str, Any] = dict(payload or {})
data["ok"] = False
data["exit_code"] = outcome.returncode
data["remedy"] = remedy_for(outcome.returncode)
return data
def json_verb(
verb: list[str],
*,
options: Callable[[dict[str, Any]], list[str]] = lambda args: [],
positionals: Callable[[dict[str, Any]], list[str]] = lambda args: [],
summary: Summary | None = None,
) -> Invoke:
"""The common case: a ``session`` verb run with ``--json``.
``--json`` on every one of them deliberately. The human rendering is a
table for a terminal; the protocol object is what the broker actually said,
including the machine-readable ``error`` name on a refusal, and scraping a
table for it would be inventing a second wire format.
"""
def run(runner: Runner, args: dict[str, Any]) -> Result:
built = argv(verb, ["--json", *options(args)], positionals(args))
return report(runner.run(built), summary=summary)
return run
# ── schema fragments ───────────────────────────────────────────────────────
SESSION_ID = {
"type": "string",
"description": (
"the session id, as `session_start` printed it or "
"`hhstream://sessions` reports it"
),
}
LEASE = {
"type": "string",
"description": (
"the `lease_id` that `pointer_acquire` returned for this session. "
"Required: this server holds no lease state, deliberately, so that "
"which lease a call used is visible in the call."
),
}
DURATION = {
"type": "string",
"description": "a duration: `30s`, `5m`, `3h`, `2d`, or a bare number of seconds",
}
REQUEST_ID = {
"type": "string",
"description": (
"deduplication token. Retrying a mutation with the same token returns "
"the original reply instead of doing it twice -- which is what makes a "
"timed-out call safe to retry."
),
}
BUTTON = {
"type": "string",
"enum": list(BUTTONS),
"description": "mouse button name (default: left)",
}
def obj(properties: dict[str, Any], required: list[str] | None = None, **extra: Any) -> dict[str, Any]:
"""An object schema that refuses what it does not know.
``additionalProperties: false`` so a flag this server does not pass through
is refused by the schema rather than silently dropped on the way to an argv
list -- a dropped argument is a tool that reports success for something it
did not do.
"""
schema: dict[str, Any] = {
"type": "object",
"properties": properties,
"additionalProperties": False,
}
if required:
schema["required"] = required
schema.update(extra)
return schema
# ── frames ─────────────────────────────────────────────────────────────────
def capture(runner: Runner, output: str | None) -> tuple[Outcome, bytes | None]:
"""One frame, as the CLI's outcome and the bytes it wrote.
Captured to a temporary file and read back, because that is the CLI's only
output shape -- `shot` writes a file and prints its path -- and because a
pipe would mean asking the CLI for something it does not offer. The
directory goes away with the call; the bytes are the return value.
Shared with :mod:`hhstream_mcp.resources`, which serves the same frames by
URI: one capture path, so a fix to it cannot reach one caller and miss the
other. ``None`` for the bytes means the CLI claimed success and left no
readable file, which is its own kind of failure and is reported as one.
"""
with tempfile.TemporaryDirectory(prefix="hhstream-mcp-shot-") as scratch:
destination = os.path.join(scratch, "frame.png")
options = [flag("out", destination)]
if output:
options.append(flag("output", output))
outcome = runner.run(argv(["shot"], options, []))
if not outcome.ok:
return outcome, None
try:
return outcome, pathlib.Path(destination).read_bytes()
except OSError:
return outcome, None
def _shot(runner: Runner, args: dict[str, Any]) -> Result:
"""One frame, as MCP image content."""
outcome, frame = capture(runner, args.get("output"))
if not outcome.ok:
return report(outcome)
if frame is None:
return Result(
text=(
"hhstream shot reported success but wrote no readable file.\n\n"
f"hhstream said:\n{outcome.stdout.strip()}"
),
data={"ok": False, "exit_code": 0, "error": "no_artifact"},
is_error=True,
)
image = media.sniff(frame)
where = args.get("output")
scope = f"output {where!r}" if where else "the published main output"
if image is None:
# Handed back anyway, with the truth about it: the bytes are what the
# compositor produced, and a client that can decode them should get the
# chance. Guessing a media type would be worse than saying so.
return Result(
text=(
f"{len(frame)} bytes from {scope}, in a format this server does "
"not recognise (not PNG, not JPEG), so no geometry and no media "
"type can be reported. The capture backend may be misconfigured."
),
data={"ok": True, "bytes": len(frame), "output": where},
is_error=False,
)
return Result(
text=(
f"{image.width}x{image.height} {image.media_type}, {image.size} bytes, "
f"from {scope}. {COORDINATES_NOTE}"
),
data={
"ok": True,
"width": image.width,
"height": image.height,
"media_type": image.media_type,
"bytes": image.size,
"output": where,
},
image=frame,
media_type=image.media_type,
)
def _record(runner: Runner, args: dict[str, Any]) -> Result:
"""Film the screen and hand back the *path*.
Not the bytes. An mp4 of a 720p desktop is megabytes, and a tool reply is
a message in a model's context -- so the artefact stays on disk and the
reply names it, which is also what makes it watchable by a human.
"""
destination = args.get("out") or temp_name("recording", ".mp4")
options = [
flag("out", destination),
*_optional(args, "seconds"),
*_optional(args, "output"),
*_optional(args, "fps"),
*_optional(args, "work_dir", "work-dir"),
*_switch(args, "keep"),
]
outcome = runner.run(argv(["record"], options, []))
if not outcome.ok:
return report(outcome)
measured = media.recording(outcome.stdout)
if measured is None:
return Result(
text=(
"hhstream record succeeded but its output could not be parsed "
f"for the measured rate:\n{outcome.stdout.strip()}"
),
data={"ok": True, "path": destination},
)
return Result(
text=(
f"{measured.path}\n{measured.frames} frames in {measured.seconds:.2f}s, "
f"encoded at the measured {measured.fps} fps (the publisher's achieved "
"rate, not the configured one). The file is on the machine running "
"this server; nothing was copied into this reply."
),
data={
"ok": True,
"path": measured.path,
"frames": measured.frames,
"seconds": measured.seconds,
"fps": measured.fps,
},
)
#: How long `run` watches the process it spawned before reporting its pid.
DEFAULT_SETTLE_S = 1.5
def _run(runner: Runner, args: dict[str, Any]) -> Result:
"""Launch an unmanaged application. Forked and left alone.
``cli.cmd_run`` cannot be called in this process -- it ends in
``os.execvpe``, which is the verb -- so :meth:`Runner.launch` does the one
thing it does, around a double fork. See that method for why the pid
handed back is the application's own and not a wrapper's.
"""
command = [str(item) for item in args["argv"]]
settle = float(args.get("settle_s", DEFAULT_SETTLE_S))
spawned = runner.launch(command, settle=settle)
if spawned.exited:
said = (spawned.stderr or spawned.stdout).strip()
return Result(
text=(
f"{remedy_for(GENERIC_FAILURE)}\n\n"
f"the application did not survive {settle:g}s, so nothing is on "
f"the screen.\n\nit said:\n{said or '(nothing)'}"
),
data={
"ok": False,
"error": "run_exited",
"pid": spawned.pid or None,
"remedy": remedy_for(GENERIC_FAILURE),
},
is_error=True,
)
return Result(
text=(
f"launched pid {spawned.pid}: {' '.join(command)}\n"
f"Still running after {settle:g}s. This is UNMANAGED: nothing tracks "
"it, it has no idle clock and no container, and `session_kill` "
"cannot stop it -- use `session_start` instead when it must be "
"findable, kept alive and stoppable by name, or `session_adopt` to "
"bring this pid under management."
),
data={"ok": True, "pid": spawned.pid, "argv": command, "managed": False},
)
# ── the table ──────────────────────────────────────────────────────────────
def _acquire_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
lease = (payload or {}).get("lease_id") or "(none reported)"
return (
f"lease_id: {lease}\n"
"Pass this as `lease` on every pointer and keyboard call for this "
"session, and call `pointer_release` when the gesture is finished. The "
"keyboard is on this same lease; acquire also took keyboard focus.\n\n"
f"{outcome.stdout.strip()}"
)
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"{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."""
tools: list[Tool] = [
Tool(
name="shot",
title="Capture one frame",
description=(
"Capture one frame and return it as an image. Reads the "
"published main output off the frame socket; with `output` "
"named it captures that one output in isolation through `grim` "
"instead, which is how a single session's container is looked "
"at (`session_container` lists the names). The geometry and "
"media type are in the text part. "
f"{COORDINATES_NOTE}"
),
schema=obj(
{
"output": {
"type": "string",
"description": (
"capture this output alone, e.g. a session's "
"container `hh-<session-id>`. Omit for the "
"published main output."
),
}
}
),
invoke=_shot,
read_only=True,
),
Tool(
name="record",
title="Film the screen",
description=(
"Film the screen for N seconds into an mp4 and return its "
"PATH, not its bytes. The encoded frame rate is the one the "
"capture actually measured, not the configured one -- a "
"software-rendered compositor tops out well below it, and the "
"reply reports both the frame count and the elapsed time. With "
"`output` named it films that output alone by running `grim` "
"once per frame, which is markedly slower. The file is written "
"on the machine running this server."
),
schema=obj(
{
"seconds": {
"type": "number",
"exclusiveMinimum": 0,
"description": "how long to film (the CLI's default is 10)",
},
"out": {
"type": "string",
"description": (
"where to write the mp4. Omitted, it goes to a "
"generated path under the system temporary "
"directory and the reply names it."
),
},
"output": {
"type": "string",
"description": "film this output alone, e.g. `hh-<session-id>`",
},
"fps": {
"type": "number",
"exclusiveMinimum": 0,
"description": (
"target frames per second, for `output` only; "
"ignored without it, where the publisher sets the rate"
),
},
"work_dir": {
"type": "string",
"description": "where the intermediate frames go (default: a temp dir)",
},
"keep": {
"type": "boolean",
"description": "keep the intermediate frames after encoding",
},
}
),
invoke=_record,
# Not read-only: it writes an mp4. Additive and not destructive --
# it creates a file, it does not change the desktop -- but a hint
# that said "modifies nothing" about a tool that leaves megabytes
# on disk would be a hint worth less than none.
),
Tool(
name="run",
title="Launch an unmanaged application",
description=(
"Launch a GUI application into the session and forget it. "
"UNMANAGED on purpose: nothing tracks the process, it gets no "
"container and no idle clock, and no tool here can stop it by "
"name. Prefer `session_start`, which registers the "
"application, gives it its own output and workspace, and can "
"be killed and reaped -- `run` is the primitive underneath "
"that, and is the right choice only for something you will "
"stop yourself. The pid returned is the application's own: the "
"CLI `exec`s into it."
),
schema=obj(
{
"argv": {
"type": "array",
"items": {"type": "string"},
"minItems": 1,
"description": (
"the command and its arguments, as a list. There "
"is never a shell: no globbing, no pipes, no quoting."
),
},
"settle_s": {
"type": "number",
"minimum": 0,
"description": (
"how long to watch the spawned process for an "
"immediate failure before reporting its pid "
f"(default: {DEFAULT_SETTLE_S:g}). A launch that "
"fails -- no Wayland socket, no such executable -- "
"fails inside this window and is reported as an "
"error; one that survives it is reported as running."
),
},
},
["argv"],
),
invoke=_run,
),
]
tools += _session_tools()
tools += _pointer_tools()
tools += _keyboard_tools()
return tuple(tools)
def _session_tools() -> list[Tool]:
return [
Tool(
name="session_start",
title="Start a tracked session",
description=(
"Launch an allowlisted application as a tracked session: it "
"gets a session id, its own output and workspace, a pid the "
"broker watches, and an idle clock. `app` is a NAME from the "
"broker's allowlist, never a path -- an unlisted name is "
"refused by policy (exit 6), and so is an argument the "
"allowlist does not permit.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{
"app": {
"type": "string",
"description": "a name from the broker's allowlist, never a path",
},
"argv": {
"type": "array",
"items": {"type": "string"},
"description": (
"arguments for the application, as a list. Passed "
"as an argv list; there is never a shell."
),
},
"idle_timeout": dict(
DURATION,
description=(
"reap the session after this long with no "
"`session_touch` (the broker's default applies if "
"omitted)"
),
),
"wait_ready": dict(
DURATION, description="how long to wait for the application to signal readiness"
),
"home": {
"type": "string",
"description": "run the application with this HOME instead of the inherited one",
},
"ephemeral_home": {
"type": "boolean",
"description": (
"give the session a private HOME and delete it when "
"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"],
# Mutually exclusive, spelled as "never both" rather than as a
# `oneOf`: a `oneOf` of two negations matches twice when
# NEITHER is given, which would refuse the ordinary call that
# names no home at all.
**{"not": {"required": ["home", "ephemeral_home"]}},
),
invoke=json_verb(
["session", "start"],
options=lambda a: [
*_optional(a, "idle_timeout", "idle-timeout"),
*_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 []]],
summary=_start_summary,
),
),
Tool(
name="session_touch",
title="Reset the idle clock",
description=(
"Reset this session's idle clock. Injects nothing and changes "
"nothing else.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({"id": SESSION_ID}, ["id"]),
invoke=json_verb(["session", "touch"], positionals=lambda a: [a["id"]]),
),
Tool(
name="session_kill",
title="Kill a session",
description=(
"Terminate a session and everything it spawned, and tear its "
"container down. The reply says what was actually signalled, "
"and WARNS if any process or any window survived -- read it, "
"because a kill that did not work looks the same as one that "
"did until you do."
),
schema=obj(
{
"id": SESSION_ID,
"grace": dict(
DURATION,
description="how long to wait after the first signal before SIGKILL",
),
"signal": {
"type": "string",
"description": "the first signal to send (the CLI's default is TERM)",
},
"request_id": REQUEST_ID,
},
["id"],
),
invoke=json_verb(
["session", "kill"],
options=lambda a: [
*_optional(a, "grace"),
*_optional(a, "signal"),
*_optional(a, "request_id", "request-id"),
],
positionals=lambda a: [a["id"]],
),
destructive=True,
),
Tool(
name="session_gc",
title="Prune and reconcile the registry",
description=(
"Prune the tombstones of ended sessions and reconcile the "
"registry against `/proc`, so a session whose process died "
"without the broker noticing is recorded as gone.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({"request_id": REQUEST_ID}),
invoke=json_verb(
["session", "gc"], options=lambda a: _optional(a, "request_id", "request-id")
),
),
Tool(
name="session_adopt",
title="Adopt a running process",
description=(
"Bring an already-running process under management, so it has "
"a session id, an idle clock and a name to kill it by. Its exit "
"code will never be available -- it is not a child of the "
"broker -- so the broker watches `/proc` for it instead."
),
schema=obj(
{
"pid": {"type": "integer", "minimum": 1, "description": "the pid to adopt"},
"app": {
"type": "string",
"description": "name to record (default: the executable's basename)",
},
"idle_timeout": dict(DURATION, description="reap it after this long with no touch"),
"request_id": REQUEST_ID,
},
["pid"],
),
invoke=json_verb(
["session", "adopt"],
options=lambda a: [
flag("pid", int(a["pid"])),
*_optional(a, "app"),
*_optional(a, "idle_timeout", "idle-timeout"),
*_optional(a, "request_id", "request-id"),
],
),
),
Tool(
name="session_container",
title="A session's output and workspace",
description=(
"The output, workspace and mode the broker gave a session -- "
"the output name is what `shot` and `record` take as `output`. "
"With no id this lists every container plus the `hh-*` outputs "
"no live session claims (orphans), and reads nothing but the "
"record.\n\n"
"WITH an id this re-reads from the compositor and brings the "
"record up to that answer, which is a write: asking where a "
"session's window is is almost always asking where it is NOW, "
"and the stored record can only say where it was put. Use no "
"id for a pure read.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({"id": dict(SESSION_ID, description=SESSION_ID["description"] + "; omit for every container and the orphan list")}),
invoke=json_verb(
["session", "container"], positionals=lambda a: [a["id"]] if a.get("id") else []
),
),
Tool(
name="session_reconcile",
title="Re-read containers from the compositor",
description=(
"Ask the compositor where a session's window actually is and "
"bring the record up to that answer; the compositor is the "
"authority and the record is a cache of it. With no id every "
"live session is reconciled and the start-up scan is re-run: "
"the quarantine rule is re-installed, adopted containers "
"re-take their workspace slots, and `hh-*` outputs with no live "
"session are removed. The reply reports the drift it found.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{
"id": dict(SESSION_ID, description=SESSION_ID["description"] + "; omit for all of them"),
"request_id": REQUEST_ID,
}
),
invoke=json_verb(
["session", "reconcile"],
options=lambda a: _optional(a, "request_id", "request-id"),
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,
),
]
def _pointer_tools() -> list[Tool]:
gesture = f"{LEASE_NOTE}\n\n{COORDINATES_NOTE}\n\n{ACTIVITY_NOTE}"
return [
Tool(
name="pointer_acquire",
title="Take the pointer lease",
description=(
"Take the one cursor for this session, aim it into the "
"session's own container, and return the `lease_id` every "
"pointer and keyboard call needs. It takes KEYBOARD FOCUS as "
"well as the cursor -- that is what makes typing possible, "
"since a virtual keyboard is seat-global and has nothing to "
"aim -- and the reply's `focus` field names which mechanism "
"took it.\n\n"
"The cursor is singular, so it is leased: a second acquire "
"while another session holds it fails with exit 8 (BUSY) and "
"names the holder. There is no way to take it from them. A "
"lease left idle past its TTL is force-released by the broker, "
"which also lifts whatever it was holding down.\n\n"
"By default the cursor resumes where this session last left "
"it; `no_restore` starts at the centre of the container "
"instead.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{
"id": SESSION_ID,
"ttl": dict(
DURATION,
description=(
"idle lifetime for this lease before the broker "
"force-releases it (the broker's default applies if "
"omitted, and its hard maximum caps it)"
),
),
"no_restore": {
"type": "boolean",
"description": "start at the centre of the container rather than where it was left",
},
},
["id"],
),
invoke=json_verb(
["session", "pointer", "acquire"],
options=lambda a: [*_optional(a, "ttl"), *_switch(a, "no_restore", "no-restore")],
positionals=lambda a: [a["id"]],
summary=_acquire_summary,
),
),
Tool(
name="pointer_move",
title="Warp the cursor",
description=(
"Warp the cursor inside this session's container. Exactly one "
"of `to` (absolute) or `by` (relative to where it is now). "
"`to` is REFUSED outside 0..1, because a caller that computed "
"1.4 has a bug and clamping would hide it; `by` IS clamped, "
"because running into the edge of the screen is what a mouse "
"does.\n\n"
f"{gesture}"
),
schema=obj(
{
"id": SESSION_ID,
"lease": LEASE,
"to": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2,
"description": "absolute [x, y], output-normalised 0..1",
},
"by": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2,
"description": "relative [dx, dy] from the current position",
},
},
["id", "lease"],
oneOf=[{"required": ["to"]}, {"required": ["by"]}],
),
invoke=json_verb(
["session", "pointer", "move"],
options=lambda a: [
flag("lease", a["lease"]),
flag("to", point(a["to"])) if "to" in a else flag("by", point(a["by"])),
],
positionals=lambda a: [a["id"]],
),
),
Tool(
name="pointer_click",
title="Click",
description=(
"Press and release a button where the cursor already is. Warp "
"first with `pointer_move` if it is somewhere else -- there is "
"no click-at-a-coordinate, and the lease is what makes "
"move-then-click one gesture no other session can interleave "
"with.\n\n"
f"{gesture}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "button": BUTTON}, ["id", "lease"]),
invoke=json_verb(
["session", "pointer", "click"],
options=lambda a: [flag("lease", a["lease"]), *_optional(a, "button")],
positionals=lambda a: [a["id"]],
),
),
Tool(
name="pointer_scroll",
title="Scroll",
description=(
"Scroll where the cursor is. `amount` is signed wheel clicks "
"and POSITIVE IS DOWN (vertical) or RIGHT (horizontal) -- the "
"protocol's direction, not a choice of ours, which is why there "
"is no up/down vocabulary over it. Bounded at 100 clicks a "
"call, so a decimal-point slip is a refusal rather than a "
"session scrolled somewhere unrecoverable. The cursor does not "
"move.\n\n"
f"{gesture}"
),
schema=obj(
{
"id": SESSION_ID,
"lease": LEASE,
"axis": {
"type": "string",
"enum": list(AXES),
"description": "vertical (default) or horizontal",
},
"amount": {
"type": "number",
"description": "wheel clicks, signed; positive is down/right (the CLI's default is 3)",
},
},
["id", "lease"],
),
invoke=json_verb(
["session", "pointer", "scroll"],
options=lambda a: [
flag("lease", a["lease"]),
*_optional(a, "axis"),
*([flag("amount", number(a["amount"]))] if "amount" in a else []),
],
positionals=lambda a: [a["id"]],
),
),
Tool(
name="pointer_down",
title="Hold a button down",
description=(
"Half a click: press a button and leave it pressed. With "
"`pointer_move` and `pointer_up` this is a drag, and the lease "
"is what makes the three calls atomic. The broker lifts "
"whatever is still down on release or on a lease timeout, so a "
"crashed agent cannot leave a button pressed.\n\n"
f"{gesture}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "button": BUTTON}, ["id", "lease"]),
invoke=json_verb(
["session", "pointer", "down"],
options=lambda a: [flag("lease", a["lease"]), *_optional(a, "button")],
positionals=lambda a: [a["id"]],
),
),
Tool(
name="pointer_up",
title="Release a held button",
description=(
"The other half of `pointer_down`. The reply lists what is "
"still held.\n\n"
f"{gesture}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "button": BUTTON}, ["id", "lease"]),
invoke=json_verb(
["session", "pointer", "up"],
options=lambda a: [flag("lease", a["lease"]), *_optional(a, "button")],
positionals=lambda a: [a["id"]],
),
),
Tool(
name="pointer_release",
title="Give the lease back",
description=(
"Give the cursor back, lifting every button AND every key still "
"held. Call it when a gesture is finished rather than letting "
"the TTL expire: until it is released no other session can "
"acquire. The lease id is dead afterwards.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE}, ["id", "lease"]),
invoke=json_verb(
["session", "pointer", "release"],
options=lambda a: [flag("lease", a["lease"])],
positionals=lambda a: [a["id"]],
),
),
]
def _keyboard_tools() -> list[Tool]:
note = f"{LEASE_NOTE}\n\n{ACTIVITY_NOTE}"
keysym = {
"type": "string",
"description": (
"an XKB keysym NAME, not a character code: `a`, `A`, `Return`, "
"`BackSpace`, `Left`, `Control_L`, `Shift_L`. Resolved against the "
"layout the driver uploaded (an operator setting, `us` by default), "
"so a name that layout does not carry is exit 2."
),
}
return [
Tool(
name="keyboard_type",
title="Type a string",
description=(
"Type one string into whatever the seat has focused -- which "
"`pointer_acquire` aimed at this session. Raw UTF-8, no "
"backslash escapes: a newline in the string is a newline, and "
"`\\n` is a backslash and an n.\n\n"
"A CHARACTER THE LAYOUT CANNOT PRODUCE FAILS THE WHOLE STRING "
"and types nothing -- there is no partial type and no prefix to "
"clean up. On the default `us` layout that includes accented "
"letters and every C0 control but newline and tab. The refusal "
"names the character's INDEX, never the character and never the "
"string, because a typed string is a password as often as not; "
"the audit log records a count and nothing else. Capped at 4096 "
"Unicode scalars.\n\n"
"A modifier held with `keyboard_down` is a baseline: its mask "
"is ORed into every character here and it is still held "
"afterwards, which is how a chord is spelled. A non-modifier "
"left held is a refusal.\n\n"
f"{note}"
),
schema=obj(
{
"id": SESSION_ID,
"lease": LEASE,
"text": {
"type": "string",
"description": "the string to type, raw UTF-8, at most 4096 Unicode scalars",
},
},
["id", "lease", "text"],
),
invoke=json_verb(
["session", "keyboard", "type"],
options=lambda a: [flag("lease", a["lease"])],
positionals=lambda a: [a["id"], a["text"]],
),
),
Tool(
name="keyboard_key",
title="Tap one key",
description=(
"Press and release one key: down then up, as two calls on the "
"wire. This is the tool for `Return`, `Tab`, `BackSpace` and "
"the arrows -- anything `keyboard_type` cannot express because "
"it has no character. A refused down sends no up.\n\n"
f"{note}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "name": keysym}, ["id", "lease", "name"]),
invoke=json_verb(
["session", "keyboard", "key"],
options=lambda a: [flag("lease", a["lease"])],
positionals=lambda a: [a["id"], a["name"]],
),
),
Tool(
name="keyboard_down",
title="Hold a key down",
description=(
"Press a key and leave it pressed. The justified use is a "
"chord.\n\n"
f"{HOLD_NOTE}\n\n"
f"{note}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "name": keysym}, ["id", "lease", "name"]),
invoke=json_verb(
["session", "keyboard", "down"],
options=lambda a: [flag("lease", a["lease"])],
positionals=lambda a: [a["id"], a["name"]],
),
),
Tool(
name="keyboard_up",
title="Release a held key",
description=(
"Release a key that was held with `keyboard_down`. The reply "
"lists what is still held. `pointer_release` and a lease "
"timeout both lift everything, so a crashed agent cannot leave "
"a key down -- but until one of those happens the application "
"is still being typed at.\n\n"
f"{note}"
),
schema=obj({"id": SESSION_ID, "lease": LEASE, "name": keysym}, ["id", "lease", "name"]),
invoke=json_verb(
["session", "keyboard", "up"],
options=lambda a: [flag("lease", a["lease"])],
positionals=lambda a: [a["id"], a["name"]],
),
),
]
#: The surface, built once. A tuple so a caller cannot reorder the listing an
#: agent reads.
TOOLS: tuple[Tool, ...] = build()
BY_NAME: dict[str, Tool] = {tool.name: tool for tool in TOOLS}
# ── toolsets ───────────────────────────────────────────────────────────────
#: The families ``--toolsets`` selects from, in listing order.
#:
#: Not a protocol feature -- MCP has no notion of a tool group, and the ``Tool``
#: object has nowhere to put one -- so this is what the ecosystem actually does:
#: the *server* is told which families to list, at launch, by whoever spawns it.
#: It exists because a tool listing is a budget. A client with room for a dozen
#: tools gets a coherent dozen this way instead of an arbitrary truncation, and
#: an agent that will never start an application need not be shown how.
#:
#: Resources are deliberately NOT filtered by it. They are the host's context,
#: not the model's budget, and making ``hhstream://sessions`` conditional on the
#: session *tools* being enabled would couple two decisions that are not the
#: same decision.
TOOLSETS: dict[str, tuple[str, ...]] = {
"frames": ("shot", "record", "run"),
"sessions": (
"session_start",
"session_touch",
"session_kill",
"session_gc",
"session_adopt",
"session_container",
"session_reconcile",
"session_stream_enable",
"session_stream_disable",
),
"pointer": (
"pointer_acquire",
"pointer_move",
"pointer_click",
"pointer_scroll",
"pointer_down",
"pointer_up",
"pointer_release",
),
"keyboard": ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"),
}
#: Tools that mcp-v1 had and mcp-v2 does not, each pointing at the resource
#: that replaced it.
#:
#: Kept so a refusal can say where the thing went. An agent (or a transcript,
#: or a prompt) that learned the v1 names will ask for these, and "no such
#: tool" alone makes that look like a server that is broken rather than a
#: surface that moved. One sentence here saves a whole loop of guessing.
MOVED_TO_RESOURCES: dict[str, str] = {
"status": "hhstream://status",
"session_list": "hhstream://sessions",
"session_status": "hhstream://sessions/<id>",
"session_logs": "hhstream://sessions/<id>/logs",
"pointer_state": "hhstream://pointer",
}
class UnknownToolset(ValueError):
"""A name ``--toolsets`` does not know. Refused, never ignored."""
def selected(names: Any = None) -> tuple[Tool, ...]:
"""The tools in the named families, in the table's own order.
``None`` is every tool, which is the default and what an unconfigured
client gets. An unknown name is refused rather than skipped: a server that
quietly served nothing because of a typo would look like a server with no
tools, which is the hardest failure of all to diagnose from the far side of
a pipe.
"""
if names is None:
return TOOLS
wanted = tuple(dict.fromkeys(names))
unknown = [name for name in wanted if name not in TOOLSETS]
if unknown:
raise UnknownToolset(
f"no such toolset: {', '.join(repr(u) for u in unknown)}. "
f"Known: {', '.join(TOOLSETS)}"
)
chosen = {tool for family in wanted for tool in TOOLSETS[family]}
return tuple(tool for tool in TOOLS if tool.name in chosen)