@phone-use/sdk 0.4.0 → 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([
@@ -50,11 +50,24 @@ function keptViewportNodes(nodes) {
 	const kept = [];
 	let above = 0;
 	let below = 0;
+	const aboveNames = [];
+	const belowNames = [];
+	const controlName = (n) => {
+		const role = n.role ?? n.type ?? "";
+		if (!TAPPABLE.has(role) || role === "StaticText" || role === "Cell") return void 0;
+		return (n.label ?? n.identifier ?? "").trim() || void 0;
+	};
 	for (const n of nodes) {
 		if (isNoise(n)) continue;
 		if (!intersectsViewport(n.rect, vw, vh)) {
-			if (n.rect && n.rect.y >= vh) below += 1;
-			else above += 1;
+			const name = controlName(n);
+			if (n.rect && n.rect.y >= vh) {
+				below += 1;
+				if (name && belowNames.length < 5 && !belowNames.includes(name)) belowNames.push(name);
+			} else {
+				above += 1;
+				if (name && aboveNames.length < 5 && !aboveNames.includes(name)) aboveNames.push(name);
+			}
 			continue;
 		}
 		kept.push(n);
@@ -63,18 +76,21 @@ function keptViewportNodes(nodes) {
 		kept,
 		above,
 		below,
+		aboveNames,
+		belowNames,
 		suppressFocused,
 		vw
 	};
 }
 function compressNodes(nodes) {
-	const { kept, above, below, suppressFocused, vw } = keptViewportNodes(nodes);
+	const { kept, above, below, aboveNames, belowNames, suppressFocused, vw } = keptViewportNodes(nodes);
 	const lines = kept.map((n) => formatNode(n, {
 		suppressFocused,
 		vw
 	}));
-	if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them]`);
-	if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them]`);
+	const controls = (names) => names.length ? ` — controls there: ${names.map((n) => `"${n}"`).join(", ")}` : "";
+	if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them${controls(aboveNames)}]`);
+	if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them${controls(belowNames)}]`);
 	return lines.join("\n");
 }
 function elementKey(n) {
@@ -281,7 +297,7 @@ var DeviceCore = class {
 	*/
 	renderObservation(full = false) {
 		const app = this.lastApp.app;
-		const { kept, above, below, suppressFocused, vw } = keptViewportNodes(this.cachedNodes);
+		const { kept, above, below, aboveNames, belowNames, suppressFocused, vw } = keptViewportNodes(this.cachedNodes);
 		const keys = kept.map(elementKey);
 		const lineByKey = /* @__PURE__ */ new Map();
 		for (const n of kept) lineByKey.set(elementKey(n), formatNode(n, {
@@ -311,8 +327,9 @@ var DeviceCore = class {
 			suppressFocused,
 			vw
 		}));
-		if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them]`);
-		if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them]`);
+		const controls = (names) => names.length ? ` — controls there: ${names.map((n) => `"${n}"`).join(", ")}` : "";
+		if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them${controls(aboveNames)}]`);
+		if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them${controls(belowNames)}]`);
 		return lines.join("\n");
 	}
 	cacheSnapshot(nodes) {
@@ -654,7 +671,7 @@ var DeviceCore = class {
 				await this.press(el.ref);
 				return true;
 			} catch (error) {
-				if (!/off-?screen/i.test(describeError(error))) throw error;
+				if (!/off-?screen|covered/i.test(describeError(error))) throw error;
 			}
 			const dir = el?.rect ? el.rect.y < 0 ? "up" : "down" : i < 5 ? "up" : "down";
 			await this.scroll(dir);
@@ -1454,363 +1471,75 @@ function createAgentDeviceBackend(config) {
 	return new AgentDeviceBackend(config);
 }
 //#endregion
-//#region src/backends/cloud-sandbox.ts
-var CloudSandboxBackend = class extends BaseDeviceBackend {
-	endpoint;
-	token;
-	fetchImpl;
-	constructor(opts) {
-		super("phone-use-cloud", opts.capabilities ?? ALL_CAPABILITIES);
-		this.endpoint = opts.endpoint.replace(/\/+$/, "");
-		this.token = opts.token;
-		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-	}
-	async rpc(method, ...args) {
-		const response = await this.fetchImpl(`${this.endpoint}/rpc`, {
-			method: "POST",
-			headers: {
-				authorization: `Bearer ${this.token}`,
-				"content-type": "application/json"
-			},
-			body: JSON.stringify({
-				method,
-				args
-			})
-		});
-		const body = await response.json().catch(() => ({}));
-		if (!response.ok || !("ok" in body)) throw new PhoneUseError(("error" in body && typeof body.error === "string" ? body.error : void 0) ?? ("message" in body ? body.message : void 0) ?? `HTTP ${response.status}`, {
-			code: "UNKNOWN",
-			retryable: false
-		});
-		if (!body.ok) throw new PhoneUseError(body.error.message, {
-			code: normalizeErrorCode(body.error.code),
-			retryable: body.error.retryable ?? false
-		});
-		return body.result;
-	}
-	snapshot(opts) {
-		return this.rpc("snapshot", opts);
-	}
-	async screenshot(opts) {
-		const result = await this.rpc("screenshot", { overlayRefs: opts.overlayRefs });
-		await writeFile(opts.path, Buffer.from(result.base64, "base64"));
-		return { path: opts.path };
-	}
-	press(target) {
-		return this.rpc("press", target);
-	}
-	longPress(ref, durationMs) {
-		return this.rpc("longPress", ref, durationMs);
-	}
-	fill(ref, text) {
-		return this.rpc("fill", ref, text);
-	}
-	typeText(text) {
-		return this.rpc("typeText", text);
-	}
-	pressKey(key) {
-		return this.rpc("pressKey", key);
-	}
-	scroll(direction) {
-		return this.rpc("scroll", direction);
-	}
-	pan(x, y, dx, dy, durationMs) {
-		return this.rpc("pan", x, y, dx, dy, durationMs);
-	}
-	waitForText(text, timeoutMs) {
-		return this.rpc("waitForText", text, timeoutMs);
-	}
-	systemAlert(action) {
-		return this.rpc("systemAlert", action);
-	}
-	home() {
-		return this.rpc("home");
-	}
-	back() {
-		return this.rpc("back");
+//#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();
 	}
-	openApp(opts) {
-		return this.rpc("openApp", opts);
+	/** Re-arm with the configured window (no-op when disabled). */
+	touch() {
+		this.arm(this.windowMs);
 	}
-	listApps() {
-		return this.rpc("listApps");
+	/** Re-arm with a one-shot override window. */
+	extend(ms) {
+		this.arm(ms ?? this.windowMs);
 	}
-	closeSession() {
-		return this.rpc("closeSession");
+	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;
 	}
-	/** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
-	installApp(base64Zip) {
-		return this.rpc("installApp", base64Zip);
+	dispose() {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = null;
 	}
 };
 /**
-* Build a CloudSandboxBackend from explicit options or the environment:
-* PHONE_USE_SANDBOX_URL + PHONE_USE_SANDBOX_TOKEN (printed by
-* `phone-use sandbox env <id>`).
+* 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 createCloudSandboxBackend(config) {
-	const endpoint = config?.endpoint ?? process.env.PHONE_USE_SANDBOX_URL;
-	const token = config?.token ?? process.env.PHONE_USE_SANDBOX_TOKEN;
-	if (!endpoint || !token) throw new PhoneUseError("cloud sandbox backend needs PHONE_USE_SANDBOX_URL and PHONE_USE_SANDBOX_TOKEN (see `phone-use sandbox env <id>`)", {
-		code: "BACKEND_NOT_FOUND",
-		retryable: false
-	});
-	return new CloudSandboxBackend({
-		...config,
-		endpoint,
-		token
-	});
-}
-function normalizeErrorCode(code) {
-	if ((/* @__PURE__ */ new Set([
-		"DEVICE_NOT_FOUND",
-		"DEVICE_IN_USE",
-		"SESSION_NOT_FOUND",
-		"TIMEOUT",
-		"ACTION_FAILED",
-		"UNSUPPORTED_CAPABILITY",
-		"BACKEND_NOT_FOUND",
-		"ABORTED",
-		"UNKNOWN"
-	])).has(code ?? "")) return code;
-	return {
-		device_gone: "DEVICE_NOT_FOUND",
-		sandbox_not_found: "DEVICE_NOT_FOUND",
-		timeout: "TIMEOUT",
-		session_conflict: "DEVICE_IN_USE",
-		target_not_found: "ACTION_FAILED",
-		unauthorized: "ABORTED",
-		payload_too_large: "ACTION_FAILED",
-		bad_request: "ACTION_FAILED",
-		internal: "UNKNOWN"
-	}[code ?? ""] ?? "UNKNOWN";
-}
-//#endregion
-//#region src/backends/device-runner.ts
-const RUNNER_CAPABILITIES = [
-	"snapshot",
-	"screenshot",
-	"press",
-	"fill",
-	"type",
-	"scroll",
-	"pan",
-	"openApp",
-	"home"
-];
-/**
-* Backend that speaks to an on-device runner: an XCTest-hosted JSON-RPC server
-* running ON the iPhone itself, which holds the automation privileges iOS
-* denies to ordinary apps.
-*
-* The endpoint is just a URL, so the same backend serves every topology:
-*   - `http://127.0.0.1:45678`  — port-forwarded from a paired host
-*   - `http://<phone-ip>:45678` — straight over the LAN / tailnet
-*   - `https://relay.example/d/<id>` — the runner dials out to a cloud relay,
-*     which is what lets an agent anywhere drive the phone with no inbound
-*     ports and no Mac in the loop.
-*
-* The wire format matches the shape proven by rounak/PhoneAgent: newline-free
-* JSON request/response over HTTP POST, one method per call.
-*/
-var DeviceRunnerBackend = class extends BaseDeviceBackend {
-	#endpoint;
-	#token;
-	#timeoutMs;
-	constructor(config) {
-		super("device-runner", RUNNER_CAPABILITIES);
-		const endpoint = config?.endpoint ?? process.env.PHONE_USE_RUNNER_URL ?? "http://127.0.0.1:45678";
-		this.#endpoint = endpoint.replace(/\/+$/, "");
-		this.#token = config?.token ?? process.env.PHONE_USE_RUNNER_TOKEN;
-		this.#timeoutMs = config?.timeoutMs ?? 3e4;
-	}
-	async #rpc(method, params = {}) {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
-		let res;
-		try {
-			res = await fetch(this.#endpoint, {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					...this.#token ? { authorization: `Bearer ${this.#token}` } : {}
-				},
-				body: JSON.stringify({
-					jsonrpc: "2.0",
-					id: Date.now(),
-					method,
-					params
-				}),
-				signal: controller.signal
-			});
-		} catch (cause) {
-			if (controller.signal.aborted) throw new TimeoutError(`runner did not answer ${method} within ${this.#timeoutMs}ms`);
-			throw new DeviceNotFoundError(`cannot reach the on-device runner at ${this.#endpoint} — is it activated on the phone?`, { cause });
-		} finally {
-			clearTimeout(timer);
-		}
-		if (!res.ok) throw new ActionFailedError(`runner returned HTTP ${res.status} for ${method}`);
-		const body = await res.json();
-		if (body.error) throw new ActionFailedError(body.error.message ?? `runner rejected ${method}`);
-		return body.result;
-	}
-	async snapshot(opts) {
-		const wire = await this.#rpc("get_tree", {
-			interactiveOnly: opts?.interactiveOnly ?? false,
-			depth: opts?.depth
-		});
-		return {
-			appBundleId: wire.app,
-			appName: wire.app,
-			nodes: (wire.elements ?? []).map((e) => ({
-				ref: e.ref,
-				role: e.role,
-				type: e.role,
-				label: e.label,
-				value: e.value,
-				enabled: e.enabled,
-				rect: e.rect ? {
-					x: e.rect.x,
-					y: e.rect.y,
-					width: e.rect.w,
-					height: e.rect.h
-				} : void 0
-			}))
-		};
-	}
-	async screenshot(opts) {
-		const { base64 } = await this.#rpc("get_screen_image", { overlayRefs: opts.overlayRefs ?? false });
-		const { writeFile } = await import("node:fs/promises");
-		await writeFile(opts.path, Buffer.from(base64, "base64"));
-		return { path: opts.path };
-	}
-	async press(target) {
-		if ("ref" in target) {
-			await this.#rpc("tap_element", { ref: target.ref });
-			return;
-		}
-		await this.#rpc("tap", {
-			x: target.x,
-			y: target.y
-		});
-	}
-	async fill(ref, text) {
-		await this.#rpc("enter_text", {
-			ref,
-			text,
-			replace: true
-		});
-	}
-	async typeText(text) {
-		await this.#rpc("enter_text", {
-			text,
-			replace: false
-		});
-	}
-	async scroll(direction) {
-		await this.#rpc("scroll", { direction });
-	}
-	async pan(x, y, dx, dy, durationMs = 300) {
-		await this.#rpc("swipe", {
-			x,
-			y,
-			dx,
-			dy,
-			durationMs
-		});
-	}
-	async home() {
-		await this.#rpc("home");
-	}
-	async openApp(opts) {
-		return this.#rpc("open_app", {
-			app: opts.app,
-			url: opts.url,
-			relaunch: opts.relaunch ?? false
-		});
-	}
-	async systemAlert(action) {
-		return this.#rpc("alert", { action });
-	}
-	async closeSession() {}
-	/** Liveness probe used by `phone-use doctor` and the relay health check. */
-	async ping() {
-		return this.#rpc("get_context");
-	}
-};
-/** Backend for a phone-runner reached by URL (defaults come from
-* `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));
+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);
@@ -1970,6 +1699,1026 @@ function createDeviceHandle(opts) {
 	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;
+	token;
+	fetchImpl;
+	constructor(opts) {
+		super("phone-use-cloud", opts.capabilities ?? ALL_CAPABILITIES);
+		this.endpoint = opts.endpoint.replace(/\/+$/, "");
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+	}
+	async rpc(method, ...args) {
+		const response = await this.fetchImpl(`${this.endpoint}/rpc`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${this.token}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				method,
+				args
+			})
+		});
+		const body = await response.json().catch(() => ({}));
+		if (!response.ok || !("ok" in body)) throw new PhoneUseError(("error" in body && typeof body.error === "string" ? body.error : void 0) ?? ("message" in body ? body.message : void 0) ?? `HTTP ${response.status}`, {
+			code: "UNKNOWN",
+			retryable: false
+		});
+		if (!body.ok) throw new PhoneUseError(body.error.message, {
+			code: normalizeErrorCode(body.error.code),
+			retryable: body.error.retryable ?? false
+		});
+		return body.result;
+	}
+	snapshot(opts) {
+		return this.rpc("snapshot", opts);
+	}
+	async screenshot(opts) {
+		const result = await this.rpc("screenshot", { overlayRefs: opts.overlayRefs });
+		await writeFile(opts.path, Buffer.from(result.base64, "base64"));
+		return { path: opts.path };
+	}
+	press(target) {
+		return this.rpc("press", target);
+	}
+	longPress(ref, durationMs) {
+		return this.rpc("longPress", ref, durationMs);
+	}
+	fill(ref, text) {
+		return this.rpc("fill", ref, text);
+	}
+	typeText(text) {
+		return this.rpc("typeText", text);
+	}
+	pressKey(key) {
+		return this.rpc("pressKey", key);
+	}
+	scroll(direction) {
+		return this.rpc("scroll", direction);
+	}
+	pan(x, y, dx, dy, durationMs) {
+		return this.rpc("pan", x, y, dx, dy, durationMs);
+	}
+	waitForText(text, timeoutMs) {
+		return this.rpc("waitForText", text, timeoutMs);
+	}
+	systemAlert(action) {
+		return this.rpc("systemAlert", action);
+	}
+	home() {
+		return this.rpc("home");
+	}
+	back() {
+		return this.rpc("back");
+	}
+	openApp(opts) {
+		return this.rpc("openApp", opts);
+	}
+	listApps() {
+		return this.rpc("listApps");
+	}
+	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}:
+	* base64 inside a JSON body inflates the payload by a third, which caps real
+	* apps near 144MB. Pass a `Bun.file(...)` (or any Blob) and the bytes go to the
+	* wire without being buffered in memory.
+	*/
+	async installAppStream(zip) {
+		const response = await this.fetchImpl(`${this.endpoint}/app`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${this.token}`,
+				"content-type": "application/zip"
+			},
+			body: zip
+		});
+		if (response.status === 404) {
+			const bytes = await zip.arrayBuffer();
+			return this.installApp(Buffer.from(bytes).toString("base64"));
+		}
+		const body = await response.json().catch(() => ({}));
+		if (!response.ok || !("ok" in body)) throw new PhoneUseError(("error" in body && typeof body.error === "string" ? body.error : void 0) ?? `HTTP ${response.status}`, {
+			code: "UNKNOWN",
+			retryable: false
+		});
+		if (!body.ok) throw new PhoneUseError(body.error.message, {
+			code: normalizeErrorCode(body.error.code),
+			retryable: body.error.retryable ?? false
+		});
+		return body.result;
+	}
+	/** @deprecated Base64-in-JSON; use {@link installAppStream}. */
+	installApp(base64Zip) {
+		return this.rpc("installApp", base64Zip);
+	}
+};
+/**
+* Build a CloudSandboxBackend from explicit options or the environment:
+* PHONE_USE_SANDBOX_URL + PHONE_USE_SANDBOX_TOKEN (printed by
+* `phone-use sandbox env <id>`).
+*/
+function createCloudSandboxBackend(config) {
+	const endpoint = config?.endpoint ?? process.env.PHONE_USE_SANDBOX_URL;
+	const token = config?.token ?? process.env.PHONE_USE_SANDBOX_TOKEN;
+	if (!endpoint || !token) throw new PhoneUseError("cloud sandbox backend needs PHONE_USE_SANDBOX_URL and PHONE_USE_SANDBOX_TOKEN (see `phone-use sandbox env <id>`)", {
+		code: "BACKEND_NOT_FOUND",
+		retryable: false
+	});
+	return new CloudSandboxBackend({
+		...config,
+		endpoint,
+		token
+	});
+}
+function normalizeErrorCode(code) {
+	if ((/* @__PURE__ */ new Set([
+		"DEVICE_NOT_FOUND",
+		"DEVICE_IN_USE",
+		"SESSION_NOT_FOUND",
+		"TIMEOUT",
+		"ACTION_FAILED",
+		"UNSUPPORTED_CAPABILITY",
+		"BACKEND_NOT_FOUND",
+		"ABORTED",
+		"UNKNOWN"
+	])).has(code ?? "")) return code;
+	return {
+		device_gone: "DEVICE_NOT_FOUND",
+		sandbox_not_found: "DEVICE_NOT_FOUND",
+		timeout: "TIMEOUT",
+		session_conflict: "DEVICE_IN_USE",
+		target_not_found: "ACTION_FAILED",
+		unauthorized: "ABORTED",
+		payload_too_large: "ACTION_FAILED",
+		bad_request: "ACTION_FAILED",
+		internal: "UNKNOWN"
+	}[code ?? ""] ?? "UNKNOWN";
+}
+//#endregion
+//#region src/backends/device-runner.ts
+const RUNNER_CAPABILITIES = [
+	"snapshot",
+	"screenshot",
+	"press",
+	"fill",
+	"type",
+	"scroll",
+	"pan",
+	"openApp",
+	"home"
+];
+/**
+* Backend that speaks to an on-device runner: an XCTest-hosted JSON-RPC server
+* running ON the iPhone itself, which holds the automation privileges iOS
+* denies to ordinary apps.
+*
+* The endpoint is just a URL, so the same backend serves every topology:
+*   - `http://127.0.0.1:45678`  — port-forwarded from a paired host
+*   - `http://<phone-ip>:45678` — straight over the LAN / tailnet
+*   - `https://relay.example/d/<id>` — the runner dials out to a cloud relay,
+*     which is what lets an agent anywhere drive the phone with no inbound
+*     ports and no Mac in the loop.
+*
+* The wire format matches the shape proven by rounak/PhoneAgent: newline-free
+* JSON request/response over HTTP POST, one method per call.
+*/
+var DeviceRunnerBackend = class extends BaseDeviceBackend {
+	#endpoint;
+	#token;
+	#timeoutMs;
+	constructor(config) {
+		super("device-runner", RUNNER_CAPABILITIES);
+		const endpoint = config?.endpoint ?? process.env.PHONE_USE_RUNNER_URL ?? "http://127.0.0.1:45678";
+		this.#endpoint = endpoint.replace(/\/+$/, "");
+		this.#token = config?.token ?? process.env.PHONE_USE_RUNNER_TOKEN;
+		this.#timeoutMs = config?.timeoutMs ?? 3e4;
+	}
+	async #rpc(method, params = {}) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+		let res;
+		try {
+			res = await fetch(this.#endpoint, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					...this.#token ? { authorization: `Bearer ${this.#token}` } : {}
+				},
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					id: Date.now(),
+					method,
+					params
+				}),
+				signal: controller.signal
+			});
+		} catch (cause) {
+			if (controller.signal.aborted) throw new TimeoutError(`runner did not answer ${method} within ${this.#timeoutMs}ms`);
+			throw new DeviceNotFoundError(`cannot reach the on-device runner at ${this.#endpoint} — is it activated on the phone?`, { cause });
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!res.ok) throw new ActionFailedError(`runner returned HTTP ${res.status} for ${method}`);
+		const body = await res.json();
+		if (body.error) throw new ActionFailedError(body.error.message ?? `runner rejected ${method}`);
+		return body.result;
+	}
+	async snapshot(opts) {
+		const wire = await this.#rpc("get_tree", {
+			interactiveOnly: opts?.interactiveOnly ?? false,
+			depth: opts?.depth
+		});
+		return {
+			appBundleId: wire.app,
+			appName: wire.app,
+			nodes: (wire.elements ?? []).map((e) => ({
+				ref: e.ref,
+				role: e.role,
+				type: e.role,
+				label: e.label,
+				value: e.value,
+				enabled: e.enabled,
+				rect: e.rect ? {
+					x: e.rect.x,
+					y: e.rect.y,
+					width: e.rect.w,
+					height: e.rect.h
+				} : void 0
+			}))
+		};
+	}
+	async screenshot(opts) {
+		const { base64 } = await this.#rpc("get_screen_image", { overlayRefs: opts.overlayRefs ?? false });
+		const { writeFile } = await import("node:fs/promises");
+		await writeFile(opts.path, Buffer.from(base64, "base64"));
+		return { path: opts.path };
+	}
+	async press(target) {
+		if ("ref" in target) {
+			await this.#rpc("tap_element", { ref: target.ref });
+			return;
+		}
+		await this.#rpc("tap", {
+			x: target.x,
+			y: target.y
+		});
+	}
+	async fill(ref, text) {
+		await this.#rpc("enter_text", {
+			ref,
+			text,
+			replace: true
+		});
+	}
+	async typeText(text) {
+		await this.#rpc("enter_text", {
+			text,
+			replace: false
+		});
+	}
+	async scroll(direction) {
+		await this.#rpc("scroll", { direction });
+	}
+	async pan(x, y, dx, dy, durationMs = 300) {
+		await this.#rpc("swipe", {
+			x,
+			y,
+			dx,
+			dy,
+			durationMs
+		});
+	}
+	async home() {
+		await this.#rpc("home");
+	}
+	async openApp(opts) {
+		return this.#rpc("open_app", {
+			app: opts.app,
+			url: opts.url,
+			relaunch: opts.relaunch ?? false
+		});
+	}
+	async systemAlert(action) {
+		return this.#rpc("alert", { action });
+	}
+	async closeSession() {}
+	/** Liveness probe used by `phone-use doctor` and the relay health check. */
+	async ping() {
+		return this.#rpc("get_context");
+	}
+};
+/** Backend for a phone-runner reached by URL (defaults come from
+* `PHONE_USE_RUNNER_URL` / `PHONE_USE_RUNNER_TOKEN` when `config` is omitted). */
+const createDeviceRunnerBackend = (config) => new DeviceRunnerBackend(config);
+//#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) {
@@ -2122,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.3.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