@xopcai/xopc 0.0.414 → 0.0.415

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

@@ -0,0 +1,7 @@
+import type { PhoneAction, PhoneCompletion, PhoneObservation } from './contracts.js';
+/** Ignore only recognized inert system-clock text, never arbitrary application content. */
+export declare function observationSignature(observation: PhoneObservation): string;
+/** Preserve full page semantics; only inert system-clock updates may be ignored. */
+export declare function canDispatchPhoneAction(action: PhoneAction, before: PhoneObservation, fresh: PhoneObservation): boolean;
+/** Evaluate all native nodes, separately from the truncated display facts. */
+export declare function phoneCompletionSatisfied(condition: PhoneCompletion, observation: PhoneObservation, changed: boolean): boolean;

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/runtime.d.ts

@@ -30,6 +30,13 @@ export declare class PhoneRuntime {
         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[];
@@ -55,6 +62,7 @@ export declare class PhoneRuntime {
         ownControl: boolean;
         allowedApps: string[];
         appAccess: "all" | "selected";
+        textInput: "manual" | "auto";
         frame: {
             seq: number;
             capturedAt: number;

package/dist/src/phone/runtime.js

@@ -10,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();
@@ -58,6 +59,16 @@ var PhoneRuntime = class {
 		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);
@@ -168,6 +179,9 @@ var PhoneRuntime = class {
 						adbPath,
 						context,
 						applications,
+						trajectory: [],
+						trajectoryCount: 0,
+						trajectorySummary: [],
 						frames: new PhoneFrameCache(),
 						io: Promise.resolve(),
 						ioBusy: false,
@@ -194,7 +208,13 @@ 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);
@@ -259,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";
@@ -282,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);
@@ -292,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";
@@ -315,10 +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) {
@@ -328,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;
@@ -340,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";
@@ -359,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";
@@ -427,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");
 		}
 	}
@@ -445,6 +575,7 @@ var PhoneRuntime = class {
 			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" && !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,
@@ -460,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;
 			}
@@ -497,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");
@@ -625,6 +792,7 @@ var PhoneRuntime = class {
 			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

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 };

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

@@ -1,3 +1,4 @@
+import { ScrcpyTextChannel } from './scrcpy-text.js';
 import type { PhoneInteractiveProvider, PhonePointer, PhoneVideoGeometry, PhoneVideoPacket } from './live-provider.js';
 export { readScrcpyServer, scrcpyServerPath, SCRCPY_VERSION, SCRCPY_SHA256 } from './scrcpy-assets.js';
 /** The pinned server sends codec metadata followed by bounded, length-prefixed packets. */
@@ -18,6 +19,7 @@ export declare abstract class ScrcpyProvider implements PhoneInteractiveProvider
     };
     geometry: PhoneVideoGeometry;
     protected closing: boolean;
+    protected textChannel: ScrcpyTextChannel;
     private touch?;
     private listeners;
     private config?;
@@ -29,6 +31,7 @@ export declare abstract class ScrcpyProvider implements PhoneInteractiveProvider
     protected abstract startTransport(): Promise<void>;
     protected abstract write(buffer: Buffer): Promise<void>;
     protected abstract cleanup(): Promise<void>;
+    pasteText(text: string, signal: AbortSignal): Promise<void>;
     start(): Promise<void>;
     protected packet(packet: PhoneVideoPacket): void;
     subscribe(listener: (packet: PhoneVideoPacket) => void): () => void;
@@ -42,6 +45,7 @@ export declare class LocalScrcpyProvider extends ScrcpyProvider {
     private adb;
     private serial;
     private tuning;
+    private textOnly;
     private process?;
     private video?;
     private control?;
@@ -51,7 +55,7 @@ export declare class LocalScrcpyProvider extends ScrcpyProvider {
     constructor(adb: string, serial: string, onFailure: () => void, tuning?: {
         maxSize: number;
         bitRate: number;
-    });
+    }, textOnly?: boolean);
     foreground(signal: AbortSignal): Promise<string>;
     protected startTransport(): Promise<void>;
     protected write(buffer: Buffer): Promise<void>;

package/dist/src/phone/scrcpy.js

@@ -2,6 +2,7 @@ import { PhoneError, init_contracts } from "./contracts.js";
 import { spawnPhoneCommand } from "../process/phone-process.js";
 import { SCRCPY_SHA256, SCRCPY_VERSION } from "../runtime-tools/phone-dependency-catalog.js";
 import { readScrcpyServer, scrcpyServerPath } from "./scrcpy-assets.js";
+import { ScrcpyTextChannel } from "./scrcpy-text.js";
 import { AdbPhoneDriver, runAdb } from "./adb-driver.js";
 import { randomBytes } from "node:crypto";
 import { connect } from "node:net";
@@ -69,6 +70,7 @@ var ScrcpyProvider = class {
 		codec: ""
 	};
 	closing = false;
+	textChannel = new ScrcpyTextChannel((bytes) => this.write(bytes));
 	touch;
 	listeners = /* @__PURE__ */ new Set();
 	config;
@@ -78,6 +80,25 @@ var ScrcpyProvider = class {
 	constructor(onFailure) {
 		this.onFailure = onFailure;
 	}
+	async pasteText(text, signal) {
+		signal.throwIfAborted();
+		const deadline = AbortSignal.any([signal, AbortSignal.timeout(25e3)]);
+		const abort = () => {
+			this.close();
+		};
+		deadline.addEventListener("abort", abort, { once: true });
+		try {
+			try {
+				await this.start();
+				deadline.throwIfAborted();
+			} catch {
+				throw new PhoneError("PHONE_TEXT_INPUT_UNAVAILABLE", "Automatic text input is unavailable. Check Phone settings or take over and type with the phone keyboard.", 409);
+			}
+			await this.textChannel.paste(text, deadline);
+		} finally {
+			deadline.removeEventListener("abort", abort);
+		}
+	}
 	start() {
 		if (this.closing) return Promise.reject(new PhoneError("PHONE_VIDEO_ENDED", "Phone video ended", 409));
 		if (!this.startResult) {
@@ -144,6 +165,7 @@ var ScrcpyProvider = class {
 	}
 	close() {
 		this.closing = true;
+		this.textChannel.close();
 		return this.closeResult ??= (async () => {
 			await this.opening?.catch(() => {});
 			try {
@@ -165,11 +187,12 @@ var LocalScrcpyProvider = class extends ScrcpyProvider {
 	constructor(adb, serial, onFailure, tuning = {
 		maxSize: 960,
 		bitRate: 2e6
-	}) {
+	}, textOnly = false) {
 		super(onFailure);
 		this.adb = adb;
 		this.serial = serial;
 		this.tuning = tuning;
+		this.textOnly = textOnly;
 	}
 	foreground(signal) {
 		return new AdbPhoneDriver(this.adb).foreground(this.serial, signal);
@@ -221,7 +244,8 @@ var LocalScrcpyProvider = class extends ScrcpyProvider {
 				"send_device_meta=false",
 				"send_codec_meta=true",
 				"send_frame_meta=true",
-				"clipboard_autosync=false"
+				"clipboard_autosync=false",
+				...this.textOnly ? ["video=false", "power_on=false"] : []
 			]);
 			this.process.once("error", () => this.fail());
 			this.process.once("exit", () => this.fail());
@@ -259,6 +283,21 @@ var LocalScrcpyProvider = class extends ScrcpyProvider {
 				await setTimeout$1(50);
 			}
 			if (!this.video) throw new Error("Scrcpy connection timed out");
+			if (this.textOnly) {
+				this.control = this.video;
+				this.video = void 0;
+				this.control.setNoDelay(true);
+				this.control.on("error", () => this.fail());
+				this.control.on("end", () => this.fail());
+				this.control.on("data", (data) => {
+					try {
+						this.textChannel.receive(Buffer.from(data));
+					} catch {
+						this.fail();
+					}
+				});
+				return;
+			}
 			const parser = new ScrcpyVideoParser();
 			this.video.on("data", (data) => {
 				try {
@@ -276,7 +315,13 @@ var LocalScrcpyProvider = class extends ScrcpyProvider {
 			this.control.setNoDelay(true);
 			this.control.on("error", () => this.fail());
 			this.control.on("end", () => this.fail());
-			this.control.on("data", () => {});
+			this.control.on("data", (data) => {
+				try {
+					this.textChannel.receive(Buffer.from(data));
+				} catch {
+					this.fail();
+				}
+			});
 			await new Promise((resolve, reject) => {
 				this.control.once("connect", resolve);
 				this.control.once("error", reject);

package/dist/src/storage/sqlite/connection.js

@@ -1,10 +1,10 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { resolveXopcDatabasePath } from "../../config/paths-state.js";
 import { init_paths } from "./paths.js";
-import { ensureXopcDatabaseSchema, init_schema } from "./schema.js";
-import { init_node_sqlite, requireNodeSqlite } from "../../infra/node-sqlite.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { ensureXopcDatabaseSchema, init_schema } from "./schema.js";
+import { init_node_sqlite, requireNodeSqlite } from "../../infra/node-sqlite.js";
 import { init_unhandled_rejections, installSqliteTransientRejectionHandler } from "../../infra/unhandled-rejections.js";
 import path from "node:path";
 import fs from "node:fs";