@phone-use/sdk 0.4.1 → 0.5.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { a as registerBackend, c as DeviceInUseError, d as SessionNotFoundError, f as TimeoutError, i as listBackends, l as DeviceNotFoundError, m as toPhoneUseError, n as BaseDeviceBackend, o as AbortedError, p as UnsupportedCapabilityError, r as getBackendFactory, s as ActionFailedError, t as ALL_CAPABILITIES, u as PhoneUseError } from "./device-Xsy_LPUF.mjs";
 import { createAgentDeviceClient } from "agent-device";
+import { execFile, spawn } from "node:child_process";
 import { writeFile } from "node:fs/promises";
-import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 //#region src/observe.ts
 const NOISE_LABELS = /* @__PURE__ */ new Set([
@@ -1471,6 +1471,917 @@ function createAgentDeviceBackend(config) {
 	return new AgentDeviceBackend(config);
 }
 //#endregion
+//#region src/exec.ts
+const pExecFile$1 = promisify(execFile);
+const defaultExecRunner = async (file, args, opts) => {
+	const { stdout, stderr } = await pExecFile$1(file, args, {
+		encoding: "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+		...opts?.timeoutMs === void 0 ? {} : { timeout: opts.timeoutMs },
+		...opts?.env === void 0 ? {} : { env: opts.env }
+	});
+	return {
+		stdout,
+		stderr
+	};
+};
+function isExecError(err) {
+	return err instanceof Error && ("code" in err || "killed" in err || "stderr" in err);
+}
+//#endregion
+//#region src/lifecycle.ts
+var IdleLease = class {
+	timer = null;
+	windowMs;
+	onExpire;
+	constructor(windowMs, onExpire) {
+		this.windowMs = windowMs;
+		this.onExpire = onExpire;
+		this.touch();
+	}
+	/** Re-arm with the configured window (no-op when disabled). */
+	touch() {
+		this.arm(this.windowMs);
+	}
+	/** Re-arm with a one-shot override window. */
+	extend(ms) {
+		this.arm(ms ?? this.windowMs);
+	}
+	arm(ms) {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = null;
+		if (ms === false) return;
+		const t = setTimeout(this.onExpire, ms);
+		t.unref?.();
+		this.timer = t;
+	}
+	dispose() {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = null;
+	}
+};
+/**
+* Assemble a Device handle over a backend: lease/reaper, verb surface,
+* close/dispose semantics. Engine authors (ios and android here,
+* phone-backend-* third parties) build on this; tests fabricate devices with
+* it over a FakeBackend.
+*/
+function createDeviceHandle(opts) {
+	let status = "running";
+	let closePromise = null;
+	const close = () => {
+		closePromise ??= (async () => {
+			status = "closed";
+			lease.dispose();
+			await opts.backend.closeSession().catch(() => void 0);
+			await opts.doClose();
+		})();
+		return closePromise;
+	};
+	const lease = new IdleLease(opts.idleTimeoutMs ?? 18e4, () => {
+		close().catch(() => void 0).then(() => opts.onIdleClose?.(device));
+	});
+	const touchingBackend = new Proxy(opts.backend, { get(target, prop, receiver) {
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value !== "function") return value;
+		return (...args) => {
+			if (status === "running") lease.touch();
+			return value.apply(target, args);
+		};
+	} });
+	const core = opts.coreFactory?.(touchingBackend) ?? new DeviceCore(touchingBackend);
+	const secrets = new SecretStore(opts.secrets);
+	const assertOpen = () => {
+		if (status === "closed") throw new SessionNotFoundError(`device ${opts.id} is closed`);
+	};
+	const toQuery = (target) => typeof target === "string" ? { label: target } : target;
+	const device = {
+		id: opts.id,
+		platform: opts.platform,
+		name: opts.name,
+		backendName: opts.backend.backendName,
+		capabilities: opts.backend.capabilities,
+		backend: touchingBackend,
+		createdByUs: opts.createdByUs,
+		get status() {
+			return status;
+		},
+		get isClosed() {
+			return status === "closed";
+		},
+		extendLease(ms) {
+			if (status === "running") lease.extend(ms);
+		},
+		close,
+		[Symbol.asyncDispose]: close,
+		observe() {
+			assertOpen();
+			return buildObserveResult(core, secrets);
+		},
+		tap(target, actOpts = {}) {
+			assertOpen();
+			return executeAction(core, {
+				formatVersion: 0,
+				verb: "tap",
+				target: toQuery(target)
+			}, actOpts, secrets);
+		},
+		type(text, actOpts = {}) {
+			assertOpen();
+			const { field, submit, ...rest } = actOpts;
+			const action = field === void 0 ? {
+				formatVersion: 0,
+				verb: "type",
+				params: {
+					text,
+					submit
+				}
+			} : {
+				formatVersion: 0,
+				verb: "fill",
+				target: toQuery(field),
+				params: {
+					text,
+					submit
+				}
+			};
+			return executeAction(core, action, rest, secrets);
+		},
+		act(action, actOpts = {}) {
+			assertOpen();
+			return executeAction(core, action, actOpts, secrets);
+		},
+		apps: {
+			open(app, o = {}) {
+				assertOpen();
+				const action = o.url === void 0 ? {
+					formatVersion: 0,
+					verb: "openApp",
+					params: {
+						app,
+						relaunch: o.relaunch
+					}
+				} : {
+					formatVersion: 0,
+					verb: "openUrl",
+					params: {
+						app,
+						url: o.url
+					}
+				};
+				return executeAction(core, action, { signal: o.signal }, secrets);
+			},
+			list(o = {}) {
+				assertOpen();
+				return core.listApps();
+			},
+			current() {
+				return core.currentApp();
+			}
+		},
+		screen: {
+			scroll(direction, o = {}) {
+				assertOpen();
+				return executeAction(core, {
+					formatVersion: 0,
+					verb: "scroll",
+					params: { direction }
+				}, { signal: o.signal }, secrets);
+			},
+			async screenshot(o) {
+				assertOpen();
+				return {
+					success: true,
+					message: `screenshot saved`,
+					path: await core.screenshot(o.path)
+				};
+			},
+			waitForText(text, o = {}) {
+				assertOpen();
+				return executeAction(core, {
+					formatVersion: 0,
+					verb: "waitForText",
+					params: { text }
+				}, {
+					signal: o.signal,
+					timeoutMs: o.timeoutMs
+				}, secrets);
+			},
+			alert(action, o = {}) {
+				assertOpen();
+				if (action === "get") return core.handleAlert("get").then((r) => ({
+					success: r.present,
+					message: r.present ? `alert: ${r.description ?? ""}` : "no system alert is showing"
+				}));
+				return executeAction(core, {
+					formatVersion: 0,
+					verb: "alert",
+					params: { alertAction: action }
+				}, { signal: o.signal }, secrets);
+			},
+			back(o = {}) {
+				assertOpen();
+				return executeAction(core, {
+					formatVersion: 0,
+					verb: "back"
+				}, { signal: o.signal }, secrets);
+			},
+			home(o = {}) {
+				assertOpen();
+				return executeAction(core, {
+					formatVersion: 0,
+					verb: "home"
+				}, { signal: o.signal }, secrets);
+			}
+		},
+		secrets
+	};
+	return device;
+}
+//#endregion
+//#region src/backends/android-hierarchy.ts
+/** `[x1,y1][x2,y2]` → a top-left Rect. Returns undefined if unparseable. */
+function parseBounds(bounds) {
+	const m = bounds?.match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/);
+	if (!m) return void 0;
+	const x1 = Number(m[1]);
+	const y1 = Number(m[2]);
+	const x2 = Number(m[3]);
+	const y2 = Number(m[4]);
+	return {
+		x: x1,
+		y: y1,
+		width: x2 - x1,
+		height: y2 - y1
+	};
+}
+/** `android.widget.Button` → `Button`; keeps a bare token as-is. */
+function shortType(className) {
+	if (!className) return void 0;
+	const tail = className.split(".").pop();
+	return tail && tail.length > 0 ? tail : className;
+}
+/**
+* Normalise Android widget classes to the harness's canonical (iOS-named)
+* element types, so every layer above — inputFields(), setField(), the
+* interactive/editable sets in the SDK — works unchanged on Android.
+*
+* This is load-bearing: without it `type --field` reports "no editable text
+* field" on a real Android because `AutoCompleteTextView` never matches the
+* SDK's EDITABLE set ({SearchField, TextField, SecureTextField}). Measured on
+* a OnePlus Nord: the Settings search box is an AutoCompleteTextView.
+*/
+function canonicalType(shortName, attrs) {
+	if (!shortName) return void 0;
+	const isPassword = attrs.password === "true";
+	switch (shortName) {
+		case "EditText":
+		case "AutoCompleteTextView":
+		case "MultiAutoCompleteTextView":
+		case "SearchView":
+		case "TextInputEditText": return isPassword ? "SecureTextField" : "TextField";
+		case "Switch":
+		case "SwitchCompat":
+		case "CheckBox":
+		case "ToggleButton":
+		case "RadioButton": return "Switch";
+		case "SeekBar": return "Slider";
+		case "ImageButton": return "Button";
+		default:
+			if (attrs.clickable === "true") return "Button";
+			return shortName;
+	}
+}
+const ATTR = /([\w:-]+)="([^"]*)"/g;
+function attrs(fragment) {
+	const out = {};
+	for (const m of fragment.matchAll(ATTR)) {
+		const key = m[1];
+		const val = m[2];
+		if (key !== void 0 && val !== void 0) out[key] = decodeEntities(val);
+	}
+	return out;
+}
+function decodeEntities(s) {
+	return s.replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'");
+}
+const isTrue = (v) => v === "true";
+/**
+* Parse a uiautomator XML dump. Each <node> becomes a SnapshotNode with a
+* fresh `@aN` ref. When `interactiveOnly`, keep only nodes that are actually
+* actionable (clickable / long-clickable / a focusable field) or that carry a
+* label — the rest is layout scaffolding an agent should not try to tap.
+*/
+function parseHierarchy(xml, opts = {}) {
+	const nodes = [];
+	const rects = /* @__PURE__ */ new Map();
+	let packageName;
+	let index = 0;
+	for (const m of xml.matchAll(/<node\b([^>]*?)\/?>/g)) {
+		const fragment = m[1];
+		if (fragment === void 0) continue;
+		const a = attrs(fragment);
+		if (!packageName && a.package) packageName = a.package;
+		const label = a.text || a["content-desc"] || void 0;
+		const clickable = isTrue(a.clickable) || isTrue(a["long-clickable"]);
+		const focusableField = isTrue(a.focusable) && (label !== void 0 || isTrue(a.editable));
+		if (opts.interactiveOnly && !clickable && !focusableField && !label) continue;
+		index += 1;
+		const ref = `@a${index}`;
+		const rect = parseBounds(a.bounds);
+		if (rect) rects.set(ref, rect);
+		const node = {
+			ref,
+			type: canonicalType(shortType(a.class), a),
+			role: canonicalType(shortType(a.class), a),
+			...label !== void 0 ? { label } : {},
+			...a.text && a.text !== label ? { value: a.text } : {},
+			...a["resource-id"] ? { identifier: a["resource-id"] } : {},
+			enabled: a.enabled ? isTrue(a.enabled) : true,
+			selected: isTrue(a.selected),
+			focused: isTrue(a.focused),
+			...rect ? { rect } : {},
+			...a.enabled && !isTrue(a.enabled) ? { interactionBlocked: "disabled" } : {}
+		};
+		nodes.push(node);
+	}
+	return {
+		nodes,
+		rects,
+		...packageName ? { packageName } : {}
+	};
+}
+//#endregion
+//#region src/backends/android.ts
+/** Android keycodes used below (KeyEvent constants). */
+const KEYCODE = {
+	home: 3,
+	back: 4,
+	enter: 66,
+	del: 67,
+	moveEnd: 123
+};
+/** Where uiautomator writes its dump: /data/local/tmp round-trips on scoped-storage builds, /sdcard does not. */
+const DUMP_PATH = "/data/local/tmp/phone-use-dump.xml";
+/** A package id as Android accepts it: dotted Java-style segments. */
+const PACKAGE_RE = /^[A-Za-z][\w]*(\.[A-Za-z][\w]*)+$/;
+/** `com.pkg/.Activity` as `cmd package resolve-activity --brief` prints it. */
+const ACTIVITY_RE = /^[\w.]+\/[\w.$]+$/;
+/** Characters that need no quoting for the device's /bin/sh. */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+* Quote one argument for the device shell. `adb shell` does not escape its
+* arguments, so this is the injection boundary for every device command.
+*/
+function shellQuote(arg) {
+	if (arg.length > 0 && SHELL_SAFE.test(arg)) return arg;
+	return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** True when every char is printable ASCII — the range `input text` can deliver. */
+function isPrintableAscii(text) {
+	for (let i = 0; i < text.length; i += 1) {
+		const c = text.charCodeAt(i);
+		if (c < 32 || c > 126) return false;
+	}
+	return true;
+}
+const pExecFile = promisify(execFile);
+const defaultBinaryExecRunner = async (file, args, opts) => {
+	const { stdout } = await pExecFile(file, args, {
+		encoding: "buffer",
+		maxBuffer: 64 * 1024 * 1024,
+		...opts?.timeoutMs === void 0 ? {} : { timeout: opts.timeoutMs }
+	});
+	return new Uint8Array(stdout);
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Drive an Android device or emulator over adb. Implements the
+* {@link DeviceBackend} contract with uiautomator for the tree, screencap for
+* pixels, and `input` for gestures. Stateless across calls except the ref → rect
+* map from the last snapshot (what makes press-by-ref work).
+*/
+var AndroidBackend = class AndroidBackend extends BaseDeviceBackend {
+	serial;
+	adbBin;
+	timeoutMs;
+	exec;
+	execBinary;
+	sleep;
+	rects = /* @__PURE__ */ new Map();
+	sizeCache = null;
+	launchablesCache = null;
+	constructor(opts = {}) {
+		super("android-adb", [
+			"snapshot",
+			"screenshot",
+			"press",
+			"longPress",
+			"fill",
+			"type",
+			"key",
+			"scroll",
+			"pan",
+			"waitForText",
+			"home",
+			"back",
+			"openApp",
+			"openUrl",
+			"listApps",
+			"closeSession"
+		]);
+		this.serial = opts.serial;
+		this.adbBin = opts.adbBin ?? "adb";
+		this.timeoutMs = opts.commandTimeoutMs ?? 3e4;
+		this.exec = opts.exec ?? defaultExecRunner;
+		this.execBinary = opts.execBinary ?? defaultBinaryExecRunner;
+		this.sleep = opts.sleep ?? defaultSleep;
+	}
+	withSerial(args) {
+		return this.serial ? [
+			"-s",
+			this.serial,
+			...args
+		] : args;
+	}
+	/** Normalize an exec failure into the PhoneUseError the contract promises. */
+	fail(what, err) {
+		if (err instanceof PhoneUseError) return err;
+		if (isExecError(err)) {
+			const stderr = (err.stderr ?? "").trim();
+			if (err.killed || err.signal) return new TimeoutError(`adb ${what} timed out after ${this.timeoutMs}ms`, { cause: err });
+			if (err.code === "ENOENT") return new ActionFailedError(`adb not found at "${this.adbBin}" — install the Android platform-tools or pass adbBin`, { cause: err });
+			if (/not found|no devices\/emulators|device offline|more than one device|unauthorized/i.test(stderr)) return new DeviceNotFoundError(`adb ${what}: ${stderr}`, { cause: err });
+			return new ActionFailedError(`adb ${what} failed (exit ${String(err.code ?? "?")}): ${stderr || err.message}`, {
+				details: { backendCode: String(err.code ?? "EXEC") },
+				cause: err
+			});
+		}
+		return new ActionFailedError(`adb ${what} failed: ${String(err)}`, { cause: err });
+	}
+	/** Run an adb command, returning stdout text. */
+	async adb(args) {
+		try {
+			return (await this.exec(this.adbBin, this.withSerial(args), { timeoutMs: this.timeoutMs })).stdout;
+		} catch (err) {
+			throw this.fail(args.slice(0, 2).join(" "), err);
+		}
+	}
+	/** `adb shell <argv>` — each argument quoted for the device shell. */
+	shell(...argv) {
+		return this.adb(["shell", argv.map(shellQuote).join(" ")]);
+	}
+	/** `adb shell <literal>` for the few CONSTANT commands that need a pipe. Never pass input. */
+	shellRaw(literal) {
+		return this.adb(["shell", literal]);
+	}
+	center(ref) {
+		const rect = this.rects.get(ref);
+		if (!rect) throw new ActionFailedError(`unknown element ${ref} — take a fresh snapshot first`);
+		return {
+			x: Math.round(rect.x + rect.width / 2),
+			y: Math.round(rect.y + rect.height / 2)
+		};
+	}
+	/** The screen size input coordinates map to (an `Override size` wins over `Physical size`). */
+	async screenSize() {
+		if (this.sizeCache) return this.sizeCache;
+		const out = await this.shell("wm", "size");
+		const m = out.match(/Override size:\s*(\d+)x(\d+)/) ?? out.match(/Physical size:\s*(\d+)x(\d+)/);
+		if (!m) throw new ActionFailedError(`could not read screen size from: ${out.trim()}`);
+		this.sizeCache = {
+			width: Number(m[1]),
+			height: Number(m[2])
+		};
+		return this.sizeCache;
+	}
+	async snapshot(opts) {
+		const size = await this.screenSize();
+		let xml = "";
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt += 1) {
+			try {
+				await this.shell("uiautomator", "dump", DUMP_PATH);
+				xml = await this.adb([
+					"exec-out",
+					"cat",
+					DUMP_PATH
+				]);
+			} catch (err) {
+				lastError = err;
+			}
+			if (xml.includes("<node")) break;
+			await this.sleep(400);
+		}
+		if (!xml.includes("<node")) throw new ActionFailedError("uiautomator dump produced no UI nodes after 3 attempts — the UI may be mid-transition or uiautomator may be wedged (try `adb shell uiautomator dump` by hand)", { cause: lastError });
+		const parsed = parseHierarchy(xml, { interactiveOnly: opts?.interactiveOnly ?? false });
+		this.rects = parsed.rects;
+		const appName = await this.foregroundPackage().catch(() => void 0) ?? parsed.packageName;
+		return {
+			nodes: [{
+				ref: "@a0",
+				type: "Application",
+				role: "Application",
+				label: appName ?? "android",
+				rect: {
+					x: 0,
+					y: 0,
+					width: size.width,
+					height: size.height
+				}
+			}, ...parsed.nodes],
+			...appName ? {
+				appName,
+				appBundleId: appName
+			} : {}
+		};
+	}
+	/** The package of the resumed (frontmost) activity, for the snapshot header. */
+	async foregroundPackage() {
+		return (await this.shellRaw("dumpsys activity activities | grep -m1 ResumedActivity")).match(/\su0\s+([\w.]+)\//)?.[1];
+	}
+	async screenshot(opts) {
+		let png;
+		try {
+			png = await this.execBinary(this.adbBin, this.withSerial([
+				"exec-out",
+				"screencap",
+				"-p"
+			]), { timeoutMs: this.timeoutMs });
+		} catch (err) {
+			throw this.fail("screencap", err);
+		}
+		await writeFile(opts.path, png);
+		return { path: opts.path };
+	}
+	async press(target) {
+		const { x, y } = "ref" in target ? this.center(target.ref) : target;
+		await this.shell("input", "tap", String(Math.round(x)), String(Math.round(y)));
+	}
+	async longPress(ref, durationMs = 700) {
+		const { x, y } = this.center(ref);
+		await this.shell("input", "swipe", String(x), String(y), String(x), String(y), String(Math.max(400, durationMs)));
+	}
+	async fill(ref, text) {
+		const { x, y } = this.center(ref);
+		await this.shell("input", "tap", String(x), String(y));
+		await this.sleep(120);
+		await this.clearFocusedField();
+		await this.typeText(text);
+	}
+	/**
+	* Empty the currently-focused text field. Ctrl+A then DEL (`input
+	* keycombination`, Android 12+); a short MOVE_END + backspace sweep stays as
+	* the fallback for the rare field that ignores the select combo. Replaces a
+	* 60-backspace sweep that left residue on long fields and made repeated
+	* `type`s ACCUMULATE, sending the agent into retry loops.
+	*/
+	async clearFocusedField() {
+		await this.shell("input", "keycombination", "113", "29").catch(() => void 0);
+		await this.shell("input", "keyevent", String(KEYCODE.del));
+		await this.shell("input", "keyevent", String(KEYCODE.moveEnd));
+		for (let i = 0; i < 8; i += 1) await this.shell("input", "keyevent", String(KEYCODE.del));
+	}
+	async typeText(text) {
+		if (!text) return;
+		for (const [i, line] of text.split("\n").entries()) {
+			if (i > 0) await this.shell("input", "keyevent", String(KEYCODE.enter));
+			for (const [j, chunk] of line.split("\b").entries()) {
+				if (j > 0) await this.shell("input", "keyevent", String(KEYCODE.del));
+				if (!chunk) continue;
+				if (isPrintableAscii(chunk)) for (let at = 0; at < chunk.length; at += 400) await this.shell("input", "text", chunk.slice(at, at + 400));
+				else await this.typeUnicode(chunk);
+			}
+		}
+	}
+	/** The IME id of senzhk/ADBKeyBoard, the de-facto Unicode input path for adb. */
+	static ADB_IME = "com.android.adbkeyboard/.AdbIME";
+	/**
+	* Type non-ASCII via the ADB Keyboard broadcast. The IME must be the ACTIVE
+	* keyboard; some OEM builds deny the shell WRITE_SECURE_SETTINGS so `ime set`
+	* cannot switch it. We try (works on stock builds) and restore the previous
+	* keyboard afterwards when we did the switching. Never a silent drop.
+	*/
+	async typeUnicode(text) {
+		const ime = AndroidBackend.ADB_IME;
+		if (!(await this.shell("pm", "list", "packages", "com.android.adbkeyboard").catch(() => "")).includes("com.android.adbkeyboard")) throw new ActionFailedError(`Android cannot type non-ASCII text ("${text.slice(0, 20)}…") over adb: the platform's own \`input text\` rejects it and no built-in alternative exists. ASCII works. For accented or non-Latin text, tap the field and use the on-screen keyboard (tap the keys), or paste text the user already has on the clipboard. (Dev/test devices only: the ADB Keyboard IME — github.com/senzhk/ADBKeyBoard — enables Unicode over adb.)`);
+		const previous = (await this.shell("settings", "get", "secure", "default_input_method").catch(() => "")).trim();
+		let switched = false;
+		if (previous !== ime) {
+			await this.shell("ime", "enable", ime).catch(() => void 0);
+			await this.shell("ime", "set", ime).catch(() => void 0);
+			switched = (await this.shell("settings", "get", "secure", "default_input_method").catch(() => "")).trim() === ime;
+			if (!switched) throw new ActionFailedError("Android cannot type non-ASCII text over adb on this device: the ADB Keyboard IME is installed but the OS blocks adb from activating it (WRITE_SECURE_SETTINGS denied). ASCII works. For accented or non-Latin text, tap the field and use the on-screen keyboard, or paste from the clipboard. (Dev/test: enable ADB Keyboard once in Settings → Languages & input → Manage keyboards.)");
+			await this.sleep(300);
+		}
+		try {
+			const b64 = Buffer.from(text, "utf8").toString("base64");
+			await this.shell("am", "broadcast", "-a", "ADB_INPUT_B64", "--es", "msg", b64);
+			await this.sleep(150);
+		} finally {
+			if (switched && previous) await this.shell("ime", "set", previous).catch(() => void 0);
+		}
+	}
+	async pressKey(_key) {
+		await this.shell("input", "keyevent", String(KEYCODE.enter));
+	}
+	async scroll(direction) {
+		const { width, height } = await this.screenSize();
+		const imeShown = (await this.shell("dumpsys", "input_method").catch(() => "")).includes("mInputShown=true");
+		const cx = Math.round(width / 2);
+		const cy = imeShown ? Math.round(height * .3) : Math.round(height / 2);
+		const dx = Math.round(width * .35);
+		const dy = imeShown ? Math.round(height * .15) : Math.round(height * .35);
+		const from = {
+			up: [cx, cy - dy],
+			down: [cx, cy + dy],
+			left: [cx - dx, cy],
+			right: [cx + dx, cy]
+		};
+		const to = {
+			up: [cx, cy + dy],
+			down: [cx, cy - dy],
+			left: [cx + dx, cy],
+			right: [cx - dx, cy]
+		};
+		const [fx, fy] = from[direction];
+		const [tx, ty] = to[direction];
+		await this.shell("input", "swipe", String(fx), String(fy), String(tx), String(ty), "300");
+	}
+	async pan(x, y, dx, dy, durationMs = 300) {
+		await this.shell("input", "swipe", String(Math.round(x)), String(Math.round(y)), String(Math.round(x + dx)), String(Math.round(y + dy)), String(Math.max(50, durationMs)));
+	}
+	async waitForText(text, timeoutMs = 8e3) {
+		const deadline = Date.now() + timeoutMs;
+		const needle = text.toLowerCase();
+		for (;;) {
+			if ((await this.snapshot()).nodes.some((n) => (n.label ?? "").toLowerCase().includes(needle))) return;
+			if (Date.now() >= deadline) throw new TimeoutError(`"${text}" did not appear within ${timeoutMs}ms`);
+			await this.sleep(500);
+		}
+	}
+	async home() {
+		await this.shell("input", "keyevent", String(KEYCODE.home));
+	}
+	async back() {
+		await this.shell("input", "keyevent", String(KEYCODE.back));
+	}
+	/** Packages that expose a launcher icon — the set `open <name>` can resolve to. */
+	async launchables() {
+		if (this.launchablesCache) return this.launchablesCache;
+		const out = await this.shell("cmd", "package", "query-activities", "-a", "android.intent.action.MAIN", "-c", "android.intent.category.LAUNCHER").catch(() => "");
+		const pkgs = [...new Set([...out.matchAll(/packageName=([\w.]+)/g)].map((m) => m[1]))];
+		if (pkgs.length) this.launchablesCache = pkgs;
+		return pkgs;
+	}
+	/**
+	* Resolve a human app name to an installed package: agents say "Markor" or
+	* "Simple Calendar", `am` needs `net.gsantner.markor`. Score each launchable
+	* package by how many of the query's words appear in its id; best (shortest
+	* on a tie) wins. An exact package id passes straight through. Returns
+	* undefined when nothing matches and the query is not a package id at all.
+	*/
+	async resolvePackage(query) {
+		const launch = await this.launchables();
+		if (launch.includes(query)) return query;
+		if (PACKAGE_RE.test(query)) return query;
+		const norm = (v) => v.toLowerCase().replace(/[^a-z0-9]/g, "");
+		const words = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+		let best = null;
+		for (const pkg of launch) {
+			const np = norm(pkg);
+			const score = words.filter((w) => np.includes(w)).length;
+			if (score === 0) continue;
+			if (!best || score > best.score || score === best.score && pkg.length < best.pkg.length) best = {
+				pkg,
+				score
+			};
+		}
+		return best?.pkg;
+	}
+	async openApp(opts) {
+		if (opts.url) {
+			await this.shell("am", "start", "-a", "android.intent.action.VIEW", "-d", opts.url);
+			return {};
+		}
+		if (!opts.app) throw new ActionFailedError("openApp needs an app name/package id or a url");
+		const pkg = await this.resolvePackage(opts.app);
+		if (!pkg) throw new DeviceNotFoundError(`no installed app matches "${opts.app}" — pass a launcher name or a package id (see listApps)`);
+		if (opts.relaunch) await this.shell("am", "force-stop", pkg).catch(() => void 0);
+		const activity = (await this.shell("cmd", "package", "resolve-activity", "--brief", "-c", "android.intent.category.LAUNCHER", pkg).catch(() => "")).trim().split("\n").pop()?.trim();
+		if (activity && ACTIVITY_RE.test(activity)) await this.shell("am", "start", "-n", activity);
+		else await this.shell("monkey", "-p", pkg, "-c", "android.intent.category.LAUNCHER", "1").catch(() => void 0);
+		return { appBundleId: pkg };
+	}
+	async listApps() {
+		return (await this.shell("pm", "list", "packages")).split("\n").map((l) => l.replace(/^package:/, "").trim()).filter(Boolean).sort();
+	}
+	closeSession() {
+		return Promise.resolve();
+	}
+};
+/**
+* Backend factory for the `android-adb` registry entry: an
+* {@link AndroidDeviceConfig} pins the serial; anything else targets the single
+* attached device.
+*/
+function createAndroidBackend(config) {
+	if (config && "platform" in config) return new AndroidBackend(config.platform === "android" ? { serial: config.serial } : {});
+	return new AndroidBackend(config);
+}
+/** Parse `adb devices -l` (header dropped). */
+function parseDevices(stdout) {
+	return stdout.split("\n").slice(1).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("*")).map((line) => {
+		const [serial = "", state = "unknown", ...rest] = line.split(/\s+/);
+		const model = rest.find((f) => f.startsWith("model:"))?.slice(6);
+		return {
+			serial,
+			state,
+			...model ? { model } : {}
+		};
+	}).filter((d) => d.serial.length > 0);
+}
+async function runAdb(exec, adbBin, args, timeoutMs) {
+	try {
+		return (await exec(adbBin, args, { timeoutMs })).stdout;
+	} catch (err) {
+		if (isExecError(err)) {
+			if (err.killed || err.signal) throw new TimeoutError(`adb ${args[0]} timed out after ${timeoutMs}ms`, { cause: err });
+			if (err.code === "ENOENT") throw new ActionFailedError(`adb not found at "${adbBin}" — install the Android platform-tools`, { cause: err });
+			throw new ActionFailedError(`adb ${args[0]} failed: ${(err.stderr ?? err.message).trim()}`, { cause: err });
+		}
+		throw new ActionFailedError(`adb ${args[0]} failed: ${String(err)}`, { cause: err });
+	}
+}
+/** Devices adb currently sees, with their state. */
+async function list(options = {}) {
+	return parseDevices(await runAdb(options.exec ?? defaultExecRunner, options.adbBin ?? "adb", ["devices", "-l"], 15e3));
+}
+function finishHandle$1(row, createdByUs, opts, doClose) {
+	const backend = new AndroidBackend({
+		serial: row.serial,
+		adbBin: opts.adbBin,
+		exec: opts.exec,
+		execBinary: opts.execBinary,
+		sleep: opts.sleep
+	});
+	return createDeviceHandle({
+		id: row.serial,
+		platform: "android",
+		name: row.model,
+		backend,
+		createdByUs,
+		idleTimeoutMs: opts.idleTimeoutMs,
+		onIdleClose: opts.onIdleClose,
+		secrets: opts.secrets,
+		coreFactory: opts.coreFactory,
+		doClose
+	});
+}
+const FIX_USB_DEBUGGING = "enable Developer options → USB debugging on the phone, connect over USB (or `adb connect <ip:port>`), and confirm with `adb devices`";
+/**
+* Attach to a device adb already sees. With a serial, that device; without,
+* the single ready device (several attached → an error naming them, so verbs
+* never land on the wrong phone). `close()` releases the handle and never
+* shuts the device down — it was yours before we connected.
+*/
+async function connect$1(serial, options = {}) {
+	const exec = options.exec ?? defaultExecRunner;
+	const devices = await list({
+		adbBin: options.adbBin,
+		exec
+	});
+	let row;
+	if (serial !== void 0) {
+		row = devices.find((d) => d.serial === serial);
+		if (!row) throw new DeviceNotFoundError(`no adb device with serial ${serial} — attached: ${devices.map((d) => `${d.serial} (${d.state})`).join(", ") || "none"}`);
+	} else {
+		const ready = devices.filter((d) => d.state === "device");
+		if (ready.length === 0) {
+			const unauthorized = devices.find((d) => d.state === "unauthorized");
+			throw new DeviceNotFoundError(unauthorized ? `device ${unauthorized.serial} is attached but unauthorized — unlock it and accept the "Allow USB debugging" prompt` : `no Android device attached — ${FIX_USB_DEBUGGING}`);
+		}
+		if (ready.length > 1) throw new DeviceNotFoundError(`several Android devices attached (${ready.map((d) => d.serial).join(", ")}) — pass a serial`);
+		row = ready[0];
+	}
+	if (row.state !== "device") throw new DeviceNotFoundError(row.state === "unauthorized" ? `device ${row.serial} is unauthorized — unlock it and accept the "Allow USB debugging" prompt` : `device ${row.serial} is ${row.state} — ${FIX_USB_DEBUGGING}`);
+	return finishHandle$1(row, false, options, () => Promise.resolve());
+}
+function defaultEmulatorBin() {
+	const root = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+	return root ? `${root}/emulator/emulator` : "emulator";
+}
+function defaultSpawn(file, args) {
+	const child = spawn(file, args, { stdio: "ignore" });
+	let exited = false;
+	child.once("exit", () => {
+		exited = true;
+	});
+	child.once("error", () => {
+		exited = true;
+		child.emit("exit");
+	});
+	return {
+		kill: (signal) => {
+			child.kill(signal);
+		},
+		once: (event, listener) => child.once(event, listener),
+		get exited() {
+			return exited;
+		}
+	};
+}
+/**
+* Boot a DEDICATED emulator instance from an AVD and return a {@link Device}
+* pinned to its serial (`emulator-<port>`). `close()` kills the instance.
+* `readOnly: true` lets several instances of one AVD run side by side, which
+* is how a cloud worker turns one golden image into N phones.
+*/
+async function launch$1(options) {
+	const exec = options.exec ?? defaultExecRunner;
+	const sleep = options.sleep ?? defaultSleep;
+	const adbBin = options.adbBin ?? "adb";
+	const port = options.port ?? 5554;
+	if (port % 2 !== 0 || port < 5554 || port > 5682) throw new ActionFailedError(`emulator port must be an even number in 5554..5682, got ${port}`);
+	const serial = `emulator-${port}`;
+	const bootTimeoutMs = options.bootTimeoutMs ?? 18e4;
+	const pollMs = options.pollIntervalMs ?? 1e3;
+	const spawnEmulator = options.spawn ?? defaultSpawn;
+	const args = [
+		"-avd",
+		options.avd,
+		"-port",
+		String(port),
+		"-no-boot-anim",
+		"-no-audio",
+		...options.headless === false ? [] : ["-no-window"],
+		...options.readOnly ? ["-read-only"] : [],
+		...options.extraArgs ?? []
+	];
+	const child = spawnEmulator(options.emulatorBin ?? defaultEmulatorBin(), args);
+	const stop = async () => {
+		await runAdb(exec, adbBin, [
+			"-s",
+			serial,
+			"emu",
+			"kill"
+		], 1e4).catch(() => void 0);
+		if (child.exited) return;
+		await new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				child.kill("SIGKILL");
+				resolve();
+			}, 1e4);
+			child.once("exit", () => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+	};
+	try {
+		const deadline = Date.now() + bootTimeoutMs;
+		await runAdb(exec, adbBin, [
+			"-s",
+			serial,
+			"wait-for-device"
+		], bootTimeoutMs);
+		for (;;) {
+			if (child.exited) throw new ActionFailedError(`emulator ${serial} exited during boot`);
+			if ((await runAdb(exec, adbBin, [
+				"-s",
+				serial,
+				"shell",
+				"getprop",
+				"sys.boot_completed"
+			], 15e3).catch(() => "")).trim() === "1") break;
+			if (Date.now() >= deadline) throw new TimeoutError(`emulator ${serial} did not finish booting within ${bootTimeoutMs}ms`);
+			await sleep(pollMs);
+		}
+	} catch (err) {
+		await stop().catch(() => void 0);
+		throw err;
+	}
+	return finishHandle$1({
+		serial,
+		state: "device",
+		model: options.avd
+	}, true, options, stop);
+}
+/**
+* The Android engine object (the `ios` twin): `android.connect()` for a device
+* adb already sees, `android.launch()` for a dedicated emulator instance,
+* `android.list()` to see what is attached. All return/describe the same
+* Device type the iOS engine does.
+*/
+const android = {
+	/** Attach to an attached device or running emulator by serial (no-arg: the single ready device). */
+	connect: connect$1,
+	/** Boot a dedicated emulator instance from an AVD and return a Device pinned to it. */
+	launch: launch$1,
+	/** Devices adb currently sees, with their state. */
+	list
+};
+//#endregion
 //#region src/backends/cloud-sandbox.ts
 var CloudSandboxBackend = class extends BaseDeviceBackend {
 	endpoint;
@@ -1555,6 +2466,24 @@ var CloudSandboxBackend = class extends BaseDeviceBackend {
 	closeSession() {
 		return this.rpc("closeSession");
 	}
+	/** Save the device's current state. Returns the checkpoint's id. */
+	checkpoint(opts) {
+		return this.rpc("checkpoint", opts);
+	}
+	/** Restore a checkpoint by id or label. The checkpoint survives — restore as
+	* often as needed. Device identity may change server-side; the sandbox
+	* endpoint/token stay valid. */
+	restoreCheckpoint(ref) {
+		return this.rpc("restoreCheckpoint", ref);
+	}
+	/** List this sandbox's checkpoints. */
+	listCheckpoints() {
+		return this.rpc("listCheckpoints");
+	}
+	/** Delete a checkpoint by id or label. */
+	deleteCheckpoint(ref) {
+		return this.rpc("deleteCheckpoint", ref);
+	}
 	/** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
 	/**
 	* Upload a zipped .app as a raw stream. Prefer this over {@link installApp}:
@@ -1790,234 +2719,6 @@ var DeviceRunnerBackend = class extends BaseDeviceBackend {
 * `PHONE_USE_RUNNER_URL` / `PHONE_USE_RUNNER_TOKEN` when `config` is omitted). */
 const createDeviceRunnerBackend = (config) => new DeviceRunnerBackend(config);
 //#endregion
-//#region src/exec.ts
-const pExecFile = promisify(execFile);
-const defaultExecRunner = async (file, args, opts) => {
-	const { stdout, stderr } = await pExecFile(file, args, {
-		encoding: "utf8",
-		maxBuffer: 16 * 1024 * 1024,
-		...opts?.timeoutMs === void 0 ? {} : { timeout: opts.timeoutMs },
-		...opts?.env === void 0 ? {} : { env: opts.env }
-	});
-	return {
-		stdout,
-		stderr
-	};
-};
-function isExecError(err) {
-	return err instanceof Error && ("code" in err || "killed" in err || "stderr" in err);
-}
-//#endregion
-//#region src/lifecycle.ts
-var IdleLease = class {
-	timer = null;
-	windowMs;
-	onExpire;
-	constructor(windowMs, onExpire) {
-		this.windowMs = windowMs;
-		this.onExpire = onExpire;
-		this.touch();
-	}
-	/** Re-arm with the configured window (no-op when disabled). */
-	touch() {
-		this.arm(this.windowMs);
-	}
-	/** Re-arm with a one-shot override window. */
-	extend(ms) {
-		this.arm(ms ?? this.windowMs);
-	}
-	arm(ms) {
-		if (this.timer) clearTimeout(this.timer);
-		this.timer = null;
-		if (ms === false) return;
-		const t = setTimeout(this.onExpire, ms);
-		t.unref?.();
-		this.timer = t;
-	}
-	dispose() {
-		if (this.timer) clearTimeout(this.timer);
-		this.timer = null;
-	}
-};
-/**
-* Assemble a Device handle over a backend: lease/reaper, verb surface,
-* close/dispose semantics. Engine authors (ios here, android in item 7b,
-* phone-backend-* third parties) build on this; tests fabricate devices with
-* it over a FakeBackend.
-*/
-function createDeviceHandle(opts) {
-	let status = "running";
-	let closePromise = null;
-	const close = () => {
-		closePromise ??= (async () => {
-			status = "closed";
-			lease.dispose();
-			await opts.backend.closeSession().catch(() => void 0);
-			await opts.doClose();
-		})();
-		return closePromise;
-	};
-	const lease = new IdleLease(opts.idleTimeoutMs ?? 18e4, () => {
-		close().catch(() => void 0).then(() => opts.onIdleClose?.(device));
-	});
-	const touchingBackend = new Proxy(opts.backend, { get(target, prop, receiver) {
-		const value = Reflect.get(target, prop, receiver);
-		if (typeof value !== "function") return value;
-		return (...args) => {
-			if (status === "running") lease.touch();
-			return value.apply(target, args);
-		};
-	} });
-	const core = opts.coreFactory?.(touchingBackend) ?? new DeviceCore(touchingBackend);
-	const secrets = new SecretStore(opts.secrets);
-	const assertOpen = () => {
-		if (status === "closed") throw new SessionNotFoundError(`device ${opts.id} is closed`);
-	};
-	const toQuery = (target) => typeof target === "string" ? { label: target } : target;
-	const device = {
-		id: opts.id,
-		platform: opts.platform,
-		name: opts.name,
-		backendName: opts.backend.backendName,
-		capabilities: opts.backend.capabilities,
-		backend: touchingBackend,
-		createdByUs: opts.createdByUs,
-		get status() {
-			return status;
-		},
-		get isClosed() {
-			return status === "closed";
-		},
-		extendLease(ms) {
-			if (status === "running") lease.extend(ms);
-		},
-		close,
-		[Symbol.asyncDispose]: close,
-		observe() {
-			assertOpen();
-			return buildObserveResult(core, secrets);
-		},
-		tap(target, actOpts = {}) {
-			assertOpen();
-			return executeAction(core, {
-				formatVersion: 0,
-				verb: "tap",
-				target: toQuery(target)
-			}, actOpts, secrets);
-		},
-		type(text, actOpts = {}) {
-			assertOpen();
-			const { field, submit, ...rest } = actOpts;
-			const action = field === void 0 ? {
-				formatVersion: 0,
-				verb: "type",
-				params: {
-					text,
-					submit
-				}
-			} : {
-				formatVersion: 0,
-				verb: "fill",
-				target: toQuery(field),
-				params: {
-					text,
-					submit
-				}
-			};
-			return executeAction(core, action, rest, secrets);
-		},
-		act(action, actOpts = {}) {
-			assertOpen();
-			return executeAction(core, action, actOpts, secrets);
-		},
-		apps: {
-			open(app, o = {}) {
-				assertOpen();
-				const action = o.url === void 0 ? {
-					formatVersion: 0,
-					verb: "openApp",
-					params: {
-						app,
-						relaunch: o.relaunch
-					}
-				} : {
-					formatVersion: 0,
-					verb: "openUrl",
-					params: {
-						app,
-						url: o.url
-					}
-				};
-				return executeAction(core, action, { signal: o.signal }, secrets);
-			},
-			list(o = {}) {
-				assertOpen();
-				return core.listApps();
-			},
-			current() {
-				return core.currentApp();
-			}
-		},
-		screen: {
-			scroll(direction, o = {}) {
-				assertOpen();
-				return executeAction(core, {
-					formatVersion: 0,
-					verb: "scroll",
-					params: { direction }
-				}, { signal: o.signal }, secrets);
-			},
-			async screenshot(o) {
-				assertOpen();
-				return {
-					success: true,
-					message: `screenshot saved`,
-					path: await core.screenshot(o.path)
-				};
-			},
-			waitForText(text, o = {}) {
-				assertOpen();
-				return executeAction(core, {
-					formatVersion: 0,
-					verb: "waitForText",
-					params: { text }
-				}, {
-					signal: o.signal,
-					timeoutMs: o.timeoutMs
-				}, secrets);
-			},
-			alert(action, o = {}) {
-				assertOpen();
-				if (action === "get") return core.handleAlert("get").then((r) => ({
-					success: r.present,
-					message: r.present ? `alert: ${r.description ?? ""}` : "no system alert is showing"
-				}));
-				return executeAction(core, {
-					formatVersion: 0,
-					verb: "alert",
-					params: { alertAction: action }
-				}, { signal: o.signal }, secrets);
-			},
-			back(o = {}) {
-				assertOpen();
-				return executeAction(core, {
-					formatVersion: 0,
-					verb: "back"
-				}, { signal: o.signal }, secrets);
-			},
-			home(o = {}) {
-				assertOpen();
-				return executeAction(core, {
-					formatVersion: 0,
-					verb: "home"
-				}, { signal: o.signal }, secrets);
-			}
-		},
-		secrets
-	};
-	return device;
-}
-//#endregion
 //#region src/backends/ios.ts
 const UDID_RE = /^[0-9A-F]{8}(-[0-9A-F]{4}){3}-[0-9A-F]{12}$/i;
 function simctlArgs(setPath, args) {
@@ -2170,16 +2871,17 @@ const ios = {
 //#region src/index.ts
 /**
 * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
-* (ios.launch/connect → Device), Device backends, config, errors, capabilities,
+* (ios.launch/connect and android.launch/connect → Device), Device backends, config, errors, capabilities,
 * and the action verb surface.
 *
 * The test double (FakeBackend) lives on the "@phone-use/sdk/testing" subpath,
 * deliberately not re-exported here.
 */
 /** The published package version (kept in sync with package.json by the release flow). */
-const VERSION = "0.4.1";
+const VERSION = "0.5.0";
 registerBackend("agent-device", createAgentDeviceBackend);
+registerBackend("android-adb", createAndroidBackend);
 //#endregion
-export { ALL_CAPABILITIES, AbortedError, ActionFailedError, BaseDeviceBackend, CloudSandboxBackend, DeviceCore, DeviceInUseError, DeviceNotFoundError, DeviceRunnerBackend, PhoneUseError, SecretStore, SessionNotFoundError, TimeoutError, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createCloudSandboxBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
+export { ALL_CAPABILITIES, AbortedError, ActionFailedError, AndroidBackend, BaseDeviceBackend, CloudSandboxBackend, DeviceCore, DeviceInUseError, DeviceNotFoundError, DeviceRunnerBackend, PhoneUseError, SecretStore, SessionNotFoundError, TimeoutError, UnsupportedCapabilityError, VERSION, android, buildObserveResult, createAgentDeviceBackend, createAndroidBackend, createCloudSandboxBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
 
 //# sourceMappingURL=index.mjs.map