`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
1264 lines
52 KiB
Python
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}
|