@beeos-ai/device-mcp-server 0.2.3

package/dist/backends/android-adb.js

@@ -0,0 +1,723 @@
+/**
+ * AndroidAdbBackend — concrete `SandboxBackend` over Android `adb`.
+ *
+ * Migrated from the legacy `device-agent` files:
+ *   - `src/device/android.ts`
+ *   - `src/adapters/device-android-adb.ts`
+ *
+ * Owns ALL `adb` invocations. The MCP server is the only process that talks
+ * to the device daemon — `device-agent` reaches it exclusively via HTTP.
+ *
+ * **Testability**: like `MacOsBackend`, the constructor accepts an injected
+ * `runner` (an `execFile`-like async callable). Defaults bind to a
+ * spawn-backed runner. Unit tests pass spy runners so the suite runs
+ * identically on Linux CI without any real `adb` binary on `PATH`.
+ *
+ * **Error normalisation**: every `adb` invocation routes through
+ * `wrapAdbFailure(verb, args, err, timeoutMs)` so callers see a single
+ * `DeviceError` shape regardless of whether the failure came from a
+ * `SIGTERM` timeout, a missing `adb` binary (`ENOENT`), or a non-zero
+ * exit. In particular `executeCommand` no longer silently coerces
+ * `ENOENT` to `exitCode:1` — it throws `adb_not_installed` so callers
+ * can surface the real cause.
+ *
+ * **Shell quoting invariant** (v0.2.3): every `adb shell ...` invocation
+ * goes through the `sh\`...\`` tagged template from `util/adb-shell.ts`,
+ * collapsing argv to the single-string pattern that adb's wire protocol
+ * actually wants. Multi-arg `["shell", "verb", a, b, ...]` is forbidden
+ * because adb on the device joins argv with spaces and re-evaluates
+ * through `/system/bin/sh -c`, which silently drops shell metacharacters
+ * (`$`, backticks, etc.) the host thought it was passing literally. See
+ * `util/adb-shell.ts` for the gory details.
+ *
+ * **File IO** (v0.2.3): `fileRead` / `fileWrite` / `listDirectory` no
+ * longer use `adb exec-out cat` or `adb shell sh -c "echo ... | base64
+ * -d"` shell hacks. They go through `adb pull` / `adb push` (the actual
+ * file-sync protocol) and `adb shell ls -laL` (deref symlinks) via the
+ * `util/adb-files.ts` helpers. This fixes:
+ *   - `fileRead` of a missing path now throws `file_not_found` instead
+ *     of returning the device-side `cat` stderr base64-encoded.
+ *   - `fileWrite` actually writes the bytes (the old `echo | base64 -d`
+ *     pipeline was eaten by the nested-`sh -c` re-evaluation).
+ *   - `listDirectory("/sdcard")` returns the contents of the linked dir
+ *     (`/storage/self/primary`) instead of a single symlink row.
+ *
+ * **Screenshot contract** (v0.2.3): `screenshot()` returns the structured
+ * `{ data, width, height, format }` shape so the MCP wire layer can keep
+ * `width/height` consistent with the actual decoded image bytes (and
+ * `deviceWidth/deviceHeight` separately track the click coordinate
+ * system). The Android backend no longer compresses by default — the
+ * agent layer decides whether to resize.
+ */
+import { spawn } from "node:child_process";
+import sharp from "sharp";
+import { COMMON_TOOLS, DeviceError, MOBILE_TOOLS, } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, } from "./base.js";
+const ADB_TOOLS = new Set([
+    ...COMMON_TOOLS,
+    ...MOBILE_TOOLS,
+]);
+import { getAppPackage, looksLikePackage } from "../util/android-apps.js";
+import { sh } from "../util/adb-shell.js";
+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.
+ */
+const SS_MAX_EDGE = SS_MAX_EDGE_RAW
+    ? parseInt(SS_MAX_EDGE_RAW, 10)
+    : Number.POSITIVE_INFINITY;
+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;
+const DEFAULT_SCREENSHOT_TIMEOUT_MS = 15_000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 120_000;
+const DEFAULT_FILE_TIMEOUT_MS = 60_000;
+const SHELL_OUTPUT_CAP_BYTES = 8 * 1024 * 1024;
+const DELAYS = {
+    tap: 1500,
+    doubleTap: 1000,
+    doubleTapInterval: 100,
+    longPress: 1500,
+    swipe: 2000,
+    back: 1500,
+    home: 1500,
+    launch: 3000,
+    keyboardSwitch: 500,
+    textClear: 300,
+    textInput: 500,
+    keyboardRestore: 300,
+};
+/* ----------------------------------------------------------------------- */
+/* Default spawn-backed runner                                              */
+/* ----------------------------------------------------------------------- */
+function defaultRunner(file, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(file, args, {
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: opts.cwd,
+            });
+        }
+        catch (e) {
+            reject(e);
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let totalStdoutBytes = 0;
+        const cap = opts.maxBufferBytes ?? SHELL_OUTPUT_CAP_BYTES;
+        let capExceeded = false;
+        child.stdout?.on("data", (c) => {
+            totalStdoutBytes += c.length;
+            if (totalStdoutBytes > cap) {
+                capExceeded = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* swallow */
+                }
+                return;
+            }
+            stdoutChunks.push(c);
+        });
+        child.stderr?.on("data", (c) => stderrChunks.push(c));
+        let timer;
+        let timedOut = false;
+        if (opts.timeoutMs && opts.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* swallow */
+                }
+            }, opts.timeoutMs);
+        }
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            if (timer)
+                clearTimeout(timer);
+            const stdoutBuf = Buffer.concat(stdoutChunks);
+            const stderr = Buffer.concat(stderrChunks).toString("utf8");
+            const stdout = opts.encoding === "buffer" ? stdoutBuf : stdoutBuf.toString("utf8");
+            if (timedOut || capExceeded) {
+                const e = new Error(capExceeded
+                    ? `${file} stdout exceeded ${cap} bytes`
+                    : `${file} timed out after ${opts.timeoutMs}ms`);
+                e.signal = "SIGTERM";
+                e.killed = true;
+                e.stdout = stdout;
+                e.stderr = stderr;
+                reject(e);
+                return;
+            }
+            if (code === 0) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            const err = new Error(`${file} exited with code ${code}${signal ? ` (signal ${signal})` : ""}`);
+            err.stdout = stdout;
+            err.stderr = stderr;
+            err.code =
+                typeof code === "number" ? code : 1;
+            reject(err);
+        });
+    });
+}
+export class AndroidAdbBackend extends BaseSandboxBackend {
+    os = "android";
+    tools = ADB_TOOLS;
+    serial;
+    skipConnectValidation;
+    runner;
+    sleep;
+    defaultTimeoutMs;
+    shellTimeoutMs;
+    screenshotTimeoutMs;
+    installTimeoutMs;
+    fileTimeoutMs;
+    constructor(opts = {}) {
+        super();
+        this.serial = opts.serial;
+        this.skipConnectValidation = !!opts.skipConnectValidation;
+        this.runner = opts.runner ?? defaultRunner;
+        this.sleep =
+            opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.shellTimeoutMs = opts.shellTimeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+        this.screenshotTimeoutMs =
+            opts.screenshotTimeoutMs ?? DEFAULT_SCREENSHOT_TIMEOUT_MS;
+        this.installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+        this.fileTimeoutMs = opts.fileTimeoutMs ?? DEFAULT_FILE_TIMEOUT_MS;
+    }
+    async connect() {
+        if (this.skipConnectValidation)
+            return;
+        const devices = await listAdbDevices(this.runner, this.defaultTimeoutMs);
+        if (devices.length === 0) {
+            throw new DeviceError("No ADB devices connected. Run `adb devices`.", {
+                subtype: "no_device",
+                retriable: true,
+            });
+        }
+    }
+    async disconnect() {
+        // No-op — adb daemon stays alive between commands.
+    }
+    /* ------------------------------------------------------------------ */
+    /* Info / screen                                                       */
+    /* ------------------------------------------------------------------ */
+    async info() {
+        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"),
+        ]);
+        const sizeMatch = size.match(/Physical size:\s*(\d+)x(\d+)/i);
+        const width = sizeMatch ? Number(sizeMatch[1]) : 1080;
+        const height = sizeMatch ? Number(sizeMatch[2]) : 1920;
+        const densityMatch = density.match(/Physical density:\s*(\d+)/i);
+        const dpi = densityMatch ? Number(densityMatch[1]) : 0;
+        const props = parseGetpropDump(propDump);
+        const model = props.get("ro.product.model") ?? "";
+        const version = props.get("ro.build.version.release") ?? "";
+        const sdk = props.get("ro.build.version.sdk") ?? "";
+        const abi = props.get("ro.product.cpu.abi") ?? "";
+        const manufacturer = props.get("ro.product.manufacturer") ?? "";
+        const brand = props.get("ro.product.brand") ?? "";
+        const serial = this.serial ?? props.get("ro.serialno") ?? "";
+        const capabilities = [
+            "screenshot",
+            "ui-tree",
+            "tap",
+            "swipe",
+            "type",
+            "press_key",
+            "install",
+            "shell",
+        ];
+        return {
+            type: "android",
+            name: model || "Android",
+            os: "android",
+            width,
+            height,
+            capabilities,
+            osVersion: version,
+            density: dpi,
+            metadata: {
+                currentApp,
+                serial,
+                sdk,
+                model,
+                abi,
+                manufacturer,
+                brand,
+            },
+        };
+    }
+    async screenshot() {
+        // 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();
+        const [rawW, rawH] = parsePngDimensions(raw);
+        if (!Number.isFinite(SS_MAX_EDGE) || Math.max(rawW, rawH) <= SS_MAX_EDGE) {
+            return { data: raw, width: rawW, height: rawH, format: "png" };
+        }
+        // Resize-on-capture path: re-encode to JPEG 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();
+            return {
+                data,
+                width: meta.width ?? rawW,
+                height: meta.height ?? rawH,
+                format: "jpeg",
+            };
+        }
+        catch {
+            return { data: raw, width: rawW, height: rawH, format: "png" };
+        }
+    }
+    async screenSize() {
+        const out = await this.runShell("wm size").catch(() => "");
+        const m = out.match(/Physical size:\s*(\d+)x(\d+)/i);
+        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 };
+        }
+        return { supported: true, content: stdout.trim() };
+    }
+    /* ------------------------------------------------------------------ */
+    /* Pointer / gesture                                                   */
+    /* ------------------------------------------------------------------ */
+    async tap(x, y) {
+        await this.adbShell(sh `input tap ${x} ${y}`);
+        await this.sleep(DELAYS.tap);
+    }
+    async click(x, y) {
+        return this.tap(x, y);
+    }
+    async doubleClick(x, y) {
+        await this.adbShell(sh `input tap ${x} ${y}`);
+        await this.sleep(DELAYS.doubleTapInterval);
+        await this.adbShell(sh `input tap ${x} ${y}`);
+        await this.sleep(DELAYS.doubleTap);
+    }
+    async longPress(x, y, durationMs = 3000) {
+        await this.adbShell(sh `input swipe ${x} ${y} ${x} ${y} ${durationMs}`);
+        await this.sleep(DELAYS.longPress);
+    }
+    async swipe(x1, y1, x2, y2, durationMs) {
+        const dur = durationMs ??
+            Math.max(1000, Math.min(Math.round(Math.hypot(x1 - x2, y1 - y2)), 2000));
+        await this.adbShell(sh `input swipe ${x1} ${y1} ${x2} ${y2} ${dur}`);
+        await this.sleep(DELAYS.swipe);
+    }
+    async drag(x1, y1, x2, y2, durationMs) {
+        return this.swipe(x1, y1, x2, y2, durationMs);
+    }
+    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;
+        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);
+    }
+    /* ------------------------------------------------------------------ */
+    /* Keyboard                                                            */
+    /* ------------------------------------------------------------------ */
+    async typeText(text) {
+        // 1) Snapshot the current IME *before* we touch anything. We MUST do
+        //    this in its own try-block so that, if the AdbIME swap below
+        //    later fails, we still know which IME to restore on the way
+        //    out — Redroid / unrooted devices that lack `com.android.adbkeyboard`
+        //    must NOT be left stranded on a half-set IME.
+        let originalIme = "";
+        try {
+            originalIme = await this.getCurrentIme();
+        }
+        catch {
+            // Detection itself failed (e.g. adb gone). Without an original IME
+            // to restore, skip the swap entirely — the broadcast still works
+            // for many keyboards even without the swap.
+            originalIme = "";
+        }
+        try {
+            if (originalIme) {
+                await this.setIme("com.android.adbkeyboard/.AdbIME");
+                await this.sleep(DELAYS.keyboardSwitch);
+            }
+            await this.clearText();
+            await this.sleep(DELAYS.textClear);
+            // ADB_INPUT_TEXT broadcast — `--es msg <value>` ships the raw text.
+            // Going through `sh\`...\`` quotes the value as a single argv
+            // element on the device side, neutralising any `$`, `;`, `|`, etc.
+            // that might otherwise be re-evaluated by the device shell.
+            await this.adbShell(sh `am broadcast -a ADB_INPUT_TEXT --es msg ${text}`);
+            await this.sleep(DELAYS.textInput);
+        }
+        finally {
+            if (originalIme) {
+                await this.setIme(originalIme).catch(() => undefined);
+                await this.sleep(DELAYS.keyboardRestore);
+            }
+        }
+    }
+    async pressKey(key) {
+        await this.adbShell(sh `input keyevent ${key}`);
+    }
+    async back() {
+        await this.adbShell(sh `input keyevent KEYCODE_BACK`);
+        await this.sleep(DELAYS.back);
+    }
+    async home() {
+        await this.adbShell(sh `input keyevent KEYCODE_HOME`);
+        await this.sleep(DELAYS.home);
+    }
+    async navigate(direction) {
+        if (direction === "back")
+            return this.back();
+        if (direction === "up")
+            return this.home();
+        throw new DeviceError(`navigate '${direction}' not supported on android`, {
+            subtype: "unsupported",
+            retriable: false,
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /* App lifecycle                                                       */
+    /* ------------------------------------------------------------------ */
+    async launchApp(pkgOrName, activity) {
+        const pkg = looksLikePackage(pkgOrName)
+            ? pkgOrName
+            : (getAppPackage(pkgOrName) ?? pkgOrName);
+        if (activity && activity.length > 0) {
+            // Caller wants a specific activity → use `am start -n pkg/activity`.
+            // Activities can be bare class names (`.MainActivity`) or fully
+            // qualified (`com.example.app.MainActivity`); `am start` accepts both.
+            // We MUST quote the component as a single shell argv element — the
+            // canonical Settings-style `Settings$WifiSettingsActivity` would
+            // otherwise be silently truncated by the device shell's `$` expansion
+            // (regression bug #1 in 0.2.2 → fixed here).
+            const component = activity.includes("/") ? activity : `${pkg}/${activity}`;
+            await this.adbShell(sh `am start -n ${component}`);
+        }
+        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`);
+        }
+        await this.sleep(DELAYS.launch);
+    }
+    /* ------------------------------------------------------------------ */
+    /* Shell / files                                                       */
+    /* ------------------------------------------------------------------ */
+    async executeCommand(body, opts = {}) {
+        const timeoutMs = (opts.timeoutS ?? this.shellTimeoutMs / 1000) * 1000;
+        // `body` is treated as opaque shell — callers pass arbitrary commands
+        // to run on the device. Quoting `cwd` keeps it safe; the user's body
+        // itself is their responsibility (we cannot disambiguate "user wants
+        // a subshell expansion" from "user wants a literal `$`" here).
+        const cmd = opts.cwd ? `cd ${shQuote(opts.cwd)} && ${body}` : body;
+        try {
+            const { stdout, stderr } = await this.runner("adb", this.adbArgs(["shell", cmd]), {
+                encoding: "utf8",
+                timeoutMs,
+                maxBufferBytes: SHELL_OUTPUT_CAP_BYTES,
+            });
+            return {
+                stdout: typeof stdout === "string" ? stdout : stdout.toString("utf8"),
+                stderr,
+                exitCode: 0,
+            };
+        }
+        catch (e) {
+            const err = e;
+            // Timeout → DeviceError so callers can retry. Same as legacy.
+            if (err.killed && err.signal === "SIGTERM") {
+                throw wrapAdbFailure("shell", ["shell", cmd], err, timeoutMs);
+            }
+            // ENOENT / non-numeric `code` means adb itself isn't installed (or
+            // bricked). Don't silently coerce to exitCode:1 — that hides the
+            // real cause from the agent. Throw `adb_not_installed` instead.
+            if (typeof err.code !== "number") {
+                throw wrapAdbFailure("shell", ["shell", cmd], err, timeoutMs);
+            }
+            const stdout = typeof err.stdout === "string"
+                ? err.stdout
+                : Buffer.isBuffer(err.stdout)
+                    ? err.stdout.toString("utf8")
+                    : "";
+            return {
+                stdout,
+                stderr: err.stderr ?? err.message,
+                exitCode: err.code,
+            };
+        }
+    }
+    async fileRead(path) {
+        return adbPull(this.runner, this.serial, path, {
+            timeoutMs: this.fileTimeoutMs,
+        });
+    }
+    async fileWrite(path, content) {
+        const buf = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+        await adbPush(this.runner, this.serial, path, buf, {
+            timeoutMs: this.fileTimeoutMs,
+        });
+    }
+    async listDirectory(path) {
+        try {
+            return await adbListDir(this.runner, this.serial, path, {
+                timeoutMs: this.defaultTimeoutMs,
+            });
+        }
+        catch (e) {
+            throw wrapAdbFailure("shell", ["shell", `ls -laL ${path}`], e, this.defaultTimeoutMs);
+        }
+    }
+    async install(path) {
+        try {
+            await this.runner("adb", this.adbArgs(["install", "-r", path]), {
+                encoding: "utf8",
+                timeoutMs: this.installTimeoutMs,
+            });
+        }
+        catch (e) {
+            throw wrapAdbFailure("install", ["install", "-r", path], e, this.installTimeoutMs);
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /* Internal helpers                                                    */
+    /* ------------------------------------------------------------------ */
+    async getCurrentApp() {
+        const { stdout } = await this.adbShell(sh `dumpsys window`);
+        const target = stdout.match(/(mCurrentFocus|mFocusedApp)=.*/g)?.[0] ?? "";
+        if (!target)
+            return "System Home";
+        const m = target.match(/[a-zA-Z][\w.]+\/[\w.$]+/);
+        return m ? m[0] : "System Home";
+    }
+    async getCurrentIme() {
+        const { stdout } = await this.adbShell(sh `settings get secure default_input_method`);
+        return stdout.trim();
+    }
+    async setIme(ime) {
+        if (ime)
+            await this.adbShell(sh `ime set ${ime}`);
+    }
+    async clearText() {
+        await this.adbShell(sh `input keyevent KEYCODE_CTRL_A`);
+        await this.adbShell(sh `input keyevent KEYCODE_DEL`);
+    }
+    async runShell(command) {
+        try {
+            const { stdout } = await this.runner("adb", this.adbArgs(["shell", command]), {
+                encoding: "utf8",
+                maxBufferBytes: SHELL_OUTPUT_CAP_BYTES,
+                timeoutMs: this.shellTimeoutMs,
+            });
+            return typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        }
+        catch (e) {
+            throw wrapAdbFailure("shell", ["shell", command], e, this.shellTimeoutMs);
+        }
+    }
+    async captureRawPng() {
+        try {
+            const { stdout } = await this.runner("adb", this.adbArgs(["exec-out", "screencap", "-p"]), {
+                encoding: "buffer",
+                maxBufferBytes: 32 * 1024 * 1024,
+                timeoutMs: this.screenshotTimeoutMs,
+            });
+            return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
+        }
+        catch (e) {
+            throw wrapAdbFailure("screencap", ["exec-out", "screencap", "-p"], e, this.screenshotTimeoutMs);
+        }
+    }
+    /**
+     * Run an `adb shell <single-command>`. Callers MUST build the command
+     * string via `sh\`...\`` (or pass a static literal). This is the ONLY
+     * sanctioned shape for shell invocations — any `["shell", a, b, ...]`
+     * call that bypasses this helper is a bug (see CHANGELOG 0.2.3).
+     */
+    async adbShell(command) {
+        try {
+            const { stdout, stderr } = await this.runner("adb", this.adbArgs(["shell", command]), {
+                encoding: "utf8",
+                timeoutMs: this.defaultTimeoutMs,
+                maxBufferBytes: 32 * 1024 * 1024,
+            });
+            return {
+                stdout: typeof stdout === "string" ? stdout : stdout.toString("utf8"),
+                stderr,
+            };
+        }
+        catch (e) {
+            throw wrapAdbFailure("shell", ["shell", command], e, this.defaultTimeoutMs);
+        }
+    }
+    adbArgs(args) {
+        return this.serial ? ["-s", this.serial, ...args] : args;
+    }
+}
+/* ----------------------------------------------------------------------- */
+/* Module-level helpers                                                    */
+/* ----------------------------------------------------------------------- */
+/**
+ * List connected ADB devices. Exposed at module scope (and as a thin
+ * member-bound helper inside `connect()`) so tests / EdgeAgent can probe
+ * device presence without instantiating a backend.
+ */
+export async function listAdbDevices(runner = defaultRunner, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    try {
+        const { stdout } = await runner("adb", ["devices"], {
+            encoding: "utf8",
+            timeoutMs,
+        });
+        const text = typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        return text
+            .split("\n")
+            .slice(1)
+            .filter((l) => l.includes("\tdevice"))
+            .map((l) => l.split("\t")[0]);
+    }
+    catch (e) {
+        throw wrapAdbFailure("devices", ["devices"], e, timeoutMs);
+    }
+}
+function parseGetpropDump(out) {
+    const map = new Map();
+    if (!out)
+        return map;
+    const re = /^\[([^\]]+)\]:\s*\[([^\]]*)\]\s*$/gm;
+    let m;
+    while ((m = re.exec(out)) !== null) {
+        const key = m[1];
+        const val = m[2];
+        if (key !== undefined && val !== undefined) {
+            map.set(key, val);
+        }
+    }
+    return map;
+}
+/**
+ * Local POSIX-quote helper used ONLY by `executeCommand`'s `cwd` prefix.
+ * The general-purpose `sh\`...\`` template lives in `util/adb-shell.ts`
+ * and should be used everywhere else; we inline a single-character helper
+ * here to avoid pulling the tagged template into a code path where the
+ * rest of the command is opaque (the user-supplied `body`).
+ */
+function shQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Normalise every adb runner failure into a single `DeviceError` shape.
+ *
+ *   - `killed && signal === "SIGTERM"` → `adb_timeout`, retriable
+ *   - `code === "ENOENT"` (string)     → `adb_not_installed`, NOT retriable
+ *   - any non-numeric `code`           → `adb_not_installed`, NOT retriable
+ *   - everything else (numeric exit)   → `adb_<verb>_failed` / `adb_failed`
+ *
+ * The verb-specific subtypes (`adb_shell_failed`, `adb_install_failed`,
+ * `adb_screencap_failed`, `adb_devices_failed`) keep the legacy adapter's
+ * shape so existing wire consumers don't break.
+ *
+ * `DeviceError` instances are passed through unchanged — `adbPull` /
+ * `adbPush` already produce well-shaped errors and we don't want to wrap
+ * a `DeviceError` in another `DeviceError`.
+ */
+export function wrapAdbFailure(verb, args, cause, timeoutMs) {
+    if (cause instanceof DeviceError)
+        return cause;
+    const err = cause;
+    const isTimeout = err.killed && err.signal === "SIGTERM";
+    if (isTimeout) {
+        const ms = timeoutMs ?? 0;
+        return new DeviceError(ms > 0
+            ? `adb ${verb} timed out after ${ms}ms`
+            : `adb ${verb} timed out`, {
+            subtype: "adb_timeout",
+            retriable: true,
+            cause: err,
+        });
+    }
+    // String `code` (typically `"ENOENT"` for missing binary) means adb
+    // itself isn't installed / not on PATH. This is unambiguously
+    // non-retriable — surface it explicitly.
+    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
+    // simply could not be located. Treat that the same as ENOENT.
+    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 summary = err.stderr?.trim() || err.message || "unknown error";
+    const subtype = verb === "shell"
+        ? "adb_shell_failed"
+        : verb === "install"
+            ? "adb_install_failed"
+            : verb === "screencap"
+                ? "screenshot_failed"
+                : verb === "devices"
+                    ? "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}`, {
+        subtype,
+        retriable: false,
+        cause: err,
+    });
+}
+//# sourceMappingURL=android-adb.js.map