@beeos-ai/device-mcp-server 0.2.3

package/dist/util/adb-files.js

@@ -0,0 +1,221 @@
+/**
+ * adb-files — file-IO and listing primitives over the native `adb`
+ * `pull` / `push` / `shell ls` protocols.
+ *
+ * # Why this module exists
+ *
+ * Earlier versions of the Android backend did file IO with two ad-hoc
+ * tricks:
+ *
+ *   - `fileRead` → `adb exec-out cat <path>` and decoded the bytes from
+ *     stdout. This silently swallowed device-side `cat` errors because
+ *     `adb exec-out` does NOT propagate the remote command's exit code
+ *     back to the host adb client (the host always exits 0 when the
+ *     channel closes cleanly), so reading a non-existent path returned
+ *     `cat`'s stderr text base64-encoded as if it were file content.
+ *
+ *   - `fileWrite` → `adb shell sh -c "echo <b64> | base64 -d > <path>"`.
+ *     Because `adb shell` joins argv with spaces and re-evaluates through
+ *     `sh -c`, the shell saw `sh -c sh -c echo <b64> | base64 -d > path`,
+ *     which dropped the pipeline body, ran `sh -c echo` with no args, and
+ *     left an empty file on the device. The bug went undetected because
+ *     the host-side `adb` still returned exit 0.
+ *
+ * The right tools for this job are `adb pull` and `adb push`: they speak
+ * the file-sync protocol designed for binary transfer, the host-side
+ * `adb` exits with a non-zero code when the device-side path is missing
+ * or unwritable, and they side-step the shell tokeniser entirely. This
+ * module wraps those primitives in async-friendly helpers and routes
+ * every error through `wrapAdbFailure` so callers see the familiar
+ * `DeviceError` shape.
+ *
+ * `adbListDir` exists in this module rather than in the backend so the
+ * "use `ls -laL` to dereference symlinks" rule has a single home. The
+ * raw `ls -la` form does not deref symlinks (so listing `/sdcard` returns
+ * the symlink itself instead of the contents of `/storage/self/primary`,
+ * which is almost never what callers want).
+ */
+import { mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DeviceError } from "@beeos-ai/device-common";
+import { sh } from "./adb-shell.js";
+const DEFAULT_PULL_CAP_BYTES = 64 * 1024 * 1024;
+/**
+ * Prepend `["-s", serial]` when a serial is set. Mirrors the private
+ * `adbArgs()` helper in the backend so the helpers here can build their
+ * own argv without leaking the backend's internal state.
+ */
+export function withSerial(serial, args) {
+    return serial ? ["-s", serial, ...args] : [...args];
+}
+/* ----------------------------------------------------------------------- */
+/* Pull / push                                                              */
+/* ----------------------------------------------------------------------- */
+/**
+ * `adb pull <remote> <hostTmp>` followed by an in-memory read of the
+ * temp file. Throws `DeviceError(file_not_found)` when the device path
+ * does not exist (host-side adb exits with code 1 and prints
+ * `adb: error: failed to stat remote object ... No such file or directory`),
+ * and the generic `adb_failed` shape for everything else.
+ */
+export async function adbPull(runner, serial, remote, opts) {
+    const tmpdir = opts.tmpdir?.() ?? os.tmpdir();
+    const stagingDir = await mkdtemp(path.join(tmpdir, "beeos-adb-pull-"));
+    const local = path.join(stagingDir, "data.bin");
+    try {
+        await runner("adb", withSerial(serial, ["pull", remote, local]), {
+            encoding: "utf8",
+            timeoutMs: opts.timeoutMs,
+            maxBufferBytes: opts.maxBufferBytes ?? DEFAULT_PULL_CAP_BYTES,
+        });
+        return await readFile(local);
+    }
+    catch (e) {
+        throw wrapPullPushFailure("pull", remote, e, opts.timeoutMs);
+    }
+    finally {
+        // Best-effort cleanup. Failure to clean up a tmp dir is never the
+        // caller's problem to handle.
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * `adb push <hostTmp> <remote>`. The buffer is written to a temp file
+ * first because `adb push` reads from disk; piping into stdin is not
+ * supported by the file-sync protocol.
+ */
+export async function adbPush(runner, serial, remote, content, opts) {
+    const tmpdir = opts.tmpdir?.() ?? os.tmpdir();
+    const stagingDir = await mkdtemp(path.join(tmpdir, "beeos-adb-push-"));
+    const local = path.join(stagingDir, "data.bin");
+    try {
+        await writeFile(local, content);
+        await runner("adb", withSerial(serial, ["push", local, remote]), {
+            encoding: "utf8",
+            timeoutMs: opts.timeoutMs,
+        });
+    }
+    catch (e) {
+        throw wrapPullPushFailure("push", remote, e, opts.timeoutMs);
+    }
+    finally {
+        await unlink(local).catch(() => undefined);
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/* ----------------------------------------------------------------------- */
+/* List directory                                                           */
+/* ----------------------------------------------------------------------- */
+/**
+ * `ls -laL <path>` over `adb shell` (single-string command, properly
+ * quoted via `sh\`...\``). The `-L` flag dereferences symlinks so callers
+ * who pass `/sdcard` (a symlink to `/storage/self/primary` on stock AOSP)
+ * see the contents of the linked directory rather than a single
+ * `lrwxrwxrwx ... /sdcard -> /storage/self/primary` row.
+ *
+ * The runner contract is: throws on non-zero adb exit (the call site
+ * handles that with `wrapAdbFailure`); on success, parses the textual
+ * output via `parseLsOutput`.
+ */
+export async function adbListDir(runner, serial, pathArg, opts) {
+    const cmd = sh `ls -laL ${pathArg}`;
+    const { stdout } = await runner("adb", withSerial(serial, ["shell", cmd]), {
+        encoding: "utf8",
+        timeoutMs: opts.timeoutMs,
+    });
+    const text = typeof stdout === "string" ? stdout : stdout.toString("utf8");
+    return parseLsOutput(text);
+}
+/**
+ * Parse the output of `ls -la` / `ls -laL` from Android's toybox `ls`
+ * into structured entries. Tolerates header lines (`total 12`) and skips
+ * the canonical `.` / `..` entries.
+ *
+ * Entry layout (toybox): `perms links owner group size month day time name`.
+ * We index by whitespace-split position rather than parsing each column
+ * type-by-type because Android's `ls` output is stable across releases.
+ *
+ * Exported here (not in the backend) so the symlink-dereferencing rule
+ * lives next to the `ls -laL` invocation it depends on.
+ */
+export function parseLsOutput(out) {
+    const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+        if (line.startsWith("total"))
+            continue;
+        const parts = line.split(/\s+/);
+        if (parts.length < 8)
+            continue;
+        const perms = parts[0];
+        const sizeStr = parts[4];
+        const name = parts.slice(7).join(" ");
+        if (!name || name === "." || name === "..")
+            continue;
+        entries.push({
+            name,
+            isDir: perms.startsWith("d"),
+            size: Number(sizeStr) || 0,
+        });
+    }
+    return entries;
+}
+/* ----------------------------------------------------------------------- */
+/* Error normalisation                                                      */
+/* ----------------------------------------------------------------------- */
+/**
+ * Translate `adb pull`/`adb push` failures into the shared `DeviceError`
+ * shape. Mirrors the verb-aware logic in `wrapAdbFailure` (kept duplicated
+ * here on purpose — `adb-shell.ts` is meant to be dependency-free of the
+ * concrete backend module to avoid an import cycle).
+ *
+ * Subtypes:
+ *   - `adb_timeout`            — runner killed by SIGTERM after timeout
+ *   - `adb_not_installed`      — `ENOENT` / non-numeric exit code
+ *   - `file_not_found`         — pull/push exit !=0 with stderr matching
+ *                                 the canonical "no such file" / "failed to
+ *                                 stat" / "remote object does not exist"
+ *                                 messages emitted by adb's file-sync code
+ *   - `adb_failed`             — anything else
+ */
+function wrapPullPushFailure(verb, remote, cause, timeoutMs) {
+    const err = cause;
+    if (err.killed && err.signal === "SIGTERM") {
+        return new DeviceError(`adb ${verb} timed out after ${timeoutMs}ms`, { subtype: "adb_timeout", retriable: true, cause: err });
+    }
+    if (typeof err.code === "string") {
+        return new DeviceError(`adb not installed (${err.code}): ${err.message}`, { subtype: "adb_not_installed", retriable: false, cause: err });
+    }
+    // Some shells / spawn shapes set `code === undefined` when the binary
+    // itself is missing.
+    if (err.code === undefined &&
+        /ENOENT|not found|spawn .*not found/i.test(err.message ?? "")) {
+        return new DeviceError(`adb not installed: ${err.message}`, {
+            subtype: "adb_not_installed",
+            retriable: false,
+            cause: err,
+        });
+    }
+    const stderr = err.stderr?.trim() ?? "";
+    const stdout = typeof err.stdout === "string"
+        ? err.stdout
+        : Buffer.isBuffer(err.stdout)
+            ? err.stdout.toString("utf8")
+            : "";
+    const blob = `${stderr}\n${stdout}`;
+    const isMissing = /no such file or directory/i.test(blob) ||
+        /failed to stat/i.test(blob) ||
+        /does not exist/i.test(blob) ||
+        /remote object .* does not exist/i.test(blob);
+    if (isMissing) {
+        return new DeviceError(`adb ${verb} failed: ${remote}: no such file or directory`, { subtype: "file_not_found", retriable: false, cause: err });
+    }
+    const summary = stderr || err.message || "unknown error";
+    return new DeviceError(`adb ${verb} failed: ${summary}`, {
+        subtype: "adb_failed",
+        retriable: false,
+        cause: err,
+    });
+}
+//# sourceMappingURL=adb-files.js.map

package/dist/util/adb-files.js.map

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

package/dist/util/adb-shell.d.ts

@@ -0,0 +1,80 @@
+/**
+ * adb-shell — quoting + safe command-building primitives for the
+ * `adb shell` protocol.
+ *
+ * # Why this module exists
+ *
+ * The wire reality of `adb shell <argv...>` is treacherous: `adbd` on the
+ * device side joins all argv elements with spaces, then re-evaluates the
+ * resulting string through `/system/bin/sh -c`. Every shell metacharacter
+ * the host passed in (`$`, `` ` ``, `\`, `'`, `"`, `(`, `)`, `;`, `&`, `|`,
+ * `*`, `?`, `#`, whitespace, glob brackets, ...) is therefore re-tokenised
+ * and possibly variable-expanded on the device. Real-world fallout:
+ *
+ *  - `am start -n com.app/.Activity$Sub` → `$Sub` expands to the empty
+ *    string, the activity is silently dropped, the launcher opens instead.
+ *  - `["shell", "sh", "-c", "echo b64 | base64 -d > path"]` → joined to
+ *    `sh -c sh -c echo b64 | base64 -d > path`; the inner `sh -c echo`
+ *    runs with no body, the pipeline drains nothing, the file ends up
+ *    empty.
+ *
+ * The contract this module enforces:
+ *
+ *  1. Backend code MUST NOT call `adb` with `["shell", argv1, argv2, ...]`
+ *     (more than two elements). The only allowed shape is
+ *     `["shell", "<single command string>"]`. The `assertShellSingleString`
+ *     helper makes this an executable invariant in tests.
+ *  2. The single command string MUST be built with `sh\`...\``
+ *     (tagged-template) or `shellEscape`. Plain string concatenation of
+ *     untrusted values into a shell command is forbidden.
+ *
+ * Both rules are static-friendly: `sh\`...\`` is a tagged template that
+ * the type system can spot, and `assertShellSingleString` runs in every
+ * unit test through the mock runner. The combination eliminates an entire
+ * class of latent injection / silent-corruption bugs (see CHANGELOG 0.2.3).
+ */
+/**
+ * POSIX single-quote escape — the canonical way to embed an arbitrary
+ * string into a `/bin/sh` command line.
+ *
+ *   shellEscape("a'b$c") → "'a'\\''b$c'"
+ *
+ * Single quotes disable every metacharacter inside the quoted span; the
+ * only character that needs splicing is `'` itself, replaced by the
+ * familiar `'\''` four-byte sequence (close-quote, escaped quote, open).
+ */
+export declare function shellEscape(s: string): string;
+/**
+ * Tagged template — builds a shell command string with auto-escaped
+ * interpolated values. Numbers pass through verbatim (they cannot
+ * introduce metacharacters); strings always go through `shellEscape`.
+ *
+ *   sh`am start -n ${component}`
+ *   //         ^ "com.app/.Activity$Sub"
+ *   //   → "am start -n 'com.app/.Activity$Sub'"
+ *
+ *   sh`input swipe ${x1} ${y1} ${x2} ${y2} ${duration}`
+ *   //   → "input swipe 100 200 300 400 250"
+ *
+ * Use this for every command that has a dynamic piece. Static literal
+ * commands (e.g. `wm size`) can be passed as a plain string — but going
+ * through `sh\`...\`` is a no-op cost and keeps the call site uniform.
+ */
+export declare function sh(parts: TemplateStringsArray, ...vals: (string | number)[]): string;
+/**
+ * Test-only invariant — assert that an `adb` argv invocation that targets
+ * the `shell` verb uses the single-string pattern (exactly one argument
+ * after `"shell"`, optionally preceded by `["-s", serial]`).
+ *
+ * Throws an `Error` with a descriptive message when the invariant is
+ * violated. Production code is expected to satisfy it by construction;
+ * the helper exists so tests can wire it through their mock runners and
+ * lock the contract from the outside.
+ *
+ * Examples:
+ *   assertShellSingleString(["shell", "wm size"])                  // ok
+ *   assertShellSingleString(["-s", "abc", "shell", "wm size"])    // ok
+ *   assertShellSingleString(["shell", "am", "start"])             // throws
+ *   assertShellSingleString(["pull", "/x", "/y"])                  // ok (not shell)
+ */
+export declare function assertShellSingleString(args: readonly string[]): void;

package/dist/util/adb-shell.js

@@ -0,0 +1,102 @@
+/**
+ * adb-shell — quoting + safe command-building primitives for the
+ * `adb shell` protocol.
+ *
+ * # Why this module exists
+ *
+ * The wire reality of `adb shell <argv...>` is treacherous: `adbd` on the
+ * device side joins all argv elements with spaces, then re-evaluates the
+ * resulting string through `/system/bin/sh -c`. Every shell metacharacter
+ * the host passed in (`$`, `` ` ``, `\`, `'`, `"`, `(`, `)`, `;`, `&`, `|`,
+ * `*`, `?`, `#`, whitespace, glob brackets, ...) is therefore re-tokenised
+ * and possibly variable-expanded on the device. Real-world fallout:
+ *
+ *  - `am start -n com.app/.Activity$Sub` → `$Sub` expands to the empty
+ *    string, the activity is silently dropped, the launcher opens instead.
+ *  - `["shell", "sh", "-c", "echo b64 | base64 -d > path"]` → joined to
+ *    `sh -c sh -c echo b64 | base64 -d > path`; the inner `sh -c echo`
+ *    runs with no body, the pipeline drains nothing, the file ends up
+ *    empty.
+ *
+ * The contract this module enforces:
+ *
+ *  1. Backend code MUST NOT call `adb` with `["shell", argv1, argv2, ...]`
+ *     (more than two elements). The only allowed shape is
+ *     `["shell", "<single command string>"]`. The `assertShellSingleString`
+ *     helper makes this an executable invariant in tests.
+ *  2. The single command string MUST be built with `sh\`...\``
+ *     (tagged-template) or `shellEscape`. Plain string concatenation of
+ *     untrusted values into a shell command is forbidden.
+ *
+ * Both rules are static-friendly: `sh\`...\`` is a tagged template that
+ * the type system can spot, and `assertShellSingleString` runs in every
+ * unit test through the mock runner. The combination eliminates an entire
+ * class of latent injection / silent-corruption bugs (see CHANGELOG 0.2.3).
+ */
+/**
+ * POSIX single-quote escape — the canonical way to embed an arbitrary
+ * string into a `/bin/sh` command line.
+ *
+ *   shellEscape("a'b$c") → "'a'\\''b$c'"
+ *
+ * Single quotes disable every metacharacter inside the quoted span; the
+ * only character that needs splicing is `'` itself, replaced by the
+ * familiar `'\''` four-byte sequence (close-quote, escaped quote, open).
+ */
+export function shellEscape(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Tagged template — builds a shell command string with auto-escaped
+ * interpolated values. Numbers pass through verbatim (they cannot
+ * introduce metacharacters); strings always go through `shellEscape`.
+ *
+ *   sh`am start -n ${component}`
+ *   //         ^ "com.app/.Activity$Sub"
+ *   //   → "am start -n 'com.app/.Activity$Sub'"
+ *
+ *   sh`input swipe ${x1} ${y1} ${x2} ${y2} ${duration}`
+ *   //   → "input swipe 100 200 300 400 250"
+ *
+ * Use this for every command that has a dynamic piece. Static literal
+ * commands (e.g. `wm size`) can be passed as a plain string — but going
+ * through `sh\`...\`` is a no-op cost and keeps the call site uniform.
+ */
+export function sh(parts, ...vals) {
+    let out = parts[0] ?? "";
+    for (let i = 0; i < vals.length; i++) {
+        const v = vals[i];
+        out +=
+            (typeof v === "number" ? String(v) : shellEscape(String(v))) +
+                (parts[i + 1] ?? "");
+    }
+    return out;
+}
+/**
+ * Test-only invariant — assert that an `adb` argv invocation that targets
+ * the `shell` verb uses the single-string pattern (exactly one argument
+ * after `"shell"`, optionally preceded by `["-s", serial]`).
+ *
+ * Throws an `Error` with a descriptive message when the invariant is
+ * violated. Production code is expected to satisfy it by construction;
+ * the helper exists so tests can wire it through their mock runners and
+ * lock the contract from the outside.
+ *
+ * Examples:
+ *   assertShellSingleString(["shell", "wm size"])                  // ok
+ *   assertShellSingleString(["-s", "abc", "shell", "wm size"])    // ok
+ *   assertShellSingleString(["shell", "am", "start"])             // throws
+ *   assertShellSingleString(["pull", "/x", "/y"])                  // ok (not shell)
+ */
+export function assertShellSingleString(args) {
+    // Strip optional ["-s", "<serial>"] prefix.
+    const rest = args[0] === "-s" ? args.slice(2) : args.slice();
+    if (rest.length === 0 || rest[0] !== "shell")
+        return;
+    if (rest.length !== 2) {
+        throw new Error(`adb shell invariant violated: expected ["shell", "<single command>"], ` +
+            `got ${JSON.stringify(args)}. Use the sh\`...\` tagged template ` +
+            `to build the command instead of passing multiple argv elements.`);
+    }
+}
+//# sourceMappingURL=adb-shell.js.map

package/dist/util/adb-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb-shell.js","sourceRoot":"","sources":["../../src/util/adb-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,EAAE,CAChB,KAA2B,EAC3B,GAAG,IAAyB;IAE5B,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,GAAG;YACD,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5D,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAuB;IAC7D,4CAA4C;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO;IACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,wEAAwE;YACtE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,sCAAsC;YACjE,iEAAiE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/util/android-apps.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Android app name → package mapping. Used by `launchApp()` so callers can say
+ * "WeChat" instead of "com.tencent.mm". Lifted verbatim from the legacy
+ * device-agent's `device/apps.ts`.
+ */
+export declare const APP_PACKAGES: Record<string, string>;
+/** Resolve app name to package, with normalization + fuzzy (substring) fallback. */
+export declare function getAppPackage(appName: string): string | undefined;
+/** Heuristic: looks like an explicit package name (`com.foo.bar`). */
+export declare function looksLikePackage(s: string): boolean;

package/dist/util/android-apps.js

@@ -0,0 +1,103 @@
+/**
+ * Android app name → package mapping. Used by `launchApp()` so callers can say
+ * "WeChat" instead of "com.tencent.mm". Lifted verbatim from the legacy
+ * device-agent's `device/apps.ts`.
+ */
+export const APP_PACKAGES = {
+    // Social & Messaging
+    "微信": "com.tencent.mm",
+    WeChat: "com.tencent.mm",
+    wechat: "com.tencent.mm",
+    QQ: "com.tencent.mobileqq",
+    "微博": "com.sina.weibo",
+    "钉钉": "com.alibaba.android.rimet",
+    DingTalk: "com.alibaba.android.rimet",
+    "飞书": "com.ss.android.lark",
+    Feishu: "com.ss.android.lark",
+    Telegram: "org.telegram.messenger",
+    WhatsApp: "com.whatsapp",
+    Whatsapp: "com.whatsapp",
+    // E-commerce
+    "淘宝": "com.taobao.taobao",
+    "京东": "com.jingdong.app.mall",
+    "拼多多": "com.xunmeng.pinduoduo",
+    "小红书": "com.xingin.xhs",
+    XiaoHongShu: "com.xingin.xhs",
+    xiaohongshu: "com.xingin.xhs",
+    RED: "com.xingin.xhs",
+    Temu: "com.einnovation.temu",
+    temu: "com.einnovation.temu",
+    // Food
+    "美团": "com.sankuai.meituan",
+    "大众点评": "com.dianping.v1",
+    "饿了么": "me.ele",
+    // Maps
+    "高德地图": "com.autonavi.minimap",
+    "百度地图": "com.baidu.BaiduMap",
+    "滴滴出行": "com.sdu.didi.psnger",
+    GoogleMaps: "com.google.android.apps.maps",
+    "Google Maps": "com.google.android.apps.maps",
+    // Travel
+    "携程": "ctrip.android.view",
+    "铁路12306": "com.MobileTicket",
+    "12306": "com.MobileTicket",
+    "去哪儿": "com.Qunar",
+    "去哪儿旅行": "com.Qunar",
+    // Video & Entertainment
+    bilibili: "tv.danmaku.bili",
+    "抖音": "com.ss.android.ugc.aweme",
+    TikTok: "com.zhiliaoapp.musically",
+    "快手": "com.smile.gifmaker",
+    "腾讯视频": "com.tencent.qqlive",
+    "爱奇艺": "com.qiyi.video",
+    "优酷": "com.youku.phone",
+    // Music
+    "网易云音乐": "com.netease.cloudmusic",
+    "QQ音乐": "com.tencent.qqmusic",
+    Spotify: "com.spotify.music",
+    // Finance
+    "支付宝": "com.eg.android.AlipayGphone",
+    Alipay: "com.eg.android.AlipayGphone",
+    "招商银行": "cmb.pb",
+    // Health
+    "微信运动": "com.tencent.mm",
+    // System
+    "设置": "com.android.settings",
+    Settings: "com.android.settings",
+    "系统设置": "com.android.settings",
+    "手机设置": "com.android.settings",
+    SystemSettings: "com.android.settings",
+    "相机": "com.android.camera2",
+    Camera: "com.android.camera2",
+    "图库": "com.android.gallery3d",
+    Gallery: "com.android.gallery3d",
+    // Browsers
+    Chrome: "com.android.chrome",
+    "夸克浏览器": "com.quark.browser",
+    "UC浏览器": "com.UCMobile.intl",
+};
+/** Resolve app name to package, with normalization + fuzzy (substring) fallback. */
+export function getAppPackage(appName) {
+    if (!appName)
+        return undefined;
+    if (APP_PACKAGES[appName])
+        return APP_PACKAGES[appName];
+    const trimmed = appName.trim();
+    if (APP_PACKAGES[trimmed])
+        return APP_PACKAGES[trimmed];
+    const lower = trimmed.toLowerCase();
+    for (const [k, v] of Object.entries(APP_PACKAGES)) {
+        if (k.toLowerCase() === lower)
+            return v;
+    }
+    for (const [k, v] of Object.entries(APP_PACKAGES)) {
+        if (trimmed.includes(k) || k.includes(trimmed))
+            return v;
+    }
+    return undefined;
+}
+/** Heuristic: looks like an explicit package name (`com.foo.bar`). */
+export function looksLikePackage(s) {
+    return /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/i.test(s);
+}
+//# sourceMappingURL=android-apps.js.map

package/dist/util/android-apps.js.map

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

package/dist/util/image-dim.d.ts

@@ -0,0 +1,27 @@
+/**
+ * image-dim — minimal in-memory image-dimension probes used by the
+ * screenshot path.
+ *
+ * Why hand-roll instead of always going through `sharp`?
+ *   - The Android / macOS backends already hold raw PNG bytes from
+ *     `screencap` / `screencapture`. Decoding the entire image just to
+ *     read 8 bytes off the IHDR chunk is wasted CPU on every frame.
+ *   - The fast-path also keeps the screenshot pipeline working on tiny
+ *     fixture buffers in unit tests where calling `sharp` would fail
+ *     (the test PNGs are not full IDAT-bearing images).
+ *
+ * Producers that re-encode (resize / convert format) MUST recompute
+ * dimensions from `sharp` metadata after the conversion — these helpers
+ * are only valid for raw input bytes.
+ */
+/**
+ * Read width / height from a PNG IHDR chunk.
+ *
+ * Layout (RFC 2083): 8-byte signature, then a 4-byte length, the
+ * "IHDR" chunk type, then the 4-byte width and 4-byte height starting
+ * at byte 16. We are deliberately tolerant — anything that does not
+ * match the layout falls back to the canonical Android default
+ * (`1080×1920`) so the screenshot path continues to function with
+ * malformed bytes (the agent layer can still consume the image).
+ */
+export declare function parsePngDimensions(data: Buffer): [number, number];

package/dist/util/image-dim.js

@@ -0,0 +1,37 @@
+/**
+ * image-dim — minimal in-memory image-dimension probes used by the
+ * screenshot path.
+ *
+ * Why hand-roll instead of always going through `sharp`?
+ *   - The Android / macOS backends already hold raw PNG bytes from
+ *     `screencap` / `screencapture`. Decoding the entire image just to
+ *     read 8 bytes off the IHDR chunk is wasted CPU on every frame.
+ *   - The fast-path also keeps the screenshot pipeline working on tiny
+ *     fixture buffers in unit tests where calling `sharp` would fail
+ *     (the test PNGs are not full IDAT-bearing images).
+ *
+ * Producers that re-encode (resize / convert format) MUST recompute
+ * dimensions from `sharp` metadata after the conversion — these helpers
+ * are only valid for raw input bytes.
+ */
+/**
+ * Read width / height from a PNG IHDR chunk.
+ *
+ * Layout (RFC 2083): 8-byte signature, then a 4-byte length, the
+ * "IHDR" chunk type, then the 4-byte width and 4-byte height starting
+ * at byte 16. We are deliberately tolerant — anything that does not
+ * match the layout falls back to the canonical Android default
+ * (`1080×1920`) so the screenshot path continues to function with
+ * malformed bytes (the agent layer can still consume the image).
+ */
+export function parsePngDimensions(data) {
+    try {
+        if (data.length < 24)
+            return [1080, 1920];
+        return [data.readUInt32BE(16), data.readUInt32BE(20)];
+    }
+    catch {
+        return [1080, 1920];
+    }
+}
+//# sourceMappingURL=image-dim.js.map

package/dist/util/image-dim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-dim.js","sourceRoot":"","sources":["../../src/util/image-dim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;YAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/util/ui-xml.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Android uiautomator XML parser + compact LLM-ready formatter.
+ *
+ * Lifted from the legacy `device-agent/src/device/ui-xml.ts`. Used by the
+ * `ui_dump` MCP tool when the caller passes `query` (server-side filtering
+ * keeps the wire payload small).
+ *
+ * Pure data — no IO, no logging, safe to call inside hot paths.
+ */
+import type { UiNode } from "@beeos-ai/device-common";
+/**
+ * Format raw uiautomator XML as a compact one-line-per-node summary suitable
+ * for VLM prompts.
+ */
+export declare function formatUiXmlToolOutput(xml: string, query?: string): string;
+/**
+ * Parse XML and return the structured `UiNode` list (for programmatic use,
+ * e.g. ACP `device/ui-tree`).
+ */
+export declare function searchUiXmlNodes(xml: string, query: string): UiNode[];