@beeos-ai/device-mcp-server 0.3.0 → 0.4.3

package/dist/backends/android-adb.js

@@ -50,9 +50,14 @@
  * agent layer decides whether to resize.
  */
 import { spawn } from "node:child_process";
+import { mkdtemp } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 import { COMMON_TOOLS, DeviceError, MOBILE_TOOLS, } from "@beeos-ai/device-common";
-import { BaseSandboxBackend, } from "./base.js";
+import { BaseSandboxBackend, normalizeLaunchAppOptions, } from "./base.js";
+import { searchUiXmlNodes } from "../util/ui-xml.js";
 const ADB_TOOLS = new Set([
     ...COMMON_TOOLS,
     ...MOBILE_TOOLS,
@@ -63,14 +68,26 @@ import { adbListDir, adbPull, adbPush } from "../util/adb-files.js";
 import { parsePngDimensions } from "../util/image-dim.js";
 const SS_MAX_EDGE_RAW = process.env.GUI_AGENT_SS_MAX_EDGE;
 /**
- * Resize-on-capture threshold for screenshots. v0.2.3 changes the default
- * from `1280` to "no resize" (`POSITIVE_INFINITY`) so the bytes the agent
- * receives match the device's logical dimensions exactly. Set the env to
- * an integer (e.g. `1280`) to opt back into resizing.
+ * Resize-on-capture threshold for screenshots.
+ *
+ * 0.4.0 (paired with the SDK migration that removes the binary
+ * `/screen.png` fast-path): default back to **1280px max edge** so the
+ * base64 payload over the SDK Streamable HTTP transport stays bounded.
+ * Capturing a raw 4K Android screenshot every step balloons the JSON-RPC
+ * envelope to ~4MB which dominates round-trip time on slow links.
+ *
+ * Override via env:
+ *  - `GUI_AGENT_SS_MAX_EDGE=4096` to keep full resolution
+ *  - `GUI_AGENT_SS_MAX_EDGE=0` (or negative) to disable resizing entirely
  */
-const SS_MAX_EDGE = SS_MAX_EDGE_RAW
-    ? parseInt(SS_MAX_EDGE_RAW, 10)
-    : Number.POSITIVE_INFINITY;
+const SS_MAX_EDGE = (() => {
+    if (SS_MAX_EDGE_RAW === undefined)
+        return 1280;
+    const n = parseInt(SS_MAX_EDGE_RAW, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return Number.POSITIVE_INFINITY;
+    return n;
+})();
 const SS_JPEG_QUALITY = parseInt(process.env.GUI_AGENT_SS_JPEG_QUALITY ?? "80", 10);
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
@@ -93,6 +110,83 @@ const DELAYS = {
     keyboardRestore: 300,
 };
 /* ----------------------------------------------------------------------- */
+/* Known browser packages — browser-specific launch fallback                */
+/* ----------------------------------------------------------------------- */
+const BROWSER_PACKAGES = new Set([
+    "com.android.chrome",
+    "com.android.browser",
+    "org.mozilla.firefox",
+    "org.mozilla.firefox_beta",
+    "org.mozilla.fenix",
+    "com.microsoft.emmx",
+    "com.opera.browser",
+    "com.opera.mini.native",
+    "com.UCMobile.intl",
+    "com.UCMobile",
+    "com.quark.browser",
+    "com.baidu.searchbox",
+    "com.brave.browser",
+    "com.duckduckgo.mobile.android",
+    "com.vivaldi.browser",
+    "com.sec.android.app.sbrowser",
+    "com.huawei.browser",
+    "com.mi.globalbrowser",
+    "com.heytap.browser",
+    "com.vivo.browser",
+]);
+/* ----------------------------------------------------------------------- */
+/* uiautomator dump retry — 0.4.1                                           */
+/* ----------------------------------------------------------------------- */
+/**
+ * `uiautomator dump` racing the foreground accessibility window can return
+ * `ERROR: null root node returned by UiTestAutomationBridge` (real-device
+ * regression on devices with frequent fullscreen transitions). Mobile-mcp
+ * documents the same flake. Retry the dump up to this many times — the
+ * window-state usually settles within 2-3 attempts.
+ */
+const UIDUMP_MAX_RETRIES = 10;
+const UIDUMP_RETRY_INTERVAL_MS = 200;
+const UIDUMP_RETRY_SUBSTRINGS = [
+    "null root node returned by UiTestAutomationBridge",
+    // toybox `cat` reports this when uiautomator failed to write the file.
+    "No such file or directory",
+];
+/* ----------------------------------------------------------------------- */
+/* press_button keymap — 0.4.1                                              */
+/* ----------------------------------------------------------------------- */
+/**
+ * Friendly button name → Android `KEYCODE_*`. Names are case-insensitive.
+ *
+ * The vocabulary mirrors mobile-mcp `mobile_press_button` so prompts that
+ * already work against mobile-mcp port over without rewording. The
+ * registry exposes `Object.keys(PRESS_BUTTON_KEYMAP)` so the MCP tool's
+ * `enum` is auto-derived rather than maintained in two places.
+ */
+export const PRESS_BUTTON_KEYMAP = {
+    BACK: "KEYCODE_BACK",
+    HOME: "KEYCODE_HOME",
+    POWER: "KEYCODE_POWER",
+    MENU: "KEYCODE_MENU",
+    CAMERA: "KEYCODE_CAMERA",
+    ENTER: "KEYCODE_ENTER",
+    // Volume + media — Android TV agents rely on these.
+    VOLUME_UP: "KEYCODE_VOLUME_UP",
+    VOLUME_DOWN: "KEYCODE_VOLUME_DOWN",
+    VOLUME_MUTE: "KEYCODE_VOLUME_MUTE",
+    MUTE: "KEYCODE_MUTE",
+    MEDIA_PLAY_PAUSE: "KEYCODE_MEDIA_PLAY_PAUSE",
+    MEDIA_PLAY: "KEYCODE_MEDIA_PLAY",
+    MEDIA_PAUSE: "KEYCODE_MEDIA_PAUSE",
+    MEDIA_NEXT: "KEYCODE_MEDIA_NEXT",
+    MEDIA_PREVIOUS: "KEYCODE_MEDIA_PREVIOUS",
+    // DPAD — Android TV / car-head-unit / accessibility navigation.
+    DPAD_UP: "KEYCODE_DPAD_UP",
+    DPAD_DOWN: "KEYCODE_DPAD_DOWN",
+    DPAD_LEFT: "KEYCODE_DPAD_LEFT",
+    DPAD_RIGHT: "KEYCODE_DPAD_RIGHT",
+    DPAD_CENTER: "KEYCODE_DPAD_CENTER",
+};
+/* ----------------------------------------------------------------------- */
 /* Default spawn-backed runner                                              */
 /* ----------------------------------------------------------------------- */
 function defaultRunner(file, args, opts = {}) {
@@ -188,6 +282,14 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
     screenshotTimeoutMs;
     installTimeoutMs;
     fileTimeoutMs;
+    processSpawner;
+    recordKillGraceMs;
+    recordTimeLimitS;
+    recordings = new Map();
+    /** Cached `android.software.leanback` system feature — drives `info().isTv`. */
+    isLeanback = false;
+    /** True after `probeLeanback()` has resolved (success OR failure). */
+    leanbackProbed = false;
     constructor(opts = {}) {
         super();
         this.serial = opts.serial;
@@ -201,6 +303,13 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
             opts.screenshotTimeoutMs ?? DEFAULT_SCREENSHOT_TIMEOUT_MS;
         this.installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
         this.fileTimeoutMs = opts.fileTimeoutMs ?? DEFAULT_FILE_TIMEOUT_MS;
+        // `spawn` itself is overloaded; wrap it so the resolved overload
+        // matches `AdbProcessSpawner`'s `(file, args, opts)` shape.
+        this.processSpawner =
+            opts.processSpawner ??
+                ((file, args, spawnOpts) => spawn(file, args, spawnOpts ?? {}));
+        this.recordKillGraceMs = opts.recordKillGraceMs ?? 5_000;
+        this.recordTimeLimitS = opts.recordTimeLimitS ?? 300;
     }
     async connect() {
         if (this.skipConnectValidation)
@@ -213,6 +322,31 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
             });
         }
     }
+    /**
+     * Detect Android TV / leanback so `info().isTv` can hint at LLM
+     * prompts that should default to DPAD navigation. Cached for the
+     * lifetime of the backend — running `pm has-feature` once per device
+     * is enough; the answer doesn't change at runtime. Lazy on purpose —
+     * `connect()` with `skipConnectValidation: true` (the registry path)
+     * MUST NOT issue any adb commands, so we defer this probe to the
+     * first `info()` call.
+     */
+    async ensureLeanbackProbed() {
+        if (this.leanbackProbed)
+            return;
+        this.leanbackProbed = true;
+        try {
+            const { stdout } = await this.adbShell(sh `pm has-feature android.software.leanback`);
+            const text = stdout.trim().toLowerCase();
+            // Newer Android prints `true` / `false`; older builds emit the
+            // raw feature line `feature:android.software.leanback`. Accept
+            // either positive shape.
+            this.isLeanback = text === "true" || /leanback/.test(text);
+        }
+        catch {
+            this.isLeanback = false;
+        }
+    }
     async disconnect() {
         // No-op — adb daemon stays alive between commands.
     }
@@ -220,11 +354,15 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
     /* Info / screen                                                       */
     /* ------------------------------------------------------------------ */
     async info() {
+        // Lazy leanback probe — see comment on `ensureLeanbackProbed`. Run
+        // it in parallel with the other info shell-outs so the call adds no
+        // latency to the first `info()` invocation.
         const [size, density, propDump, currentApp] = await Promise.all([
             this.runShell("wm size").catch(() => ""),
             this.runShell("wm density").catch(() => ""),
             this.runShell("getprop").catch(() => ""),
             this.getCurrentApp().catch(() => "System Home"),
+            this.ensureLeanbackProbed(),
         ]);
         const sizeMatch = size.match(/Physical size:\s*(\d+)x(\d+)/i);
         const width = sizeMatch ? Number(sizeMatch[1]) : 1080;
@@ -266,37 +404,82 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
                 abi,
                 manufacturer,
                 brand,
+                // 0.4.1: leanback feature is the canonical AOSP marker for TV /
+                // car-head-unit form factors. Surface as a string in `metadata`
+                // (DeviceInfo.metadata is `Record<string, string>` per
+                // common/device-info.ts) so LLM prompts can default to DPAD
+                // navigation without parsing extra fields.
+                isTv: this.isLeanback ? "true" : "false",
             },
         };
     }
-    async screenshot() {
+    async screenshot(opts = {}) {
         // Capture the raw screencap PNG. The 0.2.3 default is to forward
         // these bytes to the agent unchanged so `width/height` always match
         // `data`. Callers that need a smaller payload set
         // `GUI_AGENT_SS_MAX_EDGE` to opt back into the legacy resize path.
-        const raw = await this.captureRawPng();
+        //
+        // 0.4.1: per-call overrides. The MCP tool surfaces `maxEdge`,
+        // `quality`, and `format` so an LLM running on a 4K device can
+        // shrink a single screenshot without restarting the server.
+        //  - `opts.maxEdge` overrides the env default. `0` means "no
+        //    resize", matching the env semantics.
+        //  - `opts.quality` overrides JPEG quality; clamped 1-100 by zod.
+        //  - `opts.format = "jpeg"` forces re-encode even when the image
+        //    is already under the resize threshold (for deterministic
+        //    payload sizing). `"png"` forces raw passthrough.
+        const raw = await this.captureRawPng(opts.displayId);
         const [rawW, rawH] = parsePngDimensions(raw);
-        if (!Number.isFinite(SS_MAX_EDGE) || Math.max(rawW, rawH) <= SS_MAX_EDGE) {
+        const effectiveMaxEdge = (() => {
+            if (opts.maxEdge !== undefined) {
+                return opts.maxEdge <= 0 ? Number.POSITIVE_INFINITY : opts.maxEdge;
+            }
+            return SS_MAX_EDGE;
+        })();
+        const effectiveQuality = (() => {
+            const q = opts.quality;
+            if (q !== undefined)
+                return Math.max(1, Math.min(100, Math.round(q)));
+            return SS_JPEG_QUALITY;
+        })();
+        const formatHint = opts.format;
+        const exceedsCap = Number.isFinite(effectiveMaxEdge) &&
+            Math.max(rawW, rawH) > effectiveMaxEdge;
+        const wantJpeg = formatHint === "jpeg";
+        const wantPngPassthrough = formatHint === "png" && !exceedsCap;
+        // Fast path: caller asked for raw PNG (or default behaviour with
+        // a small enough capture).
+        if (!exceedsCap && !wantJpeg) {
             return { data: raw, width: rawW, height: rawH, format: "png" };
         }
-        // Resize-on-capture path: re-encode to JPEG and recompute dimensions
+        // Caller explicitly asked for `format: "png"` but the capture is
+        // larger than the cap → we still resize, just keep the PNG codec.
+        if (wantPngPassthrough) {
+            return { data: raw, width: rawW, height: rawH, format: "png" };
+        }
+        // Resize-on-capture path: re-encode and recompute dimensions
         // so the wire layer reports the actual encoded payload, not the
         // original device-side resolution.
         try {
             const pipeline = sharp(raw, { failOn: "none" });
-            if (rawW >= rawH)
-                pipeline.resize({ width: SS_MAX_EDGE });
-            else
-                pipeline.resize({ height: SS_MAX_EDGE });
-            const data = await pipeline
-                .jpeg({ quality: SS_JPEG_QUALITY, mozjpeg: true })
-                .toBuffer();
-            const meta = await sharp(data).metadata();
+            if (Number.isFinite(effectiveMaxEdge)) {
+                if (rawW >= rawH)
+                    pipeline.resize({ width: effectiveMaxEdge });
+                else
+                    pipeline.resize({ height: effectiveMaxEdge });
+            }
+            const usePng = formatHint === "png";
+            const encoded = usePng
+                ? await pipeline.png().toBuffer()
+                : await pipeline
+                    .jpeg({ quality: effectiveQuality, mozjpeg: true })
+                    .toBuffer();
+            const meta = await sharp(encoded).metadata();
             return {
-                data,
+                data: encoded,
                 width: meta.width ?? rawW,
                 height: meta.height ?? rawH,
-                format: "jpeg",
+                format: usePng ? "png" : "jpeg",
             };
         }
         catch {
@@ -309,12 +492,50 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
         return { w: m ? Number(m[1]) : 1080, h: m ? Number(m[2]) : 1920 };
     }
     async uiDump() {
-        await this.adbShell(sh `uiautomator dump /sdcard/ui_dump.xml`);
-        const { stdout } = await this.adbShell(sh `cat /sdcard/ui_dump.xml`);
-        if (!stdout || stdout.includes("ERROR")) {
-            return { supported: true };
+        // Mobile-mcp parity: real devices occasionally surface
+        // `null root node returned by UiTestAutomationBridge` while a
+        // fullscreen transition is in flight. Retry up to 10× with a
+        // 200 ms cool-off — the window state always settles within a
+        // few attempts in practice.
+        let lastErr;
+        for (let attempt = 0; attempt < UIDUMP_MAX_RETRIES; attempt++) {
+            try {
+                const { stdout: dumpStdout, stderr: dumpStderr } = await this.adbShell(sh `uiautomator dump /sdcard/ui_dump.xml`);
+                // `uiautomator dump` reports flake on stdout AND stderr depending
+                // on Android version. Check both before assuming success.
+                const dumpBlob = `${dumpStdout}\n${dumpStderr}`;
+                if (UIDUMP_RETRY_SUBSTRINGS.some((s) => dumpBlob.includes(s))) {
+                    await this.sleep(UIDUMP_RETRY_INTERVAL_MS);
+                    continue;
+                }
+                const { stdout } = await this.adbShell(sh `cat /sdcard/ui_dump.xml`);
+                if (!stdout || stdout.includes("ERROR")) {
+                    // Empty / error output — flake; retry.
+                    await this.sleep(UIDUMP_RETRY_INTERVAL_MS);
+                    continue;
+                }
+                if (UIDUMP_RETRY_SUBSTRINGS.some((s) => stdout.includes(s))) {
+                    await this.sleep(UIDUMP_RETRY_INTERVAL_MS);
+                    continue;
+                }
+                return { supported: true, content: stdout.trim() };
+            }
+            catch (e) {
+                lastErr = e;
+                const msg = e instanceof Error ? e.message : String(e);
+                if (UIDUMP_RETRY_SUBSTRINGS.some((s) => msg.includes(s))) {
+                    await this.sleep(UIDUMP_RETRY_INTERVAL_MS);
+                    continue;
+                }
+                // Non-flake error — surface immediately so callers see the
+                // real cause (timeout, adb gone, permission, …).
+                throw e;
+            }
+        }
+        if (lastErr) {
+            throw lastErr;
         }
-        return { supported: true, content: stdout.trim() };
+        return { supported: true };
     }
     /* ------------------------------------------------------------------ */
     /* Pointer / gesture                                                   */
@@ -345,15 +566,18 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
     async drag(x1, y1, x2, y2, durationMs) {
         return this.swipe(x1, y1, x2, y2, durationMs);
     }
-    async scroll(x, y, direction, _amount) {
+    async scroll(x, y, direction, amount) {
         let { w, h } = { w: 1080, h: 1920 };
         if (!x && !y) {
             ({ w, h } = await this.screenSize().catch(() => ({ w: 1080, h: 1920 })));
             x = Math.round(w / 2);
             y = Math.round(h / 2);
         }
-        const horizontal = direction === "left" || direction === "right";
-        const dist = horizontal ? 300 : 600;
+        // 0.4.1: `amount` is now a real multiplier (mobile-mcp parity). Each
+        // unit ≈ 300 px of swipe distance regardless of direction; defaults
+        // to 1 when caller omits it. Previous behaviour silently ignored
+        // `amount` and shipped a fixed 300 px / 600 px asymmetric distance.
+        const dist = Math.max(50, Math.round(300 * (amount ?? 1)));
         const dx = direction === "left" ? dist : direction === "right" ? -dist : 0;
         const dy = direction === "up" ? dist : direction === "down" ? -dist : 0;
         await this.swipe(x, y, x + dx, y + dy);
@@ -422,7 +646,8 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
     /* ------------------------------------------------------------------ */
     /* App lifecycle                                                       */
     /* ------------------------------------------------------------------ */
-    async launchApp(pkgOrName, activity) {
+    async launchApp(pkgOrName, opts) {
+        const { activity, locale } = normalizeLaunchAppOptions(opts);
         const pkg = looksLikePackage(pkgOrName)
             ? pkgOrName
             : (getAppPackage(pkgOrName) ?? pkgOrName);
@@ -437,15 +662,162 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
             const component = activity.includes("/") ? activity : `${pkg}/${activity}`;
             await this.adbShell(sh `am start -n ${component}`);
         }
+        else if (BROWSER_PACKAGES.has(pkg)) {
+            // Browser apps: 3-level fallback so the launch survives devices where
+            // `monkey` flakes (Redroid) or the requested browser isn't installed.
+            //   1. VIEW intent → OS picks the default browser (cheapest, most reliable)
+            //   2. monkey on the requested pkg (original behaviour)
+            //   3. monkey on Chrome as last-resort fallback
+            await this.launchBrowserApp(pkg);
+        }
         else {
             // No activity hint → fall back to the launcher intent. `monkey` is
             // intentionally used here (not `am start`) because some Redroid
             // images have flaky `am` behaviour for LAUNCHER intents and `monkey`
             // is the well-trodden path the legacy adapter has shipped for years.
-            await this.adbShell(sh `monkey -p ${pkg} -c android.intent.category.LAUNCHER 1`);
+            const { stdout } = await this.adbShell(sh `monkey -p ${pkg} -c android.intent.category.LAUNCHER 1`);
+            // `monkey` exits 0 even when it cannot find a launchable activity —
+            // it just prints "** No activities found to run, monkey aborted" to
+            // stdout. Without this check the launch silently "succeeds" and the
+            // agent waits on a screen that never changed (the TikTok no-launch
+            // incident). Surface it as a hard failure with the real reason so the
+            // caller learns the package has no LAUNCHER entry / isn't installed.
+            if (/Error|No activities found/i.test(stdout)) {
+                throw new DeviceError(`launch_app: '${pkg}' has no launchable activity ` +
+                    `(monkey: ${stdout.trim() || "no output"})`, { subtype: "launch_failed", retriable: false });
+            }
+        }
+        // 0.4.1: per-app locale (mobile-mcp parity). Best-effort — Android 12
+        // and below do not have `cmd locale`, so a non-zero exit just means
+        // "the OS predates per-app locales". We swallow that silently and
+        // log so operators can spot the platform mismatch.
+        if (locale && locale.length > 0) {
+            try {
+                await this.adbShell(sh `cmd locale set-app-locales ${pkg} --locales ${locale}`);
+            }
+            catch (e) {
+                // best-effort — do NOT fail the launch; Android 12- silently
+                // returns a non-zero exit on `cmd locale set-app-locales`.
+                // Surface as a debug-level warning so noisy CI doesn't drown
+                // every multi-region test run in stderr.
+                const msg = e instanceof Error ? e.message : String(e);
+                // Use the runner-level log at warn so callers can opt-in via
+                // LOG_LEVEL=warn — this never blocks the launch.
+                // (No structured logger handle here; rely on stderr.)
+                process.stderr.write(`[android] cmd locale set-app-locales failed for ${pkg} (${locale}): ${msg}\n`);
+            }
         }
         await this.sleep(DELAYS.launch);
     }
+    async launchBrowserApp(pkg) {
+        const launched = (await this.tryBrowserLaunch(`am start -a android.intent.action.VIEW -d "https://example.com"`)) ||
+            (await this.tryBrowserLaunch(sh `monkey -p ${pkg} -c android.intent.category.LAUNCHER 1`)) ||
+            (await this.tryBrowserLaunch(`monkey -p com.android.chrome -c android.intent.category.LAUNCHER 1`));
+        if (!launched) {
+            throw new DeviceError(`launch_app: failed to open browser '${pkg}' — all fallbacks exhausted`, { subtype: "launch_failed", retriable: true });
+        }
+    }
+    async tryBrowserLaunch(command) {
+        try {
+            const { stdout } = await this.adbShell(command);
+            return !/Error|No activities found/i.test(stdout);
+        }
+        catch {
+            return false;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /* 0.4.0: cross-OS open_url + mobile-mcp parity                        */
+    /* ------------------------------------------------------------------ */
+    async openUrl(url) {
+        assertSafeUrl(url);
+        await this.adbShell(sh `am start -a android.intent.action.VIEW -d ${url}`);
+    }
+    async listApps(opts = {}) {
+        // 0.4.1 (mobile-mcp parity): `launchableOnly: true` filters to apps
+        // that declare a `MAIN`/`LAUNCHER` activity — drops 200+ headless
+        // system services that pollute `pm list packages`. Implemented via
+        // `cmd package query-activities`, which prints one block per
+        // matching activity with a `packageName=...` line we dedupe on.
+        if (opts.launchableOnly) {
+            const { stdout } = await this.adbShell(sh `cmd package query-activities -a android.intent.action.MAIN -c android.intent.category.LAUNCHER`);
+            const pkgs = new Map();
+            for (const rawLine of stdout.split("\n")) {
+                const line = rawLine.trim();
+                if (!line.startsWith("packageName="))
+                    continue;
+                const pkg = line.slice("packageName=".length).trim();
+                if (!pkg)
+                    continue;
+                // `system` is best-effort here — `query-activities` doesn't
+                // distinguish, so we mark unknown as `false` and let
+                // `includeSystem` consumers re-query if they actually care.
+                if (!pkgs.has(pkg)) {
+                    pkgs.set(pkg, { packageId: pkg, system: false });
+                }
+            }
+            return [...pkgs.values()].sort((a, b) => a.packageId.localeCompare(b.packageId));
+        }
+        // `pm list packages -3` lists user-installed (third-party) packages.
+        // `-s` lists system packages. Default to third-party only — system
+        // apps are 200+ entries on Android and rarely actionable.
+        const args = opts.includeSystem
+            ? sh `pm list packages -f`
+            : sh `pm list packages -3 -f`;
+        const { stdout } = await this.adbShell(args);
+        const pkgs = new Map();
+        for (const line of stdout.split("\n")) {
+            // Format: `package:/data/app/com.foo-1/base.apk=com.foo`
+            const m = line.trim().match(/^package:.*=([\w.\-_]+)\s*$/);
+            if (m && m[1]) {
+                pkgs.set(m[1], { packageId: m[1], system: !!opts.includeSystem });
+            }
+        }
+        return [...pkgs.values()].sort((a, b) => a.packageId.localeCompare(b.packageId));
+    }
+    async terminateApp(pkg) {
+        if (!looksLikePackage(pkg)) {
+            throw new DeviceError(`terminate_app: '${pkg}' is not a valid Android package id`, { subtype: "invalid_args", retriable: false });
+        }
+        await this.adbShell(sh `am force-stop ${pkg}`);
+    }
+    async listElements(opts = {}) {
+        const dump = await this.uiDump();
+        if (!dump.supported || !dump.content)
+            return [];
+        const nodes = searchUiXmlNodes(dump.content, opts.query ?? "");
+        return nodes.map((n) => {
+            const m = n.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+            const [x1, y1, x2, y2] = m
+                ? [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])]
+                : [0, 0, 0, 0];
+            return {
+                text: n.text || undefined,
+                contentDesc: n.contentDesc || undefined,
+                resourceId: n.resourceId || undefined,
+                className: n.className || undefined,
+                center: n.center,
+                rect: {
+                    x: x1,
+                    y: y1,
+                    width: Math.max(0, x2 - x1),
+                    height: Math.max(0, y2 - y1),
+                },
+                clickable: n.clickable,
+            };
+        });
+    }
+    async getOrientation() {
+        const { stdout } = await this.adbShell(sh `settings get system user_rotation`);
+        const code = Number.parseInt(stdout.trim(), 10);
+        return rotationCodeToOrientation(code);
+    }
+    async setOrientation(o) {
+        const code = orientationToRotationCode(o);
+        // Disable accelerometer-driven rotation first so user_rotation sticks.
+        await this.adbShell(sh `settings put system accelerometer_rotation 0`);
+        await this.adbShell(sh `settings put system user_rotation ${String(code)}`);
+    }
     /* ------------------------------------------------------------------ */
     /* Shell / files                                                       */
     /* ------------------------------------------------------------------ */
@@ -525,6 +897,259 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
         }
     }
     /* ------------------------------------------------------------------ */
+    /* 0.4.1: mobile-mcp parity round 2                                    */
+    /* ------------------------------------------------------------------ */
+    async uninstallApp(pkgOrName) {
+        const pkg = looksLikePackage(pkgOrName)
+            ? pkgOrName
+            : (getAppPackage(pkgOrName) ?? pkgOrName);
+        if (!looksLikePackage(pkg)) {
+            throw new DeviceError(`uninstall_app: '${pkgOrName}' is not a valid Android package id`, { subtype: "invalid_args", retriable: false });
+        }
+        try {
+            // `adb uninstall <pkg>` (host-side) is the canonical pair to
+            // `adb install -r`. Going through `pm uninstall` over `adb shell`
+            // is the alternative but requires UID 0 / root for system packages
+            // and silently no-ops without it.
+            await this.runner("adb", this.adbArgs(["uninstall", pkg]), {
+                encoding: "utf8",
+                timeoutMs: this.installTimeoutMs,
+            });
+        }
+        catch (e) {
+            throw wrapAdbFailure("uninstall", ["uninstall", pkg], e, this.installTimeoutMs);
+        }
+    }
+    /**
+     * Parse `dumpsys dropbox --print` and return one entry per recorded
+     * crash / ANR / WTF. The list is best-effort — the dumpsys output
+     * format has shifted slightly across Android releases, so we tolerate
+     * unknown lines instead of rejecting them.
+     */
+    async listCrashes() {
+        const { stdout } = await this.adbShell(sh `dumpsys dropbox --print`);
+        return parseDropboxEntries(stdout);
+    }
+    /**
+     * Re-run `dumpsys dropbox --print` and return the body of the entry
+     * whose `id` matches. Stateless so the result stays correct even if
+     * `listCrashes` was called from a different MCP session.
+     */
+    async getCrash(id) {
+        if (!id) {
+            throw new DeviceError(`get_crash: id is required`, {
+                subtype: "invalid_args",
+                retriable: false,
+            });
+        }
+        const { stdout } = await this.adbShell(sh `dumpsys dropbox --print`);
+        const body = extractDropboxBody(stdout, id);
+        if (!body) {
+            throw new DeviceError(`get_crash: no crash entry with id '${id}'`, { subtype: "invalid_args", retriable: false });
+        }
+        return body;
+    }
+    /**
+     * Spawn `adb shell screenrecord` for a single recording. The device
+     * enforces a hard `--time-limit` (default 5 min, capped at 300s by
+     * Android itself); the host sends SIGINT on `stopScreenRecord` and
+     * falls back to SIGKILL after `recordKillGraceMs` if the child
+     * hasn't exited.
+     *
+     * The same-pid `screenrecord` invocation also lets us pipe the output
+     * to a `/sdcard/<id>.mp4` so `adb pull` after stop can fetch the
+     * exact file without guessing names.
+     *
+     * `opts.timeLimitS` (mobile-mcp parity, r3): caller-supplied cap,
+     * clamped into `[1, 300]` and passed to `screenrecord --time-limit`.
+     * `opts.localPath`: caller-supplied host-side destination registered
+     * at start time. Already passed through `assertSafeOutputPathWithExt`
+     * — backend treats as trusted.
+     */
+    async startScreenRecord(opts = {}) {
+        const id = `beeos-rec-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        const remotePath = `/sdcard/${id}.mp4`;
+        // Clamp into the 1-300s range Android `screenrecord` enforces. We
+        // do the clamp inside the backend (not just at the tool boundary)
+        // so direct backend callers — tests, future server APIs — get the
+        // same safety net.
+        const requested = opts.timeLimitS ?? this.recordTimeLimitS;
+        const limit = Math.min(300, Math.max(1, Math.floor(requested)));
+        const args = this.adbArgs([
+            "shell",
+            // Keep one single quoted shell command — adb shell joins argv
+            // with spaces and re-evaluates through `sh -c`, so multiple
+            // tokens here would be silently re-tokenised on the device side.
+            sh `screenrecord --time-limit ${limit} ${remotePath}`,
+        ]);
+        const child = this.processSpawner("adb", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (!child.pid) {
+            throw new DeviceError(`screen_record_start: failed to spawn adb`, {
+                subtype: "environment",
+                retriable: true,
+            });
+        }
+        const exitPromise = new Promise((resolve) => {
+            // We deliberately resolve on either `close` or `exit` — different
+            // stdio shapes on Linux vs macOS sequence them differently.
+            const done = () => resolve();
+            child.once("close", done);
+            child.once("exit", done);
+            child.once("error", done);
+        });
+        const entry = {
+            id,
+            startedAt: Date.now(),
+            remotePath,
+            child,
+            exitPromise,
+            timeLimitS: limit,
+            localPath: opts.localPath,
+        };
+        this.recordings.set(id, entry);
+        // Detach stderr so the listener doesn't keep the process alive
+        // unnecessarily but we still drain it to avoid a back-pressure
+        // deadlock.
+        child.stdout?.resume();
+        child.stderr?.resume();
+        return {
+            id,
+            startedAt: entry.startedAt,
+            timeLimitS: entry.timeLimitS,
+            remotePath: entry.remotePath,
+            ...(entry.localPath !== undefined ? { localPath: entry.localPath } : {}),
+        };
+    }
+    async stopScreenRecord(id, opts = {}) {
+        const entry = this.recordings.get(id);
+        if (!entry) {
+            throw new DeviceError(`screen_record_stop: no recording with id '${id}'`, { subtype: "invalid_args", retriable: false });
+        }
+        this.recordings.delete(id);
+        // Polite stop first — adb shell forwards SIGINT to the device-side
+        // `screenrecord`, which flushes the MP4 trailer. Then escalate to
+        // SIGKILL after a grace period so we never wedge a recording on a
+        // misbehaving device.
+        const tryKill = (sig) => {
+            try {
+                entry.child.kill(sig);
+            }
+            catch {
+                /* swallow — child already exited */
+            }
+        };
+        tryKill("SIGINT");
+        const killTimer = setTimeout(() => tryKill("SIGKILL"), this.recordKillGraceMs);
+        try {
+            await entry.exitPromise;
+        }
+        finally {
+            clearTimeout(killTimer);
+        }
+        // Determine the host-side destination. Priority order:
+        //   1. `opts.path` from this stop call (overrides the start-time
+        //      registration so a caller can re-target a recording at the
+        //      last moment without losing the kill+pull machinery).
+        //   2. `entry.localPath` registered at start time (mobile-mcp
+        //      parity, r3) — the start-time path is the canonical mobile-
+        //      mcp design and the one we expose in MCP tool descriptions.
+        //   3. Fresh per-recording tmp dir under `os.tmpdir()`.
+        // All caller-supplied paths have already passed through
+        // `assertSafeOutputPathWithExt` at the tool boundary; the backend
+        // does not re-validate.
+        const localPath = opts.path
+            ? opts.path
+            : (entry.localPath ??
+                (await (async () => {
+                    const dir = await mkdtemp(path.join(os.tmpdir(), "beeos-screenrec-"));
+                    return path.join(dir, `${id}.mp4`);
+                })()));
+        try {
+            await adbPull(this.runner, this.serial, entry.remotePath, {
+                timeoutMs: this.fileTimeoutMs,
+            }).then(async (buf) => {
+                // adbPull returns the bytes — write them to our chosen path.
+                // We do this in a tiny helper here rather than going through
+                // `adb pull <remote> <local>` directly so callers asking for a
+                // specific destination get the exact file there.
+                const { writeFile: wf } = await import("node:fs/promises");
+                await wf(localPath, buf);
+            });
+        }
+        catch (e) {
+            // Best-effort cleanup of the device-side artifact even if the
+            // host pull fails — leaving 5-min MP4s on `/sdcard` is rude.
+            this.adbShell(sh `rm -f ${entry.remotePath}`).catch(() => undefined);
+            throw e;
+        }
+        // Best-effort cleanup of the device-side file once we have the
+        // local copy.
+        this.adbShell(sh `rm -f ${entry.remotePath}`).catch(() => undefined);
+        const { stat } = await import("node:fs/promises");
+        const fstat = await stat(localPath);
+        return {
+            path: localPath,
+            bytes: fstat.size,
+            durationMs: Date.now() - entry.startedAt,
+        };
+    }
+    /**
+     * Capture a screenshot via `adb pull` of `/sdcard/screenshot.png`.
+     * Bypasses the JSON-RPC body cap by writing the bytes straight to a
+     * host filesystem path the caller chose. Useful for 4K Android
+     * captures where base64-over-HTTP would otherwise blow past 16 MB.
+     */
+    async saveScreenshot(localPath, opts = {}) {
+        const remote = `/sdcard/beeos-${Date.now()}-${randomUUID().slice(0, 8)}.png`;
+        // `screencap -p` writes to a path; `-d <id>` selects display.
+        const cmd = opts.displayId !== undefined
+            ? sh `screencap -p -d ${String(opts.displayId)} ${remote}`
+            : sh `screencap -p ${remote}`;
+        await this.adbShell(cmd);
+        try {
+            const buf = await adbPull(this.runner, this.serial, remote, {
+                timeoutMs: this.fileTimeoutMs,
+            });
+            const { writeFile: wf } = await import("node:fs/promises");
+            await wf(localPath, buf);
+            const [w, h] = parsePngDimensions(buf);
+            return {
+                path: localPath,
+                bytes: buf.length,
+                width: w,
+                height: h,
+                format: "png",
+            };
+        }
+        finally {
+            this.adbShell(sh `rm -f ${remote}`).catch(() => undefined);
+        }
+    }
+    /**
+     * Count the number of displays the device exposes. Reads
+     * `dumpsys SurfaceFlinger --display-id` (Android 10+) and falls back
+     * to "1" on older builds where the flag isn't recognised.
+     */
+    async getDisplayCount() {
+        try {
+            const { stdout } = await this.adbShell(sh `dumpsys SurfaceFlinger --display-id`);
+            // Output shape (Android 10+):
+            //   Display 4630946866250191 (HWC display 0): port=0 ...
+            //   Display 4630946866250192 (HWC display 1): port=1 ...
+            const lines = stdout
+                .split("\n")
+                .filter((l) => /^Display\s+\d+/.test(l.trim()));
+            if (lines.length > 0)
+                return lines.length;
+        }
+        catch {
+            /* fall through */
+        }
+        return 1;
+    }
+    /* ------------------------------------------------------------------ */
     /* Internal helpers                                                    */
     /* ------------------------------------------------------------------ */
     async getCurrentApp() {
@@ -560,9 +1185,16 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
             throw wrapAdbFailure("shell", ["shell", command], e, this.shellTimeoutMs);
         }
     }
-    async captureRawPng() {
+    async captureRawPng(displayId) {
+        // Multi-display capture: `screencap -d <id>` first appears on
+        // Android 10+ (API 29). On older builds the flag is silently
+        // ignored and we capture the primary display — that's still a
+        // sensible fallback so we don't gate this behind an SDK check.
+        const cmd = displayId !== undefined
+            ? ["exec-out", "screencap", "-p", "-d", String(displayId)]
+            : ["exec-out", "screencap", "-p"];
         try {
-            const { stdout } = await this.runner("adb", this.adbArgs(["exec-out", "screencap", "-p"]), {
+            const { stdout } = await this.runner("adb", this.adbArgs(cmd), {
                 encoding: "buffer",
                 maxBufferBytes: 32 * 1024 * 1024,
                 timeoutMs: this.screenshotTimeoutMs,
@@ -570,7 +1202,7 @@ export class AndroidAdbBackend extends BaseSandboxBackend {
             return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
         }
         catch (e) {
-            throw wrapAdbFailure("screencap", ["exec-out", "screencap", "-p"], e, this.screenshotTimeoutMs);
+            throw wrapAdbFailure("screencap", cmd, e, this.screenshotTimeoutMs);
         }
     }
     /**
@@ -639,6 +1271,37 @@ function parseGetpropDump(out) {
     }
     return map;
 }
+function rotationCodeToOrientation(code) {
+    switch (code) {
+        case 0:
+            return "portrait";
+        case 1:
+            return "landscape";
+        case 2:
+            return "reverse-portrait";
+        case 3:
+            return "reverse-landscape";
+        default:
+            return "portrait";
+    }
+}
+function orientationToRotationCode(o) {
+    switch (o) {
+        case "portrait":
+            return 0;
+        case "landscape":
+            return 1;
+        case "reverse-portrait":
+            return 2;
+        case "reverse-landscape":
+            return 3;
+        default:
+            throw new DeviceError(`unknown orientation '${o}'`, {
+                subtype: "invalid_args",
+                retriable: false,
+            });
+    }
+}
 /**
  * Local POSIX-quote helper used ONLY by `executeCommand`'s `cwd` prefix.
  * The general-purpose `sh\`...\`` template lives in `util/adb-shell.ts`
@@ -700,18 +1363,36 @@ export function wrapAdbFailure(verb, args, cause, timeoutMs) {
             cause: err,
         });
     }
-    const summary = err.stderr?.trim() || err.message || "unknown error";
+    // Observability: the actionable reason often lives in STDOUT, not stderr —
+    // e.g. `monkey` prints "** No activities found to run, monkey aborted" to
+    // stdout (and frequently exits non-zero with only its verbose arg echo on
+    // the wire). Folding both streams + the exit code into the summary means the
+    // agent (and the message-bus error log) sees WHY the command failed instead
+    // of an opaque arg dump.
+    const stderrTxt = err.stderr?.trim() ?? "";
+    const stdoutTxt = typeof err.stdout === "string"
+        ? err.stdout.trim()
+        : Buffer.isBuffer(err.stdout)
+            ? err.stdout.toString("utf8").trim()
+            : "";
+    const detail = [stderrTxt, stdoutTxt].filter(Boolean).join(" | ");
+    let summary = detail || err.message || "unknown error";
+    if (typeof err.code === "number") {
+        summary = `${summary} (exit ${err.code})`;
+    }
     const subtype = verb === "shell"
         ? "adb_shell_failed"
         : verb === "install"
             ? "adb_install_failed"
-            : verb === "screencap"
-                ? "screenshot_failed"
-                : verb === "devices"
-                    ? "adb_failed"
-                    : verb === "exec-out"
+            : verb === "uninstall"
+                ? "adb_uninstall_failed"
+                : verb === "screencap"
+                    ? "screenshot_failed"
+                    : verb === "devices"
                         ? "adb_failed"
-                        : "adb_failed";
+                        : verb === "exec-out"
+                            ? "adb_failed"
+                            : "adb_failed";
     // Reference unused args param for symmetry with previous signature.
     void args;
     return new DeviceError(`adb ${verb} failed: ${summary}`, {
@@ -720,4 +1401,135 @@ export function wrapAdbFailure(verb, args, cause, timeoutMs) {
         cause: err,
     });
 }
+/* ----------------------------------------------------------------------- */
+/* 0.4.1 helpers — open_url whitelist + dropbox crash parser                */
+/* ----------------------------------------------------------------------- */
+/**
+ * Default URL scheme allow-list for `open_url`. Mirrors mobile-mcp's
+ * default — `http` / `https` only. Operators who need to launch
+ * `intent://` / `file://` / custom schemes set
+ * `BEEOS_DEVICE_ALLOW_UNSAFE_URLS=1` to opt out (mobile-mcp uses
+ * `MOBILEMCP_ALLOW_UNSAFE_URLS=1`; we accept both for compatibility).
+ */
+const SAFE_URL_SCHEMES = new Set(["http", "https"]);
+export function assertSafeUrl(url) {
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+        throw new DeviceError(`open_url: '${url}' is not a fully-qualified URL`, {
+            subtype: "invalid_args",
+            retriable: false,
+        });
+    }
+    // Allow opt-out via either env name so a mobile-mcp prompt that sets
+    // the upstream variable keeps working.
+    if (process.env.BEEOS_DEVICE_ALLOW_UNSAFE_URLS === "1" ||
+        process.env.MOBILEMCP_ALLOW_UNSAFE_URLS === "1") {
+        return;
+    }
+    const colon = url.indexOf(":");
+    const scheme = url.slice(0, colon).toLowerCase();
+    if (!SAFE_URL_SCHEMES.has(scheme)) {
+        throw new DeviceError(`open_url: scheme '${scheme}' is not in the default allow-list ` +
+            `(http/https). Set BEEOS_DEVICE_ALLOW_UNSAFE_URLS=1 to permit ` +
+            `intent:/file:/content:/custom URLs.`, { subtype: "invalid_args", retriable: false });
+    }
+}
+/**
+ * Parse the textual output of `dumpsys dropbox --print` into one
+ * `CrashSummary` per crash / ANR / WTF entry.
+ *
+ * Output shape (Android 7+):
+ *
+ *   2024-08-15 12:34:56 system_app_crash (text, 1234 bytes):
+ *   Process: com.foo.bar
+ *   ...stack trace lines...
+ *   2024-08-15 12:35:00 data_app_anr (text, 5678 bytes):
+ *   ...
+ *
+ * We extract the leading `<timestamp> <tag> (text, N bytes):` row and
+ * include the first non-blank body line as a `headline` for at-a-glance
+ * triage. The id encodes both the tag and the timestamp so `getCrash`
+ * can re-locate the same row on the next `dumpsys` invocation without
+ * holding state.
+ */
+export function parseDropboxEntries(out) {
+    const headerRe = /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?)\s+([A-Za-z0-9_]+)(?:\s*\(text,\s*(\d+)\s*bytes\))?:?\s*$/;
+    const TAG_RE = /(crash|anr|wtf|kernel_panic|tombstone)/i;
+    const lines = out.split(/\r?\n/);
+    const entries = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const m = headerRe.exec(line.trim());
+        if (!m)
+            continue;
+        const tag = m[2];
+        if (!TAG_RE.test(tag))
+            continue;
+        const timestamp = m[1];
+        const bytes = m[3] ? Number(m[3]) : undefined;
+        // Pull a one-line headline from the immediate body — usually the
+        // `Process:` row for crashes and `Cmd line:` for ANRs.
+        let headline;
+        let app;
+        for (let j = i + 1; j < Math.min(lines.length, i + 8); j++) {
+            const body = (lines[j] ?? "").trim();
+            if (!body)
+                continue;
+            if (headerRe.test(body))
+                break;
+            if (!headline)
+                headline = body.length > 240 ? body.slice(0, 240) + "…" : body;
+            const procMatch = /^(?:Process|Cmd ?line):\s*(\S+)/.exec(body);
+            if (procMatch) {
+                app = procMatch[1].split(/[\s,]/)[0];
+                break;
+            }
+        }
+        const type = TAG_RE.exec(tag)?.[1]?.toLowerCase() ?? "crash";
+        entries.push({
+            id: `${tag}:${timestamp}`,
+            type,
+            timestamp,
+            app,
+            headline,
+            bytes,
+        });
+    }
+    // Newest first — dumpsys output is already chronological so we reverse.
+    return entries.reverse();
+}
+/**
+ * Pull the body of a single dumpsys-dropbox entry out of the `--print`
+ * blob, indexed by `<tag>:<timestamp>` (the same id `parseDropboxEntries`
+ * returns). The body is everything between the matching header and the
+ * next entry header.
+ */
+export function extractDropboxBody(out, id) {
+    const colon = id.indexOf(":");
+    if (colon < 0)
+        return undefined;
+    const tag = id.slice(0, colon);
+    const timestamp = id.slice(colon + 1);
+    const headerRe = /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?)\s+([A-Za-z0-9_]+)(?:\s*\(text,\s*\d+\s*bytes\))?:?\s*$/;
+    const lines = out.split(/\r?\n/);
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const m = headerRe.exec(lines[i]?.trim() ?? "");
+        if (!m)
+            continue;
+        if (m[1] === timestamp && m[2] === tag) {
+            startIdx = i + 1;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return undefined;
+    let endIdx = lines.length;
+    for (let j = startIdx; j < lines.length; j++) {
+        if (headerRe.test(lines[j]?.trim() ?? "")) {
+            endIdx = j;
+            break;
+        }
+    }
+    return lines.slice(startIdx, endIdx).join("\n").trim();
+}
 //# sourceMappingURL=android-adb.js.map