@xopcai/xopc 0.0.415 → 0.0.416

package/dist/src/agent/tool-manuals/xopc-configuration.js

@@ -18,6 +18,31 @@ requested change once with the new revision and a new intent key. After an uncer
 inspect first and retain the original idempotency key. A permission denial is not a conflict:
 do not switch identity, target or tools to bypass it. Inspect returned product ok and saved
 fields before reporting success. A saved model reference does not prove it can be called.`,
+	phone_setup: `# Phone setup
+Use configure-xopc and references/phone/overview.md. mode phone_setup commands inspect/preview,
+start, get/recheck/verification_report/cancel {setupId}. Only inspect readiness and orchestrate;
+configure models, install managed ADB/scrcpy, and upload cloud adbkey in existing product forms.
+Never paste keys into chat or modify permissions or cloud billing yourself. Phone model is
+independent of chat model. Cloud ADB does not need local adb; scrcpy provides video/Unicode.
+Owner selects local/aliyun and the exact registered device in the same chat panel. Only the
+owner can start a test. Get returns attempt.goal/completion/maxActions. Discover phone_use if
+not declared, open this device in control mode with appPackage com.android.settings, observe,
+run the exact returned goal and completion, then close and read verification_report. Host
+records actual PhoneRuntime evidence; mock or model finish alone cannot pass. On cancellation,
+unknown outcome or restart, release first. Keep the original conversation and never substitute
+another phone, widen app access, replay input or claim control released from cancellation.`,
+	browser_setup: `# Browser setup
+Use configure-xopc and its Browser references. Commands on xopc_use mode browser_setup:
+inspect/preview {} read current shared configuration and available endpoints; start {} creates
+or reuses this Agent conversation's setup. get/recheck/advance/request_interaction/
+begin_verification/verification_report/cancel take {setupId}. dryRun never creates or mutates.
+Mutations require local-owner approval in the returned settingsPath. The UI selects the Chrome
+endpoint and begins verification; never bypass that step with file writes or shell commands.
+During verification get returns attempt.fixtureUrl, sample and evidence. Use normal browser_use
+navigate, observe, click, fill, close; the host binds these calls to the approved test endpoint.
+Read guidanceRefs progressively with skill_view(name:"configure-xopc",path:<returned path>).
+Report completed only when all checks and control release pass. No API Key is needed for Chrome.
+settingsPath is navigation; opening it is not proof of installation or connection.`,
 	settings: `# xopc settings and capability checks
 settings open is navigation only; it does not read, apply or verify configuration.
 Voice: {section:"capabilities/voice",title:"语音设置"}; models: section:"capabilities/models";

package/dist/src/agent/tools/browser/tool/browser-use-tool.d.ts

@@ -3,6 +3,8 @@ import type { BrowserNotReadyError } from '../../../../browser/readiness.js';
 import type { BrowserRuntime } from '../../../../browser/runtime/browser-runtime.js';
 import { BrowserUseSchema } from './schemas.js';
 export interface CreateBrowserUseToolDeps {
+    getSetupService?: () => import('../../../../browser/setup/service.js').BrowserSetupService | undefined;
+    getAgentId?: () => string;
     getRuntime: () => BrowserRuntime;
     getTaskId: () => string;
     getReadiness?: () => Promise<BrowserNotReadyError | null>;

package/dist/src/agent/tools/browser/tool/browser-use-tool.js

@@ -24,7 +24,7 @@ function createBrowserUseTool(deps) {
 				}
 			};
 			const readiness = await deps.getReadiness?.();
-			if (readiness) return {
+			if (readiness && input.action !== "close") return {
 				content: [{
 					type: "text",
 					text: `Browser is not ready: ${readiness.hint.detail || readiness.hint.reason}. Open Settings → Browser.`
@@ -35,7 +35,11 @@ function createBrowserUseTool(deps) {
 					hint: readiness.hint
 				}
 			};
-			return presentResult(await deps.getRuntime().execute(deps.getTaskId(), input, signal));
+			const setupService = deps.getSetupService?.();
+			const verification = setupService?.beforeAction(deps.getTaskId(), deps.getAgentId?.() ?? "", input);
+			const result = await deps.getRuntime().execute(verification?.taskKey ?? deps.getTaskId(), verification?.input ?? input, signal);
+			if (verification) setupService.afterAction(verification.setupId, verification.attemptId, verification.input, result);
+			return presentResult(result);
 		}
 	};
 }

package/dist/src/agent/tools/factory.d.ts

@@ -57,6 +57,8 @@ export interface ToolFactoryDeps {
     };
     /** Gateway: enables the `automation` tool. */
     getAutomationService?: () => AutomationService | undefined;
+    getPhoneSetupService?: () => import('../../phone/setup/service.js').PhoneSetupService | undefined;
+    getBrowserSetupService?: () => import('../../browser/setup/service.js').BrowserSetupService | undefined;
     getBrowserAutomationService?: () => BrowserAutomationService | undefined;
     emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: enables the `xopc_use` product-object tool. */
@@ -127,6 +129,7 @@ export declare class AgentToolsFactory {
     private ensureBrowserRuntime;
     private computerRuntime?;
     private ensureComputerRuntime;
+    hasBrowserSessions(): boolean;
     /** Close Playwright and all pages (gateway stop, agent manager dispose, or config hot-reload). */
     shutdownBrowser(): Promise<void>;
     /** Drop the tab for a session when its agent instance is removed. */

package/dist/src/agent/tools/factory.js

@@ -196,6 +196,8 @@ var AgentToolsFactory = class AgentToolsFactory {
 				return createBrowserDriver(config.browser, this.deps.endpointTools);
 			},
 			allowedUploadRoots: [this.deps.workspace],
+			canRestoreSetupSession: (taskKey, sessionId) => this.deps.getBrowserSetupService?.()?.canRestoreSession(taskKey, sessionId) === true,
+			isTrustedSetupUrl: (taskKey, url) => this.deps.getBrowserSetupService?.()?.allowsVerificationUrl(taskKey, url) === true,
 			emit: this.deps.emitBrowserEvent,
 			resolveTarget: (conversationId) => {
 				const binding = getBrowserTabBinding(conversationId);
@@ -224,6 +226,9 @@ var AgentToolsFactory = class AgentToolsFactory {
 			return context?.conversationId === owner && context.origin.type === "endpoint" ? context.origin.endpointId : void 0;
 		});
 	}
+	hasBrowserSessions() {
+		return this.browserRuntime?.hasSessions() ?? false;
+	}
 	/** Close Playwright and all pages (gateway stop, agent manager dispose, or config hot-reload). */
 	async shutdownBrowser() {
 		await this.computerRuntime?.shutdown();
@@ -333,6 +338,8 @@ var AgentToolsFactory = class AgentToolsFactory {
 			getWorkDiscovery: this.deps.getWorkDiscovery,
 			getLocalAppService: this.deps.getLocalAppService,
 			getChatPreviewService: this.deps.getChatPreviewService,
+			getBrowserSetupService: this.deps.getBrowserSetupService,
+			getPhoneSetupService: this.deps.getPhoneSetupService,
 			dispatchTaskEvents: this.deps.dispatchTaskEvents,
 			dispatchTaskRuns: this.deps.dispatchTaskRuns,
 			onAgentCatalogMutate: this.deps.onAgentCatalogMutate
@@ -556,7 +563,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 				getProjectService: this.deps.getProjectService
 			})] : [],
 			...browserEnabled && this.deps.getBrowserAutomationService ? [createBrowserAutomationTool({ getBrowserAutomationService: this.deps.getBrowserAutomationService })] : [],
-			...this.deps.getAutomationService || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.getChatPreviewService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool(productToolDeps), ...personalToolsConfigured ? [
+			...this.deps.getPhoneSetupService || this.deps.getBrowserSetupService || this.deps.getAutomationService || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.getChatPreviewService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool(productToolDeps), ...personalToolsConfigured ? [
 				createPersonalTaskTool(productToolDeps),
 				createPersonalReadTool({
 					...productToolDeps,
@@ -571,6 +578,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 			] : []] : [],
 			...cfg?.phone?.enabled ? [createPhoneUseTool({
 				runtime: getPhoneRuntime(),
+				getSetupService: this.deps.getPhoneSetupService,
 				context: () => {
 					const config = this.deps.getConfig?.();
 					const conversationId = getEmbeddedExecutionSession() ?? currentConversationId();
@@ -595,6 +603,8 @@ var AgentToolsFactory = class AgentToolsFactory {
 			})] : [],
 			...browserEnabled ? [createBrowserUseTool({
 				getRuntime: () => this.ensureBrowserRuntime(),
+				getSetupService: this.deps.getBrowserSetupService,
+				getAgentId: () => resolvedAgentId,
 				getTaskId: () => options?.conversationId ?? this.deps.getCurrentContext()?.conversationId ?? "default",
 				getReadiness: () => this.checkBrowserReadinessCached()
 			})] : [],

package/dist/src/agent/tools/phone-use-tool.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { PhoneRuntime, phoneExecutionContext } from '../../phone/runtime.js';
 export declare function createPhoneUseTool(deps: {
     runtime: PhoneRuntime;
+    getSetupService?: () => import('../../phone/setup/service.js').PhoneSetupService | undefined;
     context(): ReturnType<typeof phoneExecutionContext> & {
         owner: string;
     };

package/dist/src/agent/tools/phone-use-tool.js

@@ -54,7 +54,15 @@ function createPhoneUseTool(deps) {
 		description: "Use an authorized Android phone via local ADB or a configured cloud connection. Load tool_manual for phone_use before first use. Discover registered devices, appAccess and allowedApps first; open with mode observe/control and optional authorized appPackage, observe native UI text, then run one small goal or step once. Device and model configuration live in Phone Use settings. Connections originate from the Gateway host; cloud credentials are configured in phone management. Mock mode only supports the explicitly requested settings-about emulator test. Never silently switch phones, execute shell commands, bypass app restrictions, or repeat a dispatch with unknown outcome. Request user assistance for login, CAPTCHA or an effect not already authorized. Pause before manual takeover; resume re-observes. Inspect verified, verificationLevel and stopReason before claiming success. Close releases device control. Raw screenshots never enter the chat transcript.",
 		async execute(_id, raw, signal) {
 			const { owner, ...context } = deps.context();
-			const result = await deps.runtime.execute(owner, PhoneInputSchema.parse(raw), context, signal);
+			const input = PhoneInputSchema.parse(raw);
+			const setup = deps.getSetupService?.();
+			const setupContext = {
+				conversationId: owner,
+				agentId: context.agentId
+			};
+			const setupOwner = setup?.beforeInput(setupContext, input);
+			const result = await deps.runtime.execute(setupOwner?.owner ?? owner, setupOwner?.input ?? input, context, signal);
+			if (setupOwner) setup.afterInput(setupContext, setupOwner.owner, input.op);
 			return {
 				content: [{
 					type: "text",

package/dist/src/agent/tools/tool-manual-tool.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 declare const ToolManualSchema: import("@sinclair/typebox").TObject<{
     tool: import("@sinclair/typebox").TString;
-    topic: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"connections">]>>;
+    topic: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"connections">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">]>>;
 }>;
 export declare function createToolManualTool(): AgentTool<typeof ToolManualSchema, {}>;
 export {};

package/dist/src/agent/tools/tool-manual-tool.js

@@ -8,7 +8,9 @@ const ToolManualSchema = Type.Object({
 		Type.Literal("agent"),
 		Type.Literal("settings"),
 		Type.Literal("automation"),
-		Type.Literal("connections")
+		Type.Literal("connections"),
+		Type.Literal("browser_setup"),
+		Type.Literal("phone_setup")
 	], { description: "Focused xopc_use workflow; omit for the full parameter manual." }))
 });
 function createToolManualTool() {

package/dist/src/agent/tools/toolExposure.js

@@ -9,6 +9,9 @@ const EAGER_CORE_TOOLS = new Set([
 	"list_dir",
 	"exec_command",
 	"review_workspace",
+	"skill_view",
+	"skills_list",
+	"tool_manual",
 	"publish_artifacts",
 	"task_collaboration",
 	"publish_task_result"

package/dist/src/agent/tools/xopc-use-tool.d.ts

@@ -9,12 +9,12 @@ import type { LocalAppService } from '../../local-apps/index.js';
 import type { ChatPreviewService } from '../../chat-previews/index.js';
 import { TaskApplicationService } from '../../tasks/task-application-service.js';
 declare const XopcUseToolSchema: import("@sinclair/typebox").TObject<{
-    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"chat_preview">, import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">]>;
+    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"chat_preview">, import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">]>;
     command: import("@sinclair/typebox").TString;
     args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
     dryRun: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
-export type XopcUseMode = 'context' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'agent' | 'settings';
+export type XopcUseMode = 'context' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'agent' | 'settings' | 'browser_setup' | 'phone_setup';
 export interface XopcUseToolInput {
     mode: XopcUseMode;
     command: string;
@@ -22,6 +22,8 @@ export interface XopcUseToolInput {
     dryRun?: boolean;
 }
 export interface XopcUseToolDeps {
+    getPhoneSetupService?: () => import('../../phone/setup/service.js').PhoneSetupService | undefined;
+    getBrowserSetupService?: () => import('../../browser/setup/service.js').BrowserSetupService | undefined;
     authorizeCapability?: CapabilityContext['authorize'];
     getWorkspace?: () => string;
     getConfig?: () => Config | undefined;

package/dist/src/agent/tools/xopc-use-tool.js

@@ -50,7 +50,9 @@ const XopcUseToolSchema = Type.Object({
 		Type.Literal("local_app"),
 		Type.Literal("chat_preview"),
 		Type.Literal("agent"),
-		Type.Literal("settings")
+		Type.Literal("settings"),
+		Type.Literal("browser_setup"),
+		Type.Literal("phone_setup")
 	]),
 	command: Type.String({ description: "Context resolve takes an explicit AppContextEnvelope; never guess a current page. Automation draft/repair_draft accept prompt/id, agentId?, language?, idempotencyKey?; simulate explains an automation without running it. Local_app record_acceptance records supplied checks and sourceHash, not proof that checks were executed. Agent profile-only changes: patch_profile {id, expectedRevision, patch:{name?,description?,style?,language?,...}, idempotencyKey?} preserves omitted fields. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, runtime?, idempotencyKey?}, update {id, expectedRevision, patch, idempotencyKey?}, set_default {id, expectedRevision, idempotencyKey?}, disable/delete/purge {id, expectedRevision, idempotencyKey?}. Purge also removes on-disk data. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, events {eventType?, source?, limit?}, deliveries {runId?, limit?}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Recovery commands: replay_event {eventId, reason, idempotencyKey}, retry_delivery {runId, destinationKey, reason, idempotencyKey}. Automation also supports cancel/read {runId, idempotencyKey?} and read_all {projectId?, idempotencyKey?}; omitted projectId means all projects. Cancel acceptance is not confirmation of stopping. Object command. Supports project list/get/create/update/resolve_workspace/list_milestones/create_milestone/update_milestone/list_updates/create_update, automation list/get/create/update/delete/run/rerun/pause/resume/history (rerun takes runId; run/rerun accept idempotencyKey), note list/get/project_summaries/history {noteId}/snapshot {noteId, timestamp}/create/append/update/preview_edit/delete, task list/get/create/update_dependencies/add_context/remove_context/command/delete, task_run list/get/cancel, chat_preview create/revise/get, local_app list/get/create/validate, and settings open." }),
 	args: Type.Optional(Type.Record(Type.String(), Type.Any())),
@@ -1915,7 +1917,7 @@ function createXopcUseTool(deps) {
 	return {
 		name: "xopc_use",
 		label: "XOPC Use",
-		description: "Operate first-class xopc objects through one safe entry point. To delegate work for immediate execution: mode task, command create, args {title:\"Short task name\", objective:\"One-sentence outcome\", body:\"Full Markdown task brief\", createMode:\"start\", agentId:\"researcher\"}; omitting createMode creates a backlog task only. To start an existing Task: mode task, command command, args {taskId, type:\"start\", expectedVersion, commandArgs:{executor:{kind:\"agent\",agentId:\"main\"}}}. Inspect an existing Task and its run before creating another Task for the same objective. For delegated work, task delegated_tasks lists this conversation's tasks; task collaboration reads the shared board; task collaboration_post writes {taskId, kind, body, causationId?, idempotencyKey?}. Workers report progress or questions; the main Agent writes instructions and answers. Use chat_preview for lightweight UI mockups in the current conversation; do not create a Local App unless the user asks for a durable app. Local App capabilities takes extensionId and discovers already granted bindings. Local App invoke requires extensionId, the discovered manifestDigest, capabilityId and a pinned call {majorVersion, descriptorDigest, input, idempotencyKey for writes}. Never manufacture grants or change a retry key after an uncertain write. Use for Agents, projects, automations, notes, tasks, TaskRuns, chat previews, local apps, and exact settings jump targets instead of editing storage files directly. For non-trivial object changes, load the built-in manual first with tool_manual({ tool: \"xopc_use\" }).",
+		description: "Use mode browser_setup for inspect/preview/start/get/advance/recheck/request_interaction/begin_verification/verification_report/cancel of local Chrome setup. Load configure-xopc for guided setup; writes require product-owner approval. Operate first-class xopc objects through one safe entry point. To delegate work for immediate execution: mode task, command create, args {title:\"Short task name\", objective:\"One-sentence outcome\", body:\"Full Markdown task brief\", createMode:\"start\", agentId:\"researcher\"}; omitting createMode creates a backlog task only. To start an existing Task: mode task, command command, args {taskId, type:\"start\", expectedVersion, commandArgs:{executor:{kind:\"agent\",agentId:\"main\"}}}. Inspect an existing Task and its run before creating another Task for the same objective. For delegated work, task delegated_tasks lists this conversation's tasks; task collaboration reads the shared board; task collaboration_post writes {taskId, kind, body, causationId?, idempotencyKey?}. Workers report progress or questions; the main Agent writes instructions and answers. Use chat_preview for lightweight UI mockups in the current conversation; do not create a Local App unless the user asks for a durable app. Local App capabilities takes extensionId and discovers already granted bindings. Local App invoke requires extensionId, the discovered manifestDigest, capabilityId and a pinned call {majorVersion, descriptorDigest, input, idempotencyKey for writes}. Never manufacture grants or change a retry key after an uncertain write. Use for Agents, projects, automations, notes, tasks, TaskRuns, chat previews, local apps, and exact settings jump targets instead of editing storage files directly. For non-trivial object changes, load the built-in manual first with tool_manual({ tool: \"xopc_use\" }).",
 		parameters: XopcUseToolSchema,
 		mutatesWorkspace: true,
 		mutationScope: "external",
@@ -1932,6 +1934,42 @@ function createXopcUseTool(deps) {
 				dryRun
 			};
 			if (!command) return errorText("command is required", details);
+			if (mode === "phone_setup") {
+				const service = deps.getPhoneSetupService?.();
+				const conversationId = deps.getCurrentConversationId?.();
+				const agentId = deps.getCurrentAgentId?.();
+				if (!service || !conversationId || !agentId) return errorText("Phone setup requires a Gateway conversation. Open Settings → Phone Use.", details);
+				if (deps.authorizeCapability && !await deps.authorizeCapability(`xopc.phone_setup.${command}`, args)) return errorText("Phone setup access denied", details);
+				try {
+					return okText({
+						...details,
+						result: await service.command(command, args, {
+							conversationId,
+							agentId
+						}, dryRun)
+					});
+				} catch (error) {
+					return errorText(error instanceof Error ? error.message : String(error), details);
+				}
+			}
+			if (mode === "browser_setup") {
+				const service = deps.getBrowserSetupService?.();
+				const conversationId = deps.getCurrentConversationId?.();
+				const agentId = deps.getCurrentAgentId?.();
+				if (!service || !conversationId || !agentId) return errorText("Browser setup requires a Gateway conversation. Open Settings → Browser.", details);
+				if (deps.authorizeCapability && !await deps.authorizeCapability(`xopc.browser_setup.${command}`, args)) return errorText("Browser setup access denied", details);
+				try {
+					return okText({
+						...details,
+						result: await service.command(command, args, {
+							conversationId,
+							agentId
+						}, dryRun)
+					});
+				} catch (error) {
+					return errorText(error instanceof Error ? error.message : String(error), details);
+				}
+			}
 			if (mode === "local_app" && (command === "capabilities" || command === "invoke")) {
 				const apps = deps.getLocalAppService?.();
 				if (!apps) return errorText("Local app service is unavailable", details);

package/dist/src/browser/drivers/browser-driver.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserActionInput, BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
+import type { BrowserActionInput, BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput, BrowserTarget } from '@xopcai/browser-control-contract';
 export type BrowserPrimitiveInput = Exclude<BrowserActionInput, BrowserNavigateInput | BrowserObserveInput | BrowserTabsInput | {
     action: 'sequence';
 } | {
@@ -9,7 +9,7 @@ export interface BrowserDriver {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     createSession(sessionId: string): Promise<void>;
-    closeSession(sessionId: string): Promise<void>;
+    closeSession(sessionId: string, target?: BrowserTarget): Promise<void>;
     navigate(sessionId: string, input: BrowserNavigateInput, signal?: AbortSignal): Promise<BrowserControlResult>;
     observe(sessionId: string, input: BrowserObserveInput, signal?: AbortSignal): Promise<BrowserObservation>;
     perform(sessionId: string, input: BrowserPrimitiveInput, signal?: AbortSignal): Promise<BrowserControlResult>;

package/dist/src/browser/drivers/extension-driver.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
+import type { BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput, BrowserTarget } from '@xopcai/browser-control-contract';
 import type { BrowserDriver, BrowserPrimitiveInput } from './browser-driver.js';
 type ExtensionProvider = {
     start(): Promise<void>;
@@ -15,7 +15,7 @@ export declare class ExtensionDriver implements BrowserDriver {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     createSession(_sessionId: string): Promise<void>;
-    closeSession(sessionId: string): Promise<void>;
+    closeSession(sessionId: string, target?: BrowserTarget): Promise<void>;
     navigate(sessionId: string, input: BrowserNavigateInput, signal?: AbortSignal): Promise<BrowserControlResult>;
     observe(sessionId: string, input: BrowserObserveInput, signal?: AbortSignal): Promise<BrowserObservation>;
     perform(sessionId: string, input: BrowserPrimitiveInput, signal?: AbortSignal): Promise<BrowserControlResult>;

package/dist/src/browser/drivers/extension-driver.js

@@ -17,11 +17,14 @@ var ExtensionDriver = class {
 	async createSession(_sessionId) {
 		await this.connect();
 	}
-	async closeSession(sessionId) {
-		await this.send({
+	async closeSession(sessionId, target) {
+		const result = await this.send({
 			action: "close",
-			sessionId
+			sessionId,
+			...target ? { target } : {}
 		});
+		if ("error" in result) throw new Error(result.error.message);
+		if (!result.receipt.verified) throw new Error("Browser control release was not verified");
 	}
 	navigate(sessionId, input, signal) {
 		return this.send({

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

@@ -9,7 +9,7 @@ import { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME } from "../extension-ide
 import "../native-messaging-host.js";
 import { resolvePackageRoot } from "../../infra/update-check.js";
 import { dirname, join } from "node:path";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
@@ -384,6 +384,7 @@ function browserNativeHostDoctor(platform = process.platform, home = process.env
 	const manifestPaths = (platform === "win32" ? windowsRegisteredNativeManifests() : directories.map((directory) => join(directory, `${BROWSER_NATIVE_HOST_NAME}.json`))).filter((manifestPath) => {
 		try {
 			const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+			if (typeof manifest.path === "string" && platform !== "win32") accessSync(manifest.path, constants.X_OK);
 			return manifest.name === "ai.xopc.browser" && typeof manifest.path === "string" && existsSync(manifest.path) && Array.isArray(manifest.allowed_origins) && manifest.allowed_origins.includes(`chrome-extension://gopbfhaojnnhiheiikblejnpgmfmkmgd/`);
 		} catch {
 			return false;

package/dist/src/browser/runtime/browser-runtime.d.ts

@@ -5,6 +5,8 @@ export interface BrowserRuntimeOptions {
     getConfig: () => Config['browser'];
     createDriver: () => Promise<BrowserDriver>;
     allowedUploadRoots?: string[];
+    canRestoreSetupSession?: (taskKey: string, sessionId: string) => boolean;
+    isTrustedSetupUrl?: (taskKey: string, url: string) => boolean;
     emit?: (type: string, payload: unknown) => void;
     resolveTarget?: (taskKey: string) => BrowserTarget | undefined;
 }
@@ -14,8 +16,9 @@ export declare class BrowserRuntime {
     private sessionsByTask;
     constructor(options: BrowserRuntimeOptions);
     execute(taskKey: string, input: BrowserActionInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    hasSessions(): boolean;
     shutdown(): Promise<void>;
-    closeTaskSession(taskKey: string): Promise<void>;
+    closeTaskSession(taskKey: string, target?: BrowserTarget): Promise<void>;
     private dispatch;
     private executeSequence;
     private actionDenied;

package/dist/src/browser/runtime/browser-runtime.js

@@ -11,7 +11,7 @@ var BrowserRuntime = class {
 	}
 	async execute(taskKey, input, signal) {
 		this.evictExpiredSessions();
-		if (!this.options.getConfig().enabled) return failure("DRIVER_UNAVAILABLE", "Browser Control is disabled.");
+		if (!this.options.getConfig().enabled && input.action !== "close") return failure("DRIVER_UNAVAILABLE", "Browser Control is disabled.");
 		if (signal?.aborted) return failure("ABORTED", "Operation was aborted.");
 		const resolvedTarget = input.target ? void 0 : this.options.resolveTarget?.(taskKey);
 		const effectiveInput = input.target || !resolvedTarget ? input : {
@@ -55,21 +55,24 @@ var BrowserRuntime = class {
 		}
 		return result;
 	}
+	hasSessions() {
+		return this.sessionsByTask.size > 0;
+	}
 	async shutdown() {
 		await this.driver?.disconnect();
 		this.driver = null;
 		this.sessionsByTask.clear();
 	}
-	async closeTaskSession(taskKey) {
+	async closeTaskSession(taskKey, target) {
 		const session = this.sessionsByTask.get(taskKey);
 		if (!session) return;
-		await this.driver?.closeSession(session.id);
+		await this.driver?.closeSession(session.id, target);
 		this.sessionsByTask.delete(taskKey);
 		this.options.emit?.("browser.session.closed", { sessionId: session.id });
 	}
 	async dispatch(driver, session, input, signal) {
 		if (input.action === "close") {
-			await this.closeTaskSession(session.taskKey);
+			await this.closeTaskSession(session.taskKey, input.target);
 			return {
 				ok: true,
 				receipt: {
@@ -91,22 +94,22 @@ var BrowserRuntime = class {
 			}
 		};
 		if (input.action === "navigate") {
-			const blocked = this.validateUrl(input.url);
+			const blocked = this.validateUrl(input.url, session.taskKey);
 			if (blocked) return failure("BLOCKED_URL", blocked);
 			if (this.crossDomainPolicy(session.observation?.url, input.url) === "deny") return failure("BLOCKED_URL", "Cross-domain navigation is denied by policy.");
 			const result = await driver.navigate(session.id, input, signal);
-			return this.validateRedirect(input.url, result);
+			return this.validateRedirect(input.url, result, session.taskKey);
 		}
 		if (input.action === "tabs") {
 			if (input.url) {
-				const blocked = this.validateUrl(input.url);
+				const blocked = this.validateUrl(input.url, session.taskKey);
 				if (blocked) return failure("BLOCKED_URL", blocked);
 				if (this.crossDomainPolicy(session.observation?.url, input.url) === "deny") return failure("BLOCKED_URL", "Cross-domain navigation is denied by policy.");
 			}
 			const result = await driver.tabs(session.id, input, signal);
 			if (!input.url || !result.ok) return result;
 			const finalUrl = result.receipt.tabs?.find((tab) => tab.active)?.url;
-			const blocked = finalUrl ? this.blockedRedirect(finalUrl) : "The created tab did not report its final URL.";
+			const blocked = finalUrl ? this.blockedRedirect(finalUrl, session.taskKey) : "The created tab did not report its final URL.";
 			return blocked ? failure("BLOCKED_URL", blocked) : result;
 		}
 		if (input.action === "sequence") return this.executeSequence(driver, session, input, signal);
@@ -119,12 +122,12 @@ var BrowserRuntime = class {
 		}
 		if (this.actionDenied(input, risk)) return failure("INVALID_INPUT", `Browser action is denied by policy (${risk}).`);
 		if (input.action === "click" && target?.href) {
-			const blocked = this.validateUrl(target.href);
+			const blocked = this.validateUrl(target.href, session.taskKey);
 			if (blocked) return failure("BLOCKED_URL", blocked);
 			if (this.crossDomainPolicy(session.observation?.url, target.href) === "deny") return failure("BLOCKED_URL", "Cross-domain navigation is denied by policy.");
 		}
 		const result = await driver.perform(session.id, input, signal);
-		return withRisk(this.validateRedirect(session.observation?.url ?? "", result), risk);
+		return withRisk(this.validateRedirect(session.observation?.url ?? "", result, session.taskKey), risk);
 	}
 	async executeSequence(driver, session, input, signal) {
 		const config = this.options.getConfig();
@@ -171,27 +174,27 @@ var BrowserRuntime = class {
 			"sensitive"
 		].includes(risk);
 	}
-	validateUrl(url) {
+	validateUrl(url, taskKey) {
 		if (containsApiKeyPattern(url)) return "URL contains a credential-like value.";
 		try {
 			const host = new URL(url).hostname.toLowerCase();
-			assertBrowserUrlAllowed(url, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) });
+			assertBrowserUrlAllowed(url, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) || this.options.isTrustedSetupUrl?.(taskKey, url) === true });
 			return null;
 		} catch (error) {
 			return error instanceof Error ? error.message : String(error);
 		}
 	}
-	validateRedirect(requestedUrl, result) {
+	validateRedirect(requestedUrl, result, taskKey) {
 		if (!result.ok || !result.receipt.observation) return result;
 		const finalUrl = result.receipt.observation.url;
 		if (finalUrl === requestedUrl) return result;
-		const blocked = this.blockedRedirect(finalUrl);
+		const blocked = this.blockedRedirect(finalUrl, taskKey);
 		return blocked ? failure("BLOCKED_URL", blocked, result.receipt.observation) : result;
 	}
-	blockedRedirect(finalUrl) {
+	blockedRedirect(finalUrl, taskKey) {
 		try {
 			const host = new URL(finalUrl).hostname.toLowerCase();
-			return checkPostRedirectUrl(finalUrl, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) });
+			return checkPostRedirectUrl(finalUrl, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) || this.options.isTrustedSetupUrl?.(taskKey, finalUrl) === true });
 		} catch {
 			return "Browser returned an invalid final URL.";
 		}
@@ -222,7 +225,16 @@ var BrowserRuntime = class {
 	async resolveSession(taskKey, requestedId) {
 		const existing = this.sessionsByTask.get(taskKey);
 		if (existing) return !requestedId || requestedId === existing.id ? existing : null;
-		if (requestedId) return null;
+		if (requestedId) {
+			if (!this.options.canRestoreSetupSession?.(taskKey, requestedId)) return null;
+			const restored = {
+				id: requestedId,
+				taskKey,
+				lastUsedAt: Date.now()
+			};
+			this.sessionsByTask.set(taskKey, restored);
+			return restored;
+		}
 		const session = {
 			id: randomUUID(),
 			taskKey,

package/dist/src/browser/setup/repository.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserSetup } from './types.js';
+export declare function readBrowserSetup(id: string): BrowserSetup | undefined;
+export declare function findBrowserSetup(conversationId: string, agentId: string): BrowserSetup | undefined;
+export declare function createBrowserSetup(conversationId: string, agentId: string, configRevision: string): BrowserSetup;
+export declare function saveBrowserSetup(next: BrowserSetup, expectedRevision: number): BrowserSetup;

package/dist/src/browser/setup/repository.js

@@ -0,0 +1,42 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/browser/setup/repository.ts
+init_transaction();
+function readBrowserSetup(id) {
+	const row = getSqliteDatabase().prepare("SELECT payload_json FROM browser_setup_runs WHERE id = ?").get(id);
+	return row ? JSON.parse(row.payload_json) : void 0;
+}
+function findBrowserSetup(conversationId, agentId) {
+	const row = getSqliteDatabase().prepare("SELECT payload_json FROM browser_setup_runs WHERE conversation_id = ? AND agent_id = ? ORDER BY updated_at DESC, rowid DESC LIMIT 1").get(conversationId, agentId);
+	return row ? JSON.parse(row.payload_json) : void 0;
+}
+function createBrowserSetup(conversationId, agentId, configRevision) {
+	return runSqliteWriteTransaction((db) => {
+		const existing = findBrowserSetup(conversationId, agentId);
+		if (existing && existing.state !== "cancelled" && existing.state !== "completed") return existing;
+		const now = Date.now();
+		const setup = {
+			id: randomUUID(),
+			conversationId,
+			agentId,
+			configRevision,
+			state: "plan_ready",
+			revision: 1,
+			createdAt: now,
+			updatedAt: now
+		};
+		db.prepare("INSERT INTO browser_setup_runs (id, conversation_id, agent_id, revision, updated_at, payload_json) VALUES (?, ?, ?, ?, ?, ?)").run(setup.id, conversationId, agentId, setup.revision, now, JSON.stringify(setup));
+		return setup;
+	});
+}
+function saveBrowserSetup(next, expectedRevision) {
+	next = {
+		...next,
+		revision: expectedRevision + 1,
+		updatedAt: Date.now()
+	};
+	if (getSqliteDatabase().prepare("UPDATE browser_setup_runs SET revision = ?, updated_at = ?, payload_json = ? WHERE id = ? AND revision = ?").run(next.revision, next.updatedAt, JSON.stringify(next), next.id, expectedRevision).changes !== 1) throw new Error("SETUP_CONFLICT: Configuration progress changed. Read it again.");
+	return next;
+}
+//#endregion
+export { createBrowserSetup, findBrowserSetup, readBrowserSetup, saveBrowserSetup };