@xopcai/xopc 0.0.413 → 0.0.415

package/dist/src/phone/reliability.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+//#region src/phone/reliability.ts
+function geometryMatches(before, after) {
+	return before.package === after.package && before.width === after.width && before.height === after.height && before.rotation === after.rotation;
+}
+function ambientClock(node) {
+	const clock = /^(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d)?(?:\s?[AP]M)?$/i;
+	return node.resourceId === "com.android.systemui:id/clock" && !node.clickable && !node.editable && !node.focused && !node.password && clock.test(node.text) && (!node.description || clock.test(node.description));
+}
+function semanticElements(observation) {
+	return observation.elements.map((node) => ambientClock(node) ? {
+		...node,
+		text: "",
+		description: ""
+	} : node);
+}
+/** Ignore only recognized inert system-clock text, never arbitrary application content. */
+function observationSignature(observation) {
+	return createHash("sha256").update(JSON.stringify([
+		observation.package,
+		observation.width,
+		observation.height,
+		observation.rotation,
+		observation.elements.length ? semanticElements(observation) : createHash("sha256").update(observation.frame).digest("hex")
+	])).digest("hex");
+}
+function atPoint(elements, x, y) {
+	return elements.filter((node) => node.bounds[0] <= x && x < node.bounds[2] && node.bounds[1] <= y && y < node.bounds[3]);
+}
+/** Preserve full page semantics; only inert system-clock updates may be ignored. */
+function canDispatchPhoneAction(action, before, fresh) {
+	if (!geometryMatches(before, fresh)) return false;
+	if (JSON.stringify(before.elements) === JSON.stringify(fresh.elements)) return before.elements.length > 0 || fresh.frame.equals(before.frame);
+	if (JSON.stringify(semanticElements(before)) !== JSON.stringify(semanticElements(fresh))) return false;
+	if (action.type === "tap" || action.type === "doubleTap" || action.type === "longPress") {
+		const [x, y] = [action.point[0] * before.width / 1e3, action.point[1] * before.height / 1e3];
+		const targets = atPoint(before.elements, x, y);
+		const identified = targets.filter((node) => node.resourceId && node.clickable && !node.password);
+		if (identified.length !== 1) return false;
+		const target = identified[0];
+		if (before.elements.filter((node) => node.resourceId === target.resourceId).length !== 1 || fresh.elements.filter((node) => node.resourceId === target.resourceId).length !== 1) return false;
+		return JSON.stringify(targets) === JSON.stringify(atPoint(fresh.elements, x, y));
+	}
+	if (action.type === "typeText") {
+		const focused = (screen) => screen.elements.filter((node) => node.focused && node.editable && !node.password);
+		const previous = focused(before);
+		const current = focused(fresh);
+		return previous.length === 1 && current.length === 1 && Boolean(previous[0].resourceId) && JSON.stringify(previous) === JSON.stringify(current);
+	}
+	return false;
+}
+/** Evaluate all native nodes, separately from the truncated display facts. */
+function phoneCompletionSatisfied(condition, observation, changed) {
+	if (condition.requireChange && !changed) return false;
+	if (condition.appPackage && condition.appPackage !== observation.package) return false;
+	const texts = observation.elements.filter((node) => !node.password).flatMap((node) => [node.text, node.description]).filter(Boolean);
+	if (condition.textAny && !condition.textAny.some((value) => texts.some((text) => text.includes(value)))) return false;
+	if (condition.textAll && !condition.textAll.every((value) => texts.some((text) => text.includes(value)))) return false;
+	if (condition.field) {
+		const fields = observation.elements.filter((node) => !node.password && node.editable && node.resourceId === condition.field.resourceId);
+		if (fields.length !== 1 || fields[0].text !== condition.field.value) return false;
+	}
+	return true;
+}
+//#endregion
+export { canDispatchPhoneAction, observationSignature, phoneCompletionSatisfied };

package/dist/src/phone/repository.js

@@ -1,11 +1,12 @@
 import { PhoneDeviceSchema, PhoneError, init_contracts } from "./contracts.js";
+import { normalizePhoneAppAccess } from "./app-access.js";
 import { DurableState } from "../storage/sqlite/durable-state.js";
 import { randomUUID } from "node:crypto";
 //#region src/phone/repository.ts
 init_contracts();
 function parseDevice(value) {
 	const { agentIds: _removed, ...device } = value;
-	return PhoneDeviceSchema.parse(device);
+	return normalizePhoneAppAccess(PhoneDeviceSchema.parse(device));
 }
 /** Small settings and latest metadata-only reports; pixels and input text are never stored. */
 var PhoneRepository = class {
@@ -24,12 +25,12 @@ var PhoneRepository = class {
 	save(input, id) {
 		const previous = id ? this.get(id) : void 0;
 		if (this.list().some((device) => device.serial === input.serial && device.id !== id)) throw new PhoneError("PHONE_DEVICE_DUPLICATE", "This ADB device is already registered");
-		const next = PhoneDeviceSchema.parse({
+		const next = normalizePhoneAppAccess(PhoneDeviceSchema.parse({
 			...input,
 			id: id ?? randomUUID(),
 			createdAt: previous?.createdAt ?? Date.now(),
 			revision: (previous?.revision ?? 0) + 1
-		});
+		}));
 		this.devices.set(next.id, next);
 		return next;
 	}

package/dist/src/phone/runtime.d.ts

@@ -5,7 +5,7 @@ import { CloudPhones } from './cloud-phones.js';
 import { type PhoneDriver } from './adb-driver.js';
 import { createPhoneModel } from './model-adapter.js';
 import { PhoneRepository } from './repository.js';
-import { type PhoneAction, type PhoneDevice, type PhoneInput, type PhoneObservation, type PhoneReport } from './contracts.js';
+import { type PhoneAction, type PhoneDevice, type PhoneInput, type PhoneApplication, type PhoneObservation, type PhoneReport } from './contracts.js';
 type ExecutionContext = {
     config: Config;
     agentId: string;
@@ -26,6 +26,17 @@ export declare class PhoneRuntime {
     constructor(repository?: PhoneRepository, driverFactory?: (path: string) => PhoneDriver, modelFactory?: typeof createPhoneModel, interactiveFactory?: (adb: string, serial: string, failed: () => void) => PhoneInteractiveProvider);
     driverFor(device: PhoneDevice, config: Config): Promise<PhoneDriver>;
     discover(config: Config, signal?: AbortSignal): Promise<import("./contracts.js").DiscoveredPhone[]>;
+    applications(input: {
+        deviceId?: string;
+        serial?: string;
+    }, config: Config, signal: AbortSignal): Promise<PhoneApplication[]>;
+    textInputStatus(id: string, config: Config, signal: AbortSignal): Promise<{
+        policy: "manual" | "auto";
+        androidSdk: number;
+        unicode: "available" | "setup_required" | "unsupported";
+        method: "scrcpy-clipboard" | "provider-native";
+        keyboardRequired: false;
+    }>;
     preview(id: string, config: Config, signal: AbortSignal): Promise<PhoneObservation>;
     previewSession(owner: string, context: ExecutionContext, signal: AbortSignal): Promise<PhoneObservation>;
     reports(): PhoneReport[];
@@ -50,6 +61,8 @@ export declare class PhoneRuntime {
         report: PhoneReport;
         ownControl: boolean;
         allowedApps: string[];
+        appAccess: "all" | "selected";
+        textInput: "manual" | "auto";
         frame: {
             seq: number;
             capturedAt: number;

package/dist/src/phone/runtime.js

@@ -2,6 +2,7 @@ import { createLogger } from "../utils/logger/index.js";
 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 { PhoneFrameCache, PhoneOperationBudget } from "./live-state.js";
 import { PhoneInteractiveSession } from "./interactive-session.js";
 import { AdbPhoneDriver, resolveAdbPath } from "./adb-driver.js";
@@ -9,6 +10,7 @@ import { LocalScrcpyProvider } from "./scrcpy.js";
 import { CloudPhones } from "./cloud-phones.js";
 import { createPhoneModel, isAboutScreen } from "./model-adapter.js";
 import { PhoneRepository } from "./repository.js";
+import { canDispatchPhoneAction, observationSignature, phoneCompletionSatisfied } from "./reliability.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/phone/runtime.ts
 init_logger();
@@ -40,13 +42,40 @@ var PhoneRuntime = class {
 	async discover(config, signal) {
 		return this.driverFactory(resolveAdbPath(config.phone.adbPath)).discover(signal);
 	}
+	async applications(input, config, signal) {
+		let driver;
+		let serial;
+		if (input.deviceId) {
+			const device = this.repository.get(input.deviceId);
+			if (!device.enabled) throw new PhoneError("PHONE_DEVICE_DENIED", "Phone access is disabled", 403);
+			driver = await this.driverFor(device, config);
+			serial = device.serial;
+		} else {
+			const found = (await this.discover(config, signal)).find((device) => device.serial === input.serial && device.state === "device");
+			if (!found) throw new PhoneError("PHONE_DEVICE_OFFLINE", "Choose a connected and authorized phone");
+			driver = this.driverFactory(resolveAdbPath(config.phone.adbPath));
+			serial = found.serial;
+		}
+		if (!driver.applications) throw new PhoneError("PHONE_APPS_UNAVAILABLE", "The phone provider cannot list applications");
+		return driver.applications(serial, signal);
+	}
+	async textInputStatus(id, config, signal) {
+		const device = this.repository.get(id);
+		if (!device.enabled) throw new PhoneError("PHONE_DEVICE_DENIED", "Phone access is disabled", 403);
+		const driver = await this.driverFor(device, config);
+		if (!driver.textInputStatus) throw new PhoneError("PHONE_TEXT_INPUT_UNAVAILABLE", "This phone provider does not expose text input diagnostics", 409);
+		return {
+			...await driver.textInputStatus(device.serial, signal),
+			policy: device.textInput ?? "auto"
+		};
+	}
 	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 lease = this.repository.acquire(device.serial);
 		try {
 			const observation = await (await this.driverFor(device, config)).observe(device.serial, signal);
-			if (!device.allowedApps.includes(observation.package)) {
+			if (!phoneAllowsApp(device, observation.package)) {
 				observation.frame.fill(0);
 				throw new PhoneError("PHONE_APP_DENIED", "Open an allowed app before previewing the screen");
 			}
@@ -91,7 +120,7 @@ var PhoneRuntime = class {
 		this.repository.renew(session.device.serial, session.lease);
 	}
 	allowedScreen(session, observation) {
-		if (!session.device.allowedApps.includes(observation.package)) throw new PhoneError("PHONE_APP_DENIED", "The foreground application is outside this phone session allowlist. Open an allowed app or reopen with appPackage.");
+		if (!phoneAllowsApp(session.device, observation.package)) throw new PhoneError("PHONE_APP_DENIED", "The foreground application is outside this phone session allowlist. Open an allowed app or reopen with appPackage.");
 	}
 	async execute(owner, raw, context, signal = new AbortController().signal) {
 		const input = PhoneInputSchema.parse(raw);
@@ -132,6 +161,12 @@ var PhoneRuntime = class {
 				try {
 					const adapter = await this.modelFactory(modelRef, context.config, context.agentId);
 					signal.throwIfAborted();
+					let applications = [];
+					if (input.mode === "control" && modelRef !== "phone-mock/settings-about" && driver.applications) try {
+						applications = await driver.applications(device.serial, signal);
+					} catch {
+						signal.throwIfAborted();
+					}
 					const now = Date.now();
 					const session = {
 						device,
@@ -143,6 +178,10 @@ var PhoneRuntime = class {
 						modelRef,
 						adbPath,
 						context,
+						applications,
+						trajectory: [],
+						trajectoryCount: 0,
+						trajectorySummary: [],
 						frames: new PhoneFrameCache(),
 						io: Promise.resolve(),
 						ioBusy: false,
@@ -169,12 +208,18 @@ var PhoneRuntime = class {
 							updatedAt: now,
 							verified: false,
 							verificationLevel: "none",
-							steps: []
+							steps: [],
+							diagnostics: {
+								stalePredictions: 0,
+								protocolRepairs: 0,
+								unchangedActions: 0,
+								completionCorrections: 0
+							}
 						}
 					};
 					this.sessions.set(owner, session);
 					if (input.appPackage) {
-						if (input.mode !== "control" || !device.allowedApps.includes(input.appPackage)) throw new PhoneError("PHONE_APP_DENIED", "Launching requires control mode and an allowed application");
+						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;
 						const observation = await this.observe(session, signal);
 						try {
@@ -234,6 +279,9 @@ var PhoneRuntime = class {
 		const startedAt = Date.now();
 		session.report.errorCode = void 0;
 		session.report.verified = false;
+		session.report.verificationLevel = "none";
+		session.report.stopReason = void 0;
+		session.report.message = void 0;
 		try {
 			await this.waitForAgent(session, signal);
 			session.report.status = "running";
@@ -257,7 +305,20 @@ var PhoneRuntime = class {
 			if (session.report.mode !== "control") throw new PhoneError("PHONE_OBSERVE_ONLY", "Reopen the phone in control mode to execute actions");
 			if (session.report.mock && input.scenario !== "settings-about") throw new PhoneError("PHONE_MOCK_SCENARIO_REQUIRED", "Mock mode only supports the explicit settings-about scenario");
 			const maxActions = input.op === "step" ? 1 : input.maxActions;
+			const requiredTexts = [...input.completion?.textAll ?? [], ...input.expectText ? [input.expectText] : []];
+			const completion = input.completion || input.expectText ? {
+				...input.completion,
+				textAll: requiredTexts.length ? requiredTexts : void 0
+			} : void 0;
 			let actions = 0;
+			let protocolFeedback;
+			let repairs = 0;
+			let completionCorrections = 0;
+			let recoveryHint;
+			let changed = false;
+			let previousSignature = observationSignature(observation);
+			let controlEpoch = session.report.controlEpoch;
+			const attempts = /* @__PURE__ */ new Map();
 			while (true) {
 				if (await this.waitForAgent(session, signal)) {
 					observation.frame.fill(0);
@@ -267,13 +328,36 @@ var PhoneRuntime = class {
 				this.guard(session, context);
 				this.allowedScreen(session, observation);
 				const epoch = session.report.controlEpoch;
+				if (controlEpoch !== epoch) {
+					attempts.clear();
+					recoveryHint = "The user handed back control. Re-evaluate the fresh screen before continuing.";
+					controlEpoch = epoch;
+				}
+				const signature = observationSignature(observation);
+				if (signature !== previousSignature) changed = true;
+				previousSignature = signature;
 				this.recordObservation(session, observation);
-				if (session.report.mock ? isAboutScreen(observation) : Boolean(input.expectText && session.report.facts?.some((text) => text.includes(input.expectText)))) {
-					session.report.verified = true;
-					session.report.verificationLevel = "ui";
-					session.report.status = "completed";
-					session.report.stopReason = actions ? "condition_satisfied" : "condition_present";
-					return this.publish(session);
+				if (session.report.mock ? isAboutScreen(observation) : Boolean(completion && phoneCompletionSatisfied(completion, observation, changed))) {
+					const confirmation = await this.observe(session, signal);
+					try {
+						signal.throwIfAborted();
+						this.guard(session, context);
+						this.allowedScreen(session, confirmation);
+						const confirmed = session.report.mock ? isAboutScreen(confirmation) : Boolean(completion && phoneCompletionSatisfied(completion, confirmation, changed));
+						if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent" || !confirmed) {
+							observation.frame.fill(0);
+							observation = confirmation;
+							continue;
+						}
+						this.recordObservation(session, confirmation);
+						session.report.verified = true;
+						session.report.verificationLevel = "ui";
+						session.report.status = "completed";
+						session.report.stopReason = actions ? "condition_satisfied" : "condition_present";
+						return this.publish(session);
+					} finally {
+						if (observation !== confirmation) confirmation.frame.fill(0);
+					}
 				}
 				if (actions >= maxActions) {
 					session.report.status = "ready";
@@ -290,8 +374,22 @@ var PhoneRuntime = class {
 					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) {
@@ -301,6 +399,14 @@ var PhoneRuntime = class {
 						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;
+					}
 					throw error;
 				} finally {
 					session.prediction = void 0;
@@ -313,9 +419,21 @@ var PhoneRuntime = class {
 					observation = await this.observe(session, signal);
 					continue;
 				}
+				protocolFeedback = void 0;
 				if (decision.kind !== "action") {
+					if (decision.kind === "complete" && !session.report.mock && (input.completion || input.expectText) && completionCorrections < 1 && session.report.modelRequests < context.config.phone.maxModelRequests) {
+						completionCorrections++;
+						session.report.diagnostics.completionCorrections++;
+						recoveryHint = `Your completion claim is not verified. These required native UI conditions are not all satisfied: ${JSON.stringify({
+							expectText: input.expectText,
+							...input.completion
+						})}. Recheck the fresh screen, preserve user constraints, and continue if a safe authorized action can satisfy the goal; otherwise report unfinished.`;
+						observation.frame.fill(0);
+						observation = await this.observe(session, signal);
+						continue;
+					}
 					session.report.status = decision.kind === "needsUser" ? "needs_user" : "completed";
-					session.report.message = decision.kind === "needsUser" ? decision.reason : void 0;
+					session.report.message = decision.kind === "needsUser" ? decision.reason : decision.summary;
 					session.report.stopReason = decision.kind === "needsUser" ? "user_takeover" : "model_finished_unverified";
 					if (decision.kind === "needsUser" && !session.report.mock) {
 						session.report.controlOwner = "none";
@@ -332,21 +450,59 @@ var PhoneRuntime = class {
 				const fresh = await this.observe(session, signal);
 				try {
 					this.allowedScreen(session, fresh);
-					if (fresh.package !== observation.package || fresh.width !== observation.width || fresh.height !== observation.height || fresh.rotation !== observation.rotation || JSON.stringify(fresh.elements) !== JSON.stringify(observation.elements) || !fresh.elements.length && !fresh.frame.equals(observation.frame)) {
+					if (!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;
 					}
 					if (epoch !== session.report.controlEpoch || session.report.controlOwner !== "agent") continue;
+					const attemptKey = `${observationSignature(fresh)}:${JSON.stringify(decision.action)}`;
+					const repetitions = attempts.get(attemptKey) ?? 0;
+					if (repetitions >= (decision.action.type === "wait" ? 3 : 2)) {
+						session.report.status = "paused";
+						session.report.controlOwner = "none";
+						session.report.controlEpoch++;
+						session.report.stopReason = "no_progress";
+						session.report.message = "Repeated actions made no progress. Inspect the phone and hand back before continuing.";
+						session.budget?.pause();
+						await session.stream?.revoke();
+						return this.publish(session);
+					}
+					attempts.set(attemptKey, repetitions + 1);
 					if (await this.dispatch(session, decision.action, fresh, context, signal, epoch)) actions++;
 				} finally {
 					if (observation !== fresh) fresh.frame.fill(0);
 				}
+				const beforeSignature = observationSignature(observation);
 				observation.frame.fill(0);
 				observation = await this.observe(session, signal);
+				const entry = session.trajectory.at(-1);
+				if (entry && entry.actor === "agent" && epoch === session.report.controlEpoch) {
+					const unchanged = beforeSignature === observationSignature(observation);
+					entry.afterApp = observation.package;
+					entry.effect = unchanged ? "unchanged" : "changed";
+					entry.facts = observation.elements.filter((node) => !node.password).flatMap((node) => [node.text, node.description]).filter(Boolean).slice(0, 12).map((text) => text.slice(0, 160));
+					if (unchanged) session.report.diagnostics.unchangedActions++;
+					recoveryHint = unchanged ? "The last dispatched action produced no observable change. Wait if loading, otherwise try a different target or route; do not repeat an uncertain input." : void 0;
+				}
 			}
 		} catch (error) {
 			const failure = signal.aborted && signal.reason instanceof PhoneError ? signal.reason : error;
+			if (!signal.aborted && failure instanceof PhoneError && ["PHONE_TEXT_INPUT_UNAVAILABLE", "PHONE_TEXT_INPUT_UNCONFIRMED"].includes(failure.code)) {
+				session.report.status = "needs_user";
+				session.human = void 0;
+				session.report.controlOwner = "none";
+				session.report.controlEpoch++;
+				session.report.errorCode = failure.code;
+				session.report.message = failure.message;
+				session.report.currentAction = void 0;
+				session.report.stopReason = failure.code === "PHONE_TEXT_INPUT_UNAVAILABLE" ? "text_input_required" : "text_input_unconfirmed";
+				session.budget?.pause();
+				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") {
 				session.report.status = "paused";
 				session.report.controlOwner = "none";
@@ -400,7 +556,8 @@ var PhoneRuntime = class {
 				status: session.report.status,
 				stopReason: session.report.stopReason,
 				actions: session.report.actions,
-				modelRequests: session.report.modelRequests
+				modelRequests: session.report.modelRequests,
+				diagnostics: session.report.diagnostics
 			}, "Phone goal finished");
 		}
 	}
@@ -416,8 +573,9 @@ var PhoneRuntime = class {
 			if (session.human && Date.now() > (session.humanExpiresAt ?? 0)) throw new PhoneError("PHONE_CONTROL_REQUIRED", "Manual control expired", 409);
 			if (!session.human && session.report.actions - (session.report.humanActions ?? 0) >= context.config.phone.maxActionsPerSession) throw new PhoneError("PHONE_ACTION_LIMIT", "Phone action limit reached");
 			if (session.human && (session.report.humanActions ?? 0) >= 1200) throw new PhoneError("PHONE_ACTION_LIMIT", "Manual input limit reached; reopen the session");
-			if (action.type === "launch" && !session.device.allowedApps.includes(action.package)) throw new PhoneError("PHONE_APP_DENIED", "Application is not authorized");
-			if (action.type === "home") throw new PhoneError("PHONE_APP_DENIED", "Home leaves the app allowlist");
+			if (action.type === "launch" && !phoneAllowsApp(session.device, action.package)) throw new PhoneError("PHONE_APP_DENIED", "Application is not authorized");
+			if (action.type === "home" && phoneAppAccess(session.device) !== "all") throw new PhoneError("PHONE_APP_DENIED", "Home leaves the app allowlist");
+			if (action.type === "typeText" && session.device.textInput === "manual") throw new PhoneError("PHONE_TEXT_INPUT_UNAVAILABLE", "Automatic text input is disabled for this phone. Ask the user to take over and type with the phone keyboard.", 409);
 			if (action.type === "typeText" && !observation.elements.some((node) => node.focused && node.editable && !node.password)) throw new PhoneError("PHONE_INPUT_NOT_FOCUSED", "Focus a non-password editable field before typing", 409);
 			const step = {
 				action: action.type,
@@ -433,14 +591,48 @@ var PhoneRuntime = class {
 				session.report.steps = session.report.steps.slice(-200);
 			}
 			this.publish(session);
+			const entry = {
+				action: structuredClone(action),
+				dispatch: "unknown",
+				actor: step.actor,
+				beforeApp: observation.package,
+				effect: "unknown"
+			};
+			session.trajectory.push(entry);
+			session.trajectoryCount++;
+			if (session.trajectory.length > 24) {
+				const earlier = session.trajectory.shift();
+				session.trajectorySummary.push(JSON.stringify({
+					action: earlier.action,
+					effect: earlier.effect,
+					afterApp: earlier.afterApp
+				}).slice(0, 250));
+				session.trajectorySummary = session.trajectorySummary.slice(-12);
+			}
 			try {
 				await session.driver.execute(session.device.serial, action, observation, signal, session.human ? {
 					settleMs: 0,
 					...resetTask ? { resetTask: true } : {}
 				} : void 0);
 				step.dispatch = "completed";
+				entry.dispatch = "completed";
 			} catch (error) {
-				session.report.status = "outcome_unknown";
+				const textFailure = error instanceof PhoneError && ["PHONE_TEXT_INPUT_UNAVAILABLE", "PHONE_TEXT_INPUT_UNCONFIRMED"].includes(error.code);
+				if (textFailure && error.code === "PHONE_TEXT_INPUT_UNAVAILABLE") {
+					session.report.steps.pop();
+					session.report.actions--;
+					session.trajectory.pop();
+					session.trajectoryCount--;
+					if (session.human) session.report.humanActions--;
+				} else session.report.status = "outcome_unknown";
+				if (textFailure && session.human) {
+					session.report.status = "paused";
+					session.report.errorCode = error.code;
+					session.report.message = error.message;
+					session.report.stopReason = error.code === "PHONE_TEXT_INPUT_UNAVAILABLE" ? "text_input_required" : "text_input_unconfirmed";
+					session.report.currentAction = void 0;
+					this.publish(session);
+				}
 				session.frames.clear();
 				throw error;
 			}
@@ -470,6 +662,8 @@ var PhoneRuntime = class {
 		if (op !== "pause") {
 			session.report.facts = void 0;
 			session.report.message = void 0;
+			session.trajectory = [];
+			session.trajectorySummary = [];
 			session.frames.clear();
 			session.adapter = { predict: async () => {
 				throw new PhoneError("PHONE_OPEN_REQUIRED", "Reopen the phone session");
@@ -497,7 +691,7 @@ var PhoneRuntime = class {
 		return this.io(session, async () => {
 			signal.throwIfAborted();
 			const observation = await (forText && session.driver.observeForText ? session.driver.observeForText : session.driver.observe).call(session.driver, session.device.serial, signal);
-			if (session.device.allowedApps.includes(observation.package)) {
+			if (phoneAllowsApp(session.device, observation.package)) {
 				if (Date.now() - session.viewedAt < 3e4 && !terminal.has(session.report.status)) session.frames.set(observation);
 			} else session.frames.clear();
 			return observation;
@@ -597,6 +791,8 @@ var PhoneRuntime = class {
 			report: structuredClone(session.report),
 			ownControl: Boolean(session.human === client),
 			allowedApps: [...session.device.allowedApps],
+			appAccess: phoneAppAccess(session.device),
+			textInput: session.device.textInput ?? "auto",
 			frame: session.frames.get() ? {
 				seq: session.frames.get().seq,
 				capturedAt: session.frames.get().capturedAt
@@ -631,7 +827,7 @@ var PhoneRuntime = class {
 				if (terminal.has(session.report.status)) throw new PhoneError("PHONE_VIDEO_ENDED", "Phone session ended", 409);
 				this.guard(session, session.context);
 				const app = await provider.foreground(AbortSignal.timeout(2e3));
-				if (!session.device.allowedApps.includes(app)) throw new PhoneError("PHONE_APP_DENIED", "Current page is outside the authorized applications", 403);
+				if (!phoneAllowsApp(session.device, app)) throw new PhoneError("PHONE_APP_DENIED", "Current page is outside the authorized applications", 403);
 				session.viewedAt = Date.now();
 			}, (client, epoch) => {
 				if (terminal.has(session.report.status) || session.report.handoff !== "idle" || session.report.controlOwner !== "human" || session.human !== client || session.report.controlEpoch !== epoch || Date.now() > (session.humanExpiresAt ?? 0)) throw new PhoneError("PHONE_CONTROL_CHANGED", "Manual control is no longer available", 409);
@@ -811,7 +1007,7 @@ var PhoneRuntime = class {
 				for (const wake of session.wake) wake();
 			} else if (input.op === "recover") {
 				if (session.human !== client || Date.now() > (session.humanExpiresAt ?? 0)) throw new PhoneError("PHONE_CONTROL_REQUIRED", "Take over the phone first", 409);
-				if (input.action?.type !== "launch" || !session.device.allowedApps.includes(input.action.package)) throw new PhoneError("PHONE_APP_DENIED", "Choose an authorized recovery application", 403);
+				if (input.action?.type !== "launch" || !phoneAllowsApp(session.device, input.action.package)) throw new PhoneError("PHONE_APP_DENIED", "Choose an authorized recovery application", 403);
 				const observation = await this.io(session, () => session.driver.capture ? session.driver.capture(session.device.serial, session.controller.signal) : session.driver.observe(session.device.serial, session.controller.signal));
 				try {
 					if (!await this.dispatch(session, input.action, observation, context, session.controller.signal, input.epoch, true)) throw new PhoneError("PHONE_CONTROL_CHANGED", "Control changed before recovery", 409);

package/dist/src/phone/scrcpy-assets.d.ts

@@ -0,0 +1,4 @@
+import { SCRCPY_SHA256, SCRCPY_VERSION } from '../runtime-tools/phone-dependency-catalog.js';
+export { SCRCPY_SHA256, SCRCPY_VERSION };
+export declare const scrcpyServerPath: (stateDir?: string) => string;
+export declare function readScrcpyServer(): Promise<Buffer>;

package/dist/src/phone/scrcpy-assets.js

@@ -0,0 +1,16 @@
+import { PhoneError, init_contracts } from "./contracts.js";
+import { SCRCPY_SHA256, SCRCPY_VERSION, managedScrcpyServerPath } from "../runtime-tools/phone-dependency-catalog.js";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+//#region src/phone/scrcpy-assets.ts
+init_contracts();
+const scrcpyServerPath = managedScrcpyServerPath;
+async function readScrcpyServer() {
+	const binary = await readFile(scrcpyServerPath()).catch(() => {
+		throw new PhoneError("PHONE_VIDEO_SETUP_REQUIRED", "Install scrcpy server in Settings → Phone Use → Dependencies");
+	});
+	if (createHash("sha256").update(binary).digest("hex") !== "7e70323ba7f259649dd4acce97ac4fefbae8102b2c6d91e2e7be613fd5354be0") throw new PhoneError("PHONE_VIDEO_HASH_MISMATCH", "Phone video server checksum mismatch");
+	return binary;
+}
+//#endregion
+export { SCRCPY_SHA256, SCRCPY_VERSION, readScrcpyServer, scrcpyServerPath };

package/dist/src/phone/scrcpy-text.d.ts

@@ -0,0 +1,11 @@
+/** Only supplied text is sent to Android; clipboard autosync and reads stay off. */
+export declare class ScrcpyTextChannel {
+    private write;
+    private buffer;
+    private sequence;
+    private pending;
+    constructor(write: (bytes: Buffer) => Promise<void>);
+    receive(bytes: Buffer): void;
+    paste(text: string, signal: AbortSignal): Promise<void>;
+    close(): void;
+}

package/dist/src/phone/scrcpy-text.js

@@ -0,0 +1,72 @@
+import { PhoneError, init_contracts } from "./contracts.js";
+//#region src/phone/scrcpy-text.ts
+init_contracts();
+/** Only supplied text is sent to Android; clipboard autosync and reads stay off. */
+var ScrcpyTextChannel = class {
+	buffer = Buffer.alloc(0);
+	sequence = 0n;
+	pending = /* @__PURE__ */ new Map();
+	constructor(write) {
+		this.write = write;
+	}
+	receive(bytes) {
+		this.buffer = Buffer.concat([this.buffer, bytes]);
+		while (this.buffer.length) {
+			const type = this.buffer[0];
+			let length;
+			if (type === 1) {
+				if (this.buffer.length < 9) return;
+				const seq = this.buffer.readBigUInt64BE(1);
+				this.pending.get(seq)?.resolve();
+				this.pending.delete(seq);
+				length = 9;
+			} else if (type === 0 || type === 2) {
+				if (this.buffer.length < 5) return;
+				length = 5 + (type === 0 ? this.buffer.readUInt32BE(1) : this.buffer.readUInt16BE(3));
+				if (length > 262144) throw new Error("Invalid device message");
+				if (this.buffer.length < length) return;
+			} else throw new Error("Unknown device message");
+			this.buffer = this.buffer.subarray(length);
+		}
+	}
+	async paste(text, signal) {
+		signal.throwIfAborted();
+		if (!text || text.length > 4e3 || this.pending.size) throw new PhoneError("PHONE_INVALID_INPUT", "Invalid or concurrent phone text input");
+		const sequence = ++this.sequence;
+		const payload = Buffer.from(text);
+		const bytes = Buffer.alloc(14 + payload.length);
+		bytes[0] = 9;
+		bytes.writeBigUInt64BE(sequence, 1);
+		bytes[9] = 1;
+		bytes.writeUInt32BE(payload.length, 10);
+		payload.copy(bytes, 14);
+		payload.fill(0);
+		const deadline = AbortSignal.any([signal, AbortSignal.timeout(1e4)]);
+		let abort;
+		const ack = new Promise((resolve, reject) => {
+			abort = () => reject(new PhoneError("PHONE_TEXT_INPUT_UNCONFIRMED", "Text may have been pasted. Take over and inspect the input field before retrying.", 409));
+			this.pending.set(sequence, {
+				resolve,
+				reject
+			});
+			deadline.addEventListener("abort", abort, { once: true });
+		});
+		try {
+			await Promise.all([this.write(bytes), ack]);
+		} catch {
+			throw new PhoneError("PHONE_TEXT_INPUT_UNCONFIRMED", "Text may have been pasted. Take over and inspect the input field before retrying.", 409);
+		} finally {
+			bytes.fill(0);
+			deadline.removeEventListener("abort", abort);
+			this.pending.delete(sequence);
+		}
+	}
+	close() {
+		for (const request of this.pending.values()) request.reject(new PhoneError("PHONE_TEXT_INPUT_UNCONFIRMED", "Phone text channel disconnected; inspect the field before retrying.", 409));
+		this.pending.clear();
+		this.buffer.fill(0);
+		this.buffer = Buffer.alloc(0);
+	}
+};
+//#endregion
+export { ScrcpyTextChannel };