@xopcai/xopc 0.0.433 → 0.0.434

package/dist/src/agent-catalog/repository.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
-import { DEFAULT_AGENT_ID, init_id, normalizeAgentId } from "./id.js";
 import { AgentDefaultsSchema, AgentEntrySchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_SKILL_POLICY } from "../agent-config/schema.js";
 import { init_agent_config } from "../agent-config/index.js";
+import { DEFAULT_AGENT_ID, init_id, normalizeAgentId } from "./id.js";
 import { BindingsSchema, init_binding_schema } from "../routing/binding-schema.js";
 import { randomUUID } from "node:crypto";
 //#region src/agent-catalog/repository.ts

package/dist/src/agent-matching/service.js

@@ -2,7 +2,7 @@ import { normalizeSpecialistRequirements } from "../../packages/gateway-contract
 import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { getAvailablePersonalAgentTools, personalAgentModelAvailability } from "../personal-agent/specialist-capabilities.js";
+import { allowsPersonalAgentTool, getAvailablePersonalAgentTools, personalAgentModelAvailability } from "../personal-agent/specialist-capabilities.js";
 //#region src/agent-matching/service.ts
 init_repository();
 init_agent_config();
@@ -37,7 +37,7 @@ function assessSpecialist(agentId, input, context) {
 			add(`tool:${tool}`, "blocked", "agent_unavailable");
 			continue;
 		}
-		if (!(config && config.tools[tool]?.mode !== "deny" && (!config.toolAllowlist || config.toolAllowlist.includes(tool)))) add(`tool:${tool}`, "blocked", "tool_unavailable");
+		if (!(config && allowsPersonalAgentTool(config, tool))) add(`tool:${tool}`, "blocked", "tool_unavailable");
 		else {
 			let check;
 			try {

package/dist/src/automations/api/routes.js

@@ -1,9 +1,9 @@
 import { AutomationCancelOutputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRunMutationOutputSchema, ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
-import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
-import { getAutomationSetup, openAutomationConfiguration } from "../configuration-conversation.js";
 import "../../capabilities/runtime/dispatcher.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
+import { getAutomationSetup, openAutomationConfiguration } from "../configuration-conversation.js";
 import { createProductDispatcher } from "../../capabilities/runtime/product.js";
 import { capabilityHttpContext, capabilityHttpError } from "../../capabilities/adapters/http.js";
 import { randomUUID } from "node:crypto";

package/dist/src/automations/capabilities/drafts.js

@@ -3,10 +3,10 @@ import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { resolveAutomationSafetyForTrust } from "../../user-context/trust-policy.js";
 import { getUserTrustPolicy } from "../../storage/sqlite/user-trust-repository.js";
 import "../../storage/sqlite/index.js";
-import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError } from "../../capabilities/runtime/external-operations.js";
 import { defineExternalCapability, defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
 import { AutomationCreateCapabilityInputSchema, materializeAutomationTrigger } from "./write.js";
 import { simulateAutomation } from "../draft/automation-draft-validator.js";
 import { AutomationDraftService } from "../draft/automation-draft-service.js";

package/dist/src/automations/capabilities/write.js

@@ -1,6 +1,7 @@
 import { AutomationCancelOutputSchema, AutomationDeleteInputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllInputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRecoveryOutputSchema, AutomationReplayEventInputSchema, AutomationRetryDeliveryInputSchema, AutomationRunMutationOutputSchema, AutomationSetEnabledInputSchema, CapabilityResourceInputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
 import { AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "../domain/validation.js";
 import { getAutomation } from "../storage/automation-repository.js";
 import { getAutomationRun, markAllAutomationRunsRead, markAutomationRunRead } from "../storage/automation-run-repository.js";
@@ -8,7 +9,6 @@ import "../storage/index.js";
 import { getAutomationEventForRun } from "../events/event-repository.js";
 import "../events/index.js";
 import { assertAutomationSetupTarget, bindAutomationSetup } from "../configuration-conversation.js";
-import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
 import { AutomationAlreadyExistsError, AutomationAlreadyRunningError, AutomationInvalidAgentError, AutomationInvalidScheduleError, AutomationInvalidSourceError } from "../service/automation-service.js";
 import { z } from "zod";
 //#region src/automations/capabilities/write.ts

package/dist/src/automations/configuration-conversation.js

@@ -3,9 +3,9 @@ import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_session_repository, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
 import "../storage/sqlite/index.js";
+import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { init_agent_scope, listAgentEntries } from "../agent/agent-scope.js";
 import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
-import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { getAutomation } from "./storage/automation-repository.js";
 import { getAutomationRun, listAutomationRuns } from "./storage/automation-run-repository.js";
 import { listAutomationResultDeliveries } from "./delivery/delivery-router.js";

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

@@ -13,8 +13,8 @@ import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync,
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
-import AdmZip from "adm-zip";
 import { readFile, readdir, rm } from "node:fs/promises";
+import AdmZip from "adm-zip";
 //#region src/browser/providers/browser-ext-install.ts
 /**
 * Install bundled Chrome extension artifacts into {resolveBinDir()}/browser-ext/.

package/dist/src/capabilities/runtime/dispatcher.js

@@ -1,7 +1,7 @@
 import { SqliteCommitEffectError, init_transaction } from "../../storage/sqlite/transaction.js";
+import { OperationConflictError, executeAtomicOperation } from "./atomic-operations.js";
 import { CapabilityError } from "./errors.js";
 import { executeExternalOperation } from "./external-operations.js";
-import { OperationConflictError, executeAtomicOperation } from "./atomic-operations.js";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 //#region src/capabilities/runtime/dispatcher.ts

package/dist/src/capabilities/runtime/product.js

@@ -1,5 +1,6 @@
 import { CapabilityError } from "./errors.js";
 import { CapabilityDispatcher } from "./dispatcher.js";
+import { registerAgentCapabilities } from "../../agent-catalog/capabilities.js";
 import { registerLocalAppReadCapabilities } from "../../local-apps/capabilities/read.js";
 import { registerNoteReadCapabilities } from "../../notes/capabilities/read.js";
 import { registerNoteWriteCapabilities } from "../../notes/capabilities/write.js";
@@ -16,7 +17,6 @@ import { registerAutomationDraftCapabilities } from "../../automations/capabilit
 import { registerTaskWriteCapabilities } from "../../tasks/capabilities/write.js";
 import { registerSettingsCapability } from "./settings.js";
 import { registerAppContextCapability } from "./app-context.js";
-import { registerAgentCapabilities } from "../../agent-catalog/capabilities.js";
 //#region src/capabilities/runtime/product.ts
 function createProductDispatcher(getNotes, taskWrites) {
 	const dispatcher = new CapabilityDispatcher();

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

@@ -1,8 +1,8 @@
 import { normalizeAgentId, validateAgentIdForNewAgent } from "../../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
 import { init_agent_scope, resolveAgentDir, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agent/agent-scope.js";
-import { resolveEffectiveAgentConfigForAgent } from "../../config/agent-profile.js";
 import { AgentCatalogService } from "../../agent-catalog/service.js";
+import { resolveEffectiveAgentConfigForAgent } from "../../config/agent-profile.js";
 import { colors } from "../utils/colors.js";
 //#region src/cli/commands/agents.ts
 init_repository();

package/dist/src/cli/commands/doctor/checks/database-schema.js

@@ -31,7 +31,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${readSchemaVersion(getSqliteDatabase())} (current release v261).`,
+		message: `SQLite schema v${readSchemaVersion(getSqliteDatabase())} (current release v262).`,
 		hints: []
 	};
 }

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

@@ -1,11 +1,11 @@
 import { creditDecimal } from "../../../packages/gateway-contract/src/cloud-credits.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
+import { AgentCatalogService } from "../../agent-catalog/service.js";
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
 import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { getAllModels, getAvailableModels, getConfiguredProviders, getProviderAuthState, getProviderDisplayName, init_providers, isProviderConfigured, providerSupportsApiKey, providerSupportsOAuth, resolveModel } from "../../providers/index.js";
 import { XopcCloudAccountService } from "../../providers/xopc-cloud-account-service.js";
-import { AgentCatalogService } from "../../agent-catalog/service.js";
 import { listImageProviderSpecs } from "../../../packages/image-providers/src/catalog.js";
 import "../../../packages/image-providers/src/index.js";
 import { loadConfig } from "../../config/loader.js";

package/dist/src/cli/commands/onboard/model.js

@@ -1,4 +1,5 @@
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
+import { AgentCatalogService } from "../../../agent-catalog/service.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
 import { ConfigSchema, getAgentDefaultModelRef, init_schema } from "../../../config/schema.js";
 import { init_models_json, loadModelsJson, saveModelsJson } from "../../../config/models-json.js";
@@ -6,7 +7,6 @@ import { getApiKeyFromEnv } from "../../../providers/env-keys.js";
 import { getModelRegistry } from "../../../providers/model-registry.js";
 import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
 import { getAllProviders, getModelsByProvider, getProviderDisplayName, init_providers, providerSupportsApiKey, providerSupportsOAuth } from "../../../providers/index.js";
-import { AgentCatalogService } from "../../../agent-catalog/service.js";
 import { prepareUpdateGlobalDefaults } from "../../../gateway/global-defaults-admin.js";
 import { discoverProviderModels, isProviderApiDiscoverable } from "../../../providers/model-discovery.js";
 import { getXopcCloudCatalogCoordinator } from "../../../providers/xopc-cloud-catalog-coordinator.js";

package/dist/src/cli/utils/init-workspace-core.js

@@ -1,6 +1,6 @@
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
-import { ConfigSchema, init_schema } from "../../config/schema.js";
 import { AgentCatalogService } from "../../agent-catalog/service.js";
+import { ConfigSchema, init_schema } from "../../config/schema.js";
 import { readConfigFileSnapshot } from "../../config/config-file.js";
 import { saveConfig } from "../../config/loader.js";
 import { ensureStarterAgentsInitialized } from "../../agent/starter-agents.js";

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,13 @@ 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;
+    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 +49,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 +73,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 +111,22 @@ 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>;
     dispose(): Promise<void>;
 }
 export {};