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

1264 lines
52 KiB
Python

"""The tool table: one tool per CLI verb. Standard library only.
**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_list`` is about
to be called for the ninth time.
3. ``readOnlyHint`` is per tool and is a real distinction here: ``session_list``
reads, ``session_kill`` destroys, and ``session_container`` with an id
reconciles -- which is a write, and is marked as one.
The cost is twenty-six tools in one listing. That 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. `session_list`, `session_status`, `session_logs` and `session_gc` "
"do NOT count, 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`."
)
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 `session_list` 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 _status(runner: Runner, args: dict[str, Any]) -> Result:
# No `--json`: `hhstream status` has none. It is a human report of the
# units, the socket's reachability and one probe frame, and this passes it
# through as text rather than inventing a shape for it.
return report(runner.run(["status"]))
def _shot(runner: Runner, args: dict[str, Any]) -> Result:
"""One frame, as MCP image content.
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 in the reply.
"""
with tempfile.TemporaryDirectory(prefix="hhstream-mcp-shot-") as scratch:
destination = os.path.join(scratch, "frame.png")
options = [flag("out", destination), *_optional(args, "output")]
outcome = runner.run(argv(["shot"], options, []))
if not outcome.ok:
return report(outcome)
try:
frame = pathlib.Path(destination).read_bytes()
except OSError as exc:
return Result(
text=(
f"hhstream shot reported success but wrote no readable file: {exc}\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 _start_summary(outcome: Outcome, payload: dict[str, Any] | None) -> str:
session_id = (payload or {}).get("id") or "(not reported)"
return (
f"session id: {session_id}\n"
f"Keep it alive with `session_touch` before its idle timeout expires.\n\n"
f"{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="status",
title="Session status",
description=(
"Is the headless Hyprland session up, and can this server reach "
"its frame socket? Reports each unit's state, the socket path "
"and whether it is readable, the Wayland socket the compositor "
"bound, and one probe frame's size and geometry. Start here "
"when any other tool fails in a way that smells like the "
"desktop being down. Human-readable text; this verb has no "
"JSON form."
),
schema=obj({}),
invoke=_status,
read_only=True,
),
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`."
),
},
"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"),
*_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_list",
title="List sessions",
description=(
"Every session the broker is tracking, with its state, pid and "
"idle deadline. `all` includes the tombstones of ended ones.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{"all": {"type": "boolean", "description": "include tombstones of ended sessions"}}
),
invoke=json_verb(["session", "list"], options=lambda a: _switch(a, "all")),
read_only=True,
),
Tool(
name="session_status",
title="One session, in detail",
description=(
"One session: its state, pid, container, idle deadline, and the "
"most recent entries from the broker's audit trail. The audit "
"events are the place to look when a session died for a reason "
"its own logs do not show.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{
"id": SESSION_ID,
"events": {
"type": "integer",
"minimum": 0,
"description": "how many recent audit events to include (the CLI's default is 20)",
},
},
["id"],
),
invoke=json_verb(
["session", "status"],
options=lambda a: _optional(a, "events"),
positionals=lambda a: [a["id"]],
),
read_only=True,
),
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_logs",
title="A session's captured output",
description=(
"The tail of the application's own stdout and stderr, as the "
"broker captured it. The first place to look when an "
"application started and then did nothing.\n\n"
"There is no follow mode here, deliberately: the CLI's "
"`--follow` polls until interrupted, and a tool call that never "
"returns hangs the client that made it. Call this again "
"instead.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj(
{
"id": SESSION_ID,
"lines": {
"type": "integer",
"minimum": 1,
"description": "how many lines to tail (the CLI's default is 100)",
},
},
["id"],
),
invoke=json_verb(
["session", "logs"],
options=lambda a: _optional(a, "lines"),
positionals=lambda a: [a["id"]],
),
read_only=True,
),
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 [],
),
),
]
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"]],
),
),
Tool(
name="pointer_state",
title="Who holds the pointer",
description=(
"Who holds the one pointer lease, since when, and which buttons "
"and KEYS are currently held down. This is the tool to call "
"after an exit 8 (BUSY): it names the holder. It takes no "
"session id -- there is one cursor.\n\n"
f"{ACTIVITY_NOTE}"
),
schema=obj({}),
invoke=json_verb(["session", "pointer", "state"]),
read_only=True,
),
]
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}