@xopcai/xopc 0.0.416 → 0.0.418

package/dist/src/phone/cloud-adb.js

@@ -1,263 +1,7 @@
-import { init_paths, resolveCredentialsDir } from "../config/paths.js";
-import { PhoneError, init_contracts } from "./contracts.js";
-import { readScrcpyServer } from "./scrcpy-assets.js";
-import { parsePhoneApplications, phoneApplicationsCommand } from "./applications.js";
 import { AdbPhoneDriver } from "./adb-driver.js";
-import { join } from "node:path";
-import { createPrivateKey, randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { connect } from "node:net";
-import { Adb, AdbDaemonTransport, AdbPacket, AdbPacketSerializeStream, AdbSignatureAuthenticator } from "@yume-chan/adb";
-import { Consumable, ReadableStream, StructDeserializeStream } from "@yume-chan/stream-extra";
+import { CloudAdbConnection as CloudAdbConnection$1, PhoneCloudKeyStore, parseCloudEndpoint, parseCloudPrivateKey } from "./cloud-adb-connection.js";
 //#region src/phone/cloud-adb.ts
-init_paths();
-init_contracts();
-/** Accept only an explicit TCP endpoint, never URLs, paths or ADB commands. */
-function parseCloudEndpoint(value) {
-	const match = /^(\[[a-fA-F0-9:]+\]|[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?):([0-9]{1,5})$/.exec(value.trim());
-	if (!match || Number(match[2]) < 1 || Number(match[2]) > 65535) throw new PhoneError("PHONE_ENDPOINT_INVALID", "Enter the cloud ADB address as host:port");
-	return {
-		host: match[1].replace(/^\[|\]$/g, ""),
-		port: Number(match[2]),
-		endpoint: `${match[1].toLowerCase()}:${Number(match[2])}`
-	};
-}
-function parseCloudPrivateKey(pem) {
-	try {
-		if (Buffer.byteLength(pem) > 16384) throw new Error();
-		const key = createPrivateKey(pem);
-		if (key.asymmetricKeyType !== "rsa" || key.asymmetricKeyDetails?.modulusLength !== 2048 || key.asymmetricKeyDetails?.publicExponent !== 65537n) throw new Error();
-		return key.export({
-			format: "der",
-			type: "pkcs8"
-		});
-	} catch {
-		throw new PhoneError("PHONE_KEY_INVALID", "Upload the unencrypted RSA 2048 private adbkey downloaded from the cloud console");
-	}
-}
-var PhoneCloudKeyStore = class {
-	constructor(root = join(resolveCredentialsDir(), "phone-adb")) {
-		this.root = root;
-	}
-	path(id) {
-		if (!/^[0-9a-f-]{36}$/i.test(id)) throw new PhoneError("PHONE_KEY_INVALID", "Invalid phone credential reference");
-		return join(this.root, `${id}.der`);
-	}
-	async save(key) {
-		await mkdir(this.root, {
-			recursive: true,
-			mode: 448
-		});
-		await chmod(this.root, 448);
-		const id = randomUUID();
-		await writeFile(this.path(id), key, {
-			mode: 384,
-			flag: "wx"
-		});
-		return id;
-	}
-	async load(id) {
-		try {
-			return await readFile(this.path(id));
-		} catch {
-			throw new PhoneError("PHONE_KEY_MISSING", "Phone private key is unavailable. Remove this connection and add it again.");
-		}
-	}
-	async remove(id) {
-		await rm(this.path(id), { force: true });
-	}
-};
-/** Direct daemon transport never starts or modifies the host ADB server. */
-var CloudAdbConnection = class CloudAdbConnection {
-	socket;
-	adb;
-	pending;
-	idle;
-	constructor(endpoint, key) {
-		this.endpoint = endpoint;
-		this.key = key;
-		parseCloudEndpoint(endpoint);
-	}
-	close() {
-		clearTimeout(this.idle);
-		this.socket?.destroy();
-		this.socket = void 0;
-		this.adb = void 0;
-	}
-	dispose() {
-		this.close();
-		this.key.fill(0);
-	}
-	/** A dedicated media connection can multiplex sync, video and control sockets. */
-	async client() {
-		if (this.adb) return this.adb;
-		if (this.pending) return this.pending;
-		const opening = this.open();
-		this.pending = opening;
-		try {
-			return await opening;
-		} finally {
-			if (this.pending === opening) this.pending = void 0;
-		}
-	}
-	async open() {
-		const { host, port } = parseCloudEndpoint(this.endpoint);
-		const socket = connect({
-			host,
-			port
-		});
-		this.socket = socket;
-		socket.setNoDelay(true);
-		socket.on("error", () => {});
-		try {
-			await new Promise((resolve, reject) => {
-				socket.once("connect", resolve);
-				socket.once("error", reject);
-				socket.once("close", () => reject(/* @__PURE__ */ new Error("closed")));
-			});
-			const iterator = socket[Symbol.asyncIterator]();
-			const raw = new ReadableStream({
-				async pull(controller) {
-					const next = await iterator.next();
-					if (next.done) controller.close();
-					else controller.enqueue(next.value);
-				},
-				cancel() {
-					socket.destroy();
-				}
-			});
-			const serializer = new AdbPacketSerializeStream();
-			serializer.readable.pipeTo(new Consumable.WritableStream({
-				write(chunk) {
-					return new Promise((resolve, reject) => socket.write(chunk, (error) => error ? reject(error) : resolve()));
-				},
-				close() {
-					socket.destroy();
-				},
-				abort() {
-					socket.destroy();
-				}
-			})).catch(() => {
-				socket.destroy();
-			});
-			const key = this.key;
-			const transport = await AdbDaemonTransport.authenticate({
-				serial: this.endpoint,
-				connection: {
-					readable: raw.pipeThrough(new StructDeserializeStream(AdbPacket)),
-					writable: serializer.writable
-				},
-				credentialStore: {
-					*iterateKeys() {
-						yield {
-							buffer: key,
-							name: "xopc-cloud-phone"
-						};
-					},
-					generateKey() {
-						throw new Error("Key generation disabled");
-					}
-				},
-				authenticators: [AdbSignatureAuthenticator]
-			});
-			if (socket.destroyed) {
-				await transport.close();
-				throw new Error("closed");
-			}
-			const adb = new Adb(transport);
-			this.adb = adb;
-			adb.disconnected.catch(() => {}).finally(() => {
-				if (this.adb === adb) this.close();
-			});
-			return adb;
-		} catch {
-			socket.destroy();
-			throw new PhoneError("PHONE_CLOUD_AUTH_FAILED", "Cloud ADB connection failed. Check address, network access and the bound private key.", 502);
-		}
-	}
-	async command(_path, args, signal, timeout = 15e3) {
-		const combined = AbortSignal.any([...signal ? [signal] : [], AbortSignal.timeout(timeout)]);
-		combined.throwIfAborted();
-		let abort;
-		const cancelled = new Promise((_resolve, reject) => {
-			abort = () => {
-				this.close();
-				reject(new PhoneError("PHONE_CLOUD_TIMEOUT", "Cloud phone connection stopped or timed out. Check its ADB address and network.", 502));
-			};
-			combined.addEventListener("abort", abort, { once: true });
-		});
-		try {
-			return await Promise.race([cancelled, (async () => {
-				const adb = await this.client();
-				if (args[0] === "devices") return Buffer.from(`List of devices attached\n${this.endpoint}\tdevice model:${adb.banner.model ?? "Cloud_Phone"}\n`);
-				if (args[0] !== "-s" || args[1] !== this.endpoint || !["shell", "exec-out"].includes(args[2])) throw new PhoneError("PHONE_CLOUD_COMMAND_INVALID", "Unsupported cloud ADB command");
-				const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
-				const channel = await adb.createSocket(`${args[2] === "exec-out" ? "exec" : "shell"}:${args.slice(3).map(quote).join(" ")}`);
-				const chunks = [];
-				let length = 0;
-				try {
-					for await (const chunk of channel.readable) {
-						length += chunk.length;
-						if (length > 16 * 1024 * 1024) throw new Error("Output exceeded");
-						chunks.push(Buffer.from(chunk));
-					}
-					return Buffer.concat(chunks);
-				} finally {
-					await channel.close();
-				}
-			})()]);
-		} catch (error) {
-			this.close();
-			if (error instanceof PhoneError) throw error;
-			throw new PhoneError("PHONE_CLOUD_ADB_FAILED", "Cloud phone operation failed. Reconnect or run diagnostics.", 502);
-		} finally {
-			combined.removeEventListener("abort", abort);
-			clearTimeout(this.idle);
-			this.idle = setTimeout(() => this.close(), 3e4);
-			this.idle.unref();
-		}
-	}
-	async applications(signal) {
-		const combined = AbortSignal.any([signal, AbortSignal.timeout(3e4)]);
-		const abort = () => this.close();
-		combined.addEventListener("abort", abort, { once: true });
-		const remote = `/data/local/tmp/xopc-apps-${randomUUID()}.jar`;
-		try {
-			combined.throwIfAborted();
-			const binary = await readScrcpyServer();
-			const adb = await this.client();
-			combined.throwIfAborted();
-			const sync = await adb.sync();
-			try {
-				await sync.write({
-					filename: remote,
-					permission: 384,
-					file: new ReadableStream({ start(controller) {
-						controller.enqueue(binary);
-						controller.close();
-					} })
-				});
-			} finally {
-				await sync.dispose();
-			}
-			return parsePhoneApplications((await this.command("", [
-				"-s",
-				this.endpoint,
-				"shell",
-				...phoneApplicationsCommand(remote)
-			], combined)).toString());
-		} finally {
-			combined.removeEventListener("abort", abort);
-			await this.command("", [
-				"-s",
-				this.endpoint,
-				"shell",
-				"rm",
-				"-f",
-				remote
-			], void 0, 3e3).catch(() => {});
-		}
-	}
+var CloudAdbConnection = class CloudAdbConnection extends CloudAdbConnection$1 {
 	driver() {
 		return new AdbPhoneDriver("", this.command.bind(this), false, async (signal) => {
 			const listing = new CloudAdbConnection(this.endpoint, Buffer.from(this.key));
@@ -274,7 +18,7 @@ var CloudAdbConnection = class CloudAdbConnection {
 			} finally {
 				await provider.close();
 			}
-		});
+		}, this.hierarchy.bind(this));
 	}
 };
 //#endregion

package/dist/src/phone/cloud-key-permissions.d.ts

@@ -0,0 +1,2 @@
+/** Fail closed if owner-only access cannot be established on the credential path. */
+export declare function protectPhoneCredential(path: string, directory: boolean): Promise<void>;

package/dist/src/phone/cloud-key-permissions.js

@@ -0,0 +1,66 @@
+import { PhoneError, init_contracts } from "./contracts.js";
+import { runProcessChecked } from "../process/run-process.js";
+import { join } from "node:path";
+import { chmod, lstat } from "node:fs/promises";
+//#region src/phone/cloud-key-permissions.ts
+init_contracts();
+const protectWindowsCredential = `
+$ErrorActionPreference = 'Stop'
+$target = $env:XOPC_PHONE_CREDENTIAL_TARGET
+$directory = $env:XOPC_PHONE_CREDENTIAL_DIRECTORY -eq '1'
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+if ($directory) {
+  $acl = New-Object System.Security.AccessControl.DirectorySecurity
+  $inheritance = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+} else {
+  $acl = New-Object System.Security.AccessControl.FileSecurity
+  $inheritance = [System.Security.AccessControl.InheritanceFlags]::None
+}
+$acl.SetOwner($sid)
+$acl.SetAccessRuleProtection($true, $false)
+$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($sid, 'FullControl', $inheritance, 'None', 'Allow')
+$acl.AddAccessRule($rule)
+Set-Acl -LiteralPath $target -AclObject $acl
+$actual = Get-Acl -LiteralPath $target
+$rules = @($actual.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier]))
+if (!$actual.AreAccessRulesProtected -or $actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value -or $rules.Count -ne 1) { throw 'Credential ACL verification failed' }
+$access = $rules[0]
+if ($access.IdentityReference.Value -ne $sid.Value -or $access.IsInherited -or $access.AccessControlType -ne 'Allow' -or $access.FileSystemRights -ne 'FullControl' -or $access.InheritanceFlags -ne $inheritance -or $access.PropagationFlags -ne 'None') { throw 'Credential ACL verification failed' }
+`;
+/** Fail closed if owner-only access cannot be established on the credential path. */
+async function protectPhoneCredential(path, directory) {
+	try {
+		const info = await lstat(path);
+		if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())) throw new Error("Invalid credential path");
+		if (process.platform === "win32") await runProcessChecked({
+			program: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+			args: [
+				"-NoProfile",
+				"-NonInteractive",
+				"-OutputFormat",
+				"Text",
+				"-EncodedCommand",
+				Buffer.from(protectWindowsCredential, "utf16le").toString("base64")
+			],
+			windowsHide: true,
+			timeoutMs: 15e3,
+			maxOutputBytes: 64 * 1024,
+			env: {
+				...Object.fromEntries(Object.entries(process.env).filter(([name]) => name.toLowerCase() !== "psmodulepath")),
+				PSModulePath: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "Modules"),
+				XOPC_PHONE_CREDENTIAL_TARGET: path,
+				XOPC_PHONE_CREDENTIAL_DIRECTORY: directory ? "1" : "0"
+			}
+		});
+		else {
+			const mode = directory ? 448 : 384;
+			await chmod(path, mode);
+			const actual = await lstat(path);
+			if ((actual.mode & 511) !== mode || process.getuid && actual.uid !== process.getuid()) throw new Error("Credential mode verification failed");
+		}
+	} catch {
+		throw new PhoneError("PHONE_KEY_PERMISSIONS", "Unable to secure phone credentials for the current user. Check filesystem permissions.", 500);
+	}
+}
+//#endregion
+export { protectPhoneCredential };

package/dist/src/phone/cloud-phones.js

@@ -1,5 +1,6 @@
 import { PhoneError, init_contracts } from "./contracts.js";
-import { CloudAdbConnection, PhoneCloudKeyStore, parseCloudEndpoint, parseCloudPrivateKey } from "./cloud-adb.js";
+import { PhoneCloudKeyStore, parseCloudEndpoint, parseCloudPrivateKey } from "./cloud-adb-connection.js";
+import { CloudAdbConnection } from "./cloud-adb.js";
 import { CloudScrcpyProvider } from "./cloud-scrcpy.js";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";

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

@@ -1,4 +1,4 @@
-import { CloudAdbConnection } from './cloud-adb.js';
+import { CloudAdbConnection } from './cloud-adb-connection.js';
 import { ScrcpyProvider } from './scrcpy.js';
 /** Dedicated authenticated ADB transport: no host ADB key, server or port forwarding. */
 export declare class CloudScrcpyProvider extends ScrcpyProvider {

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

@@ -1,8 +1,9 @@
 import { PhoneError, init_contracts } from "./contracts.js";
 import { SCRCPY_VERSION } from "../runtime-tools/phone-dependency-catalog.js";
 import { readScrcpyServer } from "./scrcpy-assets.js";
+import { readPhoneForeground } from "./foreground.js";
 import { ScrcpyProvider, ScrcpyVideoParser } from "./scrcpy.js";
-import { CloudAdbConnection } from "./cloud-adb.js";
+import { CloudAdbConnection } from "./cloud-adb-connection.js";
 import { randomBytes } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { ReadableStream } from "@yume-chan/stream-extra";
@@ -24,7 +25,7 @@ var CloudScrcpyProvider = class extends ScrcpyProvider {
 		this.connection = connect(endpoint, key);
 	}
 	foreground(signal) {
-		return this.connection.driver().foreground(this.endpoint, signal);
+		return readPhoneForeground(this.connection.command.bind(this.connection), "", this.endpoint, signal);
 	}
 	async startTransport() {
 		const timer = setTimeout(() => this.connection.close(), 2e4);

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

@@ -11,8 +11,17 @@ export declare const PhoneModelMetadataSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const MOCK_PHONE_MODEL = "phone-mock/settings-about";
 export declare const MOCK_PHONE_GOAL = "Open Android Settings and inspect About phone";
+export declare const PhoneExecutionModeSchema: z.ZodEnum<{
+    collaborative: "collaborative";
+    direct: "direct";
+}>;
+export type PhoneExecutionMode = z.infer<typeof PhoneExecutionModeSchema>;
 export declare const PhoneConfigSchema: z.ZodPrefault<z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
+    executionMode: z.ZodDefault<z.ZodEnum<{
+        collaborative: "collaborative";
+        direct: "direct";
+    }>>;
     adbPath: z.ZodOptional<z.ZodString>;
     semanticControls: z.ZodDefault<z.ZodBoolean>;
     hierarchicalPlanning: z.ZodDefault<z.ZodBoolean>;
@@ -20,6 +29,7 @@ export declare const PhoneConfigSchema: z.ZodPrefault<z.ZodObject<{
     maxModelRequests: z.ZodDefault<z.ZodNumber>;
     maxOperationDurationMs: z.ZodDefault<z.ZodNumber>;
     maxSessionDurationMs: z.ZodDefault<z.ZodNumber>;
+    idleDisconnectMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>>;
 export type PhoneConfig = z.infer<typeof PhoneConfigSchema>;
 export declare const PhoneDeviceSchema: z.ZodObject<{
@@ -41,6 +51,12 @@ export declare const PhoneDeviceSchema: z.ZodObject<{
         endpoint: z.ZodString;
         credentialId: z.ZodString;
     }, z.core.$strict>>;
+    wireless: z.ZodOptional<z.ZodObject<{
+        guid: z.ZodString;
+        hardwareSerial: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodNumber;
+    }, z.core.$strict>>;
     createdAt: z.ZodNumber;
     revision: z.ZodNumber;
 }, z.core.$strict>;
@@ -197,8 +213,93 @@ export declare const PhoneCompletionSchema: z.ZodObject<{
     requireChange: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type PhoneCompletion = z.infer<typeof PhoneCompletionSchema>;
+export declare const PhoneRequestedOutputSchema: z.ZodObject<{
+    key: z.ZodString;
+    description: z.ZodString;
+    selector: z.ZodOptional<z.ZodObject<{
+        resourceId: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const PhoneTaskBudgetSchema: z.ZodObject<{
+    maxActions: z.ZodOptional<z.ZodNumber>;
+    maxModelRequests: z.ZodOptional<z.ZodNumber>;
+    maxActiveDurationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type PhoneTaskBudget = z.infer<typeof PhoneTaskBudgetSchema>;
+export declare const PhoneTaskFields: {
+    budget: z.ZodOptional<z.ZodObject<{
+        maxActions: z.ZodOptional<z.ZodNumber>;
+        maxModelRequests: z.ZodOptional<z.ZodNumber>;
+        maxActiveDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    taskId: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        collaborative: "collaborative";
+        direct: "direct";
+    }>>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requestedOutputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        selector: z.ZodOptional<z.ZodObject<{
+            resourceId: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+};
+export type PhoneRequestedOutput = z.infer<typeof PhoneRequestedOutputSchema>;
+export type PhoneTaskContract = {
+    taskId: string;
+    executionMode: PhoneExecutionMode;
+    goal: string;
+    constraints: string[];
+    requestedOutputs: PhoneRequestedOutput[];
+    budget?: PhoneTaskBudget;
+    completion?: PhoneCompletion;
+    expectText?: string;
+};
+export type PhoneTaskFeedback = {
+    taskId: string;
+    segmentId: string;
+    executionMode: PhoneExecutionMode;
+    outcome: 'running' | 'completed' | 'partial' | 'blocked' | 'needs_user' | 'failed' | 'cancelled';
+    stopReason?: string;
+    verified: boolean;
+    verificationLevel: 'none' | 'ui';
+    progress: {
+        completed: string[];
+        remaining: string[];
+        source: 'runtime';
+    };
+    outputs: Array<{
+        key: string;
+        value?: string;
+        source?: PhoneReading['source'];
+        verification: PhoneReading['verification'];
+        frameId?: string;
+        capturedAt?: number;
+        reason?: string;
+    }>;
+    evidence: PhoneReading[];
+    usage: {
+        actions: number;
+        modelRequests: number;
+        activeDurationMs: number;
+    };
+    nextAction: 'wait' | 'replan' | 'inspect' | 'user' | 'done';
+};
 export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"discover">;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"set_mode">;
+    executionMode: z.ZodEnum<{
+        collaborative: "collaborative";
+        direct: "direct";
+    }>;
+    applyCurrent: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"open">;
     deviceId: z.ZodOptional<z.ZodString>;
@@ -210,6 +311,7 @@ export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     settingsPage: z.ZodOptional<z.ZodLiteral<"about-phone">>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"observe">;
+    goal: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodEnum<{
         run: "run";
@@ -229,6 +331,26 @@ export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         requireChange: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     maxActions: z.ZodDefault<z.ZodNumber>;
+    budget: z.ZodOptional<z.ZodObject<{
+        maxActions: z.ZodOptional<z.ZodNumber>;
+        maxModelRequests: z.ZodOptional<z.ZodNumber>;
+        maxActiveDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    taskId: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        collaborative: "collaborative";
+        direct: "direct";
+    }>>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requestedOutputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        selector: z.ZodOptional<z.ZodObject<{
+            resourceId: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodEnum<{
         cancel: "cancel";
@@ -240,6 +362,14 @@ export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>], "op">;
 export type PhoneInput = z.infer<typeof PhoneInputSchema>;
 export type PhoneStatus = 'ready' | 'running' | 'paused' | 'needs_user' | 'completed' | 'cancelled' | 'closed' | 'failed' | 'outcome_unknown';
+export type PhoneReading = {
+    source: 'native_ui' | 'screenshot';
+    verification: 'observed' | 'unverified' | 'unavailable';
+    text: string[];
+    frameId: string;
+    capturedAt: number;
+    reason?: string;
+};
 export type PhoneReport = {
     sessionId: string;
     deviceId: string;
@@ -262,6 +392,13 @@ export type PhoneReport = {
     facts?: string[];
     foregroundApp?: string;
     message?: string;
+    goalPreview?: string;
+    executionMode?: PhoneExecutionMode;
+    nextExecutionMode?: PhoneExecutionMode;
+    task?: PhoneTaskContract;
+    feedback?: PhoneTaskFeedback;
+    sourceConversationId?: string;
+    readings?: PhoneReading[];
     steps: Array<{
         action: PhoneAction['type'];
         at: number;
@@ -293,5 +430,24 @@ export type PhoneReport = {
 export declare class PhoneError extends Error {
     readonly code: string;
     readonly status: 400 | 403 | 404 | 409 | 500 | 502;
-    constructor(code: string, message: string, status?: 400 | 403 | 404 | 409 | 500 | 502);
+    readonly details?: {
+        executionStarted: false;
+        deviceId: string;
+        occupancy: {
+            kind: 'agent' | 'human' | 'opening' | 'inspection';
+            conversationId?: string;
+            sessionId?: string;
+        };
+        retryPolicy: 'user_initiated';
+    };
+    constructor(code: string, message: string, status?: 400 | 403 | 404 | 409 | 500 | 502, details?: {
+        executionStarted: false;
+        deviceId: string;
+        occupancy: {
+            kind: 'agent' | 'human' | 'opening' | 'inspection';
+            conversationId?: string;
+            sessionId?: string;
+        };
+        retryPolicy: 'user_initiated';
+    });
 }