@xopcai/xopc 0.0.415 → 0.0.417

package/dist/src/phone/runtime.js

@@ -3,44 +3,84 @@ import { init_logger } from "../utils/logger.js";
 import { MOCK_PHONE_MODEL, PhoneError, PhoneInputSchema, init_contracts } from "./contracts.js";
 import { resolveEffectiveAgentConfigForAgent } from "../config/agent-profile.js";
 import { phoneAllowsApp, phoneAppAccess } from "./app-access.js";
+import { nativePhoneOutput, updatePhoneFeedback } from "./task-feedback.js";
 import { PhoneFrameCache, PhoneOperationBudget } from "./live-state.js";
 import { PhoneInteractiveSession } from "./interactive-session.js";
-import { AdbPhoneDriver, resolveAdbPath } from "./adb-driver.js";
 import { LocalScrcpyProvider } from "./scrcpy.js";
+import { AdbPhoneDriver, resolveAdbPath } from "./adb-driver.js";
 import { CloudPhones } from "./cloud-phones.js";
+import { WirelessPhones } from "./wireless.js";
+import { advancePhonePlan, buildPhonePlan, createPhonePlanState } from "./planning.js";
+import { canDispatchPhoneAction, observationSignature, phoneCompletionSatisfied } from "./reliability.js";
+import { groundPhoneCoordinateAction, resolvePhoneSemanticAction } from "./semantic-controls.js";
 import { createPhoneModel, isAboutScreen } from "./model-adapter.js";
 import { PhoneRepository } from "./repository.js";
-import { canDispatchPhoneAction, observationSignature, phoneCompletionSatisfied } from "./reliability.js";
+import { confirmPhoneFocusRecovery, phoneBackRecovery, phoneUnfocusedTypingHint, preparePhoneFocusRecovery } from "./recovery.js";
+import { createPhoneNumericEntry, nextPhoneNumericEntry } from "./numeric-entry.js";
 import { createHash, randomUUID } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
 //#region src/phone/runtime.ts
 init_logger();
 init_contracts();
+const VIEW_MODEL = "phone-view-only";
 const log = createLogger("PhoneRuntime");
-const terminal = new Set([
-	"cancelled",
-	"closed",
-	"failed",
-	"outcome_unknown"
-]);
+const terminal = new Set(["closed"]);
 var PhoneRuntime = class {
+	reconnecting = /* @__PURE__ */ new Map();
+	reconnectAfter = /* @__PURE__ */ new Map();
 	cloudPhones;
 	get cloud() {
 		return this.cloudPhones ??= new CloudPhones(this.repository);
 	}
 	sessions = /* @__PURE__ */ new Map();
+	lastDevices = /* @__PURE__ */ new Map();
 	openings = /* @__PURE__ */ new Map();
+	deviceOpenings = /* @__PURE__ */ new Map();
 	maintenance;
-	constructor(repository = new PhoneRepository(), driverFactory = (path) => new AdbPhoneDriver(path), modelFactory = createPhoneModel, interactiveFactory = (adb, serial, failed) => new LocalScrcpyProvider(adb, serial, failed)) {
+	constructor(repository = new PhoneRepository(), driverFactory = (path) => new AdbPhoneDriver(path), modelFactory = createPhoneModel, interactiveFactory = (adb, serial, failed) => new LocalScrcpyProvider(adb, serial, failed), wireless = new WirelessPhones()) {
 		this.repository = repository;
 		this.driverFactory = driverFactory;
 		this.modelFactory = modelFactory;
 		this.interactiveFactory = interactiveFactory;
+		this.wireless = wireless;
 	}
 	async driverFor(device, config) {
 		return device.connection ? this.cloud.driver(device) : this.driverFactory(resolveAdbPath(config.phone.adbPath));
 	}
 	async discover(config, signal) {
-		return this.driverFactory(resolveAdbPath(config.phone.adbPath)).discover(signal);
+		const driver = this.driverFactory(resolveAdbPath(config.phone.adbPath));
+		let devices = await driver.discover(signal);
+		const missing = this.repository.list().filter((device) => device.enabled && device.wireless && !devices.some((item) => item.serial === device.serial && item.state === "device") && (this.reconnectAfter.get(device.id) ?? 0) < Date.now()).slice(0, 2);
+		const reconnectSignal = AbortSignal.any([AbortSignal.timeout(5e3), ...signal ? [signal] : []]);
+		await Promise.all(missing.map(async (device) => {
+			this.reconnectAfter.set(device.id, Date.now() + 3e4);
+			await this.reconnectWireless(device.id, config, reconnectSignal).catch(() => {
+				signal?.throwIfAborted();
+			});
+		}));
+		if (missing.length) devices = await driver.discover(signal);
+		return devices;
+	}
+	reconnectWireless(id, config, signal, endpoint) {
+		const active = this.reconnecting.get(id);
+		if (active) return active;
+		const task = (async () => {
+			const device = this.repository.get(id);
+			if (!device.wireless || device.connection) throw new PhoneError("PHONE_NOT_WIRELESS", "Choose a registered wireless phone");
+			if (!device.enabled) throw new PhoneError("PHONE_DEVICE_DENIED", "Phone access is disabled", 403);
+			await Promise.all(this.reports().filter((report) => report.deviceId === id).map((report) => this.stop(report.owner, "close")));
+			this.cloudPhones?.disconnect(id);
+			const result = await this.wireless.reconnect(resolveAdbPath(config.phone.adbPath), device.wireless, signal, endpoint);
+			const current = this.repository.get(id);
+			if (current.revision !== device.revision) throw new PhoneError("PHONE_DEVICE_CHANGED", "Phone settings changed; retry connection", 409);
+			return this.repository.save({
+				...current,
+				serial: result.device.serial,
+				wireless: result.wireless
+			}, id);
+		})().finally(() => this.reconnecting.delete(id));
+		this.reconnecting.set(id, task);
+		return task;
 	}
 	async applications(input, config, signal) {
 		let driver;
@@ -72,6 +112,21 @@ var PhoneRuntime = class {
 	async preview(id, config, signal) {
 		const device = this.repository.get(id);
 		if (!device.enabled) throw new PhoneError("PHONE_DEVICE_DENIED", "Phone access is disabled", 403);
+		const connected = [...this.sessions.values()].find((session) => session.device.id === id && session.report.status !== "closed");
+		if (connected) {
+			this.guard(connected, {
+				...connected.context,
+				config
+			});
+			const observation = await this.observe(connected, signal);
+			try {
+				this.allowedScreen(connected, observation);
+				return observation;
+			} catch (error) {
+				observation.frame.fill(0);
+				throw error;
+			}
+		}
 		const lease = this.repository.acquire(device.serial);
 		try {
 			const observation = await (await this.driverFor(device, config)).observe(device.serial, signal);
@@ -87,7 +142,6 @@ var PhoneRuntime = class {
 	async previewSession(owner, context, signal) {
 		const session = this.sessions.get(owner);
 		if (!session || terminal.has(session.report.status)) throw new PhoneError("PHONE_OPEN_REQUIRED", "Open a phone session first");
-		if (session.active) throw new PhoneError("PHONE_SESSION_BUSY", "Pause the task before previewing", 409);
 		this.guard(session, context);
 		const observation = await this.observe(session, signal);
 		try {
@@ -105,7 +159,56 @@ var PhoneRuntime = class {
 		const report = this.sessions.get(owner)?.report;
 		return report && structuredClone(report);
 	}
+	deviceContext(id, config) {
+		const session = [...this.sessions.values()].find((session) => session.device.id === id && session.report.status !== "closed");
+		if (!session) throw new PhoneError("PHONE_SESSION_NOT_FOUND", "Phone is not connected", 404);
+		return {
+			...session.context,
+			config
+		};
+	}
+	async viewDevice(id, config, agentId, signal) {
+		if ([...this.sessions.values()].some((session) => session.device.id === id && session.report.status !== "closed")) return;
+		const owner = `phone-view:${id}`;
+		await this.execute(owner, {
+			op: "open",
+			deviceId: id,
+			mode: "observe"
+		}, {
+			config,
+			agentId,
+			modelRef: VIEW_MODEL
+		}, signal);
+		await this.finishTask(owner);
+	}
+	updateConnectionPolicy(config) {
+		for (const session of this.sessions.values()) session.context = {
+			...session.context,
+			config
+		};
+	}
+	async releaseConversation(owner) {
+		const session = this.sessions.get(owner);
+		if (!session || session.report.status === "closed") return;
+		if (this.deviceOpenings.has(session.device.id)) return;
+		if (session.active) {
+			await this.stop(owner, "cancel");
+			return;
+		}
+		if (!session.human && ![
+			"paused",
+			"needs_user",
+			"failed",
+			"outcome_unknown"
+		].includes(session.report.status)) await this.finishTask(owner);
+	}
 	publish(session) {
+		session.report.nextExecutionMode = this.repository.executionMode(session.report.owner) ?? session.context.config.phone.executionMode;
+		if (session.report.feedback && session.segmentUsage) session.report.feedback = updatePhoneFeedback(session.report, {
+			actions: session.report.actions - session.segmentUsage.actions,
+			modelRequests: session.report.modelRequests - session.segmentUsage.modelRequests,
+			activeDurationMs: session.segmentUsage.activeDurationMs + (session.budget?.elapsedMs ?? 0)
+		}, session.report.feedback);
 		session.report.updatedAt = Date.now();
 		this.repository.report(session.report);
 		return structuredClone(session.report);
@@ -114,7 +217,6 @@ var PhoneRuntime = class {
 		if (!context.config.phone.enabled || context.toolDenied) throw new PhoneError("PHONE_DISABLED", "Phone Use is disabled for this agent");
 		if (context.modelRef !== session.modelRef || resolveAdbPath(context.config.phone.adbPath) !== session.adbPath) throw new PhoneError("PHONE_BINDING_CHANGED", "Phone model or execution configuration changed; reopen the phone");
 		if (context.validateBinding && !context.validateBinding()) throw new PhoneError("PHONE_BINDING_CHANGED", "Agent model or tool policy changed; reopen the phone");
-		if (Date.now() - session.createdAt >= context.config.phone.maxSessionDurationMs) throw new PhoneError("PHONE_SESSION_LIMIT", "Phone session duration limit reached");
 		const current = this.repository.get(session.device.id);
 		if (!current.enabled || current.revision !== session.device.revision) throw new PhoneError("PHONE_ACCESS_CHANGED", "Device access changed; reopen the phone");
 		this.repository.renew(session.device.serial, session.lease);
@@ -124,6 +226,7 @@ var PhoneRuntime = class {
 	}
 	async execute(owner, raw, context, signal = new AbortController().signal) {
 		const input = PhoneInputSchema.parse(raw);
+		if (input.op === "close") return this.finishTask(owner);
 		if ([
 			"cancel",
 			"close",
@@ -131,35 +234,151 @@ var PhoneRuntime = class {
 		].includes(input.op)) return this.stop(owner, input.op);
 		if (input.op === "status") return this.status(owner) ?? { status: "closed" };
 		if (!context.config.phone.enabled || context.toolDenied) throw new PhoneError("PHONE_DISABLED", "Enable Phone Use in settings and allow the tool for this agent");
+		if (input.op === "set_mode") return {
+			executionMode: input.executionMode,
+			report: await this.setExecutionMode(owner, input.executionMode, context, input.applyCurrent)
+		};
 		if (input.op === "discover") return {
+			executionMode: this.repository.executionMode(owner) ?? context.config.phone.executionMode,
 			devices: this.repository.list().filter((device) => device.enabled),
-			defaultDeviceId: this.repository.defaultDevice()
+			defaultDeviceId: context.preferredDeviceId ?? this.repository.defaultDevice(),
+			systemDefaultDeviceId: this.repository.defaultDevice()
 		};
 		signal.throwIfAborted();
 		if (input.op === "open") {
+			const requestedDevice = input.deviceId ?? context.preferredDeviceId ?? this.repository.defaultDevice();
+			if (requestedDevice && this.deviceOpenings.has(requestedDevice)) throw this.busy(requestedDevice);
 			if (this.openings.has(owner)) throw new PhoneError("PHONE_SESSION_BUSY", "A phone is already being opened", 409);
 			const opening = new AbortController();
 			this.openings.set(owner, opening);
+			if (requestedDevice) this.deviceOpenings.set(requestedDevice, opening);
 			signal = AbortSignal.any([signal, opening.signal]);
 			try {
 				for (const [key, value] of this.sessions) if (terminal.has(value.report.status)) this.sessions.delete(key);
-				if (this.sessions.size >= 50) throw new PhoneError("PHONE_CAPACITY", "Close an existing phone session before opening another", 409);
+				if (this.sessions.size >= 50 && ![...this.sessions.values()].some((session) => session.device.id === requestedDevice)) throw new PhoneError("PHONE_CAPACITY", "Disconnect an idle phone in the global phone panel before opening another", 409);
 				const previous = this.sessions.get(owner);
-				if (previous && !terminal.has(previous.report.status)) throw new PhoneError("PHONE_ALREADY_OPEN", "Close the current phone session before opening another");
-				const deviceId = input.deviceId ?? this.repository.defaultDevice();
+				const deviceId = requestedDevice;
 				if (!deviceId) throw new PhoneError("PHONE_DEVICE_REQUIRED", "Choose a registered phone in Phone Use settings");
-				const device = this.repository.get(deviceId);
+				if (previous && !terminal.has(previous.report.status) && previous.device.id !== deviceId) {
+					if (previous.active || previous.human || previous.report.controlOwner !== "none" || !["ready", "completed"].includes(previous.report.status)) throw this.busy(previous.device.id, previous);
+				}
+				let device = this.repository.get(deviceId);
 				if (!device.enabled) throw new PhoneError("PHONE_DEVICE_DENIED", "This phone is disabled", 403);
 				const modelRef = context.modelRef;
 				if (!modelRef) throw new PhoneError("PHONE_MODEL_REQUIRED", "Choose a Phone Use model in settings");
+				if (input.appPackage && (input.mode !== "control" || !phoneAllowsApp(device, input.appPackage))) throw new PhoneError("PHONE_APP_DENIED", "Launching requires control mode and an allowed application");
+				const connected = [...this.sessions.values()].find((value) => value.device.id === deviceId && !terminal.has(value.report.status));
+				if (connected) {
+					if (connected.active || connected.human || connected.report.handoff !== "idle" || [
+						"paused",
+						"needs_user",
+						"failed",
+						"outcome_unknown"
+					].includes(connected.report.status) || connected.report.owner !== owner && !["completed", "ready"].includes(connected.report.status) || connected.report.owner !== owner && connected.report.controlOwner !== "none") throw this.busy(deviceId, connected);
+					if (connected.report.owner === owner && connected.report.controlOwner !== "none") {
+						this.guard(connected, context);
+						if (connected.report.mode !== input.mode) throw new PhoneError("PHONE_ALREADY_OPEN", "Finish the current task before changing phone mode", 409);
+						if (input.appPackage) {
+							const observation = await this.observe(connected, signal);
+							try {
+								await this.dispatch(connected, {
+									type: "launch",
+									package: input.appPackage
+								}, observation, context, signal, connected.report.controlEpoch, false, input.settingsPage);
+							} finally {
+								observation.frame.fill(0);
+							}
+						}
+						return this.publish(connected);
+					}
+					const adapter = await this.modelFactory(modelRef, context.config, context.agentId);
+					signal.throwIfAborted();
+					this.guard(connected, connected.context);
+					if (input.mode === "control" && modelRef !== "phone-mock/settings-about" && !connected.applications.length && connected.driver.applications) try {
+						connected.applications = await connected.driver.applications(device.serial, signal);
+					} catch {
+						signal.throwIfAborted();
+					}
+					await connected.streamOpening?.catch(() => {});
+					await connected.stream?.revoke();
+					await connected.io;
+					signal.throwIfAborted();
+					this.guard(connected, connected.context);
+					this.sessions.delete(connected.report.owner);
+					if (previous && previous !== connected) {
+						this.sessions.delete(owner);
+						previous.report.owner = `phone-view:${previous.device.id}`;
+						this.sessions.set(previous.report.owner, previous);
+					}
+					connected.report.owner = owner;
+					connected.report.agentId = context.agentId;
+					connected.report.modelRef = modelRef;
+					connected.report.sourceConversationId = /^[\da-f]{8}-[\da-f-]{27}$/i.test(owner) ? owner : void 0;
+					connected.report.mode = input.mode;
+					connected.report.mock = modelRef === MOCK_PHONE_MODEL;
+					connected.report.status = "ready";
+					connected.report.controlOwner = "agent";
+					connected.report.controlEpoch++;
+					connected.report.actions = 0;
+					connected.report.modelRequests = 0;
+					connected.report.steps = [];
+					connected.report.humanActions = 0;
+					connected.report.verified = false;
+					connected.report.verificationLevel = "none";
+					connected.report.stopReason = void 0;
+					connected.report.errorCode = void 0;
+					connected.report.message = void 0;
+					connected.report.facts = void 0;
+					connected.report.readings = void 0;
+					connected.report.task = void 0;
+					connected.report.feedback = void 0;
+					connected.report.executionMode = void 0;
+					connected.segmentUsage = void 0;
+					connected.taskActiveMs = 0;
+					connected.taskStart = void 0;
+					connected.modeHandbackRequired = false;
+					connected.report.goalPreview = void 0;
+					connected.adapter = adapter;
+					connected.context = context;
+					connected.modelRef = modelRef;
+					connected.controller = new AbortController();
+					connected.createdAt = Date.now();
+					connected.taskPending = false;
+					connected.trajectory = [];
+					connected.trajectoryCount = 0;
+					connected.trajectorySummary = [];
+					connected.frames.clear();
+					connected.receipts.clear();
+					this.sessions.set(owner, connected);
+					this.lastDevices.set(owner, deviceId);
+					if (input.appPackage) {
+						if (input.mode !== "control" || !phoneAllowsApp(device, input.appPackage)) throw new PhoneError("PHONE_APP_DENIED", "Launching requires control mode and an allowed application");
+						const observation = await this.observe(connected, signal);
+						try {
+							await this.dispatch(connected, {
+								type: "launch",
+								package: input.appPackage
+							}, observation, context, signal, connected.report.controlEpoch, false, input.settingsPage);
+						} finally {
+							observation.frame.fill(0);
+						}
+					}
+					return this.publish(connected);
+				}
 				const adbPath = resolveAdbPath(context.config.phone.adbPath);
 				const driver = await this.driverFor(device, context.config);
-				const found = (await driver.discover(signal)).find((item) => item.serial === device.serial);
+				let found = (await driver.discover(signal)).find((item) => item.serial === device.serial);
+				if (found?.state !== "device" && device.wireless) {
+					device = await this.reconnectWireless(device.id, context.config, signal);
+					found = (await driver.discover(signal)).find((item) => item.serial === device.serial);
+				}
 				if (found?.state !== "device") throw new PhoneError("PHONE_DEVICE_OFFLINE", "Phone is offline or has not authorized ADB");
 				if (modelRef === "phone-mock/settings-about" && !found.emulator) throw new PhoneError("PHONE_MOCK_EMULATOR_ONLY", "The deterministic mock model is only enabled for local Android emulators");
 				const lease = this.repository.acquire(device.serial);
 				try {
-					const adapter = await this.modelFactory(modelRef, context.config, context.agentId);
+					const adapter = modelRef === VIEW_MODEL ? { predict: async () => {
+						throw new PhoneError("PHONE_OBSERVE_ONLY", "This connection is view only", 403);
+					} } : await this.modelFactory(modelRef, context.config, context.agentId);
 					signal.throwIfAborted();
 					let applications = [];
 					if (input.mode === "control" && modelRef !== "phone-mock/settings-about" && driver.applications) try {
@@ -196,6 +415,7 @@ var PhoneRuntime = class {
 							owner,
 							agentId: context.agentId,
 							modelRef,
+							sourceConversationId: /^[\da-f]{8}-[\da-f-]{27}$/i.test(owner) ? owner : void 0,
 							mock: modelRef === MOCK_PHONE_MODEL,
 							mode: input.mode,
 							status: "ready",
@@ -217,7 +437,15 @@ var PhoneRuntime = class {
 							}
 						}
 					};
+					if (previous && previous.device.id !== deviceId) {
+						this.sessions.delete(owner);
+						previous.report.owner = `phone-view:${previous.device.id}`;
+						this.sessions.set(previous.report.owner, previous);
+					}
 					this.sessions.set(owner, session);
+					this.lastDevices.set(owner, deviceId);
+					if (this.lastDevices.size > 500) this.lastDevices.delete(this.lastDevices.keys().next().value);
+					this.startMaintenance();
 					if (input.appPackage) {
 						if (input.mode !== "control" || !phoneAllowsApp(device, input.appPackage)) throw new PhoneError("PHONE_APP_DENIED", "Launching requires control mode and an allowed application");
 						const epoch = session.report.controlEpoch;
@@ -226,7 +454,7 @@ var PhoneRuntime = class {
 							await this.dispatch(session, {
 								type: "launch",
 								package: input.appPackage
-							}, observation, context, signal, epoch);
+							}, observation, context, signal, epoch, false, input.settingsPage);
 						} finally {
 							observation.frame.fill(0);
 						}
@@ -234,19 +462,29 @@ var PhoneRuntime = class {
 					return this.publish(session);
 				} catch (error) {
 					this.repository.release(device.serial, lease);
-					this.sessions.delete(owner);
+					if (this.sessions.get(owner)?.device.id === deviceId) this.sessions.delete(owner);
 					throw error;
 				}
 			} finally {
 				this.openings.delete(owner);
+				if (requestedDevice) this.deviceOpenings.delete(requestedDevice);
 			}
 		}
 		const session = this.sessions.get(owner);
-		if (!session || terminal.has(session.report.status)) throw new PhoneError("PHONE_OPEN_REQUIRED", "Open a phone session first");
-		if ((session.human || session.report.controlOwner === "none" && !(input.op === "resume" && session.controller.signal.aborted)) && input.op !== "run" && input.op !== "step") throw new PhoneError("PHONE_PAUSED", "The user controls this phone. Wait for explicit handback in the phone panel", 409);
+		if (!session || terminal.has(session.report.status)) {
+			const deviceId = this.lastDevices.get(owner);
+			const occupying = deviceId && [...this.sessions.values()].find((value) => value.device.id === deviceId && !terminal.has(value.report.status));
+			if (occupying) throw this.busy(deviceId, occupying);
+			throw new PhoneError("PHONE_OPEN_REQUIRED", "Open a phone session first");
+		}
+		if (session.switching) throw new PhoneError("PHONE_SESSION_BUSY", "Phone execution mode is changing", 409);
+		if (this.deviceOpenings.has(session.device.id)) throw this.busy(session.device.id, session);
+		if (session.human) throw new PhoneError("PHONE_PAUSED", "The user controls this phone. Wait for explicit handback in the phone panel", 409);
 		if (session.active) throw new PhoneError("PHONE_SESSION_BUSY", "A phone operation is already running", 409);
 		this.guard(session, context);
 		if (input.op === "resume") {
+			if (session.modeHandbackRequired) throw new PhoneError("PHONE_PAUSED", "Inspect the phone and explicitly hand back in the phone panel after changing execution mode", 409);
+			if (session.report.steps.at(-1)?.dispatch === "unknown") throw new PhoneError("PHONE_DISPATCH_UNKNOWN", "Inspect the previous input before continuing; do not retry automatically", 409);
 			session.controller = new AbortController();
 			session.report.controlOwner = "agent";
 			session.report.controlEpoch++;
@@ -255,23 +493,276 @@ var PhoneRuntime = class {
 			session.report.message = void 0;
 			return this.publish(session);
 		}
-		if (session.report.status === "paused" || session.report.status === "needs_user") throw new PhoneError("PHONE_PAUSED", "Complete manual interaction and resume the phone session");
-		session.budget = new PhoneOperationBudget(context.config.phone.maxOperationDurationMs);
+		if ([
+			"paused",
+			"needs_user",
+			"failed",
+			"outcome_unknown"
+		].includes(session.report.status)) throw new PhoneError("PHONE_PAUSED", "Inspect the phone and explicitly hand back control before continuing", 409);
+		if (input.op === "run" || input.op === "step") {
+			const previous = session.report.task;
+			const continuing = Boolean(input.taskId && previous?.taskId === input.taskId);
+			const executionMode = input.executionMode ?? (continuing ? previous.executionMode : this.repository.executionMode(owner) ?? context.config.phone.executionMode);
+			if (continuing && executionMode !== previous.executionMode) throw new PhoneError("PHONE_MODE_SWITCH_REQUIRED", "Pause and explicitly switch the current task before changing execution mode", 409);
+			const constraints = [...new Set([...continuing ? previous.constraints : [], ...input.constraints ?? []])];
+			if (constraints.length > 12) throw new PhoneError("PHONE_CONSTRAINT_LIMIT", "A phone task supports at most 12 constraints; existing constraints cannot be removed");
+			if (!continuing) {
+				session.trajectory = [];
+				session.trajectorySummary = [];
+				session.taskActiveMs = 0;
+				session.taskStart = {
+					actions: session.report.actions - (session.report.humanActions ?? 0),
+					modelRequests: session.report.modelRequests
+				};
+			}
+			session.report.task = {
+				taskId: continuing ? previous.taskId : input.taskId ?? randomUUID(),
+				executionMode,
+				goal: input.goal,
+				constraints,
+				requestedOutputs: input.requestedOutputs ?? (continuing ? previous.requestedOutputs : []),
+				budget: {
+					maxActions: Math.min(input.budget?.maxActions ?? 80, continuing ? previous.budget?.maxActions ?? 80 : 80),
+					maxModelRequests: Math.min(input.budget?.maxModelRequests ?? 120, continuing ? previous.budget?.maxModelRequests ?? 120 : 120),
+					maxActiveDurationMs: Math.min(input.budget?.maxActiveDurationMs ?? 9e5, continuing ? previous.budget?.maxActiveDurationMs ?? 9e5 : 9e5)
+				},
+				completion: input.completion,
+				expectText: input.expectText
+			};
+			session.report.executionMode = executionMode;
+			session.segmentUsage = {
+				actions: session.report.actions,
+				modelRequests: session.report.modelRequests,
+				activeDurationMs: 0
+			};
+			session.report.feedback = {
+				taskId: session.report.task.taskId,
+				segmentId: randomUUID(),
+				executionMode,
+				outcome: "running",
+				verified: false,
+				verificationLevel: "none",
+				progress: {
+					completed: [],
+					remaining: ["Current goal has not been verified"],
+					source: "runtime"
+				},
+				outputs: session.report.task.requestedOutputs.map((output) => ({
+					key: output.key,
+					verification: "unavailable",
+					reason: "not_observed"
+				})),
+				evidence: [],
+				usage: {
+					actions: 0,
+					modelRequests: 0,
+					activeDurationMs: 0
+				},
+				nextAction: "wait"
+			};
+			session.taskPending = true;
+			session.report.goalPreview = input.goal.slice(0, 160);
+		}
+		if (session.report.controlOwner === "none") {
+			session.report.controlOwner = "agent";
+			session.report.controlEpoch++;
+		}
+		const duration = Math.min(context.config.phone.maxOperationDurationMs, context.config.phone.maxSessionDurationMs, session.report.task?.budget?.maxActiveDurationMs ?? 9e5);
+		session.budget = new PhoneOperationBudget(Math.max(1, duration - (session.taskActiveMs ?? 0)));
 		if (session.report.controlOwner === "agent") session.budget.resume();
 		const combined = AbortSignal.any([
 			signal,
 			session.controller.signal,
 			session.budget.controller.signal
 		]);
-		const operation = this.perform(session, input, context, combined);
+		const operation = (async () => {
+			await this.perform(session, input, context, combined);
+			if ((input.op === "run" || input.op === "step") && ["ready", "completed"].includes(session.report.status) && session.report.task?.requestedOutputs.length) {
+				const observation = await this.observe(session, combined);
+				try {
+					this.guard(session, context);
+					this.allowedScreen(session, observation);
+					this.recordObservation(session, observation);
+					const conditions = input.completion || input.expectText ? {
+						...input.completion,
+						requireChange: false,
+						textAll: [...input.completion?.textAll ?? [], ...input.expectText ? [input.expectText] : []]
+					} : void 0;
+					if (session.report.verified && conditions && !phoneCompletionSatisfied({
+						...conditions,
+						textAll: conditions.textAll.length ? conditions.textAll : void 0
+					}, observation, true)) {
+						session.report.verified = false;
+						session.report.verificationLevel = "none";
+						session.report.status = "ready";
+						session.report.stopReason = "completion_changed";
+					}
+					const epoch = session.report.controlEpoch;
+					for (const request of session.report.task.requestedOutputs) {
+						if (request.selector) continue;
+						await this.readScreen(session, observation, request.description, context, combined);
+						if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") break;
+						const reading = session.report.readings?.at(-1);
+						if (reading?.source === "screenshot") {
+							const output = session.report.feedback.outputs.find((output) => output.key === request.key);
+							Object.assign(output, {
+								value: reading.text.join("\n") || void 0,
+								source: reading.source,
+								verification: reading.verification,
+								frameId: reading.frameId,
+								capturedAt: reading.capturedAt,
+								reason: reading.reason
+							});
+						}
+					}
+					this.publish(session);
+				} finally {
+					observation.frame.fill(0);
+				}
+			}
+		})();
 		session.active = operation;
 		try {
-			return await operation;
+			await operation;
+		} catch (error) {
+			if (combined.aborted && combined.reason instanceof PhoneError && combined.reason.code === "PHONE_OPERATION_TIMEOUT" && ![
+				"outcome_unknown",
+				"closed",
+				"cancelled"
+			].includes(session.report.status) && session.report.steps.at(-1)?.dispatch !== "unknown") {
+				session.report.status = "paused";
+				session.report.controlOwner = "none";
+				session.report.controlEpoch++;
+				session.report.stopReason = "operation_timeout";
+				session.report.errorCode = "PHONE_OPERATION_TIMEOUT";
+			}
+			if (["ready", "completed"].includes(session.report.status)) {
+				session.report.status = combined.aborted ? "cancelled" : "failed";
+				session.report.verified = false;
+				session.report.verificationLevel = "none";
+				session.report.errorCode = error instanceof PhoneError ? error.code : "PHONE_OPERATION_FAILED";
+				session.report.stopReason = "operation_failed";
+			}
+			if (error instanceof PhoneError && [
+				"PHONE_ACCESS_CHANGED",
+				"PHONE_APP_DENIED",
+				"PHONE_BINDING_CHANGED"
+			].includes(error.code)) {
+				session.report.facts = void 0;
+				session.report.readings = [];
+				if (session.report.feedback) session.report.feedback.outputs = session.report.feedback.outputs.map((output) => ({
+					key: output.key,
+					verification: "unavailable",
+					reason: error.code
+				}));
+			}
+			this.publish(session);
+			throw error;
 		} finally {
 			session.active = void 0;
+			const elapsed = session.budget?.elapsedMs ?? 0;
+			session.taskActiveMs = (session.taskActiveMs ?? 0) + elapsed;
+			if (session.segmentUsage) session.segmentUsage.activeDurationMs += elapsed;
 			session.budget?.dispose();
 			session.budget = void 0;
+			if (session.report.status === "cancelled" && !session.controller.signal.aborted) {
+				session.report.status = "ready";
+				session.taskPending = false;
+			}
+			if (session.report.status === "completed") session.taskPending = false;
+			if (!terminal.has(session.report.status) && !session.human && !["paused", "needs_user"].includes(session.report.status)) {
+				session.report.controlOwner = "none";
+				session.report.controlEpoch++;
+				this.publish(session);
+			}
+		}
+		return structuredClone(session.report);
+	}
+	async setExecutionMode(owner, executionMode, context, applyCurrent = false, expectedEpoch) {
+		const session = this.sessions.get(owner);
+		if (session && expectedEpoch !== void 0 && session.report.controlEpoch !== expectedEpoch) throw new PhoneError("PHONE_CONTROL_STALE", "Phone control changed; refresh before switching", 409);
+		if (applyCurrent && session?.report.task) {
+			this.guard(session, context);
+			if (session.switching) throw new PhoneError("PHONE_SESSION_BUSY", "Phone execution mode is changing", 409);
+			if (session.human || session.report.handoff !== "idle" || session.report.status === "needs_user") throw new PhoneError("PHONE_PAUSED", "Wait for explicit user handback before switching the current task", 409);
+			if (session.report.steps.at(-1)?.dispatch === "unknown" || session.report.status === "outcome_unknown") throw new PhoneError("PHONE_DISPATCH_UNKNOWN", "Inspect the previous input before switching", 409);
+			session.switching = true;
+			try {
+				await this.stop(owner, "pause");
+				if (session.report.steps.at(-1)?.dispatch === "unknown") throw new PhoneError("PHONE_DISPATCH_UNKNOWN", "Inspect the previous input before switching", 409);
+				const observation = await this.observe(session, AbortSignal.timeout(1e4));
+				try {
+					this.guard(session, context);
+					this.allowedScreen(session, observation);
+					this.recordObservation(session, observation);
+				} finally {
+					observation.frame.fill(0);
+				}
+				session.trajectory = [];
+				session.trajectorySummary = [];
+				session.frames.clear();
+				session.report.task = {
+					...session.report.task,
+					executionMode
+				};
+				session.report.executionMode = executionMode;
+				if (session.report.feedback) session.report.feedback = {
+					...session.report.feedback,
+					executionMode,
+					segmentId: randomUUID()
+				};
+				session.modeHandbackRequired = true;
+				session.report.stopReason = "mode_changed";
+				session.report.message = "Execution mode changed. Inspect and hand back control, then continue the remaining goal with the same taskId.";
+			} finally {
+				session.switching = false;
+			}
 		}
+		this.repository.setExecutionMode(owner, executionMode);
+		return session ? this.publish(session) : void 0;
+	}
+	busy(deviceId, session) {
+		const kind = session?.human ? "human" : session && [
+			"paused",
+			"needs_user",
+			"failed",
+			"outcome_unknown"
+		].includes(session.report.status) ? "inspection" : session ? "agent" : "opening";
+		return new PhoneError("PHONE_DEVICE_BUSY", kind === "human" ? "Phone is under manual control. This task did not start. Hand back control before starting another task." : kind === "inspection" ? "Phone requires inspection in the current conversation. This task did not start." : "Phone is occupied by another task or is connecting. This task did not start. View the phone or wait; do not retry automatically.", 409, {
+			executionStarted: false,
+			deviceId,
+			occupancy: {
+				kind,
+				conversationId: session?.report.owner ?? [...this.openings].find(([, controller]) => controller === this.deviceOpenings.get(deviceId))?.[0],
+				sessionId: session?.report.sessionId
+			},
+			retryPolicy: "user_initiated"
+		});
+	}
+	async finishTask(owner) {
+		const session = this.sessions.get(owner);
+		if (!session || terminal.has(session.report.status)) return this.status(owner) ?? { status: "closed" };
+		if (this.deviceOpenings.has(session.device.id)) throw this.busy(session.device.id, session);
+		if (session.human || session.report.status === "needs_user" || session.report.steps.at(-1)?.dispatch === "unknown") throw this.busy(session.device.id, session);
+		if (session.active) await this.stop(owner, "pause");
+		session.controller = new AbortController();
+		session.report.controlOwner = "none";
+		session.report.controlEpoch++;
+		if (session.report.status !== "completed") session.report.status = "ready";
+		session.report.stopReason = "task_finished";
+		session.taskPending = false;
+		session.report.goalPreview = void 0;
+		session.report.facts = void 0;
+		session.report.readings = void 0;
+		session.report.task = void 0;
+		session.report.feedback = void 0;
+		session.segmentUsage = void 0;
+		session.taskActiveMs = 0;
+		session.taskStart = void 0;
+		session.modeHandbackRequired = false;
+		session.frames.clear();
+		await session.stream?.revoke();
+		return this.publish(session);
 	}
 	async perform(session, input, context, signal) {
 		let observation;
@@ -282,6 +773,8 @@ var PhoneRuntime = class {
 		session.report.verificationLevel = "none";
 		session.report.stopReason = void 0;
 		session.report.message = void 0;
+		session.report.facts = void 0;
+		session.report.readings = void 0;
 		try {
 			await this.waitForAgent(session, signal);
 			session.report.status = "running";
@@ -298,7 +791,8 @@ var PhoneRuntime = class {
 			this.allowedScreen(session, observation);
 			if (input.op === "observe") {
 				this.recordObservation(session, observation);
-				session.report.status = "ready";
+				if (!session.report.facts?.length || input.goal) await this.readScreen(session, observation, input.goal ?? "Read the visible page text and values", context, signal);
+				if (session.report.controlOwner === "agent" && !signal.aborted) session.report.status = "ready";
 				return this.publish(session);
 			}
 			if (input.op !== "run" && input.op !== "step") throw new PhoneError("PHONE_INVALID_OPERATION", "Unsupported operation");
@@ -315,7 +809,29 @@ var PhoneRuntime = class {
 			let repairs = 0;
 			let completionCorrections = 0;
 			let recoveryHint;
+			const enhancements = {
+				semanticControls: context.config.phone.semanticControls,
+				hierarchicalPlanning: context.config.phone.hierarchicalPlanning
+			};
+			const derivedPlan = enhancements.hierarchicalPlanning ? buildPhonePlan(input.goal, completion) : void 0;
+			let planning = derivedPlan ? createPhonePlanState(derivedPlan) : void 0;
+			if (enhancements.hierarchicalPlanning) {
+				session.report.diagnostics.plannedSubgoals = planning?.steps.length ?? 0;
+				session.report.diagnostics.completedSubgoals = 0;
+			}
 			let changed = false;
+			const entryObservation = {
+				...observation,
+				frame: Buffer.alloc(0),
+				elements: structuredClone(observation.elements)
+			};
+			const trajectoryStart = session.trajectoryCount;
+			let pendingFocus;
+			let numericIntent;
+			let numericPending;
+			const focusedIntents = /* @__PURE__ */ new Set();
+			let backReplans = 0;
+			let focusReplans = 0;
 			let previousSignature = observationSignature(observation);
 			let controlEpoch = session.report.controlEpoch;
 			const attempts = /* @__PURE__ */ new Map();
@@ -331,12 +847,51 @@ var PhoneRuntime = class {
 				if (controlEpoch !== epoch) {
 					attempts.clear();
 					recoveryHint = "The user handed back control. Re-evaluate the fresh screen before continuing.";
+					pendingFocus = void 0;
+					numericIntent = void 0;
+					numericPending = void 0;
 					controlEpoch = epoch;
 				}
 				const signature = observationSignature(observation);
 				if (signature !== previousSignature) changed = true;
 				previousSignature = signature;
 				this.recordObservation(session, observation);
+				if (planning) {
+					planning = advancePhonePlan(planning, observation);
+					session.report.diagnostics.completedSubgoals = planning.verifiedSteps;
+				}
+				let numericStep;
+				if (enhancements.hierarchicalPlanning) {
+					numericIntent ??= createPhoneNumericEntry(input.goal, completion, observation);
+					if (numericIntent) {
+						let next = nextPhoneNumericEntry(numericIntent, observation, numericPending);
+						for (let poll = 0; numericPending && next.kind === "blocked" && poll < 2; poll++) {
+							await setTimeout(150, void 0, { signal });
+							observation.frame.fill(0);
+							observation = await this.observe(session, signal);
+							this.guard(session, context);
+							this.allowedScreen(session, observation);
+							if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") break;
+							next = nextPhoneNumericEntry(numericIntent, observation, numericPending);
+						}
+						if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") continue;
+						this.recordObservation(session, observation);
+						if (next.kind === "blocked") {
+							session.report.diagnostics.numericMismatches = (session.report.diagnostics.numericMismatches ?? 0) + 1;
+							session.report.status = "paused";
+							session.report.controlOwner = "none";
+							session.report.controlEpoch++;
+							session.report.stopReason = "numeric_state_mismatch";
+							session.report.message = "Numeric input was not confirmed. Inspect the displayed value before continuing; no key was retried.";
+							session.budget?.pause();
+							await session.stream?.revoke();
+							return this.publish(session);
+						}
+						if (numericPending) session.report.diagnostics.numericConfirmedSteps = (session.report.diagnostics.numericConfirmedSteps ?? 0) + 1;
+						numericPending = void 0;
+						if (next.kind === "action") numericStep = next.step;
+					}
+				}
 				if (session.report.mock ? isAboutScreen(observation) : Boolean(completion && phoneCompletionSatisfied(completion, observation, changed))) {
 					const confirmation = await this.observe(session, signal);
 					try {
@@ -350,6 +905,10 @@ var PhoneRuntime = class {
 							continue;
 						}
 						this.recordObservation(session, confirmation);
+						if (planning) {
+							planning = advancePhonePlan(planning, confirmation);
+							session.report.diagnostics.completedSubgoals = planning.verifiedSteps;
+						}
 						session.report.verified = true;
 						session.report.verificationLevel = "ui";
 						session.report.status = "completed";
@@ -359,57 +918,83 @@ var PhoneRuntime = class {
 						if (observation !== confirmation) confirmation.frame.fill(0);
 					}
 				}
+				if (session.report.actions - (session.report.humanActions ?? 0) - (session.taskStart?.actions ?? 0) >= (session.report.task?.budget?.maxActions ?? 80)) {
+					session.report.status = "ready";
+					session.report.stopReason = "task_action_limit";
+					return this.publish(session);
+				}
 				if (actions >= maxActions) {
 					session.report.status = "ready";
 					session.report.stopReason = "action_limit";
 					return this.publish(session);
 				}
-				if (session.report.modelRequests >= context.config.phone.maxModelRequests) throw new PhoneError("PHONE_MODEL_LIMIT", "Phone model request limit reached");
-				session.report.modelRequests++;
-				session.report.currentAction = void 0;
-				this.publish(session);
-				session.prediction = new AbortController();
-				let decision;
-				try {
-					decision = await session.adapter.predict({
-						goal: input.goal,
-						observation,
-						completion,
-						allowedApps: session.device.allowedApps,
-						appAccess: phoneAppAccess(session.device),
-						applications: session.applications.filter((app) => phoneAllowsApp(session.device, app.packageName)),
-						history: session.report.steps.map((step) => step.action),
-						trajectory: session.trajectory,
-						progressSummary: JSON.stringify({
-							dispatched: session.trajectoryCount,
-							earlier: [...session.trajectorySummary, ...session.trajectory.slice(0, -8).map((entry) => JSON.stringify({
-								action: entry.action,
-								effect: entry.effect,
-								afterApp: entry.afterApp
-							}).slice(0, 250))].slice(-12)
-						}).slice(-1500),
-						recoveryHint,
-						protocolFeedback,
-						scenario: input.scenario
-					}, AbortSignal.any([signal, session.prediction.signal]));
-				} catch (error) {
-					if (!signal.aborted && epoch !== session.report.controlEpoch) {
-						await this.waitForAgent(session, signal);
-						observation.frame.fill(0);
-						observation = await this.observe(session, signal);
-						continue;
-					}
-					if (!signal.aborted && error instanceof PhoneError && ["PHONE_MODEL_PROTOCOL", "PHONE_MODEL_TRUNCATED"].includes(error.code) && repairs < 1 && session.report.modelRequests < context.config.phone.maxModelRequests) {
-						repairs++;
-						session.report.diagnostics.protocolRepairs++;
-						protocolFeedback = "Your previous output was invalid or truncated. Return exactly one complete action in the specified format with no extra prose.";
-						observation.frame.fill(0);
-						observation = await this.observe(session, signal);
-						continue;
+				let decision = numericStep ? {
+					kind: "action",
+					action: numericStep.action
+				} : void 0;
+				let resumedText = false;
+				if (!decision && pendingFocus) {
+					const pending = pendingFocus;
+					pendingFocus = void 0;
+					const intended = confirmPhoneFocusRecovery(pending, observation);
+					if (intended) {
+						decision = {
+							kind: "action",
+							action: intended
+						};
+						resumedText = true;
+					} else recoveryHint = "The focus transition was not confirmed. No text was sent. Reinspect the intended editable field before another action.";
+				}
+				if (!decision) {
+					if (session.report.modelRequests >= this.modelRequestLimit(session, context)) throw new PhoneError("PHONE_MODEL_LIMIT", "Phone model request limit reached");
+					session.report.modelRequests++;
+					session.report.currentAction = void 0;
+					this.publish(session);
+					session.prediction = new AbortController();
+					try {
+						decision = await session.adapter.predict({
+							goal: input.goal,
+							task: session.report.task,
+							observation,
+							completion,
+							allowedApps: session.device.allowedApps,
+							appAccess: phoneAppAccess(session.device),
+							applications: session.applications.filter((app) => phoneAllowsApp(session.device, app.packageName)),
+							history: session.report.steps.map((step) => step.action),
+							trajectory: session.trajectory,
+							progressSummary: JSON.stringify({
+								dispatched: session.trajectoryCount,
+								earlier: [...session.trajectorySummary, ...session.trajectory.slice(0, -8).map((entry) => JSON.stringify({
+									action: entry.action,
+									effect: entry.effect,
+									afterApp: entry.afterApp
+								}).slice(0, 250))].slice(-12)
+							}).slice(-1500),
+							recoveryHint,
+							protocolFeedback,
+							scenario: input.scenario,
+							enhancements,
+							planning
+						}, AbortSignal.any([signal, session.prediction.signal]));
+					} catch (error) {
+						if (!signal.aborted && epoch !== session.report.controlEpoch) {
+							await this.waitForAgent(session, signal);
+							observation.frame.fill(0);
+							observation = await this.observe(session, signal);
+							continue;
+						}
+						if (!signal.aborted && error instanceof PhoneError && ["PHONE_MODEL_PROTOCOL", "PHONE_MODEL_TRUNCATED"].includes(error.code) && repairs < 1 && session.report.modelRequests < this.modelRequestLimit(session, context)) {
+							repairs++;
+							session.report.diagnostics.protocolRepairs++;
+							protocolFeedback = "Your previous output was invalid or truncated. Return exactly one complete action in the specified format with no extra prose.";
+							observation.frame.fill(0);
+							observation = await this.observe(session, signal);
+							continue;
+						}
+						throw error;
+					} finally {
+						session.prediction = void 0;
 					}
-					throw error;
-				} finally {
-					session.prediction = void 0;
 				}
 				signal.throwIfAborted();
 				this.guard(session, context);
@@ -420,8 +1005,13 @@ var PhoneRuntime = class {
 					continue;
 				}
 				protocolFeedback = void 0;
+				if (enhancements.hierarchicalPlanning && !planning && decision.plan) {
+					planning = advancePhonePlan(createPhonePlanState(decision.plan), observation);
+					session.report.diagnostics.plannedSubgoals = planning.steps.length;
+					session.report.diagnostics.completedSubgoals = planning.verifiedSteps;
+				}
 				if (decision.kind !== "action") {
-					if (decision.kind === "complete" && !session.report.mock && (input.completion || input.expectText) && completionCorrections < 1 && session.report.modelRequests < context.config.phone.maxModelRequests) {
+					if (decision.kind === "complete" && !session.report.mock && (input.completion || input.expectText) && completionCorrections < 1 && session.report.modelRequests < this.modelRequestLimit(session, context)) {
 						completionCorrections++;
 						session.report.diagnostics.completionCorrections++;
 						recoveryHint = `Your completion claim is not verified. These required native UI conditions are not all satisfied: ${JSON.stringify({
@@ -432,8 +1022,13 @@ var PhoneRuntime = class {
 						observation = await this.observe(session, signal);
 						continue;
 					}
-					session.report.status = decision.kind === "needsUser" ? "needs_user" : "completed";
 					session.report.message = decision.kind === "needsUser" ? decision.reason : decision.summary;
+					if (decision.kind === "complete") {
+						this.recordObservation(session, observation);
+						await this.readScreen(session, observation, input.goal, context, signal);
+						if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") return this.publish(session);
+					}
+					session.report.status = decision.kind === "needsUser" ? "needs_user" : "completed";
 					session.report.stopReason = decision.kind === "needsUser" ? "user_takeover" : "model_finished_unverified";
 					if (decision.kind === "needsUser" && !session.report.mock) {
 						session.report.controlOwner = "none";
@@ -447,10 +1042,77 @@ var PhoneRuntime = class {
 					}
 					return this.publish(session);
 				}
+				let preparedFocus;
+				if (enhancements.hierarchicalPlanning) {
+					const operationActions = session.trajectoryCount - trajectoryStart;
+					const back = phoneBackRecovery({
+						action: decision.action,
+						observation,
+						entryObservation,
+						completion,
+						trajectory: operationActions ? session.trajectory.slice(-operationActions) : []
+					});
+					if (back) {
+						session.report.diagnostics.backReplans = (session.report.diagnostics.backReplans ?? 0) + 1;
+						if (backReplans++ >= 2) {
+							session.report.status = "paused";
+							session.report.controlOwner = "none";
+							session.report.controlEpoch++;
+							session.report.stopReason = "back_boundary";
+							session.report.message = back.hint;
+							session.budget?.pause();
+							await session.stream?.revoke();
+							return this.publish(session);
+						}
+						recoveryHint = back.hint;
+						observation.frame.fill(0);
+						observation = await this.observe(session, signal);
+						continue;
+					}
+					const focusHint = phoneUnfocusedTypingHint(decision.action, observation, completion);
+					if (focusHint) {
+						const key = JSON.stringify(decision.action);
+						preparedFocus = !focusedIntents.has(key) ? preparePhoneFocusRecovery(decision.action, observation, completion) : void 0;
+						if (preparedFocus) decision = {
+							kind: "action",
+							action: preparedFocus.focusAction
+						};
+						else {
+							session.report.diagnostics.focusReplans = (session.report.diagnostics.focusReplans ?? 0) + 1;
+							if (focusReplans++ >= 2) throw new PhoneError("PHONE_INPUT_NOT_FOCUSED", "The requested editable field could not be focused; inspect before typing", 409);
+							recoveryHint = focusHint;
+							observation.frame.fill(0);
+							observation = await this.observe(session, signal);
+							continue;
+						}
+					}
+				}
 				const fresh = await this.observe(session, signal);
 				try {
 					this.allowedScreen(session, fresh);
-					if (!canDispatchPhoneAction(decision.action, observation, fresh)) {
+					if (decision.action.type !== "tapElement" && !canDispatchPhoneAction(decision.action, observation, fresh)) {
+						session.report.diagnostics.stalePredictions++;
+						recoveryHint = "The proposed action was not dispatched because its target changed. Locate it again on the fresh screen.";
+						observation.frame.fill(0);
+						observation = fresh;
+						continue;
+					}
+					let action = enhancements.semanticControls ? groundPhoneCoordinateAction(decision.action, observation) : decision.action;
+					const semanticAction = action.type === "tapElement";
+					if (action.type === "tapElement") {
+						if (!enhancements.semanticControls && !preparedFocus) throw new PhoneError("PHONE_SEMANTIC_DISABLED", "Semantic controls are disabled");
+						try {
+							action = resolvePhoneSemanticAction(action, observation, fresh);
+						} catch (error) {
+							if (!(error instanceof PhoneError) || !error.code.startsWith("PHONE_SEMANTIC_")) throw error;
+							session.report.diagnostics.semanticRejections = (session.report.diagnostics.semanticRejections ?? 0) + 1;
+							recoveryHint = "The semantic target was not dispatched: select one unique fully visible non-password control from the fresh native UI.";
+							observation.frame.fill(0);
+							observation = fresh;
+							continue;
+						}
+					}
+					if (!canDispatchPhoneAction(action, observation, fresh)) {
 						session.report.diagnostics.stalePredictions++;
 						recoveryHint = "The proposed action was not dispatched because its target changed. Locate it again on the fresh screen.";
 						observation.frame.fill(0);
@@ -458,9 +1120,9 @@ var PhoneRuntime = class {
 						continue;
 					}
 					if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") continue;
-					const attemptKey = `${observationSignature(fresh)}:${JSON.stringify(decision.action)}`;
+					const attemptKey = `${observationSignature(fresh)}:${JSON.stringify(action)}`;
 					const repetitions = attempts.get(attemptKey) ?? 0;
-					if (repetitions >= (decision.action.type === "wait" ? 3 : 2)) {
+					if (repetitions >= (action.type === "wait" ? 3 : 2)) {
 						session.report.status = "paused";
 						session.report.controlOwner = "none";
 						session.report.controlEpoch++;
@@ -471,7 +1133,20 @@ var PhoneRuntime = class {
 						return this.publish(session);
 					}
 					attempts.set(attemptKey, repetitions + 1);
-					if (await this.dispatch(session, decision.action, fresh, context, signal, epoch)) actions++;
+					if (await this.dispatch(session, action, fresh, context, signal, epoch)) {
+						actions++;
+						if (semanticAction && enhancements.semanticControls) session.report.diagnostics.semanticActions = (session.report.diagnostics.semanticActions ?? 0) + 1;
+						if (preparedFocus) {
+							pendingFocus = preparedFocus;
+							focusedIntents.add(JSON.stringify(preparedFocus.intendedAction));
+							session.report.diagnostics.focusRecoveries = (session.report.diagnostics.focusRecoveries ?? 0) + 1;
+						}
+						if (resumedText) session.report.diagnostics.resumedTextInputs = (session.report.diagnostics.resumedTextInputs ?? 0) + 1;
+						if (numericStep) {
+							numericPending = numericStep;
+							session.report.diagnostics.numericActions = (session.report.diagnostics.numericActions ?? 0) + 1;
+						}
+					}
 				} finally {
 					if (observation !== fresh) fresh.frame.fill(0);
 				}
@@ -503,7 +1178,7 @@ var PhoneRuntime = class {
 				await session.stream?.revoke();
 				return this.publish(session);
 			}
-			if (failure instanceof PhoneError && failure.code === "PHONE_OPERATION_TIMEOUT" && !terminal.has(session.report.status) && session.report.status !== "paused") {
+			if (failure instanceof PhoneError && failure.code === "PHONE_OPERATION_TIMEOUT" && !terminal.has(session.report.status) && session.report.status !== "paused" && session.report.status !== "outcome_unknown") {
 				session.report.status = "paused";
 				session.report.controlOwner = "none";
 				session.report.controlEpoch++;
@@ -562,10 +1237,67 @@ var PhoneRuntime = class {
 		}
 	}
 	recordObservation(session, observation) {
+		if (session.report.task && session.report.feedback) session.report.feedback.outputs = session.report.task.requestedOutputs.map((output) => nativePhoneOutput(output, observation));
 		session.report.foregroundApp = observation.package;
 		session.report.facts = [...new Set(observation.elements.flatMap((node) => node.password ? [] : [node.text, node.description]).filter(Boolean))].slice(0, 60);
+		session.report.readings = [{
+			source: "native_ui",
+			verification: "observed",
+			text: session.report.facts,
+			frameId: observation.frameId,
+			capturedAt: observation.capturedAt
+		}];
+	}
+	modelRequestLimit(session, context) {
+		return Math.min(context.config.phone.maxModelRequests, (session.taskStart?.modelRequests ?? 0) + (session.report.task?.budget?.maxModelRequests ?? 120));
+	}
+	async readScreen(session, observation, goal, context, signal) {
+		if (session.report.mock) return;
+		const reading = {
+			source: "screenshot",
+			verification: "unavailable",
+			text: [],
+			frameId: observation.frameId,
+			capturedAt: observation.capturedAt
+		};
+		const epoch = session.report.controlEpoch;
+		this.guard(session, context);
+		this.allowedScreen(session, observation);
+		signal.throwIfAborted();
+		if (observation.elements.some((node) => node.password)) reading.reason = "password_field_visible";
+		else if (!session.adapter.readScreen) reading.reason = "model_reading_unavailable";
+		else if (session.report.modelRequests >= this.modelRequestLimit(session, context)) reading.reason = "model_request_limit";
+		else {
+			session.report.modelRequests++;
+			session.prediction = new AbortController();
+			try {
+				const text = await session.adapter.readScreen({
+					goal,
+					observation,
+					allowedApps: session.device.allowedApps,
+					appAccess: phoneAppAccess(session.device),
+					history: []
+				}, AbortSignal.any([signal, session.prediction.signal]));
+				signal.throwIfAborted();
+				this.guard(session, context);
+				this.allowedScreen(session, observation);
+				if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") return;
+				if (text.trim()) {
+					reading.text = [text.slice(0, 1e3)];
+					reading.verification = "unverified";
+				} else reading.reason = "screen_unreadable";
+			} catch (error) {
+				signal.throwIfAborted();
+				this.guard(session, context);
+				if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") return;
+				reading.reason = error instanceof PhoneError ? error.code : "screen_reading_failed";
+			} finally {
+				session.prediction = void 0;
+			}
+		}
+		session.report.readings = [...session.report.readings ?? [], reading];
 	}
-	async dispatch(session, action, observation, context, signal, epoch = session.report.controlEpoch, resetTask = false) {
+	async dispatch(session, action, observation, context, signal, epoch = session.report.controlEpoch, resetTask = false, settingsPage) {
 		return this.io(session, async () => {
 			signal.throwIfAborted();
 			this.guard(session, context);
@@ -610,7 +1342,10 @@ var PhoneRuntime = class {
 				session.trajectorySummary = session.trajectorySummary.slice(-12);
 			}
 			try {
-				await session.driver.execute(session.device.serial, action, observation, signal, session.human ? {
+				await session.driver.execute(session.device.serial, action, observation, signal, settingsPage ? {
+					settleMs: session.human ? 0 : 350,
+					settingsPage
+				} : session.human ? {
 					settleMs: 0,
 					...resetTask ? { resetTask: true } : {}
 				} : void 0);
@@ -652,6 +1387,7 @@ var PhoneRuntime = class {
 		session.report.controlEpoch++;
 		if (op === "pause") await session.stream?.revoke();
 		else {
+			session.videoGeneration = void 0;
 			await session.stream?.close();
 			session.stream = void 0;
 		}
@@ -662,17 +1398,28 @@ var PhoneRuntime = class {
 		if (op !== "pause") {
 			session.report.facts = void 0;
 			session.report.message = void 0;
+			session.report.readings = void 0;
 			session.trajectory = [];
 			session.trajectorySummary = [];
 			session.frames.clear();
-			session.adapter = { predict: async () => {
+			if (op === "close") session.adapter = { predict: async () => {
 				throw new PhoneError("PHONE_OPEN_REQUIRED", "Reopen the phone session");
 			} };
 		}
 		this.publish(session);
 		await session.active?.catch(() => {});
 		await session.io.catch(() => {});
-		if (op !== "pause") this.repository.release(session.device.serial, session.lease);
+		if (op === "close") this.repository.release(session.device.serial, session.lease);
+		if (op === "cancel") {
+			session.controller = new AbortController();
+			session.report.status = "ready";
+			session.report.controlOwner = "none";
+			session.taskPending = false;
+			if (session.report.steps.at(-1)?.dispatch === "unknown") {
+				session.report.status = "outcome_unknown";
+				session.report.stopReason = "inspect_before_retry";
+			}
+		}
 		return this.publish(session);
 	}
 	async io(session, work) {
@@ -753,6 +1500,11 @@ var PhoneRuntime = class {
 				}
 				try {
 					this.guard(session, session.context);
+					const idleLimit = session.context.config.phone.idleDisconnectMs;
+					if (idleLimit && !session.active && !session.human && session.report.controlOwner === "none" && Date.now() - Math.max(session.viewedAt, session.report.updatedAt) >= idleLimit) {
+						this.stopDevice(session.device.id);
+						continue;
+					}
 					if (session.human && Date.now() > (session.humanExpiresAt ?? 0)) {
 						session.human = void 0;
 						session.report.controlOwner = "none";
@@ -765,7 +1517,7 @@ var PhoneRuntime = class {
 					if (Date.now() - session.viewedAt > 3e4) session.frames.clear();
 				} catch {
 					session.frames.clear();
-					this.stop(session.report.owner, "cancel");
+					this.stopDevice(session.device.id);
 				}
 			}
 		}, 3e3);
@@ -788,7 +1540,10 @@ var PhoneRuntime = class {
 	liveStatus(owner, id, context, client) {
 		const session = this.liveSession(owner, id, context);
 		return {
-			report: structuredClone(session.report),
+			report: {
+				...structuredClone(session.report),
+				nextExecutionMode: this.repository.executionMode(owner) ?? context.config.phone.executionMode
+			},
 			ownControl: Boolean(session.human === client),
 			allowedApps: [...session.device.allowedApps],
 			appAccess: phoneAppAccess(session.device),
@@ -803,7 +1558,7 @@ var PhoneRuntime = class {
 		const session = this.liveSession(owner, id, context);
 		if (terminal.has(session.report.status)) throw new PhoneError("PHONE_OPEN_REQUIRED", "Phone session ended", 409);
 		if (session.streamOpening) return session.streamOpening;
-		const opening = this.openLiveVideo(owner, session);
+		const opening = this.openLiveVideo(session);
 		session.streamOpening = opening;
 		try {
 			return await opening;
@@ -811,12 +1566,16 @@ var PhoneRuntime = class {
 			if (session.streamOpening === opening) session.streamOpening = void 0;
 		}
 	}
-	async openLiveVideo(owner, session) {
+	async openLiveVideo(session) {
 		if (!session.stream) {
 			await session.io;
 			if (terminal.has(session.report.status)) throw new PhoneError("PHONE_VIDEO_ENDED", "Phone session ended", 409);
+			const generation = Symbol();
+			session.videoGeneration = generation;
 			const failed = () => {
-				this.stop(owner, "cancel");
+				if (session.videoGeneration !== generation || ![...this.sessions.values()].includes(session)) return;
+				session.videoGeneration = void 0;
+				this.stop(session.report.owner, "pause");
 			};
 			const provider = session.device.connection ? await this.cloud.interactive(session.device, failed) : this.interactiveFactory(session.adbPath, session.device.serial, failed);
 			if (terminal.has(session.report.status)) {
@@ -912,6 +1671,8 @@ var PhoneRuntime = class {
 	}
 	async liveControl(owner, id, context, client, input) {
 		const session = this.liveSession(owner, id, context);
+		if (session.switching) throw new PhoneError("PHONE_SESSION_BUSY", "Phone execution mode is changing", 409);
+		if (this.deviceOpenings.has(session.device.id)) throw this.busy(session.device.id, session);
 		if (input.op === "heartbeat") {
 			if (terminal.has(session.report.status) || input.epoch !== session.report.controlEpoch || session.human !== client || Date.now() > (session.humanExpiresAt ?? 0)) throw new PhoneError("PHONE_CONTROL_REQUIRED", "Manual control is no longer available", 409);
 			session.humanExpiresAt = Date.now() + 15e3;
@@ -932,6 +1693,7 @@ var PhoneRuntime = class {
 		const result = session.commands.catch(() => {}).then(async () => {
 			if (terminal.has(session.report.status)) throw new PhoneError("PHONE_OPEN_REQUIRED", "Phone session ended", 409);
 			this.guard(session, context);
+			if (session.switching) throw new PhoneError("PHONE_SESSION_BUSY", "Phone execution mode is changing", 409);
 			if (input.epoch !== session.report.controlEpoch) throw new PhoneError("PHONE_CONTROL_CHANGED", "Control changed. Refresh before trying again.", 409);
 			if (session.human && session.human !== client) throw new PhoneError("PHONE_CONTROL_BUSY", "Another browser window controls this phone", 409);
 			if (input.op === "cancel") {
@@ -997,9 +1759,10 @@ var PhoneRuntime = class {
 				} finally {
 					observation?.frame.fill(0);
 				}
-				session.report.controlOwner = "agent";
+				session.report.controlOwner = session.active || session.taskPending ? "agent" : "none";
 				session.report.status = session.active ? "running" : "ready";
 				session.report.handoff = "idle";
+				session.modeHandbackRequired = false;
 				session.report.message = void 0;
 				session.report.stopReason = void 0;
 				session.budget?.resume();
@@ -1023,7 +1786,7 @@ var PhoneRuntime = class {
 				const video = input.geometry !== void 0 && session.stream?.verifyGeometry(input.geometry);
 				if (!video && (!frame || Date.now() - frame.capturedAt > 5e3)) throw new PhoneError("PHONE_FRAME_STALE", "Wait for a fresh phone image before interacting", 409);
 				if (video && input.action?.type !== "typeText" && input.action?.type !== "back") throw new PhoneError("PHONE_INVALID_INPUT", "Use the continuous input channel for video gestures", 409);
-				if (!input.action || input.action.type === "launch" || input.action.type === "home" || input.action.type === "wait") throw new PhoneError("PHONE_INVALID_INPUT", "Unsupported manual input");
+				if (!input.action || input.action.type === "launch" || input.action.type === "home" || input.action.type === "wait" || input.action.type === "tapElement") throw new PhoneError("PHONE_INVALID_INPUT", "Unsupported manual input");
 				const observation = input.action.type === "typeText" ? await this.observe(session, session.controller.signal, true) : await this.capture(session, session.controller.signal);
 				try {
 					if (input.epoch !== session.report.controlEpoch || session.human !== client || Date.now() > (session.humanExpiresAt ?? 0)) throw new PhoneError("PHONE_CONTROL_CHANGED", "Manual control expired while observing the phone", 409);
@@ -1039,7 +1802,7 @@ var PhoneRuntime = class {
 			}
 			return {
 				...this.liveStatus(owner, id, context, client),
-				resumeTurnRequired: input.op === "handback" && !session.active
+				resumeTurnRequired: input.op === "handback" && !session.active && Boolean(session.taskPending)
 			};
 		});
 		session.commands = result.catch(() => {
@@ -1058,14 +1821,19 @@ var PhoneRuntime = class {
 		return result;
 	}
 	async stopDevice(id) {
-		await Promise.all(this.reports().filter((report) => report.deviceId === id).map((report) => this.stop(report.owner, "cancel")));
+		this.deviceOpenings.get(id)?.abort();
+		await Promise.all(this.reports().filter((report) => report.deviceId === id).map((report) => this.stop(report.owner, "close")));
 		this.cloudPhones?.disconnect(id);
 	}
 	async shutdown() {
+		this.wireless.close();
+		this.reconnectAfter.clear();
+		await Promise.allSettled(this.reconnecting.values());
 		for (const controller of this.openings.values()) controller.abort();
 		await Promise.all([...this.sessions.keys()].map((owner) => this.stop(owner, "close")));
 		this.cloudPhones?.close();
 		this.sessions.clear();
+		this.lastDevices.clear();
 		if (this.maintenance) clearInterval(this.maintenance);
 		this.maintenance = void 0;
 	}