@xopcai/xopc 0.0.286 → 0.0.291

package/dist/src/auth/profiles/store.js

@@ -1,5 +1,5 @@
-import { init_paths, resolveCredentialsDir } from "../../config/paths.js";
 import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { init_paths, resolveCredentialsDir } from "../../config/paths.js";
 import path from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 //#region src/auth/profiles/store.ts

package/dist/src/auth/sync-provider-auth.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { init_paths, resolveAgentAuthProfilesPath, resolveAuthProfilesPath, resolveOAuthPath } from "../config/paths.js";
-import { init_loader, loadConfig } from "../config/loader.js";
 import { init_registry, isOAuthOnlyProvider } from "./oauth/registry.js";
+import { init_loader, loadConfig } from "../config/loader.js";
+import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/auth/sync-provider-auth.ts
 /**

package/dist/src/browser/providers/browser-ext-install.js

@@ -2,8 +2,8 @@ import { PACKAGE_VERSION, init_package_version } from "../../package-version.js"
 import { resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { init_paths, resolveBinDir, resolveConfigPath } from "../../config/paths.js";
 import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
+import { init_paths, resolveBinDir, resolveConfigPath } from "../../config/paths.js";
 import { assertCacheDir } from "../cache-dir-policy.js";
 import { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME } from "../extension-identity.js";
 import "../native-messaging-host.js";

package/dist/src/capabilities/readiness/from-config.js

@@ -1,6 +1,7 @@
 import { getAgentDefaultImageGenerationModelConfig, getAgentDefaultImageModelConfig, init_schema, parseModelRef } from "../../config/schema.js";
+import { init_model_policy, isComputerModel } from "../../computer/model-policy.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../providers/model-catalog-store.js";
-import { init_providers, isProviderConfiguredSync } from "../../providers/index.js";
+import { init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
 import { compareCatalogModels } from "../../providers/model-catalog-ranking.js";
 import { DEFAULT_LOCAL_VOICE_MODEL_ID, hasInstalledLocalVoiceModel } from "../../voice/local/models.js";
 import { planCapabilities } from "./planner.js";
@@ -8,6 +9,7 @@ import { planCapabilities } from "./planner.js";
 init_schema();
 init_model_catalog_store();
 init_providers();
+init_model_policy();
 function buildCapabilityPlansForConfig(config, options = {}) {
 	const catalog = options.catalog ?? getModelCatalogStore().load();
 	const cloud = catalog.sources["xopc-cloud"];
@@ -18,6 +20,7 @@ function buildCapabilityPlansForConfig(config, options = {}) {
 	const tts = config.messages?.tts;
 	const policies = {
 		vision: { explicit: refs(getAgentDefaultImageModelConfig(config)) },
+		"computer-use": { explicit: refs(config.agents.defaults.models.computerUse) },
 		"image-generation": { explicit: refs(getAgentDefaultImageGenerationModelConfig(config, agentId)) },
 		stt: {
 			disabled: stt?.enabled === false,
@@ -92,6 +95,11 @@ function markExplicitReadiness(policies, catalog, providerReady) {
 }
 function explicitReady(capability, provider, model, catalog, providerReady) {
 	if (!providerReady(provider)) return false;
+	if (capability === "computer-use" && provider !== "xopc-cloud") try {
+		return isComputerModel(resolveModel(`${provider}/${model}`));
+	} catch {
+		return false;
+	}
 	if (provider !== "xopc-cloud") return true;
 	return (catalog.sources["xopc-cloud"]?.models ?? []).some((entry) => entry.id === model && matchesCapability(entry, capability));
 }
@@ -106,7 +114,11 @@ function cloudCandidates(capability, models, authorized, basePriority = 0, recom
 function matchesCapability(model, capability) {
 	if (model.availability !== "available") return false;
 	switch (capability) {
-		case "vision": return model.kind === "language" && model.input.includes("image");
+		case "vision": return model.kind === "language" && model.input.includes("image") && !model.computerUse;
+		case "computer-use": return model.operations.includes("chat.completions") && isComputerModel({
+			...model,
+			api: "openai-completions"
+		});
 		case "image-generation": return model.kind === "image" && model.operations.includes("images.generate");
 		case "stt": return model.kind === "stt" && model.operations.includes("audio.transcription");
 		case "tts": return model.kind === "tts" && model.operations.includes("audio.speech") && Boolean(model.tts?.defaultVoice);

package/dist/src/capabilities/readiness/planner.js

@@ -3,7 +3,8 @@ const CAPABILITIES = [
 	"vision",
 	"image-generation",
 	"stt",
-	"tts"
+	"tts",
+	"computer-use"
 ];
 function planCapabilities(input) {
 	return Object.fromEntries(CAPABILITIES.map((capability) => [capability, planCapability(capability, input)]));
@@ -28,7 +29,7 @@ function planCapability(capability, input) {
 		reasons: entry.reasons ?? (entry.ready === false ? ["explicit_model_unavailable"] : [])
 	}));
 	const automatic = [...input.automatic[capability] ?? []].sort((left, right) => left.priority - right.priority || left.provider.localeCompare(right.provider) || left.model.localeCompare(right.model));
-	const candidates = dedupeCandidates([...explicit, ...automatic]);
+	const candidates = capability === "computer-use" ? explicit.slice(0, 1) : dedupeCandidates([...explicit, ...automatic]);
 	const ready = candidates.filter((candidate) => candidate.ready);
 	const rejected = candidates.filter((candidate) => !candidate.ready);
 	const primary = ready[0];

package/dist/src/capabilities/readiness/types.d.ts

@@ -1,4 +1,4 @@
-export type CapabilityId = 'vision' | 'image-generation' | 'stt' | 'tts';
+export type CapabilityId = 'vision' | 'image-generation' | 'stt' | 'tts' | 'computer-use';
 export type CandidateSource = 'native-model' | 'explicit-config' | 'installed-local' | 'xopc-cloud-managed' | 'configured-provider' | 'credentialless-fallback';
 export interface CapabilityCandidate {
     capability: CapabilityId;

package/dist/src/chat-commands/agent-edit.js

@@ -1,6 +1,6 @@
 import { init_agent_scope, normalizeAgentId, resolveAgentProfileDir } from "../agent/agent-scope.js";
-import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
+import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { commandRegistry } from "./registry.js";
 import { join } from "node:path";
 import { readFile } from "node:fs/promises";

package/dist/src/cli/commands/agent.js

@@ -2,8 +2,8 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
-import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
 import { loadConfig } from "../../config/loader.js";
+import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
 import { ExtensionLoader } from "../../extensions/loader.js";
 import "../../extensions/index.js";
 import { MessageBus, MessageBusShutdownError } from "../../infra/bus/queue.js";

package/dist/src/cli/commands/doctor/checks/provider-auth.js

@@ -1,9 +1,9 @@
 import { getAgentDefaultModelRef, init_schema, parseModelRef } from "../../../../config/schema.js";
-import { getDefaultAgentId, init_resolve_route } from "../../../../routing/resolve-route.js";
-import { init_loader, loadConfig } from "../../../../config/loader.js";
-import { getModelOAuthProviderIds, init_registry } from "../../../../auth/oauth/registry.js";
 import { PROVIDER_ENV_MAP, init_env_keys } from "../../../../providers/env-keys.js";
+import { getModelOAuthProviderIds, init_registry } from "../../../../auth/oauth/registry.js";
 import { CredentialResolver, init_credentials } from "../../../../auth/credentials.js";
+import { init_loader, loadConfig } from "../../../../config/loader.js";
+import { getDefaultAgentId, init_resolve_route } from "../../../../routing/resolve-route.js";
 import { existsSync } from "node:fs";
 //#region src/cli/commands/doctor/checks/provider-auth.ts
 init_credentials();

package/dist/src/cli/commands/models.js

@@ -1,6 +1,6 @@
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
-import { loadConfig, saveConfig } from "../../config/loader.js";
 import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
+import { loadConfig, saveConfig } from "../../config/loader.js";
 import { getAllModels, getAvailableModels, getConfiguredProviders, getProviderAuthState, getProviderDisplayName, init_providers, isProviderConfigured, providerSupportsApiKey, providerSupportsOAuth, resolveModel } from "../../providers/index.js";
 import { formatExamples, register } from "../registry.js";
 import { getContextWithOpts } from "../context.js";

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

@@ -0,0 +1,97 @@
+import { type ComputerAction, type ComputerCommand, type ComputerModelBinding, type ComputerObservation, type ComputerReceipt, type ComputerTarget, type ComputerApp, type ComputerWindow } from '@xopcai/computer-control-contract';
+import { type ComputerConfig } from './config.js';
+export interface DriverObservation {
+    target: ComputerTarget;
+    summary: string;
+    focusedEditableRef?: string;
+    stateDigest: string;
+    image: Uint8Array;
+    mimeType: 'image/png' | 'image/jpeg';
+    imageWidth: number;
+    imageHeight: number;
+}
+export interface ComputerDriver {
+    discover(query: string, signal: AbortSignal): Promise<Array<{
+        appId: string;
+        name: string;
+        running: boolean;
+    }>>;
+    validateAction?(action: ComputerAction): void;
+    resolveTarget(appId: string, signal: AbortSignal, options: {
+        prepare: boolean;
+        windowRef?: string;
+    }): Promise<ComputerTarget>;
+    observe(target: ComputerTarget, signal: AbortSignal): Promise<DriverObservation>;
+    perform(target: ComputerTarget, action: ComputerAction, signal: AbortSignal): Promise<void>;
+    /** Must finish only after no further input can be dispatched. */
+    stop(): Promise<void>;
+}
+export type ComputerApproval = {
+    kind: 'session';
+    id: string;
+    appId: string;
+    appName: string;
+    mode: 'observe' | 'control';
+    prepare: boolean;
+    model: ComputerModelBinding;
+} | {
+    kind: 'action';
+    id: string;
+    target: ComputerTarget;
+    action: ComputerAction;
+};
+export interface ComputerBrokerHost {
+    requestApproval(request: ComputerApproval, signal: AbortSignal): Promise<boolean>;
+    isVisible(): boolean;
+    hasFullControl?(): boolean;
+    onStateChange?(): void;
+}
+type Status = 'pending_authorization' | 'ready' | 'running' | 'pending_action' | 'paused' | 'stopped';
+export interface BrokerResult {
+    status: Status;
+    sessionId: string;
+    brokerEpoch: string;
+    generation: number;
+    grantId?: string;
+    observation?: ComputerObservation;
+    receipt?: ComputerReceipt;
+    errorCode?: string;
+    apps?: ComputerApp[];
+    windows?: ComputerWindow[];
+    frame?: {
+        bytes: Uint8Array;
+        mimeType: 'image/png' | 'image/jpeg';
+    };
+}
+/** Main-process-only authority. Never expose this object or its approval hook to a renderer. */
+export declare class ComputerBroker {
+    private readonly driver;
+    private readonly host;
+    private readonly now;
+    readonly epoch: `${string}-${string}-${string}-${string}-${string}`;
+    private session?;
+    private busy;
+    private stopping?;
+    private discovery?;
+    private readonly apps;
+    private readonly config;
+    private readonly timer;
+    constructor(driver: ComputerDriver, host: ComputerBrokerHost, config?: Partial<ComputerConfig>, now?: () => number);
+    private expired;
+    private result;
+    private active;
+    command(raw: ComputerCommand): Promise<BrokerResult>;
+    private discover;
+    private open;
+    private observe;
+    private act;
+    stop(): Promise<void>;
+    cancel(command: ComputerCommand): Promise<void>;
+    snapshot(): {
+        status: Status | 'idle';
+        errorCode?: string;
+        appId?: string;
+    };
+    dispose(): Promise<void>;
+}
+export {};

package/dist/src/computer/broker.js

@@ -0,0 +1,337 @@
+import { ComputerConfigSchema, init_config } from "./config.js";
+import { ActionEnvelopeSchema, ComputerCommandSchema, init_src } from "../../packages/computer-control-contract/src/index.js";
+import { ComputerTargetError } from "./errors.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/computer/broker.ts
+init_src();
+init_config();
+/** Main-process-only authority. Never expose this object or its approval hook to a renderer. */
+var ComputerBroker = class {
+	epoch = randomUUID();
+	session;
+	busy = false;
+	stopping;
+	discovery;
+	apps = /* @__PURE__ */ new Map();
+	config;
+	timer;
+	constructor(driver, host, config = {}, now = Date.now) {
+		this.driver = driver;
+		this.host = host;
+		this.now = now;
+		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(() => {});
+		}, 1e3);
+		this.timer.unref?.();
+	}
+	expired(s) {
+		return this.now() - s.createdAt >= this.config.maxSessionDurationMs || this.now() - s.touchedAt >= this.config.idleGrantTtlMs;
+	}
+	result(s) {
+		return {
+			sessionId: s.id,
+			brokerEpoch: this.epoch,
+			generation: s.generation,
+			status: s.status,
+			...s.errorCode ? { errorCode: s.errorCode } : {},
+			...s.windows ? { windows: s.windows } : {},
+			...s.status === "ready" ? { grantId: s.grantId } : {}
+		};
+	}
+	active(s) {
+		if (this.session !== s || s.controller.signal.aborted || this.expired(s) || !this.host.isVisible()) throw new Error("COMPUTER_GRANT_REVOKED");
+	}
+	async command(raw) {
+		const command = ComputerCommandSchema.parse(raw);
+		if (command.op === "discover") return this.discover(command);
+		if (command.op === "open") return this.open(command);
+		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();
+			return this.result(s);
+		}
+		if (command.op === "status") 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;
+		try {
+			if (command.op === "observe") {
+				if (s.pending) throw new Error("COMPUTER_ACTION_PENDING");
+				return await this.observe(s);
+			}
+			return await this.act(s, command.envelope);
+		} finally {
+			this.busy = false;
+			this.host.onStateChange?.();
+		}
+	}
+	async discover(command) {
+		if (!this.config.enabled) throw new Error("COMPUTER_DISABLED");
+		if (!this.host.isVisible()) throw new Error("COMPUTER_LOCAL_UI_REQUIRED");
+		if (this.busy || this.discovery || this.stopping || this.session && this.session.status !== "stopped" && (this.session.owner !== command.owner || this.session.status !== "ready")) throw new Error("COMPUTER_BUSY");
+		const controller = new AbortController();
+		this.discovery = {
+			controller,
+			owner: command.owner,
+			id: command.sessionId
+		};
+		this.busy = true;
+		try {
+			const found = await this.driver.discover(command.query, controller.signal);
+			controller.signal.throwIfAborted();
+			if (!this.host.isVisible()) throw new Error("COMPUTER_LOCAL_UI_REQUIRED");
+			for (const [ref, app] of this.apps) if (app.owner === command.owner || app.expires <= this.now()) this.apps.delete(ref);
+			const apps = found.slice(0, 100).map((app) => {
+				const appRef = randomUUID();
+				this.apps.set(appRef, {
+					owner: command.owner,
+					appId: app.appId,
+					name: app.name,
+					expires: this.now() + 3e5
+				});
+				return {
+					appRef,
+					name: app.name,
+					running: app.running
+				};
+			});
+			while (this.apps.size > 500) this.apps.delete(this.apps.keys().next().value);
+			return {
+				status: "ready",
+				sessionId: command.sessionId,
+				brokerEpoch: this.epoch,
+				generation: 0,
+				apps
+			};
+		} finally {
+			try {
+				if (!this.session || this.session.status === "stopped") await this.driver.stop();
+			} finally {
+				this.discovery = void 0;
+				this.busy = false;
+			}
+		}
+	}
+	async open(command) {
+		if (!this.config.enabled) throw new Error("COMPUTER_DISABLED");
+		if (!this.host.isVisible()) throw new Error("COMPUTER_LOCAL_UI_REQUIRED");
+		if (this.stopping) throw new Error("COMPUTER_STOPPING");
+		if (this.discovery || this.busy) throw new Error("COMPUTER_BUSY");
+		if (this.session && this.session.status !== "stopped") {
+			const s = this.session;
+			if (s.id !== command.sessionId || s.owner !== command.owner || s.appRef !== command.appRef || s.mode !== command.mode || s.prepare !== command.prepare || s.windowRef !== command.windowRef || JSON.stringify(s.model) !== JSON.stringify(command.model)) throw new Error("COMPUTER_DEVICE_BUSY");
+			return this.result(s);
+		}
+		const app = this.apps.get(command.appRef);
+		if (!app || app.owner !== command.owner || app.expires <= this.now()) throw new Error("COMPUTER_APP_REF_EXPIRED");
+		const s = {
+			id: command.sessionId,
+			owner: command.owner,
+			appId: app.appId,
+			model: command.model,
+			appRef: command.appRef,
+			mode: command.mode,
+			prepare: command.prepare,
+			windowRef: command.windowRef,
+			grantId: randomUUID(),
+			generation: 0,
+			status: "pending_authorization",
+			createdAt: this.now(),
+			touchedAt: this.now(),
+			controller: new AbortController(),
+			receipts: /* @__PURE__ */ new Map(),
+			actions: 0
+		};
+		this.session = s;
+		const fullControl = this.host.hasFullControl?.() === true;
+		const authorization = (fullControl ? Promise.resolve(true) : this.host.requestApproval({
+			kind: "session",
+			id: s.id,
+			appId: s.appId,
+			appName: app.name,
+			mode: s.mode,
+			prepare: s.prepare,
+			model: s.model
+		}, s.controller.signal)).then(async (approved) => {
+			this.active(s);
+			if (!approved) {
+				await this.stop();
+				return;
+			}
+			s.target = await this.driver.resolveTarget(s.appId, s.controller.signal, {
+				prepare: s.prepare,
+				windowRef: s.windowRef
+			});
+			this.active(s);
+			if (s.target.appId !== s.appId) throw new Error("COMPUTER_TARGET_MISMATCH");
+			s.status = "ready";
+			s.touchedAt = this.now();
+		}).catch((error) => {
+			if (this.session !== s) return;
+			s.errorCode = error instanceof Error && /^COMPUTER_[A-Z_]+$/.test(error.message) ? error.message : "COMPUTER_NATIVE_SETUP_FAILED";
+			if (error instanceof ComputerTargetError) s.windows = error.windows;
+			return this.stop().catch(() => {});
+		}).finally(() => this.host.onStateChange?.());
+		if (fullControl) await authorization;
+		return this.result(s);
+	}
+	async observe(s) {
+		const frame = await this.driver.observe(s.target, s.controller.signal);
+		try {
+			this.active(s);
+			if (frame.target.appId !== s.appId || frame.target.processIdentity !== s.target.processIdentity || frame.target.windowId !== s.target.windowId) throw new Error("COMPUTER_TARGET_CHANGED");
+			if (frame.image.byteLength > 5 * 1024 * 1024 || frame.imageWidth * frame.imageHeight > 16e6) throw new Error("COMPUTER_FRAME_LIMIT");
+			s.target = frame.target;
+			s.observation = {
+				id: randomUUID(),
+				sessionId: s.id,
+				brokerEpoch: this.epoch,
+				generation: s.generation,
+				target: frame.target,
+				capturedAt: this.now(),
+				imageWidth: frame.imageWidth,
+				imageHeight: frame.imageHeight,
+				summary: frame.summary.slice(0, 12e3),
+				focusedEditableRef: frame.focusedEditableRef,
+				stateDigest: frame.stateDigest
+			};
+			s.touchedAt = this.now();
+			return {
+				...this.result(s),
+				observation: s.observation,
+				frame: {
+					bytes: frame.image,
+					mimeType: frame.mimeType
+				}
+			};
+		} catch (error) {
+			frame.image.fill(0);
+			throw error;
+		}
+	}
+	async act(s, raw) {
+		if (s.mode === "observe") throw new Error("COMPUTER_READ_ONLY");
+		const e = ActionEnvelopeSchema.parse(raw);
+		if (e.sessionId !== s.id || e.brokerEpoch !== this.epoch || e.generation !== s.generation || e.grantId !== s.grantId || e.deadlineAt <= this.now()) throw new Error("COMPUTER_STALE_ACTION");
+		const digest = createHash("sha256").update(JSON.stringify(e)).digest("hex");
+		const previous = s.receipts.get(e.actionId);
+		if (previous) {
+			if (previous.digest !== digest) throw new Error("COMPUTER_ACTION_ID_REUSED");
+			return {
+				...this.result(s),
+				receipt: previous.receipt
+			};
+		}
+		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 ("point" in e.action && e.action.point && (e.action.point.x >= observed.imageWidth || e.action.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");
+		this.driver.validateAction?.(e.action);
+		if (e.action.kind !== "wait" && !this.host.hasFullControl?.()) {
+			if (!s.pending) {
+				s.pending = {
+					envelope: e,
+					digest
+				};
+				s.status = "pending_action";
+				this.host.requestApproval({
+					kind: "action",
+					id: e.actionId,
+					target: observed.target,
+					action: e.action
+				}, 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);
+			}
+			if (s.pending.digest !== digest) throw new Error("COMPUTER_DIFFERENT_ACTION_PENDING");
+			if (s.pending.approved === void 0) return this.result(s);
+			if (!s.pending.approved) {
+				await this.stop();
+				return this.result(s);
+			}
+		}
+		const current = await this.driver.observe(s.target, s.controller.signal);
+		try {
+			this.active(s);
+			if (JSON.stringify(current.target) !== JSON.stringify(observed.target) || current.stateDigest !== observed.stateDigest || e.deadlineAt <= this.now()) {
+				s.pending = void 0;
+				s.observation = void 0;
+				s.status = "ready";
+				throw new Error("COMPUTER_APPROVAL_TARGET_CHANGED");
+			}
+			this.driver.validateAction?.(e.action);
+		} finally {
+			current.image.fill(0);
+		}
+		const receipt = {
+			actionId: e.actionId,
+			dispatch: "started",
+			outcome: "unknown",
+			verification: "none"
+		};
+		s.receipts.set(e.actionId, {
+			digest,
+			receipt
+		});
+		s.actions++;
+		s.pending = void 0;
+		s.status = "running";
+		try {
+			await this.driver.perform(s.target, e.action, s.controller.signal);
+			this.active(s);
+			receipt.dispatch = "completed";
+			s.status = "ready";
+			const after = await this.observe(s);
+			receipt.verification = after.observation ? "visual" : "none";
+			return {
+				...after,
+				receipt
+			};
+		} catch {
+			receipt.dispatch = "unknown";
+			await this.stop();
+			return {
+				...this.result(s),
+				receipt
+			};
+		}
+	}
+	stop() {
+		this.discovery?.controller.abort();
+		const s = this.session;
+		if (s && s.status !== "stopped") {
+			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(() => {
+			this.stopping = void 0;
+			this.host.onStateChange?.();
+		});
+		return this.stopping;
+	}
+	async cancel(command) {
+		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() {
+		return this.session ? {
+			status: this.session.status,
+			errorCode: this.session.errorCode,
+			appId: this.session.appId
+		} : { status: "idle" };
+	}
+	async dispose() {
+		clearInterval(this.timer);
+		await this.stop();
+	}
+};
+//#endregion
+export { ComputerBroker };

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

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const ComputerConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    maxActionsPerSession: z.ZodDefault<z.ZodNumber>;
+    maxModelRequests: z.ZodDefault<z.ZodNumber>;
+    maxSessionDurationMs: z.ZodDefault<z.ZodNumber>;
+    idleGrantTtlMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>>;
+export type ComputerConfig = z.infer<typeof ComputerConfigSchema>;

package/dist/src/computer/config.js

@@ -0,0 +1,16 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { z } from "zod";
+//#region src/computer/config.ts
+var ComputerConfigSchema;
+var init_config = __esmMin((() => {
+	ComputerConfigSchema = z.object({
+		enabled: z.boolean().default(false),
+		maxActionsPerSession: z.number().int().min(1).max(80).default(80),
+		maxModelRequests: z.number().int().min(1).max(120).default(120),
+		maxSessionDurationMs: z.number().int().min(1e3).max(9e5).default(9e5),
+		idleGrantTtlMs: z.number().int().min(1e3).max(3e5).default(3e5)
+	}).strict().prefault({});
+}));
+//#endregion
+init_config();
+export { ComputerConfigSchema, init_config };

package/dist/src/computer/control-guard.d.ts

@@ -0,0 +1,4 @@
+export declare function enterComputerControl(owner: string, close: () => Promise<void>): void;
+export declare function leaveComputerControl(owner: string): void;
+export declare function isComputerControlActive(owner: string): boolean;
+export declare function stopComputerControl(owner: string): Promise<void>;

package/dist/src/computer/control-guard.js

@@ -0,0 +1,17 @@
+//#region src/computer/control-guard.ts
+/** Process-local admission gate; authority itself remains in the desktop broker. */
+const owners = /* @__PURE__ */ new Map();
+function enterComputerControl(owner, close) {
+	owners.set(owner, close);
+}
+function leaveComputerControl(owner) {
+	owners.delete(owner);
+}
+function isComputerControlActive(owner) {
+	return owners.has(owner);
+}
+async function stopComputerControl(owner) {
+	await owners.get(owner)?.();
+}
+//#endregion
+export { enterComputerControl, isComputerControlActive, leaveComputerControl, stopComputerControl };

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

@@ -0,0 +1,7 @@
+import type { ComputerWindow } from '@xopcai/computer-control-contract';
+export declare class ComputerTargetError extends Error {
+    readonly windows: ComputerWindow[];
+    constructor(code: string, windows?: ComputerWindow[]);
+}
+/** Recovery instructions are deterministic; never replay an input with unknown delivery. */
+export declare function computerRecovery(code: string): string;