@xopcai/xopc 0.0.433 → 0.0.434

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,37 @@ 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 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;

package/dist/src/computer/diagnostics.js

@@ -44,6 +44,11 @@ const ComputerFailureSchema = z.object({
 	serviceErrorCode: ComputerDiagnosticSchema.shape.serviceErrorCode
 }).strict();
 const categories = Object.create(null);
+for (const code of [
+	"NATIVE_BATCH_FAILED",
+	"NATIVE_BATCH_REFUSED",
+	"DRIVER_INVALID_BATCH_RESULT"
+]) categories[`COMPUTER_${code}`] = "native";
 for (const code of [
 	"AGENT_MODEL_REQUIRED",
 	"AGENT_MODEL_CHANGED",
@@ -74,9 +79,13 @@ for (const [category, codes] of Object.entries({
 	target: [
 		"APP_NOT_FOUND",
 		"APP_NOT_RUNNING",
+		"APP_PREPARATION_REFUSED",
+		"APP_ID_INVALID",
 		"APP_REF_EXPIRED",
 		"APP_INSTANCE_AMBIGUOUS",
 		"WINDOW_REQUIRED",
+		"WINDOW_HIDDEN",
+		"WINDOW_READY_TIMEOUT",
 		"WINDOW_OTHER_SPACE",
 		"WINDOW_AMBIGUOUS",
 		"WINDOW_CHANGED",
@@ -102,6 +111,7 @@ for (const [category, codes] of Object.entries({
 		"UI_UNSTABLE",
 		"FRAME_REQUIRED",
 		"CAPTURE_REQUIRED",
+		"CAPTURE_UNAVAILABLE",
 		"CAPTURE_TARGET_MISMATCH",
 		"FRAME_HANDOFF_FAILED",
 		"UNEXPECTED_FRAME",
@@ -138,6 +148,8 @@ for (const [category, codes] of Object.entries({
 		"DIFFERENT_ACTION_PENDING"
 	],
 	native: [
+		"BACKGROUND_INPUT_UNSUPPORTED",
+		"INPUT_REFUSED",
 		"NATIVE_SETUP_FAILED",
 		"NATIVE_ACTION_FAILED",
 		"POST_ACTION_OBSERVATION_FAILED",
@@ -251,6 +263,8 @@ const ComputerSessionReportSchema = z.object({
 		nativeMs: ComputerNativeTimingSchema.optional(),
 		kind: z.enum([
 			"activate",
+			"activateSequence",
+			"batch",
 			"showMenu",
 			"click",
 			"drag",
@@ -267,6 +281,8 @@ const ComputerSessionReportSchema = z.object({
 	recentActions: z.array(z.object({
 		kind: z.enum([
 			"activate",
+			"activateSequence",
+			"batch",
 			"showMenu",
 			"click",
 			"drag",
@@ -360,12 +376,12 @@ var ComputerSessionDiagnostics = class {
 			this.data.phaseMs[phase] += Math.max(0, Math.round(this.durationNow() - start));
 		}
 	}
-	propose(id, kind) {
+	propose(id, kind, inputCount = 1) {
 		this.pending = {
 			id,
 			kind
 		};
-		if (kind !== "wait") this.count("proposedInputs");
+		if (kind !== "wait") for (let i = 0; i < inputCount; i++) this.count("proposedInputs");
 	}
 	discard() {
 		this.pending = void 0;
@@ -376,7 +392,10 @@ var ComputerSessionDiagnostics = class {
 		this.receipts.add(receipt.actionId);
 		const kind = this.pending.kind;
 		const unchanged = kind !== "wait" && receipt.dispatch === "completed" && !!after && before?.stateDigest === after.stateDigest;
-		if (kind !== "wait" && receipt.dispatch === "completed") this.count("completedInputs");
+		if (kind !== "wait") {
+			const completed = receipt.steps?.filter((step) => step.dispatch === "completed").length ?? (receipt.dispatch === "completed" ? receipt.inputCount ?? 1 : 0);
+			for (let i = 0; i < completed; i++) this.count("completedInputs");
+		}
 		if (receipt.dispatch === "unknown" || receipt.dispatch === "started") this.count("unknownDispatches");
 		if (unchanged) this.count("unchangedInputs");
 		this.verify(verification);

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

@@ -40,5 +40,20 @@ export declare class ComputerTargetError extends Error {
     readonly windows: ComputerWindow[];
     constructor(code: string, windows?: ComputerWindow[]);
 }
+export declare const ComputerRecoverySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        wait_and_observe: "wait_and_observe";
+        show_target_window: "show_target_window";
+        move_to_same_desktop: "move_to_same_desktop";
+        show_xopc_window: "show_xopc_window";
+        check_capture_permission: "check_capture_permission";
+        manual_input: "manual_input";
+        reselect_window: "reselect_window";
+        inspect_result: "inspect_result";
+    }>;
+    automaticRetryAllowed: z.ZodBoolean;
+}, z.core.$strict>;
+/** Derived locally, so older desktop transports need no new reply fields. */
+export declare function computerRecoveryDirective(code: string, dispatch?: 'notStarted' | 'started' | 'completed' | 'unknown'): z.infer<typeof ComputerRecoverySchema>;
 /** Recovery instructions are deterministic; never replay an input with unknown delivery. */
 export declare function computerRecovery(code: string): string;

package/dist/src/computer/errors.js

@@ -52,6 +52,51 @@ var ComputerTargetError = class extends Error {
 		this.windows = windows;
 	}
 };
+const ComputerRecoverySchema = z.object({
+	action: z.enum([
+		"wait_and_observe",
+		"show_target_window",
+		"move_to_same_desktop",
+		"show_xopc_window",
+		"check_capture_permission",
+		"manual_input",
+		"reselect_window",
+		"inspect_result"
+	]),
+	automaticRetryAllowed: z.boolean()
+}).strict();
+/** Derived locally, so older desktop transports need no new reply fields. */
+function computerRecoveryDirective(code, dispatch = "notStarted") {
+	if (dispatch === "unknown" || dispatch === "started") return {
+		action: "inspect_result",
+		automaticRetryAllowed: false
+	};
+	if (/^COMPUTER_DRIVER_(CLICK|TYPE_TEXT|SET_VALUE|PRESS_KEY|HOTKEY|KEY|SCROLL|DRAG)_REFUSED$/.test(code)) return {
+		action: "manual_input",
+		automaticRetryAllowed: false
+	};
+	const actions = {
+		COMPUTER_WINDOW_HIDDEN: "show_target_window",
+		COMPUTER_WINDOW_READY_TIMEOUT: "show_target_window",
+		COMPUTER_WINDOW_REQUIRED: "show_target_window",
+		COMPUTER_WINDOW_OTHER_SPACE: "move_to_same_desktop",
+		COMPUTER_DRIVER_BRING_TO_FRONT_REFUSED: "show_target_window",
+		COMPUTER_APP_PREPARATION_REFUSED: "show_target_window",
+		COMPUTER_APP_ID_INVALID: "inspect_result",
+		COMPUTER_LOCAL_UI_REQUIRED: "show_xopc_window",
+		COMPUTER_CAPTURE_UNAVAILABLE: "wait_and_observe",
+		COMPUTER_CAPTURE_REQUIRED: "wait_and_observe",
+		COMPUTER_OS_PERMISSION_REQUIRED: "check_capture_permission",
+		COMPUTER_BACKGROUND_INPUT_UNSUPPORTED: "manual_input",
+		COMPUTER_INPUT_REFUSED: "manual_input",
+		COMPUTER_WINDOW_CHANGED: "reselect_window",
+		COMPUTER_CAPTURE_TARGET_MISMATCH: "reselect_window"
+	};
+	return {
+		action: Object.hasOwn(actions, code) ? actions[code] : "inspect_result",
+		automaticRetryAllowed: false
+	};
+}
 /** Recovery instructions are deterministic; never replay an input with unknown delivery. */
 function computerRecovery(code) {
 	if (code === "COMPUTER_AGENT_MODEL_REQUIRED") return "Direct UI programs require an active visual main-model turn. Select a visual model and open with planner:agent; do not change models inside an active desktop session.";
@@ -63,6 +108,18 @@ function computerRecovery(code) {
 	if (code === "COMPUTER_FLOW_NOT_VERIFIED" || code === "COMPUTER_FLOW_SAVE_FAILED") return "Control was released. No reusable flow was confirmed saved. Saving requires verified native navigation, non-sensitive labels and working local storage; never repeat desktop input merely to save a flow.";
 	if (code.startsWith("COMPUTER_FRAME_UPLOAD_")) return "Screenshot upload to the Gateway failed. No automatic retry. Report the diagnosticId and HTTP status; do not change model providers or bypass desktop controls.";
 	switch (code) {
+		case "COMPUTER_NATIVE_BATCH_FAILED":
+		case "COMPUTER_DRIVER_INVALID_BATCH_RESULT": return "The native batch stopped or its reply could not be validated. Inspect per-input receipts and the current window after releasing control. Completed or unknown inputs must never be replayed; do not retry the batch through scalar calls.";
+		case "COMPUTER_NATIVE_BATCH_REFUSED": return "The native driver rejected the batch before any input. Inspect the exact target, native capability and batch arguments; do not bypass this refusal through scalar calls.";
+		case "COMPUTER_WINDOW_HIDDEN": return "The selected window is hidden or minimized. If restoration is already authorized, open with prepare=true after release; otherwise ask the user to show it. Keyboard focus is not required. Never replay prior inputs.";
+		case "COMPUTER_WINDOW_READY_TIMEOUT": return "Automatic application preparation did not produce a verified ready window within five seconds. No task input was sent during preparation. Report the preparation failure and inspect local diagnostics. Resume only after a relevant application or desktop state change; do not repeat activation unchanged or bypass the window checks.";
+		case "COMPUTER_APP_PREPARATION_REFUSED": return "The desktop host could not complete the authorized system application-open request. No task input was sent. Inspect application availability and local host state before retrying; do not replace the request with paths, URLs or arbitrary command arguments.";
+		case "COMPUTER_APP_ID_INVALID": return "The application identity is not a valid native bundle identifier. Discover the intended application again and use its issued appRef; do not ask the user to supply a bundle id or substitute a path or URL.";
+		case "COMPUTER_CAPTURE_UNAVAILABLE":
+		case "COMPUTER_CAPTURE_REQUIRED": return "The selected window could not provide a usable screenshot after bounded capture attempts. This does not establish missing permissions or another desktop. Inspect its visibility and the action receipt; a completed input must not be replayed. Reopen and observe after a local state change.";
+		case "COMPUTER_CAPTURE_TARGET_MISMATCH": return "The captured native window does not match the selected target. Control is stopped. Select the intended window again; do not reuse refs, coordinates or replay prior inputs.";
+		case "COMPUTER_BACKGROUND_INPUT_UNSUPPORTED": return "The native driver explicitly reports that this input cannot be delivered in the background. Complete this step manually; do not switch to foreground/global injection or replay it.";
+		case "COMPUTER_INPUT_REFUSED": return "The application refused this input without an established cause. Inspect the receipt and actual result; do not infer that foreground focus will fix it or automatically replay input.";
 		case "COMPUTER_WINDOWS_TEXT_INPUT_UNVERIFIED":
 		case "COMPUTER_WINDOWS_KEY_INPUT_UNVERIFIED": return "This Windows control cannot be certified for safe input. Ask the user to enter text manually. Do not substitute key presses, paste, shell commands, coordinates or another tool to bypass this refusal.";
 		case "COMPUTER_WINDOWS_KEY_TARGET_REQUIRED": return "Keyboard input requires one verified non-password control focused inside the authorized window. Observe or focus the intended safe control before a new proposal; never send keys to another window or bypass the refusal with global input.";
@@ -103,11 +160,10 @@ function computerRecovery(code) {
 		case "COMPUTER_READ_ONLY": return "This session is read-only. Do not retry an action or reopen in control mode without user authorization.";
 		case "COMPUTER_DEVICE_BUSY":
 		case "COMPUTER_BUSY": return "Another desktop operation is active. Wait for it to finish; do not stop another task.";
-		case "COMPUTER_CONTROL_PAUSED":
-		case "COMPUTER_LOCAL_UI_REQUIRED": return "Ask the user to resume desktop control locally. Do not automatically resume or bypass this stop.";
+		case "COMPUTER_LOCAL_UI_REQUIRED": return "Ask the user to show the xopc desktop window before starting a new desktop task.";
 		case "COMPUTER_OS_PERMISSION_REQUIRED": return "Check local desktop access. On macOS, review Accessibility and Screen Recording. On Windows, use the signed-in interactive desktop and inspect the driver diagnostic; do not request macOS permissions or automatically elevate privileges.";
 		default: return "Do not repeat the same call without a state change. Report this error; never bypass desktop restrictions with shell or other tools.";
 	}
 }
 //#endregion
-export { ComputerDiagnosticSchema, ComputerOperationError, ComputerTargetError, computerDiagnostic, computerRecovery };
+export { ComputerDiagnosticSchema, ComputerOperationError, ComputerRecoverySchema, ComputerTargetError, computerDiagnostic, computerRecovery, computerRecoveryDirective };

package/dist/src/computer/model-adapter.d.ts

@@ -56,6 +56,64 @@ export declare const ComputerProposalSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"wait">;
         durationMs: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"activateSequence">;
+        refs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"batch">;
+        actions: z.ZodArray<z.ZodDiscriminatedUnion<[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>], "kind">>;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"finished">;