@beeos-ai/device-agent 0.4.2 → 0.5.0

package/dist/shortcuts/builtins/set-clipboard.js

@@ -0,0 +1,112 @@
+/**
+ * Shortcut: `set_clipboard`
+ *
+ * Set the device clipboard contents to a caller-supplied string.
+ *
+ * Why a shortcut:
+ *
+ *   The GUI-only VLM cannot type long strings reliably (especially
+ *   non-Latin scripts and emoji), and the legacy `apply({kind:"type"})`
+ *   path piggybacks on the IME — which on most ROMs strips zero-width
+ *   characters and re-encodes emoji. The shortcut bypasses both
+ *   problems by placing the text on the system clipboard via the ADB
+ *   Keyboard input method's broadcast hook
+ *   (`ime.adb.android.ADB_INPUT_TEXT`); the VLM's later
+ *   long-press → "粘贴 / Paste" works against bit-exact text.
+ *
+ * Compatibility note:
+ *
+ *   ADBKeyboard (com.android.adbkeyboard) must be the active IME for
+ *   the broadcast to take effect. On stock ROMs the user / agent
+ *   needs to install + select it once. When the broadcast is dropped
+ *   silently (no error code from `am`), the shortcut still returns
+ *   `ok: true` because there is no observable failure mode short of
+ *   reading the clipboard back. A future Phase-3 verification step
+ *   may add a clipboard read-back via `cmd clipboard get-text`, but
+ *   per D5 we don't gate on it now.
+ *
+ * Platform: Android only. Desktop has no equivalent ADB-keyboard
+ * primitive; calling the shortcut on a desktop device returns
+ * `unsupported_platform` from the router's platform gate.
+ *
+ * Telemetry: `shortcut.invoke` log line; counter dimension
+ * `shortcut_id="set_clipboard"`.
+ */
+const MAX_TEXT_LEN = 50_000;
+export class SetClipboardShortcut {
+    descriptor = {
+        id: "set_clipboard",
+        displayName: "Set Clipboard",
+        description: "Place arbitrary text (including non-Latin scripts and emoji) on " +
+            "the Android device's clipboard. The VLM can paste it later via " +
+            "long-press. Use this for any long / exotic text input that the " +
+            "GUI keyboard would mangle. Requires ADBKeyboard IME to be the " +
+            "active input method on the device.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                text: {
+                    type: "string",
+                    description: "Verbatim text to place on the clipboard. Up to 50,000 chars.",
+                },
+            },
+            required: ["text"],
+            additionalProperties: false,
+        },
+        kind: "api",
+        platforms: ["android"],
+        timeoutMs: 5_000,
+    };
+    async execute(args, ctx) {
+        if (typeof args?.text !== "string") {
+            return { ok: false, code: "invalid_args", message: "text must be a string" };
+        }
+        if (args.text.length > MAX_TEXT_LEN) {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: `text exceeds ${MAX_TEXT_LEN} chars`,
+            };
+        }
+        if (!ctx.mcp || typeof ctx.mcp.executeCommand !== "function") {
+            return {
+                ok: false,
+                code: "permission_denied",
+                message: "active MCP runtime cannot execute shell commands",
+            };
+        }
+        // Encode text → base64 so single-quote / newline / shell escape
+        // hazards never reach `am broadcast`. ADBKeyboard accepts the
+        // base64 form via `--es msg <b64>` paired with `--ei type 1`
+        // (1 = base64 input).
+        const b64 = Buffer.from(args.text, "utf8").toString("base64");
+        const cmd = `am broadcast -a ADB_INPUT_B64 --es msg ${shellQuote(b64)}`;
+        try {
+            const res = await ctx.mcp.executeCommand(cmd, { timeoutS: 4 });
+            if (res.exitCode !== 0) {
+                return {
+                    ok: false,
+                    code: "intent_rejected",
+                    message: `am broadcast exit=${res.exitCode}: ${res.stderr.trim() || res.stdout.trim()}`,
+                };
+            }
+        }
+        catch (e) {
+            return {
+                ok: false,
+                code: "internal_error",
+                message: e.message,
+            };
+        }
+        return { ok: true, output: { length: args.text.length } };
+    }
+}
+/**
+ * Quote `s` for safe inclusion in a single-quoted shell argument.
+ * The string is base64-encoded ASCII (no quotes possible) but we keep
+ * the quoting defensively in case the encoder ever changes.
+ */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+//# sourceMappingURL=set-clipboard.js.map

package/dist/shortcuts/builtins/set-clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-clipboard.js","sourceRoot":"","sources":["../../../src/shortcuts/builtins/set-clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B,MAAM,OAAO,oBAAoB;IACtB,UAAU,GAAG;QACpB,EAAE,EAAE,eAAe;QACnB,WAAW,EAAE,eAAe;QAC5B,WAAW,EACT,kEAAkE;YAClE,iEAAiE;YACjE,iEAAiE;YACjE,gEAAgE;YAChE,oCAAoC;QACtC,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8DAA8D;iBAC5E;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;YAClB,oBAAoB,EAAE,KAAK;SAC5B;QACD,IAAI,EAAE,KAAc;QACpB,SAAS,EAAE,CAAC,SAAS,CAAU;QAC/B,SAAS,EAAE,KAAK;KACjB,CAAC;IAEF,KAAK,CAAC,OAAO,CACX,IAAsB,EACtB,GAAoB;QAEpB,IAAI,OAAO,IAAI,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;QAC/E,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YACpC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,gBAAgB,YAAY,QAAQ;aAC9C,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;YAC7D,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,mBAAmB;gBACzB,OAAO,EAAE,kDAAkD;aAC5D,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,8DAA8D;QAC9D,6DAA6D;QAC7D,sBAAsB;QACtB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9D,MAAM,GAAG,GACP,0CAA0C,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAE9D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/D,IAAI,GAAG,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EACL,qBAAqB,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE;iBACjF,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAG,CAAW,CAAC,OAAO;aAC9B,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IAC5D,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC"}

package/dist/shortcuts/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * shortcuts/ — Hybrid Action Space barrel.
+ *
+ * Public surface for Phase 2 of the GUI-Shortcut Hybrid Plan. Mirrors
+ * the structure of `resources/index.ts` so callers reach for one
+ * import path and don't have to spelunk into the submodules.
+ */
+export type { Shortcut, ShortcutContext, ShortcutDescriptor, ShortcutDeviceFacade, ShortcutErrorCode, ShortcutFailure, ShortcutJsonSchema, ShortcutKind, ShortcutLogger, ShortcutMcpRuntime, ShortcutPlatform, ShortcutResourceFacade, ShortcutResult, ShortcutSuccess, } from "./types.js";
+export { ShortcutRegistry } from "./registry.js";
+export { ShortcutRouter, type InvokeCallerContext, type ShortcutInvoker, } from "./router.js";
+export { DownloadToDeviceShortcut, FindAppPackageShortcut, OpenDeeplinkShortcut, SetClipboardShortcut, registerBuiltinShortcuts, } from "./builtins/index.js";

package/dist/shortcuts/index.js

@@ -0,0 +1,11 @@
+/**
+ * shortcuts/ — Hybrid Action Space barrel.
+ *
+ * Public surface for Phase 2 of the GUI-Shortcut Hybrid Plan. Mirrors
+ * the structure of `resources/index.ts` so callers reach for one
+ * import path and don't have to spelunk into the submodules.
+ */
+export { ShortcutRegistry } from "./registry.js";
+export { ShortcutRouter, } from "./router.js";
+export { DownloadToDeviceShortcut, FindAppPackageShortcut, OpenDeeplinkShortcut, SetClipboardShortcut, registerBuiltinShortcuts, } from "./builtins/index.js";
+//# sourceMappingURL=index.js.map

package/dist/shortcuts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shortcuts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,cAAc,GAGf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC"}

package/dist/shortcuts/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shortcut registry — owns the in-process catalogue of shortcuts.
+ *
+ * The registry is intentionally tiny: register / unregister / list /
+ * get. There is no recall yet (D7) — the .pi extension reads `list()`
+ * once at session start and synthesises an outer-LLM tool descriptor
+ * for every entry.
+ *
+ * Lifecycle:
+ *   1. Bootstrap constructs ONE registry per device-agent process.
+ *   2. Each phase-2 shortcut module exports a `register(reg)` helper
+ *      that calls `reg.register(new MyShortcut())`. Bootstrap fans out
+ *      to every helper so adding a shortcut is one import + one
+ *      register call away.
+ *   3. The .pi extension reads `reg.list()` and emits descriptors.
+ *   4. The router (`router.ts`) calls `reg.get(id)` on every invoke.
+ *
+ * Recall seam:
+ *
+ *   `recallCandidates(taskHint)` is a no-op stub that returns the full
+ *   list. Phase 3+ can swap the implementation for a real recall (e.g.
+ *   embedding similarity over `descriptor.description`) without
+ *   touching call sites.
+ */
+import type { Shortcut } from "./types.js";
+export declare class ShortcutRegistry {
+    private readonly entries;
+    /**
+     * Register a shortcut. Throws on duplicate id — duplicate registrations
+     * almost always indicate a bootstrap-ordering bug, and the registry
+     * is process-wide so silent overwrites would be invisible.
+     */
+    register<TArgs, TOut>(shortcut: Shortcut<TArgs, TOut>): void;
+    /**
+     * Remove a shortcut by id. Returns true if the id existed. Mostly
+     * used in tests; the production process never tears shortcuts down.
+     */
+    unregister(id: string): boolean;
+    /** Look up a shortcut by id. Undefined when missing. */
+    get(id: string): Shortcut<unknown, unknown> | undefined;
+    /**
+     * Return every registered shortcut in insertion order. The .pi
+     * extension uses this for tool-descriptor generation; tests use it
+     * for snapshot assertions. The returned array is a copy so callers
+     * are free to filter / sort / iterate without disturbing the
+     * registry's internal map.
+     */
+    list(): Shortcut<unknown, unknown>[];
+    /**
+     * Future recall hook. Phase 2 returns the full list verbatim — the
+     * orchestrator gets every shortcut every time, which is fine at 4
+     * entries (D7). Phase 3+ may implement a real recall by replacing
+     * this implementation; downstream code never has to change.
+     */
+    recallCandidates(_taskHint?: string): Shortcut<unknown, unknown>[];
+}

package/dist/shortcuts/registry.js

@@ -0,0 +1,70 @@
+/**
+ * Shortcut registry — owns the in-process catalogue of shortcuts.
+ *
+ * The registry is intentionally tiny: register / unregister / list /
+ * get. There is no recall yet (D7) — the .pi extension reads `list()`
+ * once at session start and synthesises an outer-LLM tool descriptor
+ * for every entry.
+ *
+ * Lifecycle:
+ *   1. Bootstrap constructs ONE registry per device-agent process.
+ *   2. Each phase-2 shortcut module exports a `register(reg)` helper
+ *      that calls `reg.register(new MyShortcut())`. Bootstrap fans out
+ *      to every helper so adding a shortcut is one import + one
+ *      register call away.
+ *   3. The .pi extension reads `reg.list()` and emits descriptors.
+ *   4. The router (`router.ts`) calls `reg.get(id)` on every invoke.
+ *
+ * Recall seam:
+ *
+ *   `recallCandidates(taskHint)` is a no-op stub that returns the full
+ *   list. Phase 3+ can swap the implementation for a real recall (e.g.
+ *   embedding similarity over `descriptor.description`) without
+ *   touching call sites.
+ */
+export class ShortcutRegistry {
+    entries = new Map();
+    /**
+     * Register a shortcut. Throws on duplicate id — duplicate registrations
+     * almost always indicate a bootstrap-ordering bug, and the registry
+     * is process-wide so silent overwrites would be invisible.
+     */
+    register(shortcut) {
+        const id = shortcut.descriptor.id;
+        if (this.entries.has(id)) {
+            throw new Error(`ShortcutRegistry: duplicate shortcut id "${id}" — already registered`);
+        }
+        this.entries.set(id, shortcut);
+    }
+    /**
+     * Remove a shortcut by id. Returns true if the id existed. Mostly
+     * used in tests; the production process never tears shortcuts down.
+     */
+    unregister(id) {
+        return this.entries.delete(id);
+    }
+    /** Look up a shortcut by id. Undefined when missing. */
+    get(id) {
+        return this.entries.get(id);
+    }
+    /**
+     * Return every registered shortcut in insertion order. The .pi
+     * extension uses this for tool-descriptor generation; tests use it
+     * for snapshot assertions. The returned array is a copy so callers
+     * are free to filter / sort / iterate without disturbing the
+     * registry's internal map.
+     */
+    list() {
+        return Array.from(this.entries.values());
+    }
+    /**
+     * Future recall hook. Phase 2 returns the full list verbatim — the
+     * orchestrator gets every shortcut every time, which is fine at 4
+     * entries (D7). Phase 3+ may implement a real recall by replacing
+     * this implementation; downstream code never has to change.
+     */
+    recallCandidates(_taskHint) {
+        return this.list();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/shortcuts/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/shortcuts/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,OAAO,gBAAgB;IACV,OAAO,GAAG,IAAI,GAAG,EAAsC,CAAC;IAEzE;;;;OAIG;IACH,QAAQ,CAAc,QAA+B;QACnD,MAAM,EAAE,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,4CAA4C,EAAE,wBAAwB,CACvE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,QAAsC,CAAC,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,wDAAwD;IACxD,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,SAAkB;QACjC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/shortcuts/router.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shortcut router / invoker — the single call site every entry point
+ * (extension, ACP plugin, future programmatic API) goes through.
+ *
+ * Responsibilities:
+ *
+ *   1. **Lookup** — resolve `id` against the registry; return
+ *      `invalid_args` when the id is unknown so the LLM gets a
+ *      structured error instead of a 500.
+ *   2. **Platform gate** — check the active device's `info.os` /
+ *      `info.type` against the shortcut's `descriptor.platforms`.
+ *      Mismatch → `unsupported_platform`. `"any"` always passes.
+ *   3. **Timeout** — wrap the call in a per-shortcut AbortController
+ *      that honors both `descriptor.timeoutMs` and the host's
+ *      `AbortSignal`. The two are merged by linking listeners.
+ *   4. **Failure shaping** — translate thrown exceptions into
+ *      `ShortcutFailure { code: "internal_error" }` so the LLM never
+ *      sees a stack trace. Aborts (host cancel or local timeout) are
+ *      mapped to `timeout`.
+ *   5. **Telemetry** — emit a structured pino log line on every
+ *      invoke (`event: "shortcut.invoke"`, with id / outcome /
+ *      durationMs). The label set is the same closed vocabulary as
+ *      the metric `device_agent_shortcut_invocation_total` (`ok` plus
+ *      every `ShortcutErrorCode`), so a future Prometheus shim can
+ *      derive the counter directly from log lines.
+ *
+ * Why a router and not just direct `shortcut.execute` calls?
+ *
+ *   The plan deliberately separates the registry (catalogue) from the
+ *   router (call-time concerns). Tests can construct a registry
+ *   without a router; the router can be swapped (e.g. a future
+ *   recall-aware variant) without rewriting every call site. The
+ *   extension only depends on `ShortcutInvoker` — see android-tools.ts.
+ */
+import type { Logger } from "../logger/index.js";
+import type { ShortcutContext, ShortcutResult } from "./types.js";
+import type { ShortcutRegistry } from "./registry.js";
+import type { ShortcutMemoryStore } from "../agent-runtime/shortcuts/index.js";
+export interface ShortcutInvoker {
+    invoke<TOut = unknown>(id: string, args: unknown, callerCtx: InvokeCallerContext): Promise<ShortcutResult<TOut>>;
+    /** Expose the underlying registry for descriptor generation. */
+    readonly registry: ShortcutRegistry;
+}
+export interface ShortcutRouterOptions {
+    /**
+     * Phase 3 telemetry sink. When provided, every invoke increments the
+     * matching counter via `recordSuccess` / `recordFailure`. Failures
+     * inside the store are swallowed — telemetry must never break the
+     * shortcut path.
+     */
+    memoryStore?: ShortcutMemoryStore;
+}
+/**
+ * Minimal context the caller is required to supply on every invoke.
+ * The router fills in the per-call AbortSignal merge and constructs
+ * the final `ShortcutContext` so the shortcut author never has to
+ * thread its own controller chain.
+ */
+export interface InvokeCallerContext {
+    abortSignal: AbortSignal;
+    log: Logger;
+    /** Optional MCP runtime forwarded into `ShortcutContext.mcp`. */
+    mcp?: ShortcutContext["mcp"];
+    /** Optional device facade forwarded into `ShortcutContext.device`. */
+    device?: ShortcutContext["device"];
+    /** Optional resource facade forwarded into `ShortcutContext.resources`. */
+    resources?: ShortcutContext["resources"];
+    /**
+     * Optional digest of the originating user task — used as the memory
+     * store key. Callers SHOULD provide this when memory recording is
+     * enabled; absent, the router records under an empty pattern (still
+     * usable as a global "shortcut X failure rate" counter, just no
+     * task-specific bucketing).
+     */
+    taskPattern?: string;
+}
+export declare class ShortcutRouter implements ShortcutInvoker {
+    readonly registry: ShortcutRegistry;
+    private readonly memoryStore?;
+    constructor(registry: ShortcutRegistry, opts?: ShortcutRouterOptions);
+    invoke<TOut = unknown>(id: string, args: unknown, caller: InvokeCallerContext): Promise<ShortcutResult<TOut>>;
+    /**
+     * Phase 3 — fire-and-forget telemetry write. Errors are swallowed by
+     * the caller via `.catch(() => undefined)` so a malfunctioning store
+     * never blocks the shortcut return path. We still log inside the
+     * store on the way down via its own logger when wired by bootstrap.
+     */
+    private recordMemory;
+    private checkPlatform;
+    private logOutcome;
+}

package/dist/shortcuts/router.js

@@ -0,0 +1,158 @@
+/**
+ * Shortcut router / invoker — the single call site every entry point
+ * (extension, ACP plugin, future programmatic API) goes through.
+ *
+ * Responsibilities:
+ *
+ *   1. **Lookup** — resolve `id` against the registry; return
+ *      `invalid_args` when the id is unknown so the LLM gets a
+ *      structured error instead of a 500.
+ *   2. **Platform gate** — check the active device's `info.os` /
+ *      `info.type` against the shortcut's `descriptor.platforms`.
+ *      Mismatch → `unsupported_platform`. `"any"` always passes.
+ *   3. **Timeout** — wrap the call in a per-shortcut AbortController
+ *      that honors both `descriptor.timeoutMs` and the host's
+ *      `AbortSignal`. The two are merged by linking listeners.
+ *   4. **Failure shaping** — translate thrown exceptions into
+ *      `ShortcutFailure { code: "internal_error" }` so the LLM never
+ *      sees a stack trace. Aborts (host cancel or local timeout) are
+ *      mapped to `timeout`.
+ *   5. **Telemetry** — emit a structured pino log line on every
+ *      invoke (`event: "shortcut.invoke"`, with id / outcome /
+ *      durationMs). The label set is the same closed vocabulary as
+ *      the metric `device_agent_shortcut_invocation_total` (`ok` plus
+ *      every `ShortcutErrorCode`), so a future Prometheus shim can
+ *      derive the counter directly from log lines.
+ *
+ * Why a router and not just direct `shortcut.execute` calls?
+ *
+ *   The plan deliberately separates the registry (catalogue) from the
+ *   router (call-time concerns). Tests can construct a registry
+ *   without a router; the router can be swapped (e.g. a future
+ *   recall-aware variant) without rewriting every call site. The
+ *   extension only depends on `ShortcutInvoker` — see android-tools.ts.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class ShortcutRouter {
+    registry;
+    memoryStore;
+    constructor(registry, opts = {}) {
+        this.registry = registry;
+        if (opts.memoryStore !== undefined) {
+            this.memoryStore = opts.memoryStore;
+        }
+    }
+    async invoke(id, args, caller) {
+        const startedAt = Date.now();
+        const sc = this.registry.get(id);
+        if (!sc) {
+            const fail = makeFailure("invalid_args", `unknown shortcut id: ${id}`);
+            this.logOutcome(caller.log, id, fail, Date.now() - startedAt);
+            return fail;
+        }
+        const platformErr = await this.checkPlatform(sc, caller);
+        if (platformErr) {
+            this.logOutcome(caller.log, id, platformErr, Date.now() - startedAt);
+            return platformErr;
+        }
+        const timeoutMs = sc.descriptor.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const localCtl = new AbortController();
+        const onHostAbort = () => localCtl.abort();
+        if (caller.abortSignal.aborted)
+            localCtl.abort();
+        else
+            caller.abortSignal.addEventListener("abort", onHostAbort, { once: true });
+        const timer = setTimeout(() => localCtl.abort(), timeoutMs);
+        const ctx = {
+            ...(caller.mcp !== undefined ? { mcp: caller.mcp } : {}),
+            ...(caller.device !== undefined ? { device: caller.device } : {}),
+            ...(caller.resources !== undefined ? { resources: caller.resources } : {}),
+            abortSignal: localCtl.signal,
+            log: caller.log,
+        };
+        let outcome;
+        try {
+            const out = await sc.execute(args, ctx);
+            outcome = out;
+        }
+        catch (e) {
+            // Aborts (host cancel + local timeout) collapse to "timeout";
+            // anything else is an unhandled bug and surfaces as
+            // internal_error so the LLM still gets a structured failure.
+            if (localCtl.signal.aborted) {
+                outcome = makeFailure("timeout", `shortcut timed out after ${timeoutMs}ms`);
+            }
+            else {
+                const message = e instanceof Error ? e.message : String(e);
+                outcome = makeFailure("internal_error", message);
+            }
+        }
+        finally {
+            caller.abortSignal.removeEventListener("abort", onHostAbort);
+            clearTimeout(timer);
+        }
+        const durationMs = Date.now() - startedAt;
+        const stamped = withDuration(outcome, durationMs);
+        this.logOutcome(caller.log, id, stamped, durationMs);
+        this.recordMemory(id, stamped, caller).catch(() => undefined);
+        return stamped;
+    }
+    /**
+     * Phase 3 — fire-and-forget telemetry write. Errors are swallowed by
+     * the caller via `.catch(() => undefined)` so a malfunctioning store
+     * never blocks the shortcut return path. We still log inside the
+     * store on the way down via its own logger when wired by bootstrap.
+     */
+    async recordMemory(id, res, caller) {
+        if (!this.memoryStore)
+            return;
+        const pattern = caller.taskPattern ?? "";
+        if (res.ok) {
+            await this.memoryStore.recordSuccess(pattern, id);
+        }
+        else {
+            await this.memoryStore.recordFailure(pattern, id, res.code);
+        }
+    }
+    async checkPlatform(sc, caller) {
+        const platforms = sc.descriptor.platforms;
+        if (platforms.includes("any"))
+            return null;
+        if (!caller.device) {
+            // No device facade — we can't check, so fail closed.
+            return makeFailure("unsupported_platform", `shortcut "${sc.descriptor.id}" requires a device but none is attached`);
+        }
+        let info;
+        try {
+            info = await caller.device.getInfo();
+        }
+        catch (e) {
+            return makeFailure("unsupported_platform", `shortcut "${sc.descriptor.id}" platform check failed: ${e.message}`);
+        }
+        const tag = (info.type ?? info.os ?? "").toLowerCase();
+        const matches = platforms.some((p) => p === "any" || tag.includes(p));
+        if (matches)
+            return null;
+        return makeFailure("unsupported_platform", `shortcut "${sc.descriptor.id}" not supported on platform "${tag}"`);
+    }
+    logOutcome(log, id, res, durationMs) {
+        log.info({
+            event: "shortcut.invoke",
+            shortcut_id: id,
+            result: res.ok ? "ok" : res.code,
+            durationMs,
+        }, "shortcut.invoke");
+    }
+}
+/* -------------------------------------------------------------------- */
+/* Helpers                                                              */
+/* -------------------------------------------------------------------- */
+function makeFailure(code, message) {
+    return { ok: false, code, message };
+}
+function withDuration(res, durationMs) {
+    if (res.ok)
+        return { ...res, durationMs };
+    return { ...res, durationMs };
+}
+//# sourceMappingURL=router.js.map

package/dist/shortcuts/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/shortcuts/router.ts"],"names":[],"mappings":"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"}