@ishlabs/cli 0.24.1 → 0.25.0

package/dist/lib/local-sim/adb.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Thin async wrappers over the `adb` CLI for the native-Android sim path.
+ *
+ * One emulator/device is assumed (the lead coordinates a single shared
+ * emulator). Every call shells out to a resolved `adb` binary; binary output
+ * (screencap) is captured without a utf-8 round-trip so PNG bytes survive.
+ *
+ * Coordinate space: `adb shell screencap` and `adb shell input tap` share ONE
+ * pixel space — there is NO DPR correction. The native sim de-normalizes the
+ * backend's 0-1000 coordinates against the screencap pixel size and taps
+ * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
+ */
+export declare class AdbError extends Error {
+    constructor(message: string);
+}
+/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+export declare function adb(args: string[], timeoutMs?: number): Promise<string>;
+/** Run `adb shell <args>` and return trimmed stdout. */
+export declare function adbShell(args: string[], timeoutMs?: number): Promise<string>;
+/**
+ * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
+ * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
+ * output. Returns the PNG buffer at full device resolution.
+ */
+export declare function screencapPng(): Promise<Buffer>;
+/** Assert exactly one device/emulator is in the `device` state. */
+export declare function requireOneDevice(): Promise<void>;
+export declare function inputTap(x: number, y: number): Promise<void>;
+export declare function inputSwipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/**
+ * A drag GRABS an element and drops it elsewhere — press, HOLD to pick up,
+ * move, release. We use `input draganddrop`, NOT a slow `input swipe`: a swipe
+ * never holds at the start, so on the surfaces a drag actually targets
+ * (launcher icons, reorderable list rows — all `long-clickable`) the framework
+ * reads a slow swipe as a directional SWIPE (e.g. it opens the app drawer)
+ * instead of picking the element up. `draganddrop` dwells at the press point
+ * first, triggering the long-press pickup, then moves and releases — verified
+ * on-device to actually rearrange a launcher icon where the slow swipe didn't.
+ * Requires API 30+ (`input draganddrop`); on the dev emulators/sim devices the
+ * native driver targets, that's always present. Coordinates are screencap
+ * pixels (the same space as tap/swipe — no DPR correction).
+ */
+export declare function inputDrag(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/** A long-press is a zero-distance swipe held for `durationMs`. */
+export declare function inputLongPress(x: number, y: number, durationMs?: number): Promise<void>;
+export declare function pressKeyEvent(keyevent: string): Promise<void>;
+/**
+ * Force a device orientation. We first disable auto-rotation
+ * (`accelerometer_rotation 0`) — otherwise the sensor immediately overrides
+ * our fixed `user_rotation`. `user_rotation` is 0=portrait, 1=landscape (90°).
+ */
+export declare function setUserRotation(orientation: "portrait" | "landscape"): Promise<void>;
+export declare const ADB_KEYBOARD_PKG = "com.android.adbkeyboard";
+/** True if the ADBKeyboard IME is installed on the device. */
+export declare function isAdbKeyboardInstalled(): Promise<boolean>;
+/** Currently-selected IME id (so we can restore it after the run). */
+export declare function currentIme(): Promise<string | null>;
+/** Select an IME by its component id. */
+export declare function setIme(imeId: string): Promise<void>;
+/** Reset the IME to the system default (used when we had no prior IME to restore). */
+export declare function resetIme(): Promise<void>;
+/** Make ADBKeyboard the active IME. */
+export declare function enableAdbKeyboard(): Promise<void>;
+/**
+ * Type text into the focused field via ADBKeyboard's base64 broadcast.
+ * base64 keeps spaces/unicode/quotes intact across the adb shell boundary.
+ * Note: the text transits as a base64 argv arg, so it's briefly visible in the
+ * device-side process list (`ps`) — fine for sim input, not a secret channel
+ * (context secrets are resolved here but this is local-dev/emulator only).
+ */
+export declare function adbKeyboardType(text: string): Promise<void>;
+/** Clear the focused field (ADBKeyboard ADB_CLEAR_TEXT broadcast). */
+export declare function adbKeyboardClear(): Promise<void>;
+/**
+ * Read width/height from a PNG buffer's IHDR chunk. The IHDR is always the
+ * first chunk: 8-byte signature, 4-byte length, 4-byte "IHDR", then width and
+ * height as big-endian uint32 at byte offsets 16 and 20. Avoids pulling in an
+ * image library just to learn the screencap's pixel size.
+ */
+export declare function pngDimensions(png: Buffer): {
+    width: number;
+    height: number;
+};
+export declare function forceStop(pkg: string): Promise<void>;
+/** Launch the app's default launchable activity via monkey (no activity name needed). */
+export declare function launchApp(pkg: string): Promise<void>;
+export declare function installApk(apkPath: string): Promise<void>;
+export declare function isPackageInstalled(pkg: string): Promise<boolean>;
+/**
+ * Dump the current view hierarchy as uiautomator XML and return it. Mirrors the
+ * oracle's `ui_dump`: uiautomator fails transiently with "window in transition"
+ * (right after a UI change, writes nothing) or "could not get idle state" (a
+ * view animates forever), so we retry a few times, nudging the device awake
+ * between tries since a screen-off device never goes idle-with-content.
+ *
+ * Uses `exec-out uiautomator dump /dev/tty` so the XML comes back on stdout in
+ * one shot (no pull); falls back to dump-to-file + pull if the device writes the
+ * "dumped to" line to a path instead. Throws AdbError if every attempt fails so
+ * the caller can degrade to the vision path.
+ */
+export declare function dumpUiautomatorXml(): Promise<string>;
+/** All installed package names (the set of `package:<name>` lines). */
+export declare function listPackages(): Promise<Set<string>>;

package/dist/lib/local-sim/adb.js

@@ -0,0 +1,352 @@
+/**
+ * Thin async wrappers over the `adb` CLI for the native-Android sim path.
+ *
+ * One emulator/device is assumed (the lead coordinates a single shared
+ * emulator). Every call shells out to a resolved `adb` binary; binary output
+ * (screencap) is captured without a utf-8 round-trip so PNG bytes survive.
+ *
+ * Coordinate space: `adb shell screencap` and `adb shell input tap` share ONE
+ * pixel space — there is NO DPR correction. The native sim de-normalizes the
+ * backend's 0-1000 coordinates against the screencap pixel size and taps
+ * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// adb ships with Homebrew's android-platform-tools and inside the SDK. Prefer
+// an explicit absolute path so we never depend on the caller's PATH (mirrors
+// scripts/mobile-e2e/lib.sh). Override with ISH_ADB / ADB.
+function resolveAdb() {
+    const fromEnv = process.env.ISH_ADB || process.env.ADB;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    const homebrew = "/opt/homebrew/bin/adb";
+    if (existsSync(homebrew))
+        return homebrew;
+    const sdkHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+    if (sdkHome) {
+        const sdkAdb = `${sdkHome}/platform-tools/adb`;
+        if (existsSync(sdkAdb))
+            return sdkAdb;
+    }
+    // Last resort: rely on PATH and surface a clear error if it's missing.
+    return "adb";
+}
+const ADB = resolveAdb();
+const DEFAULT_TIMEOUT_MS = 30_000;
+// screencap on a cold emulator frame can be slow; give it generous headroom.
+const SCREENCAP_TIMEOUT_MS = 30_000;
+// 16 MB covers a full-resolution PNG frame from a phone-sized emulator.
+const SCREENCAP_MAX_BUFFER = 16 * 1024 * 1024;
+export class AdbError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AdbError";
+    }
+}
+/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    try {
+        const { stdout } = await execFileAsync(ADB, args, {
+            timeout: timeoutMs,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return stdout.trim();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new AdbError(`adb ${args.join(" ")} failed: ${msg}`);
+    }
+}
+/** Run `adb shell <args>` and return trimmed stdout. */
+export async function adbShell(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return adb(["shell", ...args], timeoutMs);
+}
+/**
+ * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
+ * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
+ * output. Returns the PNG buffer at full device resolution.
+ */
+export async function screencapPng() {
+    try {
+        const { stdout } = await execFileAsync(ADB, ["exec-out", "screencap", "-p"], {
+            timeout: SCREENCAP_TIMEOUT_MS,
+            maxBuffer: SCREENCAP_MAX_BUFFER,
+            encoding: "buffer",
+        });
+        return stdout;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new AdbError(`adb exec-out screencap failed: ${msg}`);
+    }
+}
+/** Assert exactly one device/emulator is in the `device` state. */
+export async function requireOneDevice() {
+    let out;
+    try {
+        out = await adb(["devices"]);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new AdbError(`Could not run adb (looked for "${ADB}"). Is the Android SDK installed and an emulator booted? ${msg}`);
+    }
+    // Output: "List of devices attached\n<serial>\tdevice\n..."
+    const online = out
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter((l) => l && l.endsWith("\tdevice"));
+    if (online.length === 0) {
+        throw new AdbError("No Android device/emulator online. Boot one first (e.g. `npm run mobile-e2e-setup`).");
+    }
+    if (online.length > 1) {
+        throw new AdbError(`Expected exactly one Android device, found ${online.length}. Stop the extras (the sim drives a single device).`);
+    }
+}
+// --- Input gestures (all in screencap pixel space) ---
+export async function inputTap(x, y) {
+    await adbShell(["input", "tap", String(Math.round(x)), String(Math.round(y))]);
+}
+export async function inputSwipe(x1, y1, x2, y2, durationMs = 300) {
+    await adbShell([
+        "input",
+        "swipe",
+        String(Math.round(x1)),
+        String(Math.round(y1)),
+        String(Math.round(x2)),
+        String(Math.round(y2)),
+        String(Math.round(durationMs)),
+    ]);
+}
+/**
+ * A drag GRABS an element and drops it elsewhere — press, HOLD to pick up,
+ * move, release. We use `input draganddrop`, NOT a slow `input swipe`: a swipe
+ * never holds at the start, so on the surfaces a drag actually targets
+ * (launcher icons, reorderable list rows — all `long-clickable`) the framework
+ * reads a slow swipe as a directional SWIPE (e.g. it opens the app drawer)
+ * instead of picking the element up. `draganddrop` dwells at the press point
+ * first, triggering the long-press pickup, then moves and releases — verified
+ * on-device to actually rearrange a launcher icon where the slow swipe didn't.
+ * Requires API 30+ (`input draganddrop`); on the dev emulators/sim devices the
+ * native driver targets, that's always present. Coordinates are screencap
+ * pixels (the same space as tap/swipe — no DPR correction).
+ */
+export async function inputDrag(x1, y1, x2, y2, durationMs = 800) {
+    await adbShell([
+        "input",
+        "draganddrop",
+        String(Math.round(x1)),
+        String(Math.round(y1)),
+        String(Math.round(x2)),
+        String(Math.round(y2)),
+        String(Math.round(durationMs)),
+    ]);
+}
+/** A long-press is a zero-distance swipe held for `durationMs`. */
+export async function inputLongPress(x, y, durationMs = 600) {
+    const px = Math.round(x);
+    const py = Math.round(y);
+    await adbShell(["input", "swipe", String(px), String(py), String(px), String(py), String(Math.round(durationMs))]);
+}
+export async function pressKeyEvent(keyevent) {
+    await adbShell(["input", "keyevent", keyevent]);
+}
+/**
+ * Force a device orientation. We first disable auto-rotation
+ * (`accelerometer_rotation 0`) — otherwise the sensor immediately overrides
+ * our fixed `user_rotation`. `user_rotation` is 0=portrait, 1=landscape (90°).
+ */
+export async function setUserRotation(orientation) {
+    await adbShell(["settings", "put", "system", "accelerometer_rotation", "0"]);
+    await adbShell(["settings", "put", "system", "user_rotation", orientation === "landscape" ? "1" : "0"]);
+}
+// --- Text input via ADBKeyboard ---
+//
+// `adb shell input text` mangles spaces, unicode, and special chars and can't
+// target a specific field. ADBKeyboard (a tiny IME, pkg below) accepts a
+// broadcast carrying base64-encoded UTF-8 and types it into the focused field
+// reliably. We set it as the active IME for the run and restore afterwards.
+export const ADB_KEYBOARD_PKG = "com.android.adbkeyboard";
+const ADB_KEYBOARD_IME = `${ADB_KEYBOARD_PKG}/.AdbIME`;
+/** True if the ADBKeyboard IME is installed on the device. */
+export async function isAdbKeyboardInstalled() {
+    return isPackageInstalled(ADB_KEYBOARD_PKG);
+}
+/** Currently-selected IME id (so we can restore it after the run). */
+export async function currentIme() {
+    const out = await adbShell(["settings", "get", "secure", "default_input_method"]);
+    const trimmed = out.trim();
+    return trimmed && trimmed !== "null" ? trimmed : null;
+}
+/** Select an IME by its component id. */
+export async function setIme(imeId) {
+    await adbShell(["ime", "set", imeId]);
+}
+/** Reset the IME to the system default (used when we had no prior IME to restore). */
+export async function resetIme() {
+    await adbShell(["ime", "reset"]);
+}
+/** Make ADBKeyboard the active IME. */
+export async function enableAdbKeyboard() {
+    await adbShell(["ime", "enable", ADB_KEYBOARD_IME]);
+    await adbShell(["ime", "set", ADB_KEYBOARD_IME]);
+}
+/**
+ * Type text into the focused field via ADBKeyboard's base64 broadcast.
+ * base64 keeps spaces/unicode/quotes intact across the adb shell boundary.
+ * Note: the text transits as a base64 argv arg, so it's briefly visible in the
+ * device-side process list (`ps`) — fine for sim input, not a secret channel
+ * (context secrets are resolved here but this is local-dev/emulator only).
+ */
+export async function adbKeyboardType(text) {
+    const b64 = Buffer.from(text, "utf-8").toString("base64");
+    await adbShell([
+        "am",
+        "broadcast",
+        "-a",
+        "ADB_INPUT_B64",
+        "--es",
+        "msg",
+        b64,
+    ]);
+}
+/** Clear the focused field (ADBKeyboard ADB_CLEAR_TEXT broadcast). */
+export async function adbKeyboardClear() {
+    await adbShell(["am", "broadcast", "-a", "ADB_CLEAR_TEXT"]);
+}
+// --- PNG dimensions (dependency-free IHDR read) ---
+/**
+ * Read width/height from a PNG buffer's IHDR chunk. The IHDR is always the
+ * first chunk: 8-byte signature, 4-byte length, 4-byte "IHDR", then width and
+ * height as big-endian uint32 at byte offsets 16 and 20. Avoids pulling in an
+ * image library just to learn the screencap's pixel size.
+ */
+export function pngDimensions(png) {
+    const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (png.length < 24 || !png.subarray(0, 8).equals(PNG_SIG)) {
+        throw new AdbError("screencap did not return a PNG (unexpected screencap output)");
+    }
+    const width = png.readUInt32BE(16);
+    const height = png.readUInt32BE(20);
+    if (width <= 0 || height <= 0) {
+        throw new AdbError(`screencap PNG has invalid dimensions ${width}x${height}`);
+    }
+    return { width, height };
+}
+// --- App lifecycle ---
+export async function forceStop(pkg) {
+    await adbShell(["am", "force-stop", pkg]);
+}
+/** Launch the app's default launchable activity via monkey (no activity name needed). */
+export async function launchApp(pkg) {
+    // `monkey` with a LAUNCHER+MAIN category resolves the entry activity for us,
+    // so callers don't have to know the activity name.
+    const out = await adbShell([
+        "monkey",
+        "-p",
+        pkg,
+        "-c",
+        "android.intent.category.LAUNCHER",
+        "1",
+    ]);
+    // monkey exits 0 even when the package has no launchable activity or isn't
+    // installed — it prints "No activities found to run, monkey aborting." to
+    // stdout. Catch that so a bad package fails loudly instead of silently
+    // leaving whatever was already in the foreground.
+    if (/no activities found to run/i.test(out) || /aborting/i.test(out)) {
+        throw new AdbError(`No launchable activity for package "${pkg}" (is it installed?): ${out.trim()}`);
+    }
+}
+export async function installApk(apkPath) {
+    // -r reinstall keeping data, -g grant runtime permissions, -t allow test apks.
+    const out = await adb(["install", "-r", "-g", "-t", apkPath], 180_000);
+    // `adb install` exits 0 even on `Failure [INSTALL_FAILED_*]` — only a
+    // "Success" line means it landed. Throw otherwise so a bad apk is a clear
+    // error, not a silently-wrong run against the previously-installed app.
+    if (!/\bSuccess\b/.test(out)) {
+        throw new AdbError(`adb install did not report Success for "${apkPath}": ${out.trim() || "(no output)"}`);
+    }
+}
+export async function isPackageInstalled(pkg) {
+    const out = await adbShell(["pm", "list", "packages", pkg]);
+    // `pm list packages <filter>` does a substring match; confirm an exact line.
+    return out.split("\n").some((l) => l.trim() === `package:${pkg}`);
+}
+// --- Accessibility tree (uiautomator) ---
+/**
+ * Dump the current view hierarchy as uiautomator XML and return it. Mirrors the
+ * oracle's `ui_dump`: uiautomator fails transiently with "window in transition"
+ * (right after a UI change, writes nothing) or "could not get idle state" (a
+ * view animates forever), so we retry a few times, nudging the device awake
+ * between tries since a screen-off device never goes idle-with-content.
+ *
+ * Uses `exec-out uiautomator dump /dev/tty` so the XML comes back on stdout in
+ * one shot (no pull); falls back to dump-to-file + pull if the device writes the
+ * "dumped to" line to a path instead. Throws AdbError if every attempt fails so
+ * the caller can degrade to the vision path.
+ */
+export async function dumpUiautomatorXml() {
+    const devPath = "/sdcard/ish-ax.xml";
+    let lastErr = "";
+    for (let i = 0; i < 3; i++) {
+        try {
+            // `exec-out ... dump /dev/tty` streams the XML to stdout; on success the
+            // output contains the `<hierarchy ...>` root. Some builds still print
+            // "UI hierchary dumped to: <path>" instead — handle both.
+            const out = await adb(["exec-out", "uiautomator", "dump", "/dev/tty"]);
+            const xml = extractHierarchyXml(out);
+            if (xml)
+                return xml;
+            // Fall back to dump-to-file + pull when stdout didn't carry the XML.
+            if (/dumped to/i.test(out)) {
+                const pulled = await adb(["exec-out", "cat", devPath]);
+                const fileXml = extractHierarchyXml(pulled);
+                if (fileXml)
+                    return fileXml;
+            }
+            lastErr = out.trim() || "(no hierarchy in output)";
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err.message : String(err);
+        }
+        // Nudge the device toward an idle, awake, content-bearing state, then retry.
+        await wakeDevice();
+        await delay(800);
+    }
+    throw new AdbError(`uiautomator dump failed after retries (last: ${lastErr})`);
+}
+/** Pull the `<hierarchy>...</hierarchy>` payload out of a dump's stdout, or "". */
+function extractHierarchyXml(out) {
+    const start = out.indexOf("<hierarchy");
+    if (start < 0)
+        return "";
+    const end = out.lastIndexOf("</hierarchy>");
+    if (end < 0)
+        return "";
+    return out.slice(start, end + "</hierarchy>".length);
+}
+/** WAKEUP keyevent (224) + MENU (82) to dismiss the keyguard. Best-effort. */
+async function wakeDevice() {
+    try {
+        await pressKeyEvent("KEYCODE_WAKEUP");
+    }
+    catch {
+        // best-effort wake; a failure here shouldn't abort the dump retry loop
+    }
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** All installed package names (the set of `package:<name>` lines). */
+export async function listPackages() {
+    const out = await adbShell(["pm", "list", "packages"]);
+    const pkgs = new Set();
+    for (const line of out.split("\n")) {
+        const t = line.trim();
+        if (t.startsWith("package:"))
+            pkgs.add(t.slice("package:".length));
+    }
+    return pkgs;
+}

package/dist/lib/local-sim/android.d.ts

@@ -0,0 +1,111 @@
+/**
+ * AndroidDevice — drives a local Android emulator/device via `adb`, implementing
+ * the SimulationDevice surface the loop expects.
+ *
+ * Two resolution paths, mirroring the browser:
+ *  - ELEMENT (preferred): observe() dumps the uiautomator a11y tree, serializes
+ *    it to the `[id] role "label"` string the backend DOMLocator reasons over,
+ *    and keeps a local `shortId → bounds` map. The backend returns a `node_id`;
+ *    executeAction() looks the bounds up locally and taps the row's CENTER.
+ *  - VISION (fallback): when the dump fails or yields a sparse tree, observe()
+ *    returns an empty tree so the backend takes its vision branch and returns
+ *    NORMALIZED 0-1000 coordinates, which we de-normalize and tap (the original
+ *    path). The vision path is also taken per-action whenever node_id is absent.
+ *
+ * Coordinate contract (see scripts/mobile-e2e + CROSS-REPO CONTRACT):
+ *   adb `screencap` and `input tap` share ONE pixel space — NO DPR correction.
+ *   - Element path: uiautomator bounds are screencap PIXELS, so the bounds-center
+ *     is already a pixel center — tap and record it as-is.
+ *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
+ */
+import type { LocalStepAction, ContextValue } from "./types.js";
+import type { SimulationDevice, DeviceObservation, DeviceActionResult } from "./device.js";
+export interface AndroidDeviceOptions {
+    /** App package name to force-stop/relaunch between participants. May be derived from --app. */
+    appPackage?: string;
+    /** Local .apk path to install before the run, or a package name to launch. */
+    appPath?: string;
+    contextValues: ContextValue[];
+    log?: (msg: string) => void;
+}
+export declare class AndroidDevice implements SimulationDevice {
+    private readonly contextValues;
+    private readonly log;
+    private appPackage;
+    private readonly appPath;
+    /** screencap pixel size from the most recent capture — the de-normalization basis. */
+    private screenWidth;
+    private screenHeight;
+    /**
+     * shortId → bounds (screencap PIXELS) from the last observe(), the local
+     * counterpart of BrowserDevice.lastTreeData. executeAction() resolves a
+     * backend `node_id` against this and taps the bounds CENTER (element path).
+     */
+    private lastNodeMap;
+    /** IME to restore on close (null if we never switched it). */
+    private previousIme;
+    private adbKeyboardActive;
+    constructor(opts: AndroidDeviceOptions);
+    launchOrReset(target: string): Promise<void>;
+    /**
+     * Resolve which package to drive, returning a non-null package name or
+     * throwing. For a local .apk we read the package straight from its binary
+     * AndroidManifest (no aapt) — works whether the apk is fresh or already
+     * installed. If that parse fails we fall back to diffing the installed-package
+     * list across install, then to a foreground read; an unresolvable case throws
+     * and asks for an explicit package.
+     */
+    private resolvePackage;
+    private ensureAdbKeyboard;
+    private refreshDimensions;
+    observe(): Promise<DeviceObservation>;
+    /**
+     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
+     * exhausted, parse error) degrades to an empty tree so the backend falls back
+     * to the vision path — a missing tree must never abort the observation.
+     */
+    private dumpTree;
+    captureScreenshot(): Promise<string>;
+    captureScreenshotJpeg(): Promise<Buffer>;
+    dimensions(): {
+        width: number;
+        height: number;
+    };
+    /** Normalized 0-1000 → screencap pixel space. NO DPR correction. */
+    private toPixels;
+    /**
+     * Resolve the pixel target for a positional action. The ELEMENT path wins when
+     * the backend returned a `node_id`: look the bounds up in the last observe()'s
+     * nodeMap and tap the row's CENTER (already in screencap pixels). Otherwise the
+     * VISION path de-normalizes the backend's 0-1000 coordinates. Returns:
+     *  - {target} on success,
+     *  - {stale:true} when a node_id has no bounds (the tree moved under us) — the
+     *    caller fails the action so the loop forwards DOM_ELEMENT_NOT_FOUND and the
+     *    agent re-observes/retries,
+     *  - {target:null} when neither node_id nor coordinates were supplied.
+     */
+    private resolveTarget;
+    executeAction(action: LocalStepAction): Promise<DeviceActionResult>;
+    private failNoCoords;
+    private failStaleNode;
+    private typeText;
+    private scroll;
+    private swipe;
+    /**
+     * Perform a drag: press the GRABBED element, move to the drop point, release.
+     * A drag is "click an element and let it go", so the press lands element-
+     * center (the resolved `grab` — node_id bounds center, or the vision
+     * coordinate when the tree is blind), NOT the backend's vision-estimated
+     * start. The release point is the drag END (drag.endX/endY). Both the grab
+     * fallback and the end de-normalize against screencap pixels. `inputDrag`
+     * (`input draganddrop`) dwells at the press point first so a long-press
+     * pickup registers — a slow swipe would read as a directional swipe instead.
+     * Returns the grab pixel point to record, or null if there's no end to drag
+     * toward.
+     */
+    private drag;
+    private rotate;
+    private failUnsupported;
+    currentUrl(): string;
+    close(): Promise<void>;
+}