@beeos-ai/device-mcp-server 0.2.3 → 0.4.2

package/dist/server/tool-registry.js

@@ -1,42 +1,82 @@
 /**
- * MCP tool registry — verbs exposed by the device sandbox.
+ * SDK-style tool catalogue for device-mcp-server.
  *
- * Each tool entry carries:
- *  - a name (the MCP tool identifier, e.g. `click`)
- *  - a JSON schema describing the expected `arguments` payload
- *  - a `handler` that maps `arguments` → `SandboxBackend` method call.
+ * Each tool is a `ToolSpec` describing:
+ *   - `name`              MCP tool identifier (`screenshot`, `tap`, ...)
+ *   - `description`       human-readable verb
+ *   - `inputShape`        zod raw shape — every shape gets an implicit
+ *                         `device?: z.string().optional()` injected by
+ *                         `registerAllTools` so multi-device callers can
+ *                         target a specific backend per call
+ *   - `annotations`       `ToolAnnotations` (read-only / destructive /
+ *                         idempotent / open-world hints)
+ *   - `requires`          MCP tool name the resolved backend must declare
+ *                         in `backend.tools`. Tools with `requires:
+ *                         "registry"` are registry-level (don't touch a
+ *                         backend) — used for `list_available_devices` /
+ *                         `use_device`.
+ *   - `handler`           async `(args, ctx) => CallToolResult`
  *
- * Filtering is driven entirely by `backend.tools` (a flat
- * `ReadonlySet<string>` declared on each backend). The registry is
- * purely a name → schema/handler lookup table; it does not encode
- * support gates of its own. `listToolDescriptorsFor(backend)` filters
- * via `backend.tools.has(name)`; `getToolFor(name, backend)` mirrors
- * the same gate so `/mcp/tools/call` returns 404 (instead of 200 +
- * runtime `unsupported`) for any tool the active backend doesn't
- * advertise.
+ * `registerAllTools(server, registry)` iterates the catalogue and calls
+ * `server.registerTool` for each entry. The handler closure captures the
+ * registry so it can resolve the per-call backend via `registry.resolve`.
  *
- * Inspired by the Python `mcp_tools/registry.py` reference; verbs are kept
- * verbatim for cross-runtime compatibility.
+ * Returning shapes:
+ *   - Every handler returns `{ content, structuredContent }`. `content`
+ *     carries the human-friendly text summary (printable in MCP clients
+ *     like Claude Desktop / Cursor); `structuredContent` carries the
+ *     typed payload that programmatic callers (`device-agent`) parse.
  */
+import { z } from "zod";
+import { DeviceError, } from "@beeos-ai/device-common";
 import { formatUiXmlToolOutput } from "../util/ui-xml.js";
+import { assertSafeUrl, PRESS_BUTTON_KEYMAP } from "../backends/android-adb.js";
+import { assertSafeOutputPathWithExt, } from "../util/output-path.js";
+import { assertValidPackageName } from "../util/package-name.js";
+import { assertValidLocale } from "../util/locale.js";
 /* ----------------------------------------------------------------------- */
-/* Helpers                                                                  */
+/* Helpers                                                                 */
 /* ----------------------------------------------------------------------- */
-function n(args, key) {
-    const v = args[key];
-    if (typeof v !== "number" || !Number.isFinite(v)) {
-        throw new TypeError(`argument '${key}' must be a finite number`);
-    }
-    return v;
+const xy = {
+    x: z.number().describe("Click coordinate x (device pixels)"),
+    y: z.number().describe("Click coordinate y (device pixels)"),
+};
+const segment = {
+    x1: z.number(),
+    y1: z.number(),
+    x2: z.number(),
+    y2: z.number(),
+};
+/**
+ * Shared `durationMs` schema for gesture tools (mobile-mcp parity, r3).
+ *
+ * mobile-mcp clamps duration into `[1, 10000]` ms — without an upper
+ * bound a prompt-injected `durationMs: 600000` would wedge an `adb
+ * input swipe` for 10 minutes. We pick the same range and require an
+ * integer (the underlying `input swipe` rounds anyway, so accepting
+ * floats just hides typos).
+ */
+const durationMsField = z.number().int().min(1).max(10000).optional();
+function ok(text, structured) {
+    return {
+        content: [{ type: "text", text }],
+        ...(structured !== undefined ? { structuredContent: structured } : {}),
+    };
+}
+function ack(verb) {
+    return {
+        content: [{ type: "text", text: `${verb} ok` }],
+        structuredContent: { ok: true },
+    };
 }
-function s(args, key) {
+function getStr(args, key) {
     const v = args[key];
     if (typeof v !== "string") {
         throw new TypeError(`argument '${key}' must be a string`);
     }
     return v;
 }
-function optS(args, key) {
+function optStr(args, key) {
     const v = args[key];
     if (v === undefined || v === null)
         return undefined;
@@ -44,7 +84,14 @@ function optS(args, key) {
         throw new TypeError(`argument '${key}' must be a string`);
     return v;
 }
-function optN(args, key) {
+function num(args, key) {
+    const v = args[key];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new TypeError(`argument '${key}' must be a finite number`);
+    }
+    return v;
+}
+function optNum(args, key) {
     const v = args[key];
     if (v === undefined || v === null)
         return undefined;
@@ -53,452 +100,882 @@ function optN(args, key) {
     }
     return v;
 }
-const xy = {
-    type: "object",
-    properties: {
-        x: { type: "number" },
-        y: { type: "number" },
-    },
-    required: ["x", "y"],
-};
 /* ----------------------------------------------------------------------- */
-/* Tool definitions                                                         */
+/* Tool catalogue                                                          */
 /* ----------------------------------------------------------------------- */
-export const TOOLS = {
-    /* — observation — */
-    screenshot: {
-        descriptor: {
-            name: "screenshot",
-            description: "Capture a screenshot. Returns base64 image bytes plus actual " +
-                "image dimensions (width/height) and click coordinate-system " +
-                "dimensions (deviceWidth/deviceHeight).",
-            inputSchema: { type: "object", properties: {} },
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const MUTATING = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+const OPEN_WORLD_READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+export const TOOL_SPECS = [
+    /* ---------------- Registry-level (no backend) ---------------- */
+    {
+        name: "list_available_devices",
+        description: "List every device currently registered in this device-mcp-server. Returns id, OS, default flag, and source (adb / desktop). Pass an `id` from this list as the `device` argument on subsequent tool calls.",
+        inputShape: {},
+        annotations: { ...READ_ONLY, title: "List available devices" },
+        requires: "registry",
+        handler: async (_args, { registry }) => {
+            const devices = registry.list();
+            const text = devices.length
+                ? devices
+                    .map((d) => `- ${d.id}${d.isDefault ? " (default)" : ""}  os=${d.os} source=${d.source}`)
+                    .join("\n")
+                : "(no devices connected)";
+            return ok(text, { devices });
         },
-        handler: async (_args, { backend }) => {
-            // 0.2.3 split: `width/height` reflect the actual encoded bytes
-            // (so an agent that decodes `b64` always agrees with these
-            // numbers), while `deviceWidth/deviceHeight` carry the click
-            // coordinate-system size used by `tap(x, y)` / `click(x, y)`.
-            const shot = await backend.screenshot();
-            const size = await backend
-                .screenSize()
-                .catch(() => ({ w: shot.width, h: shot.height }));
-            return {
+    },
+    {
+        name: "use_device",
+        description: "Set the session-sticky default device for subsequent tool calls. Only meaningful when the client uses the stdio transport (single persistent session). Stateless HTTP callers should pass `device` on every tool call instead.",
+        inputShape: {
+            device: z.string().describe("Device id from list_available_devices."),
+        },
+        annotations: { ...MUTATING, title: "Use device" },
+        requires: "registry",
+        handler: async (args, { registry, sessionId }) => {
+            const device = getStr(args, "device");
+            registry.useDevice(sessionId, device);
+            return ok(`active device set to ${device}`, { device });
+        },
+    },
+    /* ---------------- Observation ---------------- */
+    {
+        name: "screenshot",
+        description: "Capture a screenshot. Returns base64 image bytes plus the actual encoded image dimensions (width/height) and the click coordinate-system size (deviceWidth/deviceHeight). Optional `displayId` (Android multi-display), `maxEdge` (resize cap; pass `0` for no resize), `quality` (JPEG 1-100), and `format` (`png`/`jpeg`) override the env defaults `GUI_AGENT_SS_MAX_EDGE` / `GUI_AGENT_SS_JPEG_QUALITY` per call — useful when an LLM running against a 4K Android / Retina macOS host needs a smaller image without restarting the server.",
+        inputShape: {
+            displayId: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Android-only: capture display id N (Android 10+). Other backends ignore."),
+            maxEdge: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Cap the longest edge to this many pixels (resizes proportionally). Pass `0` to disable resizing for this call. Overrides `GUI_AGENT_SS_MAX_EDGE`."),
+            quality: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("JPEG quality (1-100). Honoured only on the JPEG re-encode path. Overrides `GUI_AGENT_SS_JPEG_QUALITY`."),
+            format: z
+                .enum(["png", "jpeg"])
+                .optional()
+                .describe("Force a specific output codec. `jpeg` triggers re-encode even when the raw capture is under the resize cap (for deterministic payload sizing)."),
+        },
+        annotations: { ...READ_ONLY, title: "Take a screenshot" },
+        requires: "screenshot",
+        handler: async (args, { backend }) => {
+            const [shot, size, currentApp] = await Promise.all([
+                backend.screenshot({
+                    displayId: optNum(args, "displayId"),
+                    maxEdge: optNum(args, "maxEdge"),
+                    quality: optNum(args, "quality"),
+                    format: optStr(args, "format") ?? undefined,
+                }),
+                backend.screenSize().catch(() => null),
+                backend.getCurrentApp?.().catch(() => "") ?? Promise.resolve(""),
+            ]);
+            const result = {
                 b64: shot.data.toString("base64"),
                 format: shot.format,
                 width: shot.width,
                 height: shot.height,
-                deviceWidth: size.w,
-                deviceHeight: size.h,
+                deviceWidth: size?.w ?? shot.width,
+                deviceHeight: size?.h ?? shot.height,
+                ...(currentApp ? { currentApp } : {}),
+            };
+            return {
+                content: [
+                    {
+                        type: "image",
+                        data: result.b64,
+                        mimeType: shot.format === "png" ? "image/png" : "image/jpeg",
+                    },
+                ],
+                structuredContent: result,
             };
         },
     },
-    ui_dump: {
-        descriptor: {
-            name: "ui_dump",
-            description: "Dump the active UI hierarchy. Optional `query` filters nodes server-side.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: { type: "string" },
-                    format: { type: "string", enum: ["compact", "raw"] },
-                },
-            },
-        },
+    {
+        name: "ui_dump",
+        description: "Dump the active UI hierarchy. Optional `query` filters nodes server-side. `format=raw` returns the original uiautomator XML; `format=compact` (default) returns a one-line-per-node summary.",
+        inputShape: {
+            query: z.string().optional(),
+            format: z.enum(["compact", "raw"]).optional(),
+        },
+        annotations: { ...READ_ONLY, title: "Dump UI hierarchy" },
+        requires: "ui_dump",
         handler: async (args, { backend }) => {
             const out = await backend.uiDump();
-            if (!out.supported)
-                return { supported: false };
-            const fmt = optS(args, "format") ?? "compact";
-            const query = optS(args, "query");
-            if (fmt === "raw")
-                return { supported: true, content: out.content ?? "" };
-            const compact = formatUiXmlToolOutput(out.content ?? "", query);
-            return { supported: true, content: compact };
-        },
-    },
-    device_info: {
-        descriptor: {
-            name: "device_info",
-            description: "Return DeviceInfo (type, name, screen size, capabilities, metadata).",
-            inputSchema: { type: "object", properties: {} },
-        },
-        // Always available — every backend has `info()` (platform metadata
-        // is the one thing even a stub backend can report). Backends still
-        // need to include `device_info` in their `tools` set to advertise
-        // it; the iOS stub uses this as its single advertised tool so the
-        // health check has something to call.
-        handler: async (_args, { backend }) => backend.info(),
+            if (!out.supported) {
+                return ok("UI dump not supported by this backend.", { supported: false });
+            }
+            const fmt = optStr(args, "format") ?? "compact";
+            const query = optStr(args, "query");
+            const content = fmt === "raw"
+                ? (out.content ?? "")
+                : formatUiXmlToolOutput(out.content ?? "", query);
+            return ok(content, { supported: true, content });
+        },
+    },
+    {
+        name: "device_info",
+        description: "Return DeviceInfo (type, name, screen size, capabilities, metadata).",
+        inputShape: {},
+        annotations: { ...READ_ONLY, title: "Device info" },
+        requires: "device_info",
+        handler: async (_args, { backend }) => {
+            const info = await backend.info();
+            return ok(`${info.name} (${info.type}) ${info.width}x${info.height}`, info);
+        },
     },
-    screen_size: {
-        descriptor: {
-            name: "screen_size",
-            description: "Return current screen size (w, h).",
-            inputSchema: { type: "object", properties: {} },
-        },
-        handler: async (_args, { backend }) => backend.screenSize(),
-    },
-    /* — pointer / gesture — */
-    click: {
-        descriptor: {
-            name: "click",
-            description: "Mouse click at (x, y). Equivalent to tap on touch backends.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    ...xy.properties,
-                    button: { type: "string", enum: ["left", "right", "middle"] },
-                    clicks: { type: "number" },
-                },
-                required: ["x", "y"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.click(n(args, "x"), n(args, "y"), optS(args, "button") ?? "left", optN(args, "clicks") ?? 1);
-            return { ok: true };
-        },
-    },
-    double_click: {
-        descriptor: {
-            name: "double_click",
-            description: "Double click at (x, y).",
-            inputSchema: { ...xy },
-        },
-        handler: async (args, { backend }) => {
-            await backend.doubleClick(n(args, "x"), n(args, "y"));
-            return { ok: true };
-        },
-    },
-    right_click: {
-        descriptor: {
-            name: "right_click",
-            description: "Right click at (x, y).",
-            inputSchema: { ...xy },
-        },
-        handler: async (args, { backend }) => {
-            await backend.rightClick(n(args, "x"), n(args, "y"));
-            return { ok: true };
-        },
-    },
-    tap: {
-        descriptor: {
-            name: "tap",
-            description: "Tap at (x, y) on a touch device.",
-            inputSchema: { ...xy },
-        },
-        handler: async (args, { backend }) => {
-            await backend.tap(n(args, "x"), n(args, "y"));
-            return { ok: true };
-        },
-    },
-    long_press: {
-        descriptor: {
-            name: "long_press",
-            description: "Long-press at (x, y) for `durationMs` (default 3000).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    ...xy.properties,
-                    durationMs: { type: "number" },
-                },
-                required: ["x", "y"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.longPress(n(args, "x"), n(args, "y"), optN(args, "durationMs"));
-            return { ok: true };
-        },
-    },
-    drag: {
-        descriptor: {
-            name: "drag",
-            description: "Drag from (x1, y1) to (x2, y2).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    x1: { type: "number" },
-                    y1: { type: "number" },
-                    x2: { type: "number" },
-                    y2: { type: "number" },
-                    durationMs: { type: "number" },
-                },
-                required: ["x1", "y1", "x2", "y2"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.drag(n(args, "x1"), n(args, "y1"), n(args, "x2"), n(args, "y2"), optN(args, "durationMs"));
-            return { ok: true };
-        },
-    },
-    swipe: {
-        descriptor: {
-            name: "swipe",
-            description: "Swipe from (x1, y1) to (x2, y2).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    x1: { type: "number" },
-                    y1: { type: "number" },
-                    x2: { type: "number" },
-                    y2: { type: "number" },
-                    durationMs: { type: "number" },
-                },
-                required: ["x1", "y1", "x2", "y2"],
-            },
+    {
+        name: "screen_size",
+        description: "Return current screen size (w, h) in click coordinates.",
+        inputShape: {},
+        annotations: { ...READ_ONLY, title: "Screen size" },
+        requires: "screen_size",
+        handler: async (_args, { backend }) => {
+            const size = await backend.screenSize();
+            return ok(`${size.w}x${size.h}`, size);
         },
+    },
+    {
+        name: "list_elements",
+        description: "Return a structured list of UI elements (text/contentDesc/resourceId/className + rect + center) from the active screen. Optional `query` filters elements by substring.",
+        inputShape: {
+            query: z.string().optional(),
+        },
+        annotations: { ...READ_ONLY, title: "List UI elements" },
+        requires: "list_elements",
         handler: async (args, { backend }) => {
-            await backend.swipe(n(args, "x1"), n(args, "y1"), n(args, "x2"), n(args, "y2"), optN(args, "durationMs"));
-            return { ok: true };
+            const elements = await backend.listElements({
+                query: optStr(args, "query"),
+            });
+            const text = elements
+                .slice(0, 200)
+                .map((e) => `(${e.center.x},${e.center.y}) ${e.className ?? ""} ${e.text ? `"${e.text}"` : ""}${e.contentDesc ? ` desc="${e.contentDesc}"` : ""}${e.clickable ? " *click" : ""}`)
+                .join("\n");
+            return ok(text || "(no elements)", { elements });
+        },
+    },
+    {
+        name: "get_orientation",
+        description: "Return the current screen orientation (portrait | landscape | reverse-portrait | reverse-landscape).",
+        inputShape: {},
+        annotations: { ...READ_ONLY, title: "Get orientation" },
+        requires: "get_orientation",
+        handler: async (_args, { backend }) => {
+            const o = await backend.getOrientation();
+            return ok(o, { orientation: o });
         },
     },
-    scroll: {
-        descriptor: {
-            name: "scroll",
-            description: "Scroll at (x, y) in `direction` (up | down | left | right).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    x: { type: "number" },
-                    y: { type: "number" },
-                    direction: { type: "string", enum: ["up", "down", "left", "right"] },
-                    amount: { type: "number" },
-                },
-                required: ["direction"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.scroll(optN(args, "x") ?? 0, optN(args, "y") ?? 0, s(args, "direction"), optN(args, "amount"));
-            return { ok: true };
-        },
-    },
-    /* — keyboard — */
-    type: {
-        descriptor: {
-            name: "type",
-            description: "Type the given Unicode `text` into the focused field.",
-            inputSchema: {
-                type: "object",
-                properties: { text: { type: "string" } },
-                required: ["text"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.typeText(s(args, "text"));
-            return { ok: true };
-        },
-    },
-    key: {
-        descriptor: {
-            name: "key",
-            description: "Press a single named key (e.g. `KEYCODE_HOME`, `Escape`).",
-            inputSchema: {
-                type: "object",
-                properties: { key: { type: "string" } },
-                required: ["key"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.pressKey(s(args, "key"));
-            return { ok: true };
-        },
-    },
-    hotkey: {
-        descriptor: {
-            name: "hotkey",
-            description: "Press a hotkey combo, e.g. ['Cmd', 'Shift', 'P'].",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    keys: { type: "array", items: { type: "string" } },
-                },
-                required: ["keys"],
-            },
+    {
+        name: "set_orientation",
+        description: "Set the screen orientation. Mobile only.",
+        inputShape: {
+            orientation: z.enum([
+                "portrait",
+                "landscape",
+                "reverse-portrait",
+                "reverse-landscape",
+            ]),
+        },
+        annotations: { ...MUTATING, title: "Set orientation" },
+        requires: "set_orientation",
+        handler: async (args, { backend }) => {
+            const o = getStr(args, "orientation");
+            await backend.setOrientation(o);
+            return ack("set_orientation");
         },
+    },
+    /* ---------------- Pointer / gesture ---------------- */
+    {
+        name: "click",
+        description: "Mouse click at (x, y). Equivalent to tap on touch backends.",
+        inputShape: {
+            ...xy,
+            button: z.enum(["left", "right", "middle"]).optional(),
+            clicks: z.number().int().positive().optional(),
+        },
+        annotations: { ...MUTATING, title: "Click" },
+        requires: "click",
         handler: async (args, { backend }) => {
-            const keys = args.keys;
-            if (!Array.isArray(keys) || keys.some((k) => typeof k !== "string")) {
-                throw new TypeError("argument 'keys' must be a string[]");
+            await backend.click(num(args, "x"), num(args, "y"), optStr(args, "button") ?? "left", optNum(args, "clicks") ?? 1);
+            return ack("click");
+        },
+    },
+    {
+        name: "double_click",
+        description: "Double click at (x, y).",
+        inputShape: { ...xy },
+        annotations: { ...MUTATING, title: "Double-click" },
+        requires: "double_click",
+        handler: async (args, { backend }) => {
+            await backend.doubleClick(num(args, "x"), num(args, "y"));
+            return ack("double_click");
+        },
+    },
+    {
+        name: "right_click",
+        description: "Right click at (x, y).",
+        inputShape: { ...xy },
+        annotations: { ...MUTATING, title: "Right-click" },
+        requires: "right_click",
+        handler: async (args, { backend }) => {
+            await backend.rightClick(num(args, "x"), num(args, "y"));
+            return ack("right_click");
+        },
+    },
+    {
+        name: "tap",
+        description: "Tap at (x, y) on a touch device.",
+        inputShape: { ...xy },
+        annotations: { ...MUTATING, title: "Tap" },
+        requires: "tap",
+        handler: async (args, { backend }) => {
+            await backend.tap(num(args, "x"), num(args, "y"));
+            return ack("tap");
+        },
+    },
+    {
+        name: "double_tap",
+        description: "Double-tap at (x, y) on a touch device. Mobile-side alias for `double_click` — the underlying backend method is the same (`doubleClick`); this wire name exists for prompt parity with `mobile_double_tap_on_screen` (mobile-mcp).",
+        inputShape: { ...xy },
+        annotations: { ...MUTATING, title: "Double-tap" },
+        requires: "double_tap",
+        handler: async (args, { backend }) => {
+            await backend.doubleClick(num(args, "x"), num(args, "y"));
+            return ack("double_tap");
+        },
+    },
+    {
+        name: "long_press",
+        description: "Long-press at (x, y) for `durationMs` (default 3000, clamped to 1-10000 ms — mobile-mcp parity, r3).",
+        inputShape: {
+            ...xy,
+            durationMs: durationMsField,
+        },
+        annotations: { ...MUTATING, title: "Long-press" },
+        requires: "long_press",
+        handler: async (args, { backend }) => {
+            await backend.longPress(num(args, "x"), num(args, "y"), optNum(args, "durationMs"));
+            return ack("long_press");
+        },
+    },
+    {
+        name: "drag",
+        description: "Drag from (x1, y1) to (x2, y2). Optional `durationMs` clamped to 1-10000.",
+        inputShape: {
+            ...segment,
+            durationMs: durationMsField,
+        },
+        annotations: { ...MUTATING, title: "Drag" },
+        requires: "drag",
+        handler: async (args, { backend }) => {
+            await backend.drag(num(args, "x1"), num(args, "y1"), num(args, "x2"), num(args, "y2"), optNum(args, "durationMs"));
+            return ack("drag");
+        },
+    },
+    {
+        name: "swipe",
+        description: "Swipe from (x1, y1) to (x2, y2). Optional `durationMs` clamped to 1-10000.",
+        inputShape: {
+            ...segment,
+            durationMs: durationMsField,
+        },
+        annotations: { ...MUTATING, title: "Swipe" },
+        requires: "swipe",
+        handler: async (args, { backend }) => {
+            await backend.swipe(num(args, "x1"), num(args, "y1"), num(args, "x2"), num(args, "y2"), optNum(args, "durationMs"));
+            return ack("swipe");
+        },
+    },
+    {
+        name: "scroll",
+        description: "Scroll at (x, y) in `direction` (up | down | left | right). `amount` is a multiplier — each unit ≈ 300 px of swipe distance (default 1). Pass `(0, 0)` to auto-pick the centre of the screen.",
+        inputShape: {
+            x: z.number().optional(),
+            y: z.number().optional(),
+            direction: z.enum(["up", "down", "left", "right"]),
+            amount: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Scroll distance multiplier (≈ 300 px per unit). Default 1; pass 2-3 for long pages."),
+        },
+        annotations: { ...MUTATING, title: "Scroll" },
+        requires: "scroll",
+        handler: async (args, { backend }) => {
+            await backend.scroll(optNum(args, "x") ?? 0, optNum(args, "y") ?? 0, getStr(args, "direction"), optNum(args, "amount"));
+            return ack("scroll");
+        },
+    },
+    /* ---------------- Keyboard ---------------- */
+    {
+        name: "type",
+        description: "Type the given Unicode `text` into the focused field. Set `submit: true` to auto-press ENTER after typing — saves a round-trip on chat / search / login forms.",
+        inputShape: {
+            text: z.string(),
+            submit: z
+                .boolean()
+                .optional()
+                .describe("When true, send a press-ENTER (mobile: KEYCODE_ENTER, desktop: Return) after the text — useful for search bars / chat composers."),
+        },
+        annotations: { ...MUTATING, title: "Type text" },
+        requires: "type",
+        handler: async (args, { backend }) => {
+            await backend.typeText(getStr(args, "text"));
+            if (args.submit === true) {
+                // Mobile uses Android `KEYCODE_ENTER`; desktop accepts the
+                // friendly `Enter` / `Return` strings via their own pressKey
+                // mapping. We try `KEYCODE_ENTER` first, fall back to `Enter`
+                // for desktop backends that don't speak Android keycodes.
+                try {
+                    await backend.pressKey("KEYCODE_ENTER");
+                }
+                catch {
+                    await backend.pressKey("Enter");
+                }
             }
-            await backend.hotkey(...keys);
-            return { ok: true };
+            return ack("type");
+        },
+    },
+    {
+        name: "key",
+        description: "Press a single named key (e.g. `KEYCODE_HOME`, `Escape`).",
+        inputShape: { key: z.string() },
+        annotations: { ...MUTATING, title: "Press key" },
+        requires: "key",
+        handler: async (args, { backend }) => {
+            await backend.pressKey(getStr(args, "key"));
+            return ack("key");
         },
     },
-    /* — system nav — */
-    back: {
-        descriptor: {
-            name: "back",
-            description: "Press the system back button (Android) / browser back.",
-            inputSchema: { type: "object", properties: {} },
+    {
+        name: "hotkey",
+        description: "Press a hotkey combo, e.g. ['Cmd', 'Shift', 'P'].",
+        inputShape: { keys: z.array(z.string()).min(1) },
+        annotations: { ...MUTATING, title: "Press hotkey" },
+        requires: "hotkey",
+        handler: async (args, { backend }) => {
+            const keys = args.keys;
+            await backend.hotkey(...keys);
+            return ack("hotkey");
         },
+    },
+    /* ---------------- System nav ---------------- */
+    {
+        name: "back",
+        description: "Press the system back button (Android) / browser back.",
+        inputShape: {},
+        annotations: { ...MUTATING, title: "Back" },
+        requires: "back",
         handler: async (_args, { backend }) => {
             await backend.back();
-            return { ok: true };
+            return ack("back");
         },
     },
-    home: {
-        descriptor: {
-            name: "home",
-            description: "Press the system home button (Android).",
-            inputSchema: { type: "object", properties: {} },
-        },
+    {
+        name: "home",
+        description: "Press the system home button (Android).",
+        inputShape: {},
+        annotations: { ...MUTATING, title: "Home" },
+        requires: "home",
         handler: async (_args, { backend }) => {
             await backend.home();
-            return { ok: true };
-        },
-    },
-    /* — app — */
-    launch_app: {
-        descriptor: {
-            name: "launch_app",
-            description: "Launch app by package or display name.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    pkg: { type: "string" },
-                    activity: { type: "string" },
-                },
-                required: ["pkg"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.launchApp(s(args, "pkg"), optS(args, "activity"));
-            return { ok: true };
-        },
-    },
-    /* — shell / files — */
-    execute_command: {
-        descriptor: {
-            name: "execute_command",
-            description: "Run a shell command on the sandbox. Returns stdout/stderr/exitCode.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    body: { type: "string" },
-                    timeoutS: { type: "number" },
-                    cwd: { type: "string" },
-                },
-                required: ["body"],
-            },
-        },
-        handler: async (args, { backend }) => backend.executeCommand(s(args, "body"), {
-            timeoutS: optN(args, "timeoutS"),
-            cwd: optS(args, "cwd"),
-        }),
-    },
-    file_read: {
-        descriptor: {
-            name: "file_read",
-            description: "Read a file from the sandbox. Returns base64 content.",
-            inputSchema: {
-                type: "object",
-                properties: { path: { type: "string" } },
-                required: ["path"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            const buf = await backend.fileRead(s(args, "path"));
-            return { contentB64: buf.toString("base64"), bytes: buf.length };
-        },
-    },
-    file_write: {
-        descriptor: {
-            name: "file_write",
-            description: "Write base64 content to a file in the sandbox.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    path: { type: "string" },
-                    contentB64: { type: "string" },
-                },
-                required: ["path", "contentB64"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            const buf = Buffer.from(s(args, "contentB64"), "base64");
-            await backend.fileWrite(s(args, "path"), buf);
-            return { ok: true, bytes: buf.length };
-        },
-    },
-    list_directory: {
-        descriptor: {
-            name: "list_directory",
-            description: "List directory entries.",
-            inputSchema: {
-                type: "object",
-                properties: { path: { type: "string" } },
-                required: ["path"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            const entries = await backend.listDirectory(s(args, "path"));
-            return { entries };
-        },
-    },
-    /**
-     * `install_package` — backend-agnostic native-package install.
-     *
-     * Dispatches to whichever installer the backend implements (APK on
-     * Android, DMG/PKG on macOS, MSI/EXE on Windows, DEB/RPM on Linux).
-     * Wire-compatible alias `install_apk` is kept registered for
-     * existing agents that still hardcode the Android verb name.
-     *
-     * Reference: plan §3.4 — "工具命名上，去掉 backend 私有词".
-     */
-    install_package: installToolEntry("install_package"),
-    install_apk: installToolEntry("install_apk"),
-};
-function installToolEntry(name) {
-    return {
-        descriptor: {
-            name,
-            description: name === "install_package"
-                ? "Install a native package at `path`. Backend-agnostic — dispatches " +
-                    "to APK / DMG / MSI / DEB based on the active backend."
-                : "Install an APK at `path` (Android only). Alias for `install_package`.",
-            inputSchema: {
-                type: "object",
-                properties: { path: { type: "string" } },
-                required: ["path"],
-            },
-        },
-        handler: async (args, { backend }) => {
-            await backend.install(s(args, "path"));
-            return { ok: true };
+            return ack("home");
         },
-    };
-}
+    },
+    /* ---------------- App lifecycle ---------------- */
+    {
+        name: "launch_app",
+        description: "Launch app by package or display name. Optional `locale` (BCP-47, e.g. `fr-FR`, `zh-Hant-TW`) applies a per-app locale on Android 13+ via `cmd locale set-app-locales` (best-effort — silently no-ops on older OS or non-Android backends). Mirrors mobile-mcp's `mobile_launch_app.locale`.",
+        inputShape: {
+            pkg: z.string(),
+            activity: z.string().optional(),
+            locale: z
+                .string()
+                .optional()
+                .describe("BCP-47 locale tag (e.g. `fr-FR`, `de`, `zh-Hant-TW`). Best-effort per-app locale on Android 13+; ignored on older Android, iOS, and desktop."),
+        },
+        annotations: { ...MUTATING, title: "Launch app", openWorldHint: true },
+        requires: "launch_app",
+        handler: async (args, { backend }) => {
+            // r3: locale must match `[a-zA-Z0-9,\\- ]+` so a prompt-injected
+            // `$(...)` value is rejected before it reaches `adb shell`. The
+            // sh\`...\` template literal in android-adb already escapes the
+            // value, so this is defence-in-depth + a clearer error.
+            const rawLocale = optStr(args, "locale");
+            const locale = rawLocale ? assertValidLocale(rawLocale) : undefined;
+            await backend.launchApp(getStr(args, "pkg"), {
+                activity: optStr(args, "activity"),
+                ...(locale !== undefined ? { locale } : {}),
+            });
+            return ack("launch_app");
+        },
+    },
+    {
+        name: "list_apps",
+        description: "List installed apps. Set `includeSystem` to include OS-shipped packages (Android only). Set `launchableOnly` to drop headless system services and return only apps with a launcher activity (mobile-mcp parity, recommended for LLM prompts).",
+        inputShape: {
+            includeSystem: z.boolean().optional(),
+            launchableOnly: z
+                .boolean()
+                .optional()
+                .describe("Android-only: when true, run `cmd package query-activities -a MAIN -c LAUNCHER` and dedupe by package id. Drops headless services / system providers."),
+        },
+        annotations: { ...READ_ONLY, title: "List apps" },
+        requires: "list_apps",
+        handler: async (args, { backend }) => {
+            const includeSystem = args.includeSystem === true;
+            const launchableOnly = args.launchableOnly === true;
+            const apps = await backend.listApps({ includeSystem, launchableOnly });
+            const text = apps.length
+                ? apps
+                    .slice(0, 100)
+                    .map((a) => `${a.packageId}${a.label ? `  ${a.label}` : ""}`)
+                    .join("\n")
+                : "(no apps)";
+            return ok(text, { apps });
+        },
+    },
+    {
+        name: "terminate_app",
+        description: "Force-stop an app by package id (Android `am force-stop`). `pkg` is validated against the Android package-name grammar (`[a-zA-Z0-9._]+`) at the tool boundary (mobile-mcp parity, r3).",
+        inputShape: { pkg: z.string() },
+        annotations: { ...DESTRUCTIVE, title: "Terminate app" },
+        requires: "terminate_app",
+        handler: async (args, { backend }) => {
+            // r3: fail malformed package ids EARLY at the tool boundary —
+            // before the runner shell-escapes them and `pm` returns a vague
+            // "package not found". `terminate_app` does NOT accept display
+            // names so a strict validator is safe here.
+            const pkg = assertValidPackageName(getStr(args, "pkg"));
+            await backend.terminateApp(pkg);
+            return ack("terminate_app");
+        },
+    },
+    {
+        name: "open_url",
+        description: "Open a URL in the platform's default browser / VIEW intent. Mobile uses `am start -a android.intent.action.VIEW`; macOS uses `open`; Linux/Windows are intentionally unsupported on the stub backends. By default only `http`/`https` schemes are accepted — set `BEEOS_DEVICE_ALLOW_UNSAFE_URLS=1` to permit `intent:`/`file:`/custom URLs (mobile-mcp's `MOBILEMCP_ALLOW_UNSAFE_URLS=1` is also honoured).",
+        inputShape: { url: z.string().min(1) },
+        annotations: { ...OPEN_WORLD_READ_ONLY, title: "Open URL" },
+        requires: "open_url",
+        handler: async (args, { backend }) => {
+            // Validate the URL at the registry layer so backends without
+            // native scheme guards (mock desktop / mac / linux / windows)
+            // pick up the same protection as Android.
+            const url = getStr(args, "url");
+            assertSafeUrl(url);
+            await backend.openUrl(url);
+            return ack("open_url");
+        },
+    },
+    /* ---------------- Shell / files ---------------- */
+    {
+        name: "execute_command",
+        description: "Run a shell command on the sandbox. Returns stdout/stderr/exitCode.",
+        inputShape: {
+            body: z.string(),
+            timeoutS: z.number().positive().optional(),
+            cwd: z.string().optional(),
+        },
+        annotations: { ...DESTRUCTIVE, title: "Execute shell command", openWorldHint: true },
+        requires: "execute_command",
+        handler: async (args, { backend }) => {
+            const out = await backend.executeCommand(getStr(args, "body"), {
+                timeoutS: optNum(args, "timeoutS"),
+                cwd: optStr(args, "cwd"),
+            });
+            const text = out.stdout || out.stderr || `exit=${out.exitCode}`;
+            return ok(text, out);
+        },
+    },
+    {
+        name: "file_read",
+        description: "Read a file from the sandbox. Returns base64 content + size.",
+        inputShape: { path: z.string() },
+        annotations: { ...READ_ONLY, title: "Read file" },
+        requires: "file_read",
+        handler: async (args, { backend }) => {
+            const buf = await backend.fileRead(getStr(args, "path"));
+            const result = { contentB64: buf.toString("base64"), bytes: buf.length };
+            return ok(`${buf.length} bytes`, result);
+        },
+    },
+    {
+        name: "file_write",
+        description: "Write base64 content to a file in the sandbox.",
+        inputShape: {
+            path: z.string(),
+            contentB64: z.string(),
+        },
+        annotations: { ...DESTRUCTIVE, title: "Write file" },
+        requires: "file_write",
+        handler: async (args, { backend }) => {
+            const buf = Buffer.from(getStr(args, "contentB64"), "base64");
+            await backend.fileWrite(getStr(args, "path"), buf);
+            return ok(`wrote ${buf.length} bytes`, { ok: true, bytes: buf.length });
+        },
+    },
+    {
+        name: "list_directory",
+        description: "List directory entries.",
+        inputShape: { path: z.string() },
+        annotations: { ...READ_ONLY, title: "List directory" },
+        requires: "list_directory",
+        handler: async (args, { backend }) => {
+            const entries = await backend.listDirectory(getStr(args, "path"));
+            return ok(`${entries.length} entries`, { entries });
+        },
+    },
+    {
+        name: "install_package",
+        description: "Install a native package at `path`. Backend-agnostic — dispatches to APK / DMG / MSI / DEB based on the active backend.",
+        inputShape: { path: z.string() },
+        annotations: { ...DESTRUCTIVE, title: "Install package" },
+        requires: "install_package",
+        handler: async (args, { backend }) => {
+            await backend.install(getStr(args, "path"));
+            return ack("install_package");
+        },
+    },
+    {
+        name: "install_apk",
+        description: "Install an APK at `path` (Android only). Wire-compatible alias for `install_package`.",
+        inputShape: { path: z.string() },
+        annotations: { ...DESTRUCTIVE, title: "Install APK" },
+        requires: "install_apk",
+        handler: async (args, { backend }) => {
+            await backend.install(getStr(args, "path"));
+            return ack("install_apk");
+        },
+    },
+    {
+        name: "uninstall_app",
+        description: "Uninstall an app by package id (Android `adb uninstall`). `pkg` is validated against the Android package-name grammar (`[a-zA-Z0-9._]+`) at the tool boundary (mobile-mcp parity, r3). The dual of `install_apk` — multi-device CI / test flows need both.",
+        inputShape: { pkg: z.string() },
+        annotations: { ...DESTRUCTIVE, title: "Uninstall app" },
+        requires: "uninstall_app",
+        handler: async (args, { backend }) => {
+            const pkg = assertValidPackageName(getStr(args, "pkg"));
+            await backend.uninstallApp(pkg);
+            return ack("uninstall_app");
+        },
+    },
+    /* ---------------- Diagnostics (mobile-mcp parity) ---------------- */
+    {
+        name: "list_crashes",
+        description: "List recent crash / ANR / WTF entries from `dumpsys dropbox`. Returns a `CrashSummary[]` — pass each `id` to `get_crash` for the full body.",
+        inputShape: {},
+        annotations: { ...READ_ONLY, title: "List crashes" },
+        requires: "list_crashes",
+        handler: async (_args, { backend }) => {
+            const crashes = await backend.listCrashes();
+            const text = crashes.length
+                ? crashes
+                    .slice(0, 50)
+                    .map((c) => `${c.timestamp} ${c.type} ${c.app ?? "(no-app)"}  id=${c.id}${c.headline ? `\n  ${c.headline}` : ""}`)
+                    .join("\n")
+                : "(no crashes)";
+            return ok(text, { crashes });
+        },
+    },
+    {
+        name: "get_crash",
+        description: "Fetch the full body (stack trace / log block) of a specific crash entry. `id` comes from `list_crashes`.",
+        inputShape: { id: z.string() },
+        annotations: { ...READ_ONLY, title: "Get crash details" },
+        requires: "get_crash",
+        handler: async (args, { backend }) => {
+            const id = getStr(args, "id");
+            const body = await backend.getCrash(id);
+            return ok(body, { id, body });
+        },
+    },
+    /* ---------------- Screen recording (mobile-mcp parity) ---------------- */
+    {
+        name: "screen_record_start",
+        description: "Start recording the device screen. Returns a `ScreenRecordHandle` whose `id` must be passed to `screen_record_stop`. Each recording is hard-capped at `timeLimitS` seconds (1-300, default 300; matches Android `screenrecord --time-limit` ceiling) — a missed `stop` will not leak space on the device. Optional `output` registers the host-side `.mp4` destination at start time (mobile-mcp parity, r3); when set, `screen_record_stop` writes there unless overridden.",
+        inputShape: {
+            output: z
+                .string()
+                .optional()
+                .describe("Optional host-side destination path (`.mp4`). Sandboxed to cwd / tmpdir / `BEEOS_DEVICE_OUTPUT_DIRS`. When set, `screen_record_stop` writes the pulled MP4 here unless its own `path` overrides."),
+            timeLimitS: z
+                .number()
+                .int()
+                .min(1)
+                .max(300)
+                .optional()
+                .describe("Hard cap on recording length in seconds (1-300, mobile-mcp range). Defaults to the backend default (300s on Android)."),
+        },
+        annotations: { ...MUTATING, title: "Start screen recording" },
+        requires: "screen_record_start",
+        handler: async (args, { backend }) => {
+            // r3: caller may pre-declare the host-side `.mp4` path and the
+            // device-side time-limit. Both pass through their respective
+            // sandboxes / clamps before reaching the backend.
+            const userOutput = optStr(args, "output");
+            const localPath = userOutput
+                ? assertSafeOutputPathWithExt(userOutput, [".mp4"])
+                : undefined;
+            const handle = await backend.startScreenRecord({
+                ...(localPath !== undefined ? { localPath } : {}),
+                ...(args.timeLimitS !== undefined
+                    ? { timeLimitS: optNum(args, "timeLimitS") }
+                    : {}),
+            });
+            return ok(`recording started: id=${handle.id} cap=${handle.timeLimitS}s${handle.localPath ? ` -> ${handle.localPath}` : ""}`, handle);
+        },
+    },
+    {
+        name: "screen_record_stop",
+        description: "Stop the recording started by `screen_record_start`, pull the MP4 to the host filesystem, and return its path / size / duration. Destination resolution: caller-supplied `path` here wins over the start-time `output`; both are sandboxed to cwd / tmpdir / `BEEOS_DEVICE_OUTPUT_DIRS` AND must end in `.mp4` (mobile-mcp parity, r3). When neither is supplied, the backend picks a per-recording temp path.",
+        inputShape: {
+            id: z.string(),
+            path: z
+                .string()
+                .optional()
+                .describe("Optional host-side destination path (`.mp4`). Overrides the start-time `output` when provided. Must resolve under cwd, the system tmpdir, or one of `BEEOS_DEVICE_OUTPUT_DIRS`."),
+        },
+        annotations: { ...MUTATING, title: "Stop screen recording" },
+        requires: "screen_record_stop",
+        handler: async (args, { backend }) => {
+            // r3: extension allow-list (.mp4) on top of the sandbox check —
+            // a screenrecord that lands as `.mov` confuses every player on
+            // earth. Default (no path) lets the backend honour the start-
+            // time `output` (set via screen_record_start) or fall back to a
+            // tmp dir, both already-trusted.
+            const userPath = optStr(args, "path");
+            const safePath = userPath
+                ? assertSafeOutputPathWithExt(userPath, [".mp4"])
+                : undefined;
+            const result = await backend.stopScreenRecord(getStr(args, "id"), {
+                path: safePath,
+            });
+            return ok(`recording saved: ${result.path} (${result.bytes} bytes, ${result.durationMs}ms)`, result);
+        },
+    },
+    /* ---------------- screenshot_to_file ---------------- */
+    {
+        name: "screenshot_to_file",
+        description: "Capture a screenshot and write the encoded bytes directly to a host filesystem `path`. Bypasses the JSON-RPC body cap (16 MB) — use this when an in-band `screenshot` would be too large (4K Android, Retina captures). `path` is sandboxed to cwd / tmpdir / `BEEOS_DEVICE_OUTPUT_DIRS` AND must end in `.png` / `.jpg` / `.jpeg` (mobile-mcp parity, r3).",
+        inputShape: {
+            path: z
+                .string()
+                .describe("Host-side destination path (`.png` / `.jpg` / `.jpeg`). Must resolve under cwd, the system tmpdir, or one of `BEEOS_DEVICE_OUTPUT_DIRS` (`,`/`:`-separated)."),
+            displayId: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Android-only: capture display id N (Android 10+, see `getDisplayCount`). Other backends ignore."),
+        },
+        annotations: { ...READ_ONLY, title: "Save screenshot to file" },
+        requires: "screenshot_to_file",
+        handler: async (args, { backend }) => {
+            // 0.4.1 sandbox + 0.4.1 r3 extension allow-list: caller-supplied
+            // destination must resolve under cwd/tmpdir/BEEOS_DEVICE_OUTPUT_DIRS
+            // AND end in a screenshot extension. The extension check is
+            // mobile-mcp parity (validateFileExtension) — without it, a
+            // prompt-injected agent could write `cute.png.exe` (cwd-relative).
+            const safePath = assertSafeOutputPathWithExt(getStr(args, "path"), [
+                ".png",
+                ".jpg",
+                ".jpeg",
+            ]);
+            const result = await backend.saveScreenshot(safePath, {
+                displayId: optNum(args, "displayId"),
+            });
+            return ok(`wrote ${result.bytes} bytes to ${result.path} (${result.width}x${result.height} ${result.format})`, result);
+        },
+    },
+    /* ---------------- High-level mobile gestures ---------------- */
+    {
+        name: "swipe_direction",
+        description: "High-level swipe in a cardinal `direction` from an optional anchor point. When `x`/`y` are omitted the centre of the screen is used; `distance` defaults to ~30% of the screen edge. Prefer this over the low-level `swipe(x1,y1,x2,y2)` in agent prompts — it's far easier for an LLM to reason about.",
+        inputShape: {
+            direction: z.enum(["up", "down", "left", "right"]),
+            x: z.number().optional(),
+            y: z.number().optional(),
+            distance: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Pixel distance to swipe (default ≈ 30% of screen edge)."),
+            durationMs: durationMsField,
+        },
+        annotations: { ...MUTATING, title: "Swipe in a direction" },
+        requires: "swipe_direction",
+        handler: async (args, { backend }) => {
+            const direction = getStr(args, "direction");
+            // Resolve anchor + distance against the live screen size so the
+            // gesture lands inside the device viewport regardless of which
+            // device the registry routed to.
+            const size = await backend
+                .screenSize()
+                .catch(() => ({ w: 1080, h: 1920 }));
+            const anchorX = optNum(args, "x") ?? Math.round(size.w / 2);
+            const anchorY = optNum(args, "y") ?? Math.round(size.h / 2);
+            const horizontal = direction === "left" || direction === "right";
+            const fallbackDist = Math.max(80, Math.round((horizontal ? size.w : size.h) * 0.3));
+            const dist = optNum(args, "distance") ?? fallbackDist;
+            const dx = direction === "left" ? -dist : direction === "right" ? dist : 0;
+            const dy = direction === "up" ? -dist : direction === "down" ? dist : 0;
+            // Clamp endpoints so we don't try to swipe off the viewport.
+            const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+            const x2 = clamp(anchorX + dx, 0, size.w - 1);
+            const y2 = clamp(anchorY + dy, 0, size.h - 1);
+            await backend.swipe(anchorX, anchorY, x2, y2, optNum(args, "durationMs"));
+            return ack("swipe_direction");
+        },
+    },
+    {
+        name: "press_button",
+        description: "Press a friendly hardware / nav button on the device (BACK / HOME / DPAD_* / VOLUME_* / MEDIA_* / ENTER, …). Mobile-only — desktop backends should use `key`/`hotkey` instead.",
+        inputShape: {
+            button: z
+                .enum(Object.keys(PRESS_BUTTON_KEYMAP))
+                .describe("Friendly button name (case-insensitive)."),
+        },
+        annotations: { ...MUTATING, title: "Press hardware button" },
+        requires: "press_button",
+        handler: async (args, { backend }) => {
+            const name = getStr(args, "button").toUpperCase();
+            const keycode = PRESS_BUTTON_KEYMAP[name];
+            if (!keycode) {
+                throw new DeviceError(`press_button: unknown button '${name}'. Known: ${Object.keys(PRESS_BUTTON_KEYMAP).join(", ")}`, { subtype: "invalid_args", retriable: false });
+            }
+            await backend.pressKey(keycode);
+            return ack("press_button");
+        },
+    },
+    /* ---------------- Desktop pointer / nav ---------------- */
+    {
+        name: "move",
+        description: "Move the pointer to (x, y) without clicking. Desktop only — used for hover triggers, tooltips, and slow-click prelude.",
+        inputShape: { ...xy },
+        annotations: { ...MUTATING, title: "Move pointer" },
+        requires: "move",
+        handler: async (args, { backend }) => {
+            await backend.move(num(args, "x"), num(args, "y"));
+            return ack("move");
+        },
+    },
+    {
+        name: "navigate",
+        description: "Navigate the active surface — `back`/`forward`/`up`. Mobile maps `back` → KEYCODE_BACK, `up` → KEYCODE_HOME (no `forward` analogue). Desktop maps to browser-style hotkeys when implemented.",
+        inputShape: {
+            direction: z.enum(["back", "forward", "up"]),
+        },
+        annotations: { ...MUTATING, title: "Navigate" },
+        requires: "navigate",
+        handler: async (args, { backend }) => {
+            await backend.navigate(getStr(args, "direction"));
+            return ack("navigate");
+        },
+    },
+];
 /* ----------------------------------------------------------------------- */
-/* Public API                                                               */
+/* Public API                                                              */
 /* ----------------------------------------------------------------------- */
 /**
- * Return ALL registered tool descriptors regardless of backend support.
- *
- * Useful for documentation / tests that want to enumerate the catalog.
- * Wire callers SHOULD use `listToolDescriptorsFor(backend)` so the list
- * only contains tools the active backend can actually execute.
+ * Look up a tool spec by name. Used by tests / introspection — production
+ * code goes through `registerAllTools(server, registry)`.
  */
-export function listToolDescriptors() {
-    return Object.values(TOOLS).map((t) => t.descriptor);
-}
-/** Return tool descriptors filtered by the backend's advertised tool set. */
-export function listToolDescriptorsFor(backend) {
-    return Object.values(TOOLS)
-        .filter((t) => backend.tools.has(t.descriptor.name))
-        .map((t) => t.descriptor);
+export function getToolSpec(name) {
+    return TOOL_SPECS.find((t) => t.name === name);
 }
-/** Look up a tool by name, ignoring backend tool-set gates. */
-export function getTool(name) {
-    return TOOLS[name];
+/** Ordered list of every tool name advertised by the server. */
+export function allToolNames() {
+    return TOOL_SPECS.map((t) => t.name);
 }
 /**
- * Look up a tool by name, **gated** on the backend's advertised tool
- * set. Returns `undefined` for tools the active backend cannot
- * satisfy — the `/mcp/tools/call` route uses this and returns 404,
- * mirroring the filtering applied at `/mcp/tools/list`.
+ * Register every tool spec onto the given `McpServer`. Each handler closure
+ * captures the registry so per-call backend resolution stays inside the
+ * tool layer (the SDK itself is backend-agnostic).
+ *
+ * Backend-bound tools are gated on the resolved backend's `tools` set —
+ * if the active backend doesn't advertise the tool we throw a
+ * `DeviceError("unsupported")` so the SDK returns a structured error to
+ * the client. Registry-level tools (`list_available_devices`,
+ * `use_device`) skip this gate.
  */
-export function getToolFor(name, backend) {
-    if (!backend.tools.has(name))
-        return undefined;
-    return TOOLS[name];
+export function registerAllTools(server, registry) {
+    for (const spec of TOOL_SPECS) {
+        const inputShape = {
+            ...spec.inputShape,
+            // Multi-device dispatch hint. Optional — registry.resolve() falls
+            // back to use_device sticky / single-device default when absent.
+            device: z
+                .string()
+                .optional()
+                .describe("Target device id from list_available_devices. Required when more than one device is connected."),
+        };
+        server.registerTool(spec.name, {
+            description: spec.description,
+            inputSchema: inputShape,
+            annotations: spec.annotations,
+        }, async (args, extra) => {
+            const sessionId = extra?.sessionId;
+            const a = (args ?? {});
+            try {
+                if (spec.requires === "registry") {
+                    return await spec.handler(a, {
+                        backend: undefined,
+                        registry,
+                        sessionId,
+                    });
+                }
+                const backend = registry.resolve(a, sessionId);
+                if (!backend.tools.has(spec.requires)) {
+                    throw new DeviceError(`tool '${spec.name}' is not supported by backend '${backend.os}'`, { subtype: "unsupported", retriable: false });
+                }
+                return await spec.handler(a, { backend, registry, sessionId });
+            }
+            catch (e) {
+                // mobile-mcp parity (r3): user-actionable DeviceErrors come
+                // back as plain text WITHOUT `isError: true`, so the LLM can
+                // read the message as a normal observation and react ("install
+                // adb", "approve permission", "fix the path") instead of
+                // surfacing a protocol-level failure to the caller.
+                //
+                // What counts as actionable is decided by `DeviceError`'s
+                // subtype-based default (see `isSubtypeUserActionable` in
+                // common/src/errors.ts) or by an explicit `userActionable`
+                // override at the throw site.
+                //
+                // Anything else (internal errors, raw `Error`s, network
+                // hiccups, screenshot pipeline failures) keeps the existing
+                // `isError: true` path so callers can distinguish "you can
+                // fix this" from "the server hit a real failure".
+                const message = e instanceof Error ? e.message : String(e);
+                if (e instanceof DeviceError && e.userActionable) {
+                    return {
+                        content: [{ type: "text", text: message }],
+                        structuredContent: {
+                            actionable: true,
+                            subtype: e.subtype,
+                            error: message,
+                        },
+                    };
+                }
+                const subtype = e instanceof DeviceError ? e.subtype : "internal_error";
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: message }],
+                    structuredContent: { error: message, subtype },
+                };
+            }
+        });
+    }
 }
 //# sourceMappingURL=tool-registry.js.map