@phone-use/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1848 @@
+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-BzPnHvQy.mjs";
+import { createAgentDeviceClient } from "agent-device";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/observe.ts
+const NOISE_LABELS = /* @__PURE__ */ new Set([
+	"|",
+	"(",
+	")",
+	",",
+	"·",
+	"•"
+]);
+function isNoise(n) {
+	const kind = n.type ?? n.role ?? "";
+	if (!n.label) return false;
+	return (kind === "StaticText" || kind === "Other") && NOISE_LABELS.has(n.label.trim());
+}
+function intersectsViewport(rect, vw, vh) {
+	if (!rect) return true;
+	return rect.x < vw && rect.y < vh && rect.x + rect.width > 0 && rect.y + rect.height > 0;
+}
+const RENDER_TEXT_MAX = 160;
+function renderText(s) {
+	return s.length <= RENDER_TEXT_MAX ? JSON.stringify(s) : `${JSON.stringify(s.slice(0, RENDER_TEXT_MAX))} [truncated]`;
+}
+function formatNode(n, opts) {
+	const role = n.role ?? n.type ?? "element";
+	const parts = [`${n.ref && !n.ref.startsWith("@") ? `@${n.ref}` : n.ref ?? ""} [${role}]`];
+	const label = n.label ?? n.identifier;
+	if (label) parts.push(renderText(label));
+	if (n.value && n.value !== n.label) parts.push(`value=${renderText(n.value)}`);
+	if (n.rect) parts.push(`(${Math.round(n.rect.x)},${Math.round(n.rect.y)} ${Math.round(n.rect.width)}x${Math.round(n.rect.height)})`);
+	if (n.rect && opts.vw !== void 0) {
+		const cx = n.rect.x + n.rect.width / 2;
+		if (cx < 0 || cx > opts.vw) parts.push("(center off-screen)");
+	}
+	if (n.enabled === false) parts.push("(disabled)");
+	if (n.selected) parts.push("(selected)");
+	if (n.focused && !opts.suppressFocused) parts.push("(focused)");
+	if (n.interactionBlocked) parts.push(`(blocked: ${n.interactionBlocked})`);
+	return parts.join(" ");
+}
+function keptViewportNodes(nodes) {
+	const root = nodes.find((n) => (n.type === "Application" || n.type === "Window") && n.rect);
+	const vw = root?.rect?.width ?? 500;
+	const vh = root?.rect?.height ?? 1e3;
+	const suppressFocused = nodes.filter((n) => n.focused).length > nodes.length / 3;
+	const kept = [];
+	let above = 0;
+	let below = 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;
+			continue;
+		}
+		kept.push(n);
+	}
+	return {
+		kept,
+		above,
+		below,
+		suppressFocused,
+		vw
+	};
+}
+function compressNodes(nodes) {
+	const { kept, above, below, 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]`);
+	return lines.join("\n");
+}
+function elementKey(n) {
+	return `${n.role ?? n.type ?? "element"}|${(n.label ?? n.identifier ?? "").trim()}|${n.rect ? `${Math.round(n.rect.x)},${Math.round(n.rect.y)}` : ""}`;
+}
+function arraysEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+const TAPPABLE = /* @__PURE__ */ new Set([
+	"Button",
+	"Cell",
+	"Link",
+	"MenuItem",
+	"Tab",
+	"StaticText",
+	"Switch"
+]);
+const EDITABLE = /* @__PURE__ */ new Set([
+	"SearchField",
+	"TextField",
+	"SecureTextField"
+]);
+const EDITABLE_MULTILINE = /* @__PURE__ */ new Set([
+	...EDITABLE,
+	"TextView",
+	"TextEditor"
+]);
+function labelTokens(s) {
+	return s.toLowerCase().split(/[^a-z0-9]+/i).filter((t) => t.length > 2);
+}
+function fuzzyScore(label, query) {
+	const qt = new Set(labelTokens(query));
+	const lt = labelTokens(label);
+	if (!qt.size || !lt.length) return 0;
+	return lt.filter((t) => qt.has(t)).length / lt.length;
+}
+/**
+* Does a label match a query — by substring, or a strict punctuation/spacing-
+* tolerant fuzzy match? Shared by the task layer's cached-map lookups so
+* ask/toggle tolerate rewording the same way findElement does.
+*/
+function labelMatches(label, query) {
+	return label.toLowerCase().includes(query.toLowerCase()) || fuzzyScore(label, query) >= .75;
+}
+function center(e) {
+	return e.rect ? {
+		x: e.rect.x + e.rect.width / 2,
+		y: e.rect.y + e.rect.height / 2
+	} : null;
+}
+function disambiguate(matches, via, opts, els) {
+	let pool = matches;
+	if (opts.role) {
+		const byRole = pool.filter((e) => e.role.toLowerCase() === opts.role.toLowerCase());
+		if (byRole.length) pool = byRole;
+	}
+	if (pool.length > 1 && opts.near) {
+		const anchor = els.find((e) => labelMatches(e.label, opts.near));
+		const ac = anchor ? center(anchor) : null;
+		if (ac) {
+			pool = [...pool].sort((a, b) => {
+				const ca = center(a);
+				const cb = center(b);
+				return (ca ? (ca.x - ac.x) ** 2 + (ca.y - ac.y) ** 2 : Infinity) - (cb ? (cb.x - ac.x) ** 2 + (cb.y - ac.y) ** 2 : Infinity);
+			});
+			return {
+				el: pool[0],
+				via: `${via}, nearest "${opts.near}"`
+			};
+		}
+	}
+	if (pool.length === 1) return {
+		el: pool[0],
+		via
+	};
+	return {
+		el: null,
+		candidates: pool,
+		via
+	};
+}
+/**
+* One screen's worth of the resolution ladder: id exact → exact label →
+* substring → fuzzy above a strict bar. This is the per-iteration body of
+* resolveElement's scroll loop, extracted so callers holding a fresh cache
+* (item-4 auto-wait) can match without scrolling. Returns `{ el: null }` with
+* no candidates when no rung matched at all.
+*/
+function matchInElements(els, query, opts) {
+	const q = query.toLowerCase();
+	const byId = els.filter((e) => e.id && e.id.toLowerCase() === q);
+	if (byId.length) return disambiguate(byId, "id", opts, els);
+	const exact = els.filter((e) => e.label.toLowerCase() === q);
+	if (exact.length) return disambiguate(exact, "exact label", opts, els);
+	const sub = els.filter((e) => e.label.toLowerCase().includes(q));
+	if (sub.length) return disambiguate(sub, "label substring", opts, els);
+	let best = null;
+	let bestScore = 0;
+	for (const e of els) {
+		const s = fuzzyScore(e.label, query);
+		if (s > bestScore) {
+			bestScore = s;
+			best = e;
+		}
+	}
+	if (best && bestScore >= .75) return {
+		el: best,
+		via: `fuzzy ${bestScore.toFixed(2)}`
+	};
+	return { el: null };
+}
+const na = (s) => s.toLowerCase().replace(/[’']/g, "'").trim();
+const ALERT_ACCEPT = [
+	"allow while using app",
+	"always allow",
+	"allow",
+	"ok",
+	"yes",
+	"continue",
+	"allow once",
+	"turn on",
+	"enable",
+	"agree",
+	"accept",
+	"got it",
+	"join"
+];
+const ALERT_DISMISS = [
+	"don't allow",
+	"not now",
+	"cancel",
+	"no thanks",
+	"no",
+	"deny",
+	"dismiss",
+	"later",
+	"skip",
+	"don't"
+];
+function pickAlertButton(buttons, action) {
+	const prefs = action === "accept" ? ALERT_ACCEPT : ALERT_DISMISS;
+	for (const p of prefs) {
+		const hit = buttons.find((b) => na(b.label) === p);
+		if (hit) return hit;
+	}
+	for (const p of prefs) {
+		const hit = buttons.find((b) => na(b.label).includes(p));
+		if (hit) return hit;
+	}
+	if (action === "accept") return buttons.find((b) => !ALERT_DISMISS.some((d) => na(b.label).includes(d)));
+	return buttons[0];
+}
+function describeAlert(info) {
+	return `${info.title}${info.message ? ` ${info.message}` : ""}`.trim() + (info.buttons.length ? ` [buttons: ${info.buttons.map((b) => b.label).join(", ")}]` : "");
+}
+function normRef(ref) {
+	return ref.startsWith("@") ? ref : `@${ref}`;
+}
+/** Render any thrown value as a one-line message (appends `details.hint` when present). */
+function describeError(error) {
+	if (error instanceof Error && error.message) {
+		const hint = error.details?.hint;
+		return hint ? `${error.message} (${hint})` : error.message;
+	}
+	return String(error);
+}
+/**
+* The device core: one instance = one device's observe/resolve/act state,
+* driving one {@link DeviceBackend}. Everything here is portable — no
+* runtime-specific globals and no image libraries — so it runs under Node.
+* The harness's DeviceContext subclasses this and adds the cursor +
+* live-viewer layer via the onCacheUpdated hook.
+*/
+var DeviceCore = class {
+	/** The backend this core drives. */
+	backend;
+	cachedNodes = [];
+	cachedViewport = {
+		width: 390,
+		height: 844
+	};
+	lastApp = {};
+	lastRender = null;
+	cacheAt = 0;
+	constructor(backend) {
+		this.backend = backend;
+	}
+	onCacheUpdated() {}
+	/**
+	* Canonical post-action report for LLM tool results, shared by every tool
+	* surface (agent tools + MCP): verdict from the action's own evidence, then a
+	* delta-rendered view of the screen it left behind.
+	*/
+	async renderActionResult(prefix, evidence, refresh = false) {
+		if (refresh) await this.observe();
+		return `${prefix}${evidence?.detail ? ` (${evidence.detail})` : ""}\n\nCurrent screen (app: ${this.currentApp() ?? "unknown"}):\n${this.renderObservation()}`;
+	}
+	/**
+	* Render the current cached screen for the LLM. full=true (or a structural
+	* change since last render) yields the complete compressed tree; otherwise a
+	* compact delta. Always updates the baseline.
+	*/
+	renderObservation(full = false) {
+		const app = this.lastApp.app;
+		const { kept, above, below, 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, {
+			suppressFocused,
+			vw
+		}));
+		if (!full && this.lastRender != null && this.lastRender.app === app && arraysEqual(this.lastRender.keys, keys) && lineByKey.size === keys.length && this.lastRender.lineByKey.size === this.lastRender.keys.length && this.lastRender) {
+			const changed = [];
+			for (const key of keys) {
+				const now = lineByKey.get(key);
+				if (this.lastRender.lineByKey.get(key) !== now) changed.push(`~ ${now}`);
+			}
+			this.lastRender = {
+				app,
+				keys,
+				lineByKey
+			};
+			if (changed.length === 0) return `Screen unchanged since last observation (${keys.length} elements).`;
+			return `Same screen; ${changed.length} of ${keys.length} element(s) changed:\n${changed.join("\n")}\n(other elements and their @refs unchanged)`;
+		}
+		this.lastRender = {
+			app,
+			keys,
+			lineByKey
+		};
+		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]`);
+		return lines.join("\n");
+	}
+	cacheSnapshot(nodes) {
+		this.cachedNodes = nodes;
+		const root = nodes.find((n) => (n.type === "Application" || n.type === "Window") && n.rect);
+		if (root?.rect) this.cachedViewport = {
+			width: root.rect.width,
+			height: root.rect.height
+		};
+		this.cacheAt = Date.now();
+		this.onCacheUpdated();
+	}
+	async refreshCache() {
+		const snap = await this.backend.snapshot({ interactiveOnly: true });
+		this.cacheSnapshot(snap.nodes);
+		this.lastApp = {
+			app: snap.appName,
+			bundleId: snap.appBundleId
+		};
+	}
+	cacheSignature() {
+		const head = this.cachedNodes.slice(0, 16).map((n) => `${n.ref ?? ""}:${n.label ?? n.type ?? ""}`).join("|");
+		return `${this.cachedNodes.length}#${head}`;
+	}
+	/** Milliseconds since the cache was last refreshed (Infinity before first). */
+	cacheAgeMs() {
+		return this.cacheAt === 0 ? Number.POSITIVE_INFINITY : Date.now() - this.cacheAt;
+	}
+	/** Public fingerprint of the cached tree — the settle/verify signal. */
+	stateSignature() {
+		return this.cacheSignature();
+	}
+	/** The cached screen as a compressed {@link Observation} (no new snapshot). */
+	currentElements() {
+		return {
+			app: this.lastApp.app,
+			bundleId: this.lastApp.bundleId,
+			truncated: false,
+			elements: compressNodes(this.cachedNodes)
+		};
+	}
+	/**
+	* The frontmost app name from the last snapshot — cheap label without paying
+	* the full tree compression (used by the delta renderer's callers).
+	*/
+	currentApp() {
+		return this.lastApp.app;
+	}
+	/**
+	* Structured interactive elements from the current cache — the crawler taps
+	* these by label (refs are only valid within one snapshot).
+	*/
+	interactiveElements() {
+		const out = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const n of this.cachedNodes) {
+			if (!n.ref || !n.rect) continue;
+			const role = n.role ?? n.type ?? "";
+			if (!TAPPABLE.has(role)) continue;
+			const label = (n.label ?? n.identifier ?? "").trim();
+			if (!label) continue;
+			if (n.rect.width >= this.cachedViewport.width && n.rect.height >= this.cachedViewport.height) continue;
+			const key = `${role}:${label}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			out.push({
+				ref: normRef(n.ref),
+				label,
+				role,
+				value: n.value,
+				rect: n.rect,
+				id: n.identifier?.trim() || void 0,
+				enabled: n.enabled,
+				blocked: n.interactionBlocked
+			});
+		}
+		return out;
+	}
+	/**
+	* Editable text inputs from the current cache. These roles are deliberately
+	* excluded from interactiveElements() (they aren't "tap" targets), so the
+	* input primitive needs its own accessor to find a search bar / text field to
+	* focus. includeMultiline adds TextView bodies for form/compose filling.
+	*/
+	inputFields(includeMultiline = false) {
+		const editable = includeMultiline ? EDITABLE_MULTILINE : EDITABLE;
+		const out = [];
+		for (const n of this.cachedNodes) {
+			if (!n.ref || !n.rect) continue;
+			const role = n.role ?? n.type ?? "";
+			if (!editable.has(role)) continue;
+			out.push({
+				ref: normRef(n.ref),
+				label: (n.label ?? n.identifier ?? "").trim(),
+				role,
+				value: n.value,
+				rect: n.rect,
+				enabled: n.enabled,
+				blocked: n.interactionBlocked
+			});
+		}
+		return out;
+	}
+	/**
+	* Run the resolution ladder against the current cache only — no scrolling,
+	* no fresh snapshot. resolveElement drives this per scroll step.
+	*/
+	resolveInCache(query, opts = {}) {
+		return matchInElements(this.interactiveElements(), query, opts);
+	}
+	/** The full ladder: scroll to top, then match + scroll down until found or stable. */
+	async resolveElement(query, opts = {}) {
+		await this.scrollToTop();
+		for (let i = 0; i < 10; i++) {
+			const r = this.resolveInCache(query, opts);
+			if (r.el || r.candidates) return r;
+			const before = this.screenSignature();
+			await this.scroll("down");
+			await this.observe();
+			if (this.screenSignature() === before) break;
+		}
+		return { el: null };
+	}
+	/**
+	* Compatibility wrapper: single best element or null (read paths — ask/read a
+	* value — where picking the first match is low-risk). Tap paths use
+	* resolveElement directly and honor the ambiguity contract.
+	*/
+	async findElement(labelSubstring) {
+		const r = await this.resolveElement(labelSubstring);
+		return r.el ?? r.candidates?.[0] ?? null;
+	}
+	/**
+	* Read a labeled value. iOS list rows fold the value into the label
+	* ("iOS Version, 26.1") or expose it as a Switch value ("1"/"0"); handle both.
+	*/
+	async readField(labelSubstring) {
+		const el = await this.findElement(labelSubstring);
+		if (!el) return null;
+		if (el.value != null && el.value !== "") return el.value;
+		const idx = el.label.toLowerCase().indexOf(labelSubstring.toLowerCase());
+		if (idx < 0) return el.label;
+		return el.label.slice(idx + labelSubstring.length).replace(/^[\s,:]+/, "").trim() || el.label;
+	}
+	/**
+	* A structural fingerprint of the current screen that is stable across
+	* dynamic content (times, battery, values) — it keys the crawler's graph
+	* nodes so the same screen is recognized regardless of transient text.
+	*/
+	screenSignature() {
+		const title = this.cachedNodes.find((n) => (n.type === "NavigationBar" || n.role === "NavigationBar") && n.label)?.label ?? "";
+		const labels = this.cachedNodes.filter((n) => TAPPABLE.has(n.role ?? n.type ?? "") && (n.label ?? "").trim()).map((n) => `${n.role ?? n.type}:${(n.label ?? "").trim()}`).sort();
+		const uniq = [...new Set(labels)];
+		return `${this.lastApp.bundleId ?? ""}|${title}|${uniq.join("~")}`;
+	}
+	/** Navigation-bar title of the cached screen ('' when absent). */
+	screenTitle() {
+		return this.cachedNodes.find((n) => (n.type === "NavigationBar" || n.role === "NavigationBar") && n.label)?.label ?? "";
+	}
+	/** Take one fresh snapshot into the cache and return the compressed observation. */
+	async observe() {
+		try {
+			await this.refreshCache();
+			return this.currentElements();
+		} catch (error) {
+			if (error instanceof SessionNotFoundError || error?.code === "SESSION_NOT_FOUND") return {
+				truncated: false,
+				elements: "No app session is active yet. Use open_app to launch an app first."
+			};
+			throw error;
+		}
+	}
+	/**
+	* Open an app by name/bundle id. relaunch forces a fresh launch (clean
+	* initial screen) instead of just foregrounding — iOS keeps an app's
+	* navigation state across foregrounding, so primitives that need a known
+	* starting screen pass relaunch=true.
+	*/
+	async openApp(app, relaunch = false) {
+		const result = await this.backend.openApp({
+			app,
+			relaunch
+		});
+		return `Opened ${result.appName ?? app} (${result.appBundleId ?? "unknown bundle"})`;
+	}
+	/**
+	* Level-2 of the action ladder: deep links beat tap sequences when a URL route
+	* exists (maps://, app schemes, https:// universal links). XCTest sessions are
+	* app-scoped, so a link that opens a different app must re-scope the session
+	* to that app or observations keep tracking the old one.
+	*/
+	async openUrl(url, app) {
+		const target = app ?? await this.currentBundleId();
+		await this.backend.openApp(target ? {
+			app: target,
+			url
+		} : { url });
+		return app ? `Opened ${url} in ${app}` : `Opened ${url}`;
+	}
+	async currentBundleId() {
+		try {
+			return (await this.backend.snapshot({
+				interactiveOnly: true,
+				depth: 1
+			})).appBundleId;
+		} catch {
+			return;
+		}
+	}
+	/** List installed app bundle ids. */
+	async listApps() {
+		return this.backend.listApps();
+	}
+	async tapAndDiff(tap) {
+		const before = this.cacheSignature();
+		await tap();
+		await this.refreshCache();
+		const changed = before !== this.cacheSignature();
+		return {
+			changed,
+			detail: changed ? "screen changed" : "screen did NOT change — the action may have had no effect"
+		};
+	}
+	/** Tap an element ref, self-diffing the cache to report whether the screen changed. */
+	async press(ref) {
+		try {
+			return await this.tapAndDiff(() => this.backend.press({ ref }));
+		} catch (error) {
+			if (!/off-?screen/i.test(describeError(error))) throw error;
+			const mid = this.visibleMidpoint(this.findNode(ref)?.rect);
+			if (!mid) throw error;
+			return this.tapAndDiff(() => this.backend.press({
+				x: mid.x,
+				y: mid.y
+			}));
+		}
+	}
+	visibleMidpoint(rect) {
+		if (!rect) return null;
+		const x1 = Math.max(rect.x, 0);
+		const y1 = Math.max(rect.y, 0);
+		const x2 = Math.min(rect.x + rect.width, this.cachedViewport.width);
+		const y2 = Math.min(rect.y + rect.height, this.cachedViewport.height);
+		if (x2 <= x1 || y2 <= y1) return null;
+		return {
+			x: Math.round((x1 + x2) / 2),
+			y: Math.round((y1 + y2) / 2)
+		};
+	}
+	onScreen(rect) {
+		if (!rect) return false;
+		const cy = rect.y + rect.height / 2;
+		return cy > 56 && cy < this.cachedViewport.height - 44 && rect.x < this.cachedViewport.width;
+	}
+	/**
+	* Open an app and walk its nav stack back to the root (dismissing modals), so
+	* map-based navigation always starts from a known origin.
+	*/
+	async goToRoot(app) {
+		const DISMISS = [
+			"Close",
+			"Cancel",
+			"Done",
+			"Not Now",
+			"Dismiss"
+		];
+		await this.observe().catch(() => void 0);
+		if (this.lastApp.bundleId !== app) {
+			await this.openApp(app);
+			await this.observe();
+		}
+		await this.clearBlockingAlerts("accept");
+		for (let i = 0; i < 12; i++) {
+			const els = this.interactiveElements();
+			const back = els.find((e) => e.role === "Button" && !!e.rect && e.rect.x < 70 && e.rect.y < 110);
+			const dismiss = els.find((e) => e.role === "Button" && DISMISS.includes(e.label));
+			const target = back ?? dismiss;
+			if (!target) break;
+			await this.press(target.ref);
+			await this.observe();
+		}
+		await this.scrollToTop();
+	}
+	/** Height of the cached viewport in points. */
+	viewportHeight() {
+		return this.cachedViewport.height;
+	}
+	/**
+	* Vertical span of interactive content in the current cache. Used to decide
+	* whether scrolling is even necessary — scroll gestures cost ~2s each, so
+	* skipping them on screens that already fit is the single biggest crawl
+	* speedup.
+	*/
+	contentBounds() {
+		let minY = Infinity;
+		let maxY = -Infinity;
+		for (const n of this.cachedNodes) {
+			if (!n.rect) continue;
+			if (!TAPPABLE.has(n.role ?? n.type ?? "")) continue;
+			minY = Math.min(minY, n.rect.y);
+			maxY = Math.max(maxY, n.rect.y + n.rect.height);
+		}
+		return {
+			minY: minY === Infinity ? 0 : minY,
+			maxY: maxY === -Infinity ? 0 : maxY
+		};
+	}
+	/**
+	* Tapping the status bar scrolls the active scroll view to the top — native
+	* iOS behavior, one fast tap instead of multiple ~2s scroll gestures. Falls
+	* back to gesture scrolling if the tap doesn't take.
+	*/
+	async scrollToTop() {
+		try {
+			await this.backend.press({
+				x: Math.round(this.cachedViewport.width / 2),
+				y: 6
+			});
+			await this.observe();
+			return;
+		} catch {}
+		for (let i = 0; i < 6; i++) {
+			const before = this.screenSignature();
+			await this.scroll("up");
+			await this.observe();
+			if (this.screenSignature() === before) return;
+		}
+	}
+	/**
+	* Tap an element by its label, scrolling it into view first if it's
+	* off-screen. The crawler and the map navigator use this so a target below
+	* the fold (a long Settings list) is still reachable. Re-resolves the ref
+	* after each scroll.
+	*/
+	async tapLabel(label) {
+		for (let i = 0; i < 12; i++) {
+			const el = this.interactiveElements().find((e) => e.label === label);
+			if (el && this.onScreen(el.rect)) try {
+				await this.press(el.ref);
+				return true;
+			} catch (error) {
+				if (!/off-?screen/i.test(describeError(error))) throw error;
+			}
+			const dir = el?.rect ? el.rect.y < 0 ? "up" : "down" : i < 5 ? "up" : "down";
+			await this.scroll(dir);
+			await this.observe();
+		}
+		return false;
+	}
+	/**
+	* Vision-path fallback: tap raw coordinates when the accessibility tree is
+	* missing or wrong (canvas, games, custom controls). Coordinates are in the
+	* same space as observe()'s rects and the screenshot pixels (@1x points).
+	*/
+	async pressAt(x, y) {
+		return this.tapAndDiff(() => this.backend.press({
+			x,
+			y
+		}));
+	}
+	/**
+	* Coordinate drag: touch down at (x,y), move by (dx,dy). The primitive for
+	* controls a tap can't operate — picker wheels (drag vertically on the wheel
+	* column), sliders, and custom carousels. Same coordinate space as rects.
+	*/
+	async pan(x, y, dx, dy, durationMs) {
+		await this.backend.pan(x, y, dx, dy, durationMs);
+	}
+	/**
+	* Set-of-Marks visual observation: screenshot with `@ref` labels drawn on the
+	* elements, so a vision model can ground itself in pixels and still act by ref.
+	*/
+	async screenshotWithRefs(path) {
+		return (await this.backend.screenshot({
+			path,
+			overlayRefs: true
+		})).path;
+	}
+	async currentViewport() {
+		try {
+			const root = (await this.backend.snapshot({
+				interactiveOnly: true,
+				depth: 1
+			})).nodes.find((n) => (n.type === "Application" || n.type === "Window") && n.rect);
+			return {
+				width: root?.rect?.width ?? 390,
+				height: root?.rect?.height ?? 844
+			};
+		} catch {
+			return {
+				width: 390,
+				height: 844
+			};
+		}
+	}
+	/** Long-press an element ref. */
+	async longPress(ref, durationMs = 800) {
+		await this.backend.longPress(ref, durationMs);
+	}
+	/** Focus a field and replace its text, self-diffing the cache for evidence. */
+	async fill(ref, text) {
+		return this.tapAndDiff(() => this.backend.fill(ref, text));
+	}
+	/** Type into whatever currently has keyboard focus. */
+	async typeText(text) {
+		await this.backend.typeText(text);
+	}
+	/**
+	* Press the keyboard's return/go key. Submits a search bar that acts on
+	* Return (Safari's address bar, web forms) rather than filtering results as
+	* you type.
+	*/
+	async pressReturn() {
+		await this.backend.pressKey("return");
+	}
+	/** Scroll the active scroll view one step. */
+	async scroll(direction) {
+		await this.backend.scroll(direction);
+	}
+	/** Block until `text` appears on screen; returns a confirmation note. */
+	async waitForText(text, timeoutMs = 5e3) {
+		await this.backend.waitForText(text, timeoutMs);
+		return `"${text}" appeared on screen`;
+	}
+	alertFromCache() {
+		const alert = this.cachedNodes.find((n) => (n.type ?? n.role) === "Alert");
+		if (!alert) return null;
+		const texts = this.cachedNodes.filter((n) => (n.type ?? n.role) === "StaticText" && n.label).map((n) => (n.label ?? "").trim());
+		const buttons = [];
+		for (const n of this.cachedNodes) {
+			if (!n.ref || !n.rect || (n.role ?? n.type) !== "Button") continue;
+			const label = (n.label ?? n.identifier ?? "").trim();
+			if (label) buttons.push({
+				ref: normRef(n.ref),
+				label,
+				role: "Button",
+				value: n.value,
+				rect: n.rect,
+				enabled: n.enabled,
+				blocked: n.interactionBlocked
+			});
+		}
+		const title = (alert.label ?? texts[0] ?? "Alert").trim();
+		return {
+			title,
+			message: texts.find((t) => t !== title),
+			buttons
+		};
+	}
+	/**
+	* System dialogs (permissions, sign-in prompts) block everything else; the
+	* driver exposes them as a first-class action instead of hoping a tap lands.
+	*/
+	async handleAlert(action) {
+		await this.observe().catch(() => void 0);
+		const info = this.alertFromCache();
+		if (info) {
+			const description = describeAlert(info);
+			if (action === "get") return {
+				present: true,
+				description
+			};
+			const btn = pickAlertButton(info.buttons, action);
+			if (!btn?.rect) return {
+				present: true,
+				handled: false,
+				description
+			};
+			await this.pressAt(btn.rect.x + btn.rect.width / 2, btn.rect.y + btn.rect.height / 2);
+			await this.observe().catch(() => void 0);
+			const still = this.alertFromCache();
+			return {
+				present: true,
+				handled: still == null || still.title !== info.title,
+				button: btn.label,
+				description
+			};
+		}
+		try {
+			const result = await this.backend.systemAlert(action);
+			const alert = result.alert;
+			return {
+				present: alert != null,
+				handled: result.handled,
+				button: result.button,
+				description: alert ? `${alert.title ?? ""} ${alert.message ?? ""}`.trim() + (alert.buttons?.length ? ` [buttons: ${alert.buttons.join(", ")}]` : "") : void 0
+			};
+		} catch (error) {
+			if (/alert not found/i.test(describeError(error))) return { present: false };
+			throw error;
+		}
+	}
+	/**
+	* Clear the launch permission gauntlet — real apps stack location /
+	* notification / tracking prompts on first open, each blocking the app.
+	* Grants by default so the crawl sees the most surface. Returns the buttons
+	* tapped. Bounded so a non-clearing dialog can't loop forever.
+	*/
+	async clearBlockingAlerts(action = "accept", max = 6) {
+		const tapped = [];
+		let lastTitle = "";
+		for (let i = 0; i < max; i++) {
+			if (!this.alertFromCache()) {
+				await this.observe().catch(() => void 0);
+				if (!this.alertFromCache()) break;
+			}
+			const r = await this.handleAlert(action);
+			if (!r.present || !r.button || !r.handled) break;
+			if (r.description === lastTitle) break;
+			lastTitle = r.description ?? "";
+			tapped.push(r.button);
+		}
+		return tapped;
+	}
+	/** Go to the home screen. */
+	async goHome() {
+		await this.backend.home();
+	}
+	/** Navigate back (nav-bar back / hardware back). */
+	async goBack() {
+		await this.backend.back();
+	}
+	/** Save a screenshot to `path`; returns the written path. */
+	async screenshot(path) {
+		return (await this.backend.screenshot({ path })).path;
+	}
+	/** Close the backend's transport session. */
+	async closeSession() {
+		await this.backend.closeSession();
+	}
+	findNode(ref) {
+		const want = normRef(ref);
+		return this.cachedNodes.find((n) => n.ref && normRef(n.ref) === want);
+	}
+	async ensureCache() {
+		if (this.cachedNodes.length === 0) await this.observe();
+	}
+};
+//#endregion
+//#region src/secrets.ts
+const MIN_SECRET_LENGTH = 4;
+/**
+* `%variable%` secret substitution (docs/19 §API shape, Stagehand's pattern):
+* the model/caller plans against NAMES; values are injected at the last moment
+* before backend.fill/typeText and never rendered into Actions, results,
+* observations, or traces. Redaction is best-effort belt-and-braces; the hard
+* guarantee is at the substitution point — values never enter stored Actions
+* by construction.
+*/
+var SecretStore = class SecretStore {
+	values = /* @__PURE__ */ new Map();
+	constructor(values) {
+		if (values) for (const [k, v] of Object.entries(values)) this.set(k, v);
+	}
+	/**
+	* Store a secret under `name`. Rejects values shorter than 4 chars — a
+	* 2-char secret would redact innocent UI text everywhere.
+	*/
+	set(name, value) {
+		if (value.length < MIN_SECRET_LENGTH) throw new Error(`secret "${name}" is too short (<${MIN_SECRET_LENGTH} chars) to redact safely`);
+		this.values.set(name, value);
+	}
+	/** The stored secret NAMES (never the values). */
+	names() {
+		return [...this.values.keys()];
+	}
+	/** %name% → value. Unknown %x% stays literal. */
+	substitute(text) {
+		return text.replace(/%([A-Za-z0-9_-]+)%/g, (whole, name) => this.values.get(name) ?? whole);
+	}
+	/** value → %name% across outbound text (messages, rendered observations). */
+	redact(text) {
+		let out = text;
+		for (const [name, value] of this.values) out = out.split(value).join(`%${name}%`);
+		return out;
+	}
+	/** Per-call vars layered over the store (call-scoped, never persisted). */
+	withOverrides(vars) {
+		if (!vars || Object.keys(vars).length === 0) return this;
+		const merged = new SecretStore();
+		for (const [k, v] of this.values) merged.values.set(k, v);
+		for (const [k, v] of Object.entries(vars)) merged.set(k, v);
+		return merged;
+	}
+};
+//#endregion
+//#region src/actions.ts
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw new AbortedError();
+}
+/** Race a backend promise against the caller's abort. The abandoned in-flight
+*  call may still land on the device — documented abort semantics (state
+*  indeterminate); no retry follows an abort. */
+async function raceWithAbort(promise, signal) {
+	if (!signal) return promise;
+	throwIfAborted(signal);
+	let onAbort;
+	const aborted = new Promise((_, reject) => {
+		onAbort = () => reject(new AbortedError());
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		return await Promise.race([promise, aborted]);
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+function sleep(ms, signal) {
+	return raceWithAbort(new Promise((r) => setTimeout(r, ms)), signal);
+}
+function queryFor(el) {
+	return el.id ? { id: el.id } : { label: el.label };
+}
+function provenance(core, el, via) {
+	return {
+		...via === void 0 ? {} : { via },
+		label: el.label,
+		role: el.role,
+		...el.rect === void 0 ? {} : { rect: el.rect },
+		...core.currentApp() === void 0 ? {} : { app: core.currentApp() },
+		...core.screenTitle() ? { screenTitle: core.screenTitle() } : {}
+	};
+}
+/** Synthesize portable actions from the CURRENT cache (observe-time). */
+function toActions(core) {
+	const actions = [];
+	for (const el of core.interactiveElements()) {
+		const kind = el.role;
+		if (TAPPABLE.has(kind)) actions.push({
+			formatVersion: 0,
+			verb: "tap",
+			target: queryFor(el),
+			observed: provenance(core, el, el.id ? "id" : "exact label")
+		});
+	}
+	for (const el of core.inputFields(true)) actions.push({
+		formatVersion: 0,
+		verb: "fill",
+		target: queryFor(el),
+		params: { text: "" },
+		observed: provenance(core, el, el.id ? "id" : "exact label")
+	});
+	return actions;
+}
+const NO_SECRETS = new SecretStore();
+/**
+* Take one fresh snapshot and assemble the full {@link ObserveResult}:
+* deduped element channel, secret-redacted rendered text, and a portable
+* Action per tappable / input field.
+*/
+async function buildObserveResult(core, secrets = NO_SECRETS) {
+	const obs = await core.observe();
+	const redact = (s) => secrets.redact(s);
+	const seen = /* @__PURE__ */ new Set();
+	const elements = [];
+	for (const el of [...core.interactiveElements(), ...core.inputFields(true)]) {
+		if (seen.has(el.ref)) continue;
+		seen.add(el.ref);
+		elements.push({
+			...el,
+			label: redact(el.label),
+			...el.value === void 0 || el.value === null ? {} : { value: redact(el.value) }
+		});
+	}
+	return {
+		success: true,
+		message: elements.length ? `observed ${elements.length} interactive elements` : obs.elements.slice(0, 120),
+		...obs.app === void 0 ? {} : { app: obs.app },
+		...obs.bundleId === void 0 ? {} : { bundleId: obs.bundleId },
+		...core.screenTitle() ? { screenTitle: core.screenTitle() } : {},
+		elements,
+		rendered: redact(core.renderObservation(true)),
+		actions: toActions(core)
+	};
+}
+function toResolveOpts(q) {
+	return {
+		...q.role === void 0 ? {} : { role: q.role },
+		...q.near === void 0 ? {} : { near: q.near }
+	};
+}
+function queryText(q) {
+	const t = q.id ?? q.label;
+	if (t === void 0 || t === "") throw new ActionFailedError("action target needs an id or label");
+	return t;
+}
+function isActionable(el) {
+	return el.enabled !== false && !el.blocked;
+}
+const CACHE_FRESH_MS = 2e3;
+const POLL_STEPS_MS = [
+	150,
+	300,
+	600,
+	800
+];
+/**
+* Resolve + auto-wait (docs/19: visible+hittable+enabled+settled on every
+* action, no caller sleep; docs/20 risk 2: must not double latency).
+* Fast path: a fresh cache resolving to an actionable target executes with
+* ZERO extra snapshots. Slow path: poll in place (never scroll — scrolling is
+* the ladder's job, and polling must not dismiss transient menus) until the
+* target is actionable AND the tree signature is stable between polls.
+*/
+async function resolveWithWait(core, q, opts, pool) {
+	const signal = opts.signal;
+	const deadline = Date.now() + (opts.timeoutMs ?? 5e3);
+	const text = queryText(q);
+	const rOpts = toResolveOpts(q);
+	const inCache = () => pool === "fields" ? matchInElements(core.inputFields(true), text, rOpts) : core.resolveInCache(text, rOpts);
+	if (core.cacheAgeMs() < CACHE_FRESH_MS) {
+		const r = inCache();
+		if (r.el && isActionable(r.el)) return {
+			ok: true,
+			el: r.el,
+			via: r.via ?? "cache",
+			waited: void 0
+		};
+		if (r.candidates?.length) return {
+			ok: false,
+			result: ambiguityResult(text, r)
+		};
+	}
+	throwIfAborted(signal);
+	let r;
+	if (pool === "tappable") r = await raceWithAbort(core.resolveElement(text, rOpts), signal);
+	else {
+		await raceWithAbort(core.observe(), signal);
+		r = inCache();
+	}
+	if (!r.el && r.candidates?.length) return {
+		ok: false,
+		result: ambiguityResult(text, r)
+	};
+	if (r.el && isActionable(r.el)) return {
+		ok: true,
+		el: r.el,
+		via: r.via ?? "ladder",
+		waited: void 0
+	};
+	const started = Date.now();
+	let polls = 0;
+	let lastSig = core.stateSignature();
+	let step = 0;
+	while (Date.now() < deadline) {
+		await sleep(POLL_STEPS_MS[Math.min(step, POLL_STEPS_MS.length - 1)], signal);
+		step++;
+		polls++;
+		throwIfAborted(signal);
+		await raceWithAbort(core.observe(), signal);
+		const sig = core.stateSignature();
+		const settled = sig === lastSig;
+		lastSig = sig;
+		const rr = inCache();
+		if (rr.el && isActionable(rr.el) && settled) return {
+			ok: true,
+			el: rr.el,
+			via: rr.via ?? "wait",
+			waited: {
+				ms: Date.now() - started,
+				polls
+			}
+		};
+		if (!rr.el && rr.candidates?.length) return {
+			ok: false,
+			result: ambiguityResult(text, rr)
+		};
+		r = rr;
+	}
+	return {
+		ok: false,
+		result: {
+			success: false,
+			code: "TIMEOUT",
+			message: r.el ? `timed out after ${opts.timeoutMs ?? 5e3}ms waiting for "${text}" to become enabled/settled` : `timed out after ${opts.timeoutMs ?? 5e3}ms — no element matching "${text}" on this screen`,
+			waited: {
+				ms: Date.now() - started,
+				polls
+			}
+		}
+	};
+}
+function ambiguityResult(text, r) {
+	const list = (r.candidates ?? []).map((c) => `${c.role} "${c.label}"${c.rect ? ` at (${Math.round(c.rect.x)},${Math.round(c.rect.y)})` : ""}`).join("; ");
+	return {
+		success: false,
+		message: `"${text}" is ambiguous — ${r.candidates?.length ?? 0} matches: ${list}. Disambiguate with role or near.`,
+		candidates: r.candidates ?? []
+	};
+}
+function resolvedOf(el, via) {
+	return {
+		via,
+		ref: el.ref,
+		label: el.label,
+		role: el.role,
+		...el.rect === void 0 ? {} : { rect: el.rect }
+	};
+}
+/**
+* THE dispatcher: resolve → auto-wait → execute → diff. One brain — used by
+* device.tap/type/act, and (items 5-6) by the harness and the skill runner.
+*/
+async function executeAction(core, action, opts = {}, secrets = NO_SECRETS) {
+	const signal = opts.signal;
+	throwIfAborted(signal);
+	const store = secrets.withOverrides(opts.vars);
+	const redact = (s) => store.redact(s);
+	try {
+		switch (action.verb) {
+			case "tap":
+			case "longPress":
+			case "fill": {
+				if (!action.target) return {
+					success: false,
+					message: `${action.verb} needs a target query`
+				};
+				const wait = await resolveWithWait(core, action.target, opts, action.verb === "fill" ? "fields" : "tappable");
+				if (!wait.ok) return wait.result;
+				const { el, via, waited } = wait;
+				if (action.verb === "longPress") {
+					await raceWithAbort(core.longPress(el.ref, action.params?.durationMs), signal);
+					return {
+						success: true,
+						message: redact(`long-pressed "${el.label}"`),
+						resolved: resolvedOf(el, via),
+						waited
+					};
+				}
+				if (action.verb === "fill") {
+					const text = store.substitute(action.params?.text ?? "");
+					const ev = await raceWithAbort(core.fill(el.ref, text), signal);
+					if (action.params?.submit) await raceWithAbort(core.pressReturn(), signal);
+					return {
+						success: true,
+						message: redact(`filled "${el.label}"${action.params?.submit ? ", pressed Return" : ""}`),
+						...ev.changed === void 0 ? {} : { changed: ev.changed },
+						resolved: resolvedOf(el, via),
+						waited
+					};
+				}
+				const ev = await raceWithAbort(core.press(el.ref), signal);
+				return {
+					success: true,
+					message: redact(`tapped "${el.label}"${ev.changed === false ? " (no change)" : ""}`),
+					...ev.changed === void 0 ? {} : { changed: ev.changed },
+					resolved: resolvedOf(el, via),
+					waited
+				};
+			}
+			case "type": {
+				const text = store.substitute(action.params?.text ?? "");
+				await raceWithAbort(core.typeText(text), signal);
+				if (action.params?.submit) await raceWithAbort(core.pressReturn(), signal);
+				return {
+					success: true,
+					message: redact(`typed ${JSON.stringify(action.params?.text ?? "")}`)
+				};
+			}
+			case "pressKey":
+				await raceWithAbort(core.pressReturn(), signal);
+				return {
+					success: true,
+					message: "pressed Return"
+				};
+			case "scroll": {
+				const direction = action.params?.direction ?? "down";
+				await raceWithAbort(core.scroll(direction), signal);
+				await raceWithAbort(core.observe(), signal);
+				return {
+					success: true,
+					message: `scrolled ${direction}`
+				};
+			}
+			case "openApp":
+				if (!action.params?.app) return {
+					success: false,
+					message: "openApp needs params.app"
+				};
+				return {
+					success: true,
+					message: await raceWithAbort(core.openApp(action.params.app, action.params.relaunch ?? false), signal)
+				};
+			case "openUrl":
+				if (!action.params?.url) return {
+					success: false,
+					message: "openUrl needs params.url"
+				};
+				return {
+					success: true,
+					message: await raceWithAbort(core.openUrl(action.params.url, action.params.app), signal)
+				};
+			case "back":
+				await raceWithAbort(core.goBack(), signal);
+				return {
+					success: true,
+					message: "went back"
+				};
+			case "home":
+				await raceWithAbort(core.goHome(), signal);
+				return {
+					success: true,
+					message: "went home"
+				};
+			case "alert": {
+				const outcome = await raceWithAbort(core.handleAlert(action.params?.alertAction ?? "accept"), signal);
+				if (!outcome.present) return {
+					success: false,
+					message: "no system alert is showing"
+				};
+				return {
+					success: outcome.handled !== false,
+					message: `alert ${outcome.handled ? `handled via "${outcome.button}"` : "NOT handled"}: ${outcome.description ?? ""}`
+				};
+			}
+			case "waitForText": {
+				if (!action.params?.text) return {
+					success: false,
+					message: "waitForText needs params.text"
+				};
+				const note = await raceWithAbort(core.waitForText(action.params.text, opts.timeoutMs ?? 5e3), signal);
+				const ok = !/did not appear|not found|timed out/i.test(note);
+				return {
+					success: ok,
+					message: redact(note),
+					...ok ? {} : { code: "TIMEOUT" }
+				};
+			}
+			default: return {
+				success: false,
+				message: `unknown verb ${String(action.verb)}`
+			};
+		}
+	} catch (error) {
+		if (error instanceof AbortedError) throw error;
+		if (error instanceof PhoneUseError) {
+			if (error instanceof ActionFailedError || error instanceof TimeoutError) return {
+				success: false,
+				message: redact(error.message),
+				code: error.code
+			};
+			throw error;
+		}
+		throw error;
+	}
+}
+//#endregion
+//#region src/backends/agent-device.ts
+var AgentDeviceBackend = class extends BaseDeviceBackend {
+	client;
+	selection;
+	used = false;
+	constructor(config) {
+		super("agent-device", ALL_CAPABILITIES);
+		this.client = createAgentDeviceClient(config && (config.session !== void 0 || config.daemonBaseUrl !== void 0 || config.daemonAuthToken !== void 0) ? {
+			...config.session === void 0 ? {} : { session: config.session },
+			...config.daemonBaseUrl === void 0 ? {} : { daemonBaseUrl: config.daemonBaseUrl },
+			...config.daemonAuthToken === void 0 ? {} : { daemonAuthToken: config.daemonAuthToken }
+		} : void 0);
+		this.selection = !config ? {} : {
+			platform: config.platform,
+			...config.device === void 0 ? {} : { device: config.device },
+			...config.platform === "ios" && config.udid !== void 0 ? { udid: config.udid } : {},
+			...config.platform === "ios" && config.simulatorDeviceSet !== void 0 ? { iosSimulatorDeviceSet: config.simulatorDeviceSet } : {},
+			...config.platform === "android" && config.serial !== void 0 ? { serial: config.serial } : {}
+		};
+	}
+	async guard(capability, fn) {
+		if (capability !== "closeSession") this.used = true;
+		try {
+			return await fn();
+		} catch (error) {
+			throw toPhoneUseError(error, {
+				backend: this.backendName,
+				capability
+			});
+		}
+	}
+	snapshot(opts) {
+		return this.guard("snapshot", async () => {
+			const snap = await this.client.capture.snapshot({
+				...this.selection,
+				...opts?.interactiveOnly === void 0 ? {} : { interactiveOnly: opts.interactiveOnly },
+				...opts?.depth === void 0 ? {} : { depth: opts.depth }
+			});
+			return {
+				nodes: snap.nodes,
+				appName: snap.appName,
+				appBundleId: snap.appBundleId
+			};
+		});
+	}
+	screenshot(opts) {
+		return this.guard("screenshot", async () => {
+			return { path: (await this.client.capture.screenshot({
+				...this.selection,
+				path: opts.path,
+				...opts.overlayRefs === void 0 ? {} : { overlayRefs: opts.overlayRefs }
+			})).path };
+		});
+	}
+	press(target) {
+		return this.guard("press", async () => {
+			await this.client.interactions.press({
+				...this.selection,
+				...target
+			});
+		});
+	}
+	longPress(ref, durationMs) {
+		return this.guard("longPress", async () => {
+			await this.client.interactions.longPress({
+				...this.selection,
+				ref,
+				...durationMs === void 0 ? {} : { durationMs },
+				settle: true
+			});
+		});
+	}
+	fill(ref, text) {
+		return this.guard("fill", async () => {
+			await this.client.interactions.fill({
+				...this.selection,
+				ref,
+				text
+			});
+		});
+	}
+	typeText(text) {
+		return this.guard("type", async () => {
+			await this.client.interactions.type({
+				...this.selection,
+				text
+			});
+		});
+	}
+	pressKey(_key) {
+		return this.guard("key", async () => {
+			await this.client.command.keyboard({
+				...this.selection,
+				action: "return"
+			});
+		});
+	}
+	scroll(direction) {
+		return this.guard("scroll", async () => {
+			const args = {
+				...this.selection,
+				direction
+			};
+			await this.client.interactions.scroll(args);
+		});
+	}
+	pan(x, y, dx, dy, durationMs) {
+		return this.guard("pan", async () => {
+			await this.client.interactions.pan({
+				...this.selection,
+				x,
+				y,
+				dx,
+				dy,
+				...durationMs === void 0 ? {} : { durationMs }
+			});
+		});
+	}
+	waitForText(text, timeoutMs) {
+		return this.guard("waitForText", async () => {
+			await this.client.command.wait({
+				...this.selection,
+				text,
+				...timeoutMs === void 0 ? {} : { timeoutMs }
+			});
+		});
+	}
+	systemAlert(action) {
+		return this.guard("alert", async () => {
+			const result = await this.client.command.alert({
+				...this.selection,
+				action
+			});
+			return {
+				alert: result.alert,
+				handled: result.handled,
+				button: result.button
+			};
+		});
+	}
+	home() {
+		return this.guard("home", async () => {
+			await this.client.command.home({ ...this.selection });
+		});
+	}
+	back() {
+		return this.guard("back", async () => {
+			await this.client.command.back({ ...this.selection });
+		});
+	}
+	openApp(opts) {
+		return this.guard("openApp", async () => {
+			const args = opts.url === void 0 ? {
+				app: opts.app,
+				...opts.relaunch === void 0 ? {} : { relaunch: opts.relaunch }
+			} : opts.app !== void 0 ? {
+				app: opts.app,
+				url: opts.url
+			} : { url: opts.url };
+			const result = await this.client.apps.open({
+				...this.selection,
+				...args
+			});
+			return {
+				appName: result.appName,
+				appBundleId: result.appBundleId
+			};
+		});
+	}
+	listApps() {
+		return this.guard("listApps", async () => {
+			return await this.client.apps.list(Object.keys(this.selection).length ? this.selection : void 0);
+		});
+	}
+	closeSession() {
+		if (!this.used) return Promise.resolve();
+		return this.guard("closeSession", async () => {
+			await this.client.sessions.close({ ...this.selection });
+		});
+	}
+};
+/**
+* Build the agent-device backend: the ONE place agent-device is called. Device
+* pinning is per-request in agent-device, so the backend holds a selection
+* object and spreads it into every call. With no config, selection is `{}` and
+* the client is default-constructed — requests are byte-identical to the
+* pre-seam process-global path (booted-sim auto-detect). Every method
+* normalizes errors via `toPhoneUseError`; no agent-device type or error ever
+* escapes this module.
+*/
+function createAgentDeviceBackend(config) {
+	return new AgentDeviceBackend(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) {
+	return setPath === void 0 ? ["simctl", ...args] : [
+		"simctl",
+		"--set",
+		setPath,
+		...args
+	];
+}
+function isAlreadyInState(err) {
+	if (!isExecError(err)) return false;
+	if (err.code === 149) return true;
+	return /current state.*(Booted|Shutdown)/i.test(err.stderr ?? "");
+}
+async function runSimctl(exec, setPath, args, opts = {}) {
+	try {
+		return (await exec("xcrun", simctlArgs(setPath, args), opts.timeoutMs === void 0 ? void 0 : { timeoutMs: opts.timeoutMs })).stdout;
+	} catch (err) {
+		if (opts.tolerateState && isAlreadyInState(err)) return "";
+		if (isExecError(err)) {
+			if (err.killed || err.signal) throw new TimeoutError(`simctl ${args[0]} timed out${opts.timeoutMs ? ` after ${opts.timeoutMs}ms` : ""}`, { cause: err });
+			throw new ActionFailedError(`simctl ${args[0]} failed (exit ${String(err.code ?? "?")}): ${(err.stderr ?? err.message).trim()}`, {
+				details: { backendCode: String(err.code ?? "EXEC") },
+				cause: err
+			});
+		}
+		throw toPhoneUseError(err);
+	}
+}
+function parseCreatedUdid(stdout) {
+	const lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+	const last = lines[lines.length - 1] ?? "";
+	if (!UDID_RE.test(last)) throw new ActionFailedError(`could not parse udid from simctl create output: ${JSON.stringify(stdout.slice(0, 200))}`);
+	return last;
+}
+function parseList(stdout) {
+	let parsed;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch (err) {
+		throw new ActionFailedError("could not parse simctl list output as JSON", { cause: err });
+	}
+	return Object.values(parsed.devices ?? {}).flat();
+}
+function makeBackendConfig(udid, opts) {
+	return {
+		platform: "ios",
+		udid,
+		...opts.simulatorDeviceSet === void 0 ? {} : { simulatorDeviceSet: opts.simulatorDeviceSet },
+		session: opts.session ?? `phone-use-${udid}`,
+		...opts.daemonBaseUrl === void 0 ? {} : { daemonBaseUrl: opts.daemonBaseUrl },
+		...opts.daemonAuthToken === void 0 ? {} : { daemonAuthToken: opts.daemonAuthToken }
+	};
+}
+async function bootAndWait(exec, setPath, udid, bootTimeoutMs) {
+	await runSimctl(exec, setPath, ["boot", udid], { tolerateState: true });
+	await runSimctl(exec, setPath, [
+		"bootstatus",
+		udid,
+		"-b"
+	], { timeoutMs: bootTimeoutMs });
+}
+async function finishHandle(udid, name, createdByUs, opts, exec) {
+	const backend = createAgentDeviceBackend(makeBackendConfig(udid, opts));
+	if (opts.failFast) await backend.listApps();
+	return createDeviceHandle({
+		id: udid,
+		platform: "ios",
+		name,
+		backend,
+		createdByUs,
+		idleTimeoutMs: opts.idleTimeoutMs,
+		onIdleClose: opts.onIdleClose,
+		secrets: opts.secrets,
+		coreFactory: opts.coreFactory,
+		doClose: async () => {
+			await runSimctl(exec, opts.simulatorDeviceSet, ["shutdown", udid], { tolerateState: true });
+			if (createdByUs) await runSimctl(exec, opts.simulatorDeviceSet, ["delete", udid]);
+		}
+	});
+}
+/**
+* Create and boot a DEDICATED simulator via simctl — no more "whatever is
+* booted" — and return a {@link Device} pinned to its udid. Created sims are
+* named `phone-use-<hex>` deliberately: if the process is kill -9'd the
+* in-process reaper can't run, and the name prefix is how orphans are found.
+* `close()` shuts the sim down AND deletes it (we created it); a failed boot
+* best-effort-deletes before rethrowing.
+*/
+async function launch(options = {}) {
+	const exec = options.exec ?? defaultExecRunner;
+	const deviceType = options.deviceType ?? "iPhone 16";
+	const name = options.name ?? `phone-use-${Math.random().toString(16).slice(2, 10)}`;
+	const bootTimeoutMs = options.bootTimeoutMs ?? 12e4;
+	const createArgs = [
+		"create",
+		name,
+		deviceType,
+		...options.runtime === void 0 ? [] : [options.runtime]
+	];
+	const udid = parseCreatedUdid(await runSimctl(exec, options.simulatorDeviceSet, createArgs));
+	try {
+		await bootAndWait(exec, options.simulatorDeviceSet, udid, bootTimeoutMs);
+	} catch (err) {
+		await runSimctl(exec, options.simulatorDeviceSet, ["delete", udid]).catch(() => void 0);
+		throw err;
+	}
+	return finishHandle(udid, name, true, options, exec);
+}
+/**
+* Reattach to an existing simulator by udid (booting it if shut down). The
+* no-arg form is the sole survivor of the old booted-sim auto-detect: it
+* attaches to the first booted, available sim. `close()` on a connected
+* device shuts it down but never deletes it.
+*/
+async function connect(udid, options = {}) {
+	const exec = options.exec ?? defaultExecRunner;
+	const bootTimeoutMs = options.bootTimeoutMs ?? 12e4;
+	if (udid === void 0) {
+		const booted = parseList(await runSimctl(exec, options.simulatorDeviceSet, [
+			"list",
+			"devices",
+			"booted",
+			"-j"
+		])).find((d) => d.state === "Booted" && d.isAvailable !== false);
+		if (!booted) throw new DeviceNotFoundError("no booted simulator — use ios.launch() or boot one");
+		return finishHandle(booted.udid, booted.name, false, options, exec);
+	}
+	const row = parseList(await runSimctl(exec, options.simulatorDeviceSet, [
+		"list",
+		"devices",
+		"-j"
+	])).find((d) => d.udid.toLowerCase() === udid.toLowerCase());
+	if (!row) throw new DeviceNotFoundError(`no simulator with udid ${udid}`);
+	if (row.state !== "Booted") await bootAndWait(exec, options.simulatorDeviceSet, row.udid, bootTimeoutMs);
+	return finishHandle(row.udid, row.name, false, options, exec);
+}
+/**
+* The iOS engine object (Playwright-style): `ios.launch()` for a dedicated
+* simulator, `ios.connect()` to reattach. Both return the same Device type.
+*/
+const ios = {
+	/** Create + boot a dedicated simulator and return a Device pinned to it. */
+	launch,
+	/** Reattach to an existing simulator (no-arg: first booted sim). */
+	connect
+};
+//#endregion
+//#region src/index.ts
+/**
+* @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
+* (ios.launch/connect → Device), Device backends, config, errors, capabilities
+* (docs/20-runtime-sdk-v1-plan.md items 2-3; action verbs land in item 4).
+*
+* 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.1.0";
+registerBackend("agent-device", createAgentDeviceBackend);
+//#endregion
+export { ALL_CAPABILITIES, AbortedError, ActionFailedError, BaseDeviceBackend, DeviceCore, DeviceInUseError, DeviceNotFoundError, PhoneUseError, SecretStore, SessionNotFoundError, TimeoutError, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createDeviceHandle, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
+
+//# sourceMappingURL=index.mjs.map