@beeos-ai/device-agent 0.4.2 → 0.5.0

package/dist/shortcuts/builtins/find-app-package.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shortcut: `find_app_package`
+ *
+ * Look up Android package names by fuzzy-matching against the output
+ * of `pm list packages`.
+ *
+ * Why a shortcut:
+ *
+ *   The orchestrator often needs the package name to (a) generate a
+ *   deep link with the package as host, (b) issue `monkey -p <pkg> 1`
+ *   to launch an app cold, or (c) reason about which app currently
+ *   owns the foreground. Discovering it from the GUI VLM alone is
+ *   wasteful — the package name is one ADB call away.
+ *
+ * Matching strategy:
+ *
+ *   - Lowercase compare on every package line returned by
+ *     `pm list packages` (one entry per line, prefixed `package:`).
+ *   - Substring match against the user-supplied `query` (lowercased).
+ *   - Returns up to `limit` matches (default 10), preserving original
+ *     order (`pm` returns alphabetical order on most ROMs, which is
+ *     stable enough for the LLM).
+ *
+ * Why fuzzy and not exact:
+ *
+ *   - The LLM rarely knows the exact reverse-domain package; it
+ *     knows fragments like "wechat" / "amap" / "bilibili". Substring
+ *     match is the cheapest heuristic that still works.
+ *   - We do NOT depend on `dumpsys` or `cmd package` — `pm list` is
+ *     supported on Android 5+ without root.
+ *
+ * Failure modes:
+ *
+ *   - No matches → `app_not_found`.
+ *   - `pm list` exit != 0 → `intent_rejected` (mirrors the rest of
+ *     the shortcut contract; the orchestrator can interpret it
+ *     uniformly).
+ *
+ * Platform: Android only.
+ */
+import type { Shortcut, ShortcutContext, ShortcutResult } from "../types.js";
+interface FindAppPackageArgs {
+    query: string;
+    limit?: number;
+}
+interface FindAppPackageOutput {
+    matches: string[];
+    /** Total number of installed packages observed (for telemetry). */
+    totalSeen: number;
+}
+export declare class FindAppPackageShortcut implements Shortcut<FindAppPackageArgs, FindAppPackageOutput> {
+    readonly descriptor: {
+        id: string;
+        displayName: string;
+        description: string;
+        jsonSchema: {
+            type: string;
+            properties: {
+                query: {
+                    type: string;
+                    description: string;
+                };
+                limit: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        kind: "api";
+        platforms: readonly ["android"];
+        timeoutMs: number;
+    };
+    execute(args: FindAppPackageArgs, ctx: ShortcutContext): Promise<ShortcutResult<FindAppPackageOutput>>;
+}
+export {};

package/dist/shortcuts/builtins/find-app-package.js

@@ -0,0 +1,168 @@
+/**
+ * Shortcut: `find_app_package`
+ *
+ * Look up Android package names by fuzzy-matching against the output
+ * of `pm list packages`.
+ *
+ * Why a shortcut:
+ *
+ *   The orchestrator often needs the package name to (a) generate a
+ *   deep link with the package as host, (b) issue `monkey -p <pkg> 1`
+ *   to launch an app cold, or (c) reason about which app currently
+ *   owns the foreground. Discovering it from the GUI VLM alone is
+ *   wasteful — the package name is one ADB call away.
+ *
+ * Matching strategy:
+ *
+ *   - Lowercase compare on every package line returned by
+ *     `pm list packages` (one entry per line, prefixed `package:`).
+ *   - Substring match against the user-supplied `query` (lowercased).
+ *   - Returns up to `limit` matches (default 10), preserving original
+ *     order (`pm` returns alphabetical order on most ROMs, which is
+ *     stable enough for the LLM).
+ *
+ * Why fuzzy and not exact:
+ *
+ *   - The LLM rarely knows the exact reverse-domain package; it
+ *     knows fragments like "wechat" / "amap" / "bilibili". Substring
+ *     match is the cheapest heuristic that still works.
+ *   - We do NOT depend on `dumpsys` or `cmd package` — `pm list` is
+ *     supported on Android 5+ without root.
+ *
+ * Failure modes:
+ *
+ *   - No matches → `app_not_found`.
+ *   - `pm list` exit != 0 → `intent_rejected` (mirrors the rest of
+ *     the shortcut contract; the orchestrator can interpret it
+ *     uniformly).
+ *
+ * Platform: Android only.
+ */
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+export class FindAppPackageShortcut {
+    descriptor = {
+        id: "find_app_package",
+        displayName: "Find App Package",
+        description: "Look up Android package names that contain `query` as a substring. " +
+            "Useful when you know the app by display name / English fragment but " +
+            "need the reverse-domain identifier (`com.tencent.mm`, `com.autonavi.minimap`, " +
+            "etc.) to generate a deep link or launch the app via `monkey -p`. " +
+            "Substring match is case-insensitive; results are returned in the order " +
+            "`pm list packages` emits them.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Substring fragment to match against package names. Case-insensitive.",
+                },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: MAX_LIMIT,
+                    description: `Maximum number of matches to return (default ${DEFAULT_LIMIT}).`,
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        kind: "api",
+        platforms: ["android"],
+        timeoutMs: 10_000,
+    };
+    async execute(args, ctx) {
+        if (typeof args?.query !== "string" || args.query.length === 0) {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: "query must be a non-empty string",
+            };
+        }
+        const limitRaw = args.limit ?? DEFAULT_LIMIT;
+        if (!Number.isInteger(limitRaw) || limitRaw < 1 || limitRaw > MAX_LIMIT) {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: `limit must be an integer in [1, ${MAX_LIMIT}]`,
+            };
+        }
+        if (!ctx.mcp || typeof ctx.mcp.executeCommand !== "function") {
+            return {
+                ok: false,
+                code: "permission_denied",
+                message: "active MCP runtime cannot execute shell commands",
+            };
+        }
+        let res;
+        try {
+            res = await ctx.mcp.executeCommand("pm list packages", { timeoutS: 8 });
+        }
+        catch (e) {
+            return { ok: false, code: "internal_error", message: e.message };
+        }
+        if (res.exitCode !== 0) {
+            return {
+                ok: false,
+                code: "intent_rejected",
+                message: `pm list exit=${res.exitCode}: ${(res.stderr || res.stdout).trim()}`,
+            };
+        }
+        const all = parsePackageList(res.stdout);
+        const needle = args.query.toLowerCase();
+        const matches = [];
+        for (const pkg of all) {
+            if (pkg.toLowerCase().includes(needle)) {
+                matches.push(pkg);
+                if (matches.length >= limitRaw)
+                    break;
+            }
+        }
+        if (matches.length === 0) {
+            return {
+                ok: false,
+                code: "app_not_found",
+                message: `no installed package contains "${args.query}" (scanned ${all.length})`,
+            };
+        }
+        return { ok: true, output: { matches, totalSeen: all.length } };
+    }
+}
+/**
+ * Parse `pm list packages` output. Each line looks like:
+ *
+ *   package:com.android.systemui
+ *   package:com.tencent.mm
+ *   package:com.example.app:1.2.3   (rare but legal — version suffix)
+ *
+ * We strip the `package:` prefix and any trailing `:<version>` / `=<path>`
+ * decorations (`pm list packages -f` adds the path; we never pass `-f`
+ * but we tolerate the shape just in case).
+ */
+function parsePackageList(stdout) {
+    if (!stdout)
+        return [];
+    const out = [];
+    for (const raw of stdout.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const idx = line.indexOf("package:");
+        if (idx < 0)
+            continue;
+        const tail = line.slice(idx + "package:".length);
+        // Strip optional `:<version>` and `=<path>` decorations.
+        const eqIdx = tail.indexOf("=");
+        const colonIdx = tail.indexOf(":");
+        let cut = tail.length;
+        if (colonIdx >= 0)
+            cut = Math.min(cut, colonIdx);
+        if (eqIdx >= 0)
+            cut = Math.min(cut, eqIdx);
+        const pkg = tail.slice(0, cut).trim();
+        if (pkg)
+            out.push(pkg);
+    }
+    return out;
+}
+//# sourceMappingURL=find-app-package.js.map

package/dist/shortcuts/builtins/find-app-package.js.map

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

package/dist/shortcuts/builtins/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Built-in shortcuts (Phase 2 of the GUI-Shortcut Hybrid Plan).
+ *
+ * Adding a shortcut:
+ *  1. Implement `Shortcut` in a new file under this folder.
+ *  2. Export the class here.
+ *  3. Add it to `registerBuiltinShortcuts(reg)` below.
+ *
+ * The bootstrap layer calls `registerBuiltinShortcuts` once on startup
+ * — there is no dynamic-load magic. Tests that need a different set
+ * of shortcuts construct their own `ShortcutRegistry` and register
+ * only what they need.
+ */
+import { ShortcutRegistry } from "../registry.js";
+import { SetClipboardShortcut } from "./set-clipboard.js";
+import { OpenDeeplinkShortcut } from "./open-deeplink.js";
+import { FindAppPackageShortcut } from "./find-app-package.js";
+import { DownloadToDeviceShortcut } from "./download-to-device.js";
+export { SetClipboardShortcut, OpenDeeplinkShortcut, FindAppPackageShortcut, DownloadToDeviceShortcut, };
+/**
+ * Register the four canonical Phase-2 shortcuts.
+ *
+ * Order matters for the LLM tool descriptor list (insertion order is
+ * preserved by the registry). The current ordering puts the most
+ * frequently useful shortcuts first:
+ *
+ *   1. `download_to_device` — most powerful; pairs with most flows
+ *   2. `set_clipboard`      — reliable text-input bypass
+ *   3. `open_deeplink`      — fastest cross-app navigation
+ *   4. `find_app_package`   — supporting query helper for the others
+ */
+export declare function registerBuiltinShortcuts(reg: ShortcutRegistry): void;

package/dist/shortcuts/builtins/index.js

@@ -0,0 +1,37 @@
+/**
+ * Built-in shortcuts (Phase 2 of the GUI-Shortcut Hybrid Plan).
+ *
+ * Adding a shortcut:
+ *  1. Implement `Shortcut` in a new file under this folder.
+ *  2. Export the class here.
+ *  3. Add it to `registerBuiltinShortcuts(reg)` below.
+ *
+ * The bootstrap layer calls `registerBuiltinShortcuts` once on startup
+ * — there is no dynamic-load magic. Tests that need a different set
+ * of shortcuts construct their own `ShortcutRegistry` and register
+ * only what they need.
+ */
+import { SetClipboardShortcut } from "./set-clipboard.js";
+import { OpenDeeplinkShortcut } from "./open-deeplink.js";
+import { FindAppPackageShortcut } from "./find-app-package.js";
+import { DownloadToDeviceShortcut } from "./download-to-device.js";
+export { SetClipboardShortcut, OpenDeeplinkShortcut, FindAppPackageShortcut, DownloadToDeviceShortcut, };
+/**
+ * Register the four canonical Phase-2 shortcuts.
+ *
+ * Order matters for the LLM tool descriptor list (insertion order is
+ * preserved by the registry). The current ordering puts the most
+ * frequently useful shortcuts first:
+ *
+ *   1. `download_to_device` — most powerful; pairs with most flows
+ *   2. `set_clipboard`      — reliable text-input bypass
+ *   3. `open_deeplink`      — fastest cross-app navigation
+ *   4. `find_app_package`   — supporting query helper for the others
+ */
+export function registerBuiltinShortcuts(reg) {
+    reg.register(new DownloadToDeviceShortcut());
+    reg.register(new SetClipboardShortcut());
+    reg.register(new OpenDeeplinkShortcut());
+    reg.register(new FindAppPackageShortcut());
+}
+//# sourceMappingURL=index.js.map

package/dist/shortcuts/builtins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shortcuts/builtins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAqB;IAC5D,GAAG,CAAC,QAAQ,CAAC,IAAI,wBAAwB,EAAE,CAAC,CAAC;IAC7C,GAAG,CAAC,QAAQ,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACzC,GAAG,CAAC,QAAQ,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACzC,GAAG,CAAC,QAAQ,CAAC,IAAI,sBAAsB,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/shortcuts/builtins/open-deeplink.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shortcut: `open_deeplink`
+ *
+ * Open a URI on the device using `am start -a android.intent.action.VIEW`.
+ *
+ * Why a shortcut:
+ *
+ *   Deep links jump straight to the target screen of a target app
+ *   without any navigation steps the VLM would otherwise have to
+ *   click through (typically 3–6 taps on a launcher → app → category
+ *   → search → result). For navigation (`geo:`, `amap://route`),
+ *   payments, sharing flows, etc., this is dramatically faster *and*
+ *   more reliable than visual reasoning.
+ *
+ * Why we accept failure on success:
+ *
+ *   `am start` reports "Starting: Intent {…}" on stdout when it
+ *   *dispatched* the intent — but Android then silently drops
+ *   intents nothing handles. Per D5 we deliberately do NOT try to
+ *   verify post-condition (the plan defers that to phase 3+ when
+ *   we have screenshot-diff or ActivityManager hooks). The shortcut
+ *   succeeds iff `am start` exits 0; if no app handled the intent
+ *   the agent will see it visually on the next screenshot and can
+ *   recover.
+ *
+ * Validation:
+ *
+ *   - URI must parse via `new URL(uri)`.
+ *   - URI must NOT use the `file:` scheme (path-traversal-style
+ *     attacks against `am start -a VIEW`).
+ *   - The whole URI is enforced into the `am start -d <uri>` slot via
+ *     defensive single-quote shell escaping; intent extras are not
+ *     accepted in Phase 2 (kept simple by design).
+ *
+ * Platform: Android only. Desktop has no equivalent.
+ */
+import type { Shortcut, ShortcutContext, ShortcutResult } from "../types.js";
+interface DeeplinkOutput {
+    uri: string;
+    starterStdout: string;
+}
+export declare class OpenDeeplinkShortcut implements Shortcut<{
+    uri: string;
+}, DeeplinkOutput> {
+    readonly descriptor: {
+        id: string;
+        displayName: string;
+        description: string;
+        jsonSchema: {
+            type: string;
+            properties: {
+                uri: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        kind: "deeplink";
+        platforms: readonly ["android"];
+        timeoutMs: number;
+    };
+    execute(args: {
+        uri: string;
+    }, ctx: ShortcutContext): Promise<ShortcutResult<DeeplinkOutput>>;
+}
+export {};

package/dist/shortcuts/builtins/open-deeplink.js

@@ -0,0 +1,142 @@
+/**
+ * Shortcut: `open_deeplink`
+ *
+ * Open a URI on the device using `am start -a android.intent.action.VIEW`.
+ *
+ * Why a shortcut:
+ *
+ *   Deep links jump straight to the target screen of a target app
+ *   without any navigation steps the VLM would otherwise have to
+ *   click through (typically 3–6 taps on a launcher → app → category
+ *   → search → result). For navigation (`geo:`, `amap://route`),
+ *   payments, sharing flows, etc., this is dramatically faster *and*
+ *   more reliable than visual reasoning.
+ *
+ * Why we accept failure on success:
+ *
+ *   `am start` reports "Starting: Intent {…}" on stdout when it
+ *   *dispatched* the intent — but Android then silently drops
+ *   intents nothing handles. Per D5 we deliberately do NOT try to
+ *   verify post-condition (the plan defers that to phase 3+ when
+ *   we have screenshot-diff or ActivityManager hooks). The shortcut
+ *   succeeds iff `am start` exits 0; if no app handled the intent
+ *   the agent will see it visually on the next screenshot and can
+ *   recover.
+ *
+ * Validation:
+ *
+ *   - URI must parse via `new URL(uri)`.
+ *   - URI must NOT use the `file:` scheme (path-traversal-style
+ *     attacks against `am start -a VIEW`).
+ *   - The whole URI is enforced into the `am start -d <uri>` slot via
+ *     defensive single-quote shell escaping; intent extras are not
+ *     accepted in Phase 2 (kept simple by design).
+ *
+ * Platform: Android only. Desktop has no equivalent.
+ */
+const FORBIDDEN_SCHEMES = new Set(["file"]);
+export class OpenDeeplinkShortcut {
+    descriptor = {
+        id: "open_deeplink",
+        displayName: "Open Deeplink",
+        description: "Launch a URI via `am start -a android.intent.action.VIEW -d <uri>` on " +
+            "the connected Android device. Use this for app deep links " +
+            "(`weixin://`, `bilibili://`, `geo:39.9,116.3`, `https://...`) so the " +
+            "agent can skip multi-step manual navigation. Returns once `am start` " +
+            "exits — does NOT verify the target app actually handled the intent.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                uri: {
+                    type: "string",
+                    description: "Fully-qualified URI (any scheme except file://).",
+                },
+            },
+            required: ["uri"],
+            additionalProperties: false,
+        },
+        kind: "deeplink",
+        platforms: ["android"],
+        timeoutMs: 8_000,
+    };
+    async execute(args, ctx) {
+        if (typeof args?.uri !== "string" || args.uri.length === 0) {
+            return { ok: false, code: "invalid_args", message: "uri must be a non-empty string" };
+        }
+        let parsed;
+        try {
+            parsed = new URL(args.uri);
+        }
+        catch {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: `uri is not a valid URL: ${args.uri}`,
+            };
+        }
+        const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+        if (!scheme) {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: "uri is missing a scheme",
+            };
+        }
+        if (FORBIDDEN_SCHEMES.has(scheme)) {
+            return {
+                ok: false,
+                code: "invalid_args",
+                message: `uri scheme "${scheme}" is forbidden`,
+            };
+        }
+        if (!ctx.mcp || typeof ctx.mcp.executeCommand !== "function") {
+            return {
+                ok: false,
+                code: "permission_denied",
+                message: "active MCP runtime cannot execute shell commands",
+            };
+        }
+        const cmd = `am start -a android.intent.action.VIEW -d ${shellQuote(args.uri)}`;
+        try {
+            const res = await ctx.mcp.executeCommand(cmd, { timeoutS: 6 });
+            if (res.exitCode !== 0) {
+                // `am start` returns 0 even when no activity handles the
+                // intent (it just prints "Activity not started, …"). A
+                // non-zero exit therefore really is an OS-level rejection,
+                // mapped to intent_rejected per the plan's error contract.
+                return {
+                    ok: false,
+                    code: "intent_rejected",
+                    message: `am start exit=${res.exitCode}: ${(res.stderr || res.stdout).trim()}`,
+                };
+            }
+            // Detect "no Activity found to handle Intent" in stdout — Android
+            // doesn't surface it as a non-zero exit, but the message is
+            // stable enough for a string match. We map it to app_not_found
+            // so the LLM can fallback to mobile_use.
+            const out = (res.stdout || "").toLowerCase();
+            if (out.includes("error: activity class") || out.includes("does not exist")) {
+                return {
+                    ok: false,
+                    code: "app_not_found",
+                    message: res.stdout.trim(),
+                };
+            }
+            return {
+                ok: true,
+                output: { uri: args.uri, starterStdout: res.stdout },
+            };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                code: "internal_error",
+                message: e.message,
+            };
+        }
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+//# sourceMappingURL=open-deeplink.js.map

package/dist/shortcuts/builtins/open-deeplink.js.map

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

package/dist/shortcuts/builtins/set-clipboard.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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"`.
+ */
+import type { Shortcut, ShortcutContext, ShortcutResult } from "../types.js";
+export declare class SetClipboardShortcut implements Shortcut<{
+    text: string;
+}, {
+    length: number;
+}> {
+    readonly descriptor: {
+        id: string;
+        displayName: string;
+        description: string;
+        jsonSchema: {
+            type: string;
+            properties: {
+                text: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        kind: "api";
+        platforms: readonly ["android"];
+        timeoutMs: number;
+    };
+    execute(args: {
+        text: string;
+    }, ctx: ShortcutContext): Promise<ShortcutResult<{
+        length: number;
+    }>>;
+}