@xopcai/xopc 0.0.433 → 0.0.435

package/dist/src/computer/batch.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { type ComputerExpectation, type ComputerVerification } from './task-state.js';
+import type { ComputerProgramHost } from './program-runtime.js';
+export declare const ComputerBatchSchema: z.ZodObject<{
+    snapshotId: z.ZodString;
+    steps: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"action">;
+        action: z.ZodUnion<(z.ZodObject<{
+            kind: z.ZodLiteral<"activate">;
+            ref: z.ZodString;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"showMenu">;
+            ref: z.ZodString;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"click">;
+            point: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>;
+            button: z.ZodEnum<{
+                left: "left";
+                right: "right";
+            }>;
+            count: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"drag">;
+            from: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>;
+            to: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"setValue">;
+            ref: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"typeText">;
+            text: z.ZodString;
+            point: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"pressKeys">;
+            keys: z.ZodArray<z.ZodString>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"scroll">;
+            point: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>;
+            deltaX: z.ZodNumber;
+            deltaY: z.ZodNumber;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"wait">;
+            durationMs: z.ZodNumber;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"setValue">;
+            text: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"showMenu">;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict> | z.ZodObject<{
+            kind: z.ZodLiteral<"activate">;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>)[]>;
+        target: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"observe">;
+        expect: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"field">;
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"selected">;
+            label: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        visual: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+type State = Record<string, unknown> & {
+    snapshotId: string;
+};
+/** Checkpoints delimit native dispatches; a failed condition never starts the next segment. */
+export declare function executeComputerBatch(raw: unknown, host: ComputerProgramHost, options: {
+    remainingInputs: number;
+    signal: AbortSignal;
+    state(snapshotId: string): State;
+    verify(expect: ComputerExpectation): ComputerVerification | undefined;
+}): Promise<{
+    verification?: ComputerVerification;
+    status: string;
+    nextStep: number;
+    receipts: unknown[];
+    snapshotId: string;
+}>;
+export {};

package/dist/src/computer/batch.js

@@ -0,0 +1,125 @@
+import { ComputerPrimitiveActionSchema, init_src } from "../../packages/computer-control-contract/src/index.js";
+import { ComputerExpectationSchema } from "./task-state.js";
+import { z } from "zod";
+import { setTimeout } from "node:timers/promises";
+//#region src/computer/batch.ts
+init_src();
+const Target = z.object({
+	role: z.string().min(1).max(100),
+	label: z.string().max(300)
+}).strict();
+const PlannedAction = z.union(ComputerPrimitiveActionSchema.options.map((option) => "ref" in option.shape ? option.extend({ ref: z.string().min(1).max(200).optional() }) : option));
+const ComputerBatchSchema = z.object({
+	snapshotId: z.string().min(1).max(200),
+	steps: z.array(z.union([z.object({
+		kind: z.literal("action"),
+		action: PlannedAction,
+		target: Target.optional()
+	}).strict(), z.object({
+		kind: z.literal("observe"),
+		expect: ComputerExpectationSchema.optional(),
+		timeoutMs: z.number().int().min(0).max(5e3).optional(),
+		visual: z.boolean().optional()
+	}).strict()])).min(1).max(24)
+}).strict();
+/** Checkpoints delimit native dispatches; a failed condition never starts the next segment. */
+async function executeComputerBatch(raw, host, options) {
+	const input = ComputerBatchSchema.parse(raw);
+	if (input.steps.filter((step) => step.kind === "action").length > options.remainingInputs) throw new Error("COMPUTER_ACTION_BUDGET");
+	let state = options.state(input.snapshotId);
+	let afterCheckpoint = false;
+	let queued = [];
+	const receipts = [];
+	const finish = (status, nextStep, verification) => ({
+		...state,
+		status,
+		nextStep,
+		receipts,
+		...verification ? { verification } : {}
+	});
+	const flush = async () => {
+		if (!queued.length) return;
+		state = await host("act", {
+			snapshotId: state.snapshotId,
+			action: {
+				kind: "batch",
+				actions: queued
+			}
+		}, options.signal);
+		receipts.push(state.receipt);
+		queued = [];
+	};
+	for (const [index, step] of input.steps.entries()) {
+		options.signal.throwIfAborted();
+		if (step.kind === "action") {
+			let action = step.action;
+			if (step.target) {
+				if (!("ref" in action) && ![
+					"activate",
+					"showMenu",
+					"setValue",
+					"click",
+					"scroll",
+					"typeText"
+				].includes(action.kind)) throw new Error("COMPUTER_INVALID_INPUT");
+				const element = await host("resolve", {
+					snapshotId: state.snapshotId,
+					...step.target
+				}, options.signal);
+				if ([
+					"activate",
+					"showMenu",
+					"setValue"
+				].includes(action.kind)) action = {
+					...action,
+					ref: element.ref
+				};
+				else {
+					const bounds = z.object({
+						x: z.number().finite(),
+						y: z.number().finite(),
+						width: z.number().positive(),
+						height: z.number().positive()
+					}).parse(element.bounds);
+					action = {
+						...action,
+						point: {
+							x: bounds.x + bounds.width / 2,
+							y: bounds.y + bounds.height / 2
+						}
+					};
+				}
+			} else if (afterCheckpoint && ("ref" in action || [
+				"activate",
+				"showMenu",
+				"setValue",
+				"click",
+				"scroll",
+				"typeText",
+				"drag"
+			].includes(action.kind))) throw new Error("COMPUTER_ELEMENT_REF_REQUIRED");
+			queued.push(ComputerPrimitiveActionSchema.parse(action));
+			continue;
+		}
+		await flush();
+		let verification;
+		if (step.expect) {
+			const deadline = Date.now() + (step.timeoutMs ?? 2e3);
+			for (let sample = 0;; sample++) {
+				verification = options.verify(step.expect);
+				if (verification?.status === "satisfied") break;
+				if (sample >= 19 || Date.now() >= deadline) return finish("condition_not_met", index, verification);
+				await setTimeout(Math.min(25 * 2 ** Math.min(sample, 3), 200, Math.max(0, deadline - Date.now())), void 0, { signal: options.signal });
+				state = await host("observe", {}, options.signal);
+			}
+		}
+		if (step.visual) await host("emitScreenshot", { snapshotId: state.snapshotId }, options.signal);
+		if ((!step.expect || step.visual) && index < input.steps.length - 1) return finish("observation_required", index + 1, verification);
+		afterCheckpoint = true;
+		if (index === input.steps.length - 1) return finish("batch_completed", index + 1, verification);
+	}
+	await flush();
+	return finish("batch_completed", input.steps.length);
+}
+//#endregion
+export { ComputerBatchSchema, executeComputerBatch };

package/dist/src/computer/broker.d.ts

@@ -12,6 +12,9 @@ export interface DriverObservation {
     imageHeight: number;
 }
 export interface ComputerDriver {
+    getPreparationState?(): {
+        startedAt: number;
+    } | undefined;
     discover(query: string, signal: AbortSignal): Promise<Array<{
         appId: string;
         name: string;
@@ -23,10 +26,14 @@ export interface ComputerDriver {
         windowRef?: string;
     }): Promise<ComputerTarget>;
     observe(target: ComputerTarget, signal: AbortSignal): Promise<DriverObservation>;
-    perform(target: ComputerTarget, action: ComputerAction, signal: AbortSignal): Promise<void>;
+    perform(target: ComputerTarget, action: ComputerAction, signal: AbortSignal, onProgress?: (index: number, dispatch: 'notStarted' | 'started' | 'completed' | 'unknown') => void): Promise<void>;
     getLastInputTiming?(): ComputerInputTiming | undefined;
+    focusTarget?(target: ComputerTarget, signal: AbortSignal): Promise<void>;
+    validatePreviewTarget?(target: ComputerTarget, signal: AbortSignal): Promise<void>;
     /** Must finish only after no further input can be dispatched. */
     stop(): Promise<void>;
+    /** Quiescent broker-only release: discard target state, retain private transport briefly. */
+    idle?(): Promise<void>;
 }
 export type ComputerApproval = {
     kind: 'session';
@@ -43,6 +50,8 @@ export type ComputerApproval = {
     action: ComputerAction;
 };
 export interface ComputerBrokerHost {
+    /** Hosts exposing a separate approval UI may opt into the legacy held-action protocol. */
+    deferApproval?: boolean;
     requestApproval(request: ComputerApproval, signal: AbortSignal): Promise<boolean>;
     isVisible(): boolean;
     onStateChange?(): void;
@@ -65,6 +74,17 @@ export interface BrokerResult {
         mimeType: 'image/png' | 'image/jpeg';
     };
 }
+/** Host-only authority; never serialize target identities or the session signal. */
+export interface ComputerPreviewAuthority {
+    conversationId: string;
+    runId?: string;
+    computerSessionId: string;
+    brokerEpoch: string;
+    appName: string;
+    status: string;
+    target?: ComputerTarget;
+    signal: AbortSignal;
+}
 /** Main-process-only authority. Never expose this object or its approval hook to a renderer. */
 export declare class ComputerBroker {
     private readonly driver;
@@ -92,15 +112,23 @@ export declare class ComputerBroker {
     command(raw: ComputerCommand): Promise<BrokerResult>;
     private discover;
     private open;
+    private awaitDecision;
     private observe;
     private act;
-    stop(): Promise<void>;
+    stop(errorCode?: 'COMPUTER_LOCAL_UI_REQUIRED', retainDriver?: boolean): Promise<void>;
     cancel(command: ComputerCommand): Promise<void>;
     snapshot(): {
         status: Status | 'idle';
         errorCode?: string;
         appId?: string;
+        preparation?: {
+            startedAt: number;
+        };
+        dispatch?: ComputerReceipt['dispatch'];
     };
+    previewAuthority(): ComputerPreviewAuthority | undefined;
+    validatePreview(authority: ComputerPreviewAuthority): Promise<void>;
+    focusConversation(conversationId: string): Promise<void>;
     dispose(): Promise<void>;
 }
 export {};

package/dist/src/computer/broker.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { ComputerConfigSchema, init_config } from "./config.js";
-import { ActionEnvelopeSchema, ComputerCommandSchema, init_src } from "../../packages/computer-control-contract/src/index.js";
+import { ActionEnvelopeSchema, ComputerCommandSchema, computerActionInputCount, computerActionInputs, init_src } from "../../packages/computer-control-contract/src/index.js";
 import { ComputerTargetError } from "./errors.js";
 import { createHash, randomUUID } from "node:crypto";
 import { setTimeout } from "node:timers/promises";
@@ -28,7 +28,7 @@ var ComputerBroker = class {
 		this.config = ComputerConfigSchema.parse(config);
 		this.timer = setInterval(() => {
 			const s = this.session;
-			if (s && s.status !== "stopped" && (this.expired(s) || !this.host.isVisible())) this.stop().catch(() => {});
+			if (s && s.status !== "stopped" && (this.expired(s) || !this.host.isVisible())) this.stop(!this.host.isVisible() ? "COMPUTER_LOCAL_UI_REQUIRED" : void 0).catch(() => {});
 		}, 1e3);
 		this.timer.unref?.();
 	}
@@ -47,7 +47,11 @@ var ComputerBroker = class {
 		};
 	}
 	active(s) {
-		if (this.session !== s || s.controller.signal.aborted || this.expired(s) || !this.host.isVisible()) throw new Error("COMPUTER_GRANT_REVOKED");
+		if (!this.host.isVisible()) {
+			s.errorCode ??= "COMPUTER_LOCAL_UI_REQUIRED";
+			throw new Error("COMPUTER_LOCAL_UI_REQUIRED");
+		}
+		if (this.session !== s || s.controller.signal.aborted || this.expired(s)) throw new Error("COMPUTER_GRANT_REVOKED");
 	}
 	/** Settings-only app catalog. It never returns window contents or task-bound refs. */
 	async listAppsForSettings() {
@@ -70,10 +74,15 @@ var ComputerBroker = class {
 		const s = this.session;
 		if (!s || s.id !== command.sessionId || s.owner !== command.owner) throw new Error("COMPUTER_SESSION_NOT_FOUND");
 		if (command.op === "release") {
-			await this.stop();
+			await this.stop(void 0, !this.busy && s.status === "ready");
 			return this.result(s);
 		}
 		if (command.op === "status") return this.result(s);
+		if (command.op === "settle") {
+			const decision = s.status === "pending_authorization" ? s.preparation : s.pending?.decision;
+			if (decision) await this.awaitDecision(s, decision);
+			return this.result(s);
+		}
 		this.active(s);
 		if (this.busy || s.status !== "ready" && s.status !== "pending_action") throw new Error("COMPUTER_NOT_READY");
 		this.busy = true;
@@ -128,7 +137,8 @@ var ComputerBroker = class {
 			};
 		} finally {
 			try {
-				if (!this.session || this.session.status === "stopped") await this.driver.stop();
+				if (!this.session || this.session.status === "stopped") if (!controller.signal.aborted && this.driver.idle) await this.driver.idle();
+				else await this.driver.stop();
 			} finally {
 				this.discovery = void 0;
 				this.busy = false;
@@ -166,7 +176,7 @@ var ComputerBroker = class {
 			actions: 0
 		};
 		this.session = s;
-		this.host.requestApproval({
+		const preparation = this.host.requestApproval({
 			kind: "session",
 			id: s.id,
 			appId: s.appId,
@@ -194,8 +204,23 @@ var ComputerBroker = class {
 			if (error instanceof ComputerTargetError) s.windows = error.windows;
 			return this.stop().catch(() => {});
 		}).finally(() => this.host.onStateChange?.());
+		s.preparation = preparation;
+		if (!this.host.deferApproval) await this.awaitDecision(s, preparation);
 		return this.result(s);
 	}
+	async awaitDecision(s, decision) {
+		if (s.controller.signal.aborted) return;
+		let abort;
+		const cancelled = new Promise((resolve) => {
+			abort = () => resolve(void 0);
+			s.controller.signal.addEventListener("abort", abort, { once: true });
+		});
+		try {
+			return await Promise.race([decision, cancelled]);
+		} finally {
+			s.controller.signal.removeEventListener("abort", abort);
+		}
+	}
 	async observe(s) {
 		let frame;
 		try {
@@ -255,6 +280,7 @@ var ComputerBroker = class {
 			};
 		} catch (error) {
 			frame?.image.fill(0);
+			s.errorCode ??= error instanceof Error && /^COMPUTER_[A-Z_0-9]+$/.test(error.message) ? error.message : "COMPUTER_OBSERVE_FAILED";
 			await this.stop().catch(() => {
 				log.warn({
 					sessionId: s.id,
@@ -279,9 +305,10 @@ var ComputerBroker = class {
 		}
 		const observed = s.observation;
 		if (!observed || e.observationId !== observed.id || this.now() - observed.capturedAt > 12e4) throw new Error("COMPUTER_STALE_OBSERVATION");
-		if (s.actions >= this.config.maxActionsPerSession) throw new Error("COMPUTER_ACTION_BUDGET");
-		if ((e.action.kind === "drag" ? [e.action.from, e.action.to] : "point" in e.action && e.action.point ? [e.action.point] : []).some((point) => point.x >= observed.imageWidth || point.y >= observed.imageHeight)) throw new Error("COMPUTER_COORDINATE_OUTSIDE_WINDOW");
-		if (e.action.kind === "typeText" && !e.action.point && !observed.focusedEditableRef) throw new Error("COMPUTER_EDITABLE_TARGET_REQUIRED");
+		if (s.actions + computerActionInputCount(e.action) > this.config.maxActionsPerSession) throw new Error("COMPUTER_ACTION_BUDGET");
+		const inputs = computerActionInputs(e.action);
+		if (inputs.flatMap((action) => action.kind === "drag" ? [action.from, action.to] : "point" in action && action.point ? [action.point] : []).some((point) => point.x >= observed.imageWidth || point.y >= observed.imageHeight)) throw new Error("COMPUTER_COORDINATE_OUTSIDE_WINDOW");
+		if (inputs.some((action) => action.kind === "typeText" && !action.point && !observed.focusedEditableRef)) throw new Error("COMPUTER_EDITABLE_TARGET_REQUIRED");
 		this.driver.validateAction?.(e.action);
 		if (e.action.kind !== "wait") {
 			if (!s.pending) {
@@ -290,7 +317,7 @@ var ComputerBroker = class {
 					digest
 				};
 				s.status = "pending_action";
-				this.host.requestApproval({
+				const decision = this.host.requestApproval({
 					kind: "action",
 					id: e.actionId,
 					target: observed.target,
@@ -298,8 +325,15 @@ var ComputerBroker = class {
 				}, s.controller.signal).then((approved) => {
 					this.active(s);
 					if (s.pending?.digest === digest) s.pending.approved = approved;
-				}).catch(() => {}).finally(() => this.host.onStateChange?.());
-				return this.result(s);
+				}).catch(async (error) => {
+					if (this.session !== s) return;
+					s.errorCode ??= error instanceof Error && /^COMPUTER_[A-Z_0-9]+$/.test(error.message) ? error.message : "COMPUTER_APP_NOT_AUTHORIZED";
+					await this.stop();
+				}).finally(() => this.host.onStateChange?.());
+				s.pending.decision = decision;
+				if (this.host.deferApproval) return this.result(s);
+				await this.awaitDecision(s, decision);
+				if (s.controller.signal.aborted) return this.result(s);
 			}
 			if (s.pending.digest !== digest) throw new Error("COMPUTER_DIFFERENT_ACTION_PENDING");
 			if (s.pending.approved === void 0) return this.result(s);
@@ -318,6 +352,7 @@ var ComputerBroker = class {
 			try {
 				current = await this.driver.observe(s.target, s.controller.signal);
 			} catch (error) {
+				s.errorCode ??= error instanceof Error && /^COMPUTER_[A-Z_0-9]+$/.test(error.message) ? error.message : "COMPUTER_OBSERVE_FAILED";
 				await this.stop().catch(() => {});
 				throw error;
 			}
@@ -347,8 +382,16 @@ var ComputerBroker = class {
 			postObserveMs: 0,
 			precheckSamples
 		};
+		const grouped = e.action.kind === "activateSequence" || e.action.kind === "batch";
 		const receipt = {
 			actionId: e.actionId,
+			...grouped ? {
+				inputCount: inputs.length,
+				steps: inputs.map((_, index) => ({
+					index,
+					dispatch: "notStarted"
+				}))
+			} : {},
 			dispatch: "started",
 			outcome: "unknown",
 			verification: "none"
@@ -357,19 +400,28 @@ var ComputerBroker = class {
 			digest,
 			receipt
 		});
-		s.actions++;
+		s.actions += computerActionInputCount(e.action);
 		s.pending = void 0;
 		s.status = "running";
 		try {
 			const inputStarted = this.durationNow();
 			try {
-				await this.driver.perform(s.target, e.action, s.controller.signal);
+				if (grouped) await this.driver.perform(s.target, e.action, s.controller.signal, (index, dispatch) => {
+					if (dispatch === "started") {
+						this.active(s);
+						if (e.deadlineAt <= this.now()) throw new Error("COMPUTER_STALE_ACTION");
+					}
+					if (!receipt.steps?.[index]) throw new Error("COMPUTER_RECEIPT_MISMATCH");
+					receipt.steps[index].dispatch = dispatch;
+				});
+				else await this.driver.perform(s.target, e.action, s.controller.signal);
 			} finally {
 				nativeMs.inputMs = Math.max(0, Math.round(this.durationNow() - inputStarted));
 				nativeMs.inputDetail = this.driver.getLastInputTiming?.();
 			}
 			this.active(s);
 			receipt.dispatch = "completed";
+			for (const step of receipt.steps ?? []) step.dispatch = "completed";
 			s.status = "ready";
 			const observationStarted = this.durationNow();
 			let after;
@@ -402,17 +454,18 @@ var ComputerBroker = class {
 			};
 		}
 	}
-	stop() {
+	stop(errorCode, retainDriver = false) {
 		this.discovery?.controller.abort();
 		const s = this.session;
 		if (s && s.status !== "stopped") {
+			s.errorCode ??= errorCode;
 			s.generation++;
 			s.status = "stopped";
 			s.pending = void 0;
 			s.observation = void 0;
 			s.controller.abort();
 		}
-		if (!this.stopping) this.stopping = this.driver.stop().finally(() => {
+		if (!this.stopping) this.stopping = (retainDriver && this.driver.idle ? this.driver.idle() : this.driver.stop()).finally(() => {
 			this.stopping = void 0;
 			this.host.onStateChange?.();
 		});
@@ -422,12 +475,51 @@ var ComputerBroker = class {
 		if (this.session?.id === command.sessionId && this.session.owner === command.owner || this.discovery?.id === command.sessionId && this.discovery.owner === command.owner) await this.stop();
 	}
 	snapshot() {
+		const preparation = this.session?.status === "pending_authorization" ? this.driver.getPreparationState?.() : void 0;
 		return this.session ? {
 			status: this.session.status,
 			errorCode: this.session.errorCode,
-			appId: this.session.appId
+			appId: this.session.appId,
+			dispatch: [...this.session.receipts.values()].at(-1)?.receipt.dispatch ?? "notStarted",
+			...preparation ? { preparation } : {}
 		} : { status: "idle" };
 	}
+	previewAuthority() {
+		const s = this.session;
+		if (!s || s.status === "stopped" || s.controller.signal.aborted || this.expired(s) || !this.host.isVisible()) return;
+		return {
+			conversationId: s.owner,
+			..."runId" in s.model ? { runId: s.model.runId } : {},
+			computerSessionId: s.id,
+			brokerEpoch: this.epoch,
+			appName: this.apps.get(s.appRef)?.name ?? s.appId,
+			status: s.status,
+			target: s.target ? { ...s.target } : void 0,
+			signal: s.controller.signal
+		};
+	}
+	async validatePreview(authority) {
+		const current = this.previewAuthority();
+		if (!current?.target || !authority.target || current.computerSessionId !== authority.computerSessionId || current.brokerEpoch !== authority.brokerEpoch || current.target.windowId !== authority.target.windowId || current.target.processIdentity !== authority.target.processIdentity || current.target.appId !== authority.target.appId) throw new Error("COMPUTER_PREVIEW_REVOKED");
+		if (!this.driver.validatePreviewTarget) throw new Error("COMPUTER_PREVIEW_UNSUPPORTED");
+		await this.driver.validatePreviewTarget(current.target, current.signal);
+		current.signal.throwIfAborted();
+		if (this.previewAuthority()?.computerSessionId !== current.computerSessionId) throw new Error("COMPUTER_PREVIEW_REVOKED");
+	}
+	async focusConversation(conversationId) {
+		if (this.busy || this.discovery || this.stopping) throw new Error("COMPUTER_BUSY");
+		const s = this.session;
+		if (!s || s.owner !== conversationId || s.status !== "ready" || !s.target) throw new Error("COMPUTER_PREVIEW_REVOKED");
+		this.active(s);
+		if (!this.driver.focusTarget) throw new Error("COMPUTER_PREVIEW_UNSUPPORTED");
+		this.busy = true;
+		try {
+			await this.driver.focusTarget(s.target, s.controller.signal);
+			this.active(s);
+		} finally {
+			this.busy = false;
+		}
+	}
 	async dispose() {
 		clearInterval(this.timer);
 		await this.stop();

package/dist/src/computer/diagnostics.d.ts

@@ -211,6 +211,7 @@ export declare const ComputerSessionReportSchema: z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
             wait: "wait";
             typeText: "typeText";
+            batch: "batch";
             activate: "activate";
             showMenu: "showMenu";
             click: "click";
@@ -218,6 +219,7 @@ export declare const ComputerSessionReportSchema: z.ZodObject<{
             setValue: "setValue";
             pressKeys: "pressKeys";
             scroll: "scroll";
+            activateSequence: "activateSequence";
         }>>;
         transport: z.ZodOptional<z.ZodObject<{
             brokerWallMs: z.ZodNumber;
@@ -231,6 +233,7 @@ export declare const ComputerSessionReportSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             wait: "wait";
             typeText: "typeText";
+            batch: "batch";
             activate: "activate";
             showMenu: "showMenu";
             click: "click";
@@ -238,6 +241,7 @@ export declare const ComputerSessionReportSchema: z.ZodObject<{
             setValue: "setValue";
             pressKeys: "pressKeys";
             scroll: "scroll";
+            activateSequence: "activateSequence";
         }>;
         dispatch: z.ZodEnum<{
             unknown: "unknown";
@@ -273,7 +277,7 @@ export declare class ComputerSessionDiagnostics {
     count(key: keyof ComputerSessionReport['counters']): void;
     timing(value: NonNullable<ComputerSessionReport['timings']>[number]): void;
     measure<T>(phase: keyof ComputerSessionReport['phaseMs'], fn: () => Promise<T>): Promise<T>;
-    propose(id: string, kind: ComputerAction['kind']): void;
+    propose(id: string, kind: ComputerAction['kind'], inputCount?: number): void;
     discard(): void;
     record(receipt: ComputerReceipt, before?: ComputerObservation, after?: ComputerObservation, verification?: ComputerVerification): void;
     verify(verification?: ComputerVerification): void;