@xopcai/xopc 0.0.251 → 0.0.253

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

@@ -1,10 +1,9 @@
 import { PACKAGE_VERSION, init_package_version } from "../../package-version.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { assertCacheDir, init_cache_dir_policy } from "../cache-dir-policy.js";
-import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
 import { init_paths, resolveBinDir } from "../../config/paths.js";
-import { shouldRunExtensionBridgeServer } from "../backend-from-config.js";
+import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
+import { assertCacheDir } from "../cache-dir-policy.js";
 import { resolvePackageRoot } from "../../infra/update-check.js";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -20,7 +19,6 @@ init_package_version();
 init_paths();
 init_write_file_atomic();
 init_logger();
-init_cache_dir_policy();
 const log = createLogger("BrowserExtInstall");
 const META_FILENAME = ".meta.json";
 const STAGING_MAX_AGE_MS = 3600 * 1e3;
@@ -270,9 +268,9 @@ async function ensureBrowserExtensionArtifacts(opts) {
 		copied: true
 	};
 }
-/** Gateway startup hook: ensure artifacts only while the extension backend is active. */
+/** Gateway startup hook: ensure artifacts only while the extension driver is active. */
 async function ensureBrowserExtensionOnStartup(config) {
-	if (!shouldRunExtensionBridgeServer(config)) return;
+	if (config?.browser.enabled === false || config?.browser.driver.kind !== "extension") return;
 	await ensureBrowserExtensionArtifacts();
 }
 async function readInstalledExtensionDir(cacheDir) {

package/dist/src/browser/providers/browser-use.js

@@ -23,7 +23,7 @@ var BrowserUseProvider = class {
 	}
 	async connect() {
 		const apiKey = this.config.apiKey || process.env.BROWSER_USE_API_KEY;
-		if (!apiKey) throw new Error("Browser Use API key not configured (set BROWSER_USE_API_KEY or browser.cloudProvider config)");
+		if (!apiKey) throw new Error("Browser Use API key not configured (set BROWSER_USE_API_KEY or browser.driver.apiKey)");
 		const response = await fetch("https://api.browser-use.com/api/v1/sessions", {
 			method: "POST",
 			headers: {

package/dist/src/browser/providers/browserbase.js

@@ -23,7 +23,7 @@ var BrowserbaseProvider = class {
 	}
 	async connect() {
 		const apiKey = this.config.apiKey || process.env.BROWSERBASE_API_KEY;
-		if (!apiKey) throw new Error("Browserbase API key not configured (set BROWSERBASE_API_KEY or browser.cloudProvider config)");
+		if (!apiKey) throw new Error("Browserbase API key not configured (set BROWSERBASE_API_KEY or browser.driver.apiKey)");
 		const projectId = this.config.projectId || process.env.BROWSERBASE_PROJECT_ID;
 		const createUrl = "https://www.browserbase.com/v1/sessions";
 		const body = {};

package/dist/src/browser/providers/extension-ws-acquire.d.ts

@@ -1,6 +1,6 @@
 /**
  * Single shared HTTP + WebSocket listener for the Chrome extension bridge.
- * Gateway and BrowserManager both need the server; only one process may bind a port.
+ * Gateway and Browser Control sessions share one listener because only one process may bind the port.
  */
 import type { ExtensionBrowserProvider, ExtensionProviderConfig } from './extension.js';
 export type ExtensionBrowserServerSnapshot = {
@@ -9,9 +9,6 @@ export type ExtensionBrowserServerSnapshot = {
     key: string | null;
 };
 export declare function getExtensionBrowserServerSnapshot(): ExtensionBrowserServerSnapshot;
-export declare function getExtensionBrowserProvider(): ExtensionBrowserProvider | null;
-/** Shut down the shared listener regardless of remaining ref counts (settings UI stop). */
-export declare function forceShutdownExtensionBrowserServer(): Promise<boolean>;
 /**
  * Increment ref count and return the shared provider plus a one-shot release.
  * First acquire starts the listener; further acquires reuse it (same host:port).

package/dist/src/browser/providers/extension-ws-acquire.js

@@ -25,18 +25,6 @@ function getExtensionBrowserServerSnapshot() {
 		key: state.key
 	};
 }
-function getExtensionBrowserProvider() {
-	return state?.provider ?? null;
-}
-/** Shut down the shared listener regardless of remaining ref counts (settings UI stop). */
-async function forceShutdownExtensionBrowserServer() {
-	return withExclusive(async () => {
-		if (!state) return false;
-		await state.provider.shutdown();
-		state = null;
-		return true;
-	});
-}
 function normalizeConfig(config) {
 	return {
 		port: config?.port ?? DEFAULT_PORT,
@@ -87,4 +75,4 @@ function acquireExtensionBrowserServer(config) {
 	});
 }
 //#endregion
-export { acquireExtensionBrowserServer, forceShutdownExtensionBrowserServer, getExtensionBrowserProvider, getExtensionBrowserServerSnapshot };
+export { acquireExtensionBrowserServer, getExtensionBrowserServerSnapshot };

package/dist/src/browser/providers/extension.d.ts

@@ -4,21 +4,7 @@
  * The xopc process starts a WebSocket server; the Chrome Extension connects as a client.
  * Commands are sent over the WS connection and results are returned asynchronously.
  */
-export type ExtensionAction = 'open' | 'navigate' | 'reload' | 'back' | 'forward' | 'get_url' | 'get_title' | 'state' | 'snapshot' | 'screenshot' | 'content' | 'evaluate' | 'click' | 'type' | 'scroll' | 'wait' | 'query_selector' | 'query_selector_all' | 'wait_for_selector' | 'mouse_move' | 'mouse_click' | 'mouse_down' | 'mouse_up' | 'mouse_wheel' | 'keys' | 'keyboard_type' | 'keyboard_down' | 'keyboard_up' | 'keyboard_insert_text' | 'get_bounding_box' | 'get_element_text' | 'get_element_attribute' | 'get_elements_count' | 'set_input_files' | 'scroll_into_view' | 'set_viewport_size' | 'get_viewport_size' | 'network_start' | 'network_events' | 'network_stop' | 'dialog' | 'get_cookies' | 'set_cookies' | 'clear_cookies' | 'close' | 'new_tab' | 'list_tabs' | 'cdp' | 'ping';
-export interface ExtensionCommand {
-    id: string;
-    action: ExtensionAction;
-    tabId?: number;
-    args?: Record<string, unknown>;
-    timeout?: number;
-}
-export interface ExtensionResult {
-    id: string;
-    ok: boolean;
-    data?: unknown;
-    error?: string;
-    durationMs?: number;
-}
+import type { BrowserActionInput, BrowserWireResult } from '@xopcai/browser-control-contract';
 export interface ExtensionProviderConfig {
     /** WebSocket server port. Default: 19820. */
     port?: number;
@@ -48,15 +34,10 @@ export declare class ExtensionBrowserProvider {
     start(): Promise<void>;
     /** Wait for the Chrome Extension to connect. */
     waitForConnection(timeoutMs?: number): Promise<void>;
-    /** Send a command to the extension and wait for the result. */
-    sendCommand(action: ExtensionAction, args?: Record<string, unknown>, options?: {
-        tabId?: number;
-        timeout?: number;
-    }): Promise<ExtensionResult>;
+    /** Send one Browser Control v2 action to the extension. */
+    send(input: BrowserActionInput, timeoutMs?: number, visualFallback?: boolean): Promise<BrowserWireResult>;
     /** Whether the extension is currently connected. */
     isConnected(): boolean;
-    /** Close the Chrome Extension client without stopping the WebSocket server. */
-    disconnectClient(): void;
     /** Shutdown the WebSocket server. */
     shutdown(): Promise<void>;
     private _handleMessage;

package/dist/src/browser/providers/extension.js

@@ -139,22 +139,21 @@ var ExtensionBrowserProvider = class {
 			});
 		});
 	}
-	/** Send a command to the extension and wait for the result. */
-	async sendCommand(action, args, options) {
+	/** Send one Browser Control v2 action to the extension. */
+	async send(input, timeoutMs, visualFallback = true) {
 		if (!this.connected || !this.clientWs) throw new Error("Extension not connected. Ensure the Chrome Extension is installed and connected.");
 		const id = `cmd_${++this.commandCounter}_${Date.now()}`;
 		const cmd = {
 			id,
-			action,
-			args,
-			tabId: options?.tabId,
-			timeout: options?.timeout ?? this.config.commandTimeout
+			input,
+			timeoutMs: timeoutMs ?? this.config.commandTimeout,
+			visualFallback
 		};
 		return new Promise((resolve, reject) => {
 			const timer = setTimeout(() => {
 				this.pending.delete(id);
-				reject(/* @__PURE__ */ new Error(`Command timeout: ${action} (${cmd.timeout}ms)`));
-			}, cmd.timeout);
+				reject(/* @__PURE__ */ new Error(`Browser action timed out: ${input.action} (${cmd.timeoutMs}ms)`));
+			}, cmd.timeoutMs);
 			this.pending.set(id, {
 				resolve,
 				reject,
@@ -173,13 +172,6 @@ var ExtensionBrowserProvider = class {
 	isConnected() {
 		return this.connected;
 	}
-	/** Close the Chrome Extension client without stopping the WebSocket server. */
-	disconnectClient() {
-		if (!this.clientWs) return;
-		try {
-			this.clientWs.close();
-		} catch {}
-	}
 	/** Shutdown the WebSocket server. */
 	async shutdown() {
 		for (const waiter of this.connectionWaiters) waiter.reject(/* @__PURE__ */ new Error("Provider shutting down"));

package/dist/src/browser/providers/index.d.ts

@@ -1,4 +1,4 @@
-export type { BrowserBackend, CdpConnectionConfig, CloakBrowserConfig, CloudBrowserProvider, CloudBrowserProviderConfig, } from './types.js';
+export type { CloudBrowserProvider, CloudBrowserProviderConfig } from './types.js';
 export { BrowserbaseProvider } from './browserbase.js';
 export { BrowserUseProvider } from './browser-use.js';
-export { launchCloakBrowser, cleanupCloakBrowser, cloakBrowserDoctor, type CloakBrowserLaunchResult, type CloakBrowserDoctorResult, } from './cloakbrowser.js';
+export { ExtensionBrowserProvider } from './extension.js';

package/dist/src/browser/providers/index.js

@@ -1,4 +1,4 @@
-import { BrowserUseProvider } from "./browser-use.js";
 import { BrowserbaseProvider } from "./browserbase.js";
-import { cleanupCloakBrowser, cloakBrowserDoctor, launchCloakBrowser } from "./cloakbrowser.js";
-export { BrowserUseProvider, BrowserbaseProvider, cleanupCloakBrowser, cloakBrowserDoctor, launchCloakBrowser };
+import { BrowserUseProvider } from "./browser-use.js";
+import { ExtensionBrowserProvider } from "./extension.js";
+export { BrowserUseProvider, BrowserbaseProvider, ExtensionBrowserProvider };

package/dist/src/browser/providers/types.d.ts

@@ -1,110 +1,16 @@
 import type { Browser, BrowserContext } from 'playwright-core';
-/**
- * Cloud browser provider abstraction — aligned with hermes-agent's multi-backend architecture.
- *
- * Each provider is responsible for creating a Playwright-compatible Browser/Context
- * that the BrowserManager can use interchangeably with local Chromium.
- */
 export interface CloudBrowserProvider {
-    /** Human-readable provider name for logging. */
     readonly name: string;
-    /**
-     * Connect to the cloud browser and return a Playwright BrowserContext.
-     * The provider owns the underlying Browser instance lifecycle.
-     */
     connect(): Promise<{
         browser: Browser;
         context: BrowserContext;
     }>;
-    /**
-     * Gracefully disconnect from the cloud browser.
-     * Called during shutdown or session cleanup.
-     */
     disconnect(): Promise<void>;
-    /** Whether the provider is currently connected. */
     isConnected(): boolean;
 }
-/** Configuration needed to instantiate a cloud browser provider. */
 export interface CloudBrowserProviderConfig {
-    /** Provider type identifier. */
     type: 'browserbase' | 'browser-use';
-    /** API key for the cloud provider. Falls back to provider-specific environment variables. */
     apiKey?: string;
-    /** Optional project/session identifier. */
     projectId?: string;
-    /** Optional region preference. */
     region?: string;
 }
-/** Configuration for direct CDP WebSocket connection (bypasses cloud provider). */
-export interface CdpConnectionConfig {
-    /** WebSocket endpoint URL (e.g. ws://localhost:9222/devtools/browser/...). */
-    wsEndpoint: string;
-}
-/** Configuration for the xopc Chrome Extension bridge backend. */
-export interface ExtensionConnectionConfig {
-    /** WebSocket server port. Default: 19820. */
-    port?: number;
-    /** Host to bind. Default: 127.0.0.1. */
-    host?: string;
-    /** Timeout waiting for extension to connect (ms). Default: 30000. */
-    connectionTimeout?: number;
-    /** Default command timeout (ms). Default: 30000. */
-    commandTimeout?: number;
-}
-import type { BrowserInstallProgress } from '../install-progress.js';
-/** Configuration for CloakBrowser — anti-fingerprint Chromium with stealth capabilities. */
-export interface CloakBrowserConfig {
-    /** Directory for cached CloakBrowser binaries. Default: ~/.xopc/bin/cloakbrowser. */
-    cacheDir?: string;
-    /** Override the CloakBrowser binary path (skip auto-download). */
-    binaryPath?: string;
-    /** Run headless. Default: false. */
-    headless?: boolean;
-    /** Fixed CDP debugging port. Default: auto-pick free port, or 9222 if keepOpen. */
-    cdpPort?: number;
-    /** Keep browser process alive between tasks. Default: true. */
-    keepOpen?: boolean;
-    /** Reuse an already-running CloakBrowser instance on the same port. Default: false. */
-    reuseExisting?: boolean;
-    /** Create a temporary profile directory, cleaned up on close. Default: false. */
-    temporaryProfile?: boolean;
-    /** Persistent user data directory (overrides temporaryProfile). */
-    userDataDir?: string;
-    /** Extra Chromium launch args (override defaults with same --key= prefix). */
-    extraArgs?: string[];
-    /** Timezone to emulate (e.g. "America/New_York"). */
-    timezone?: string;
-    /** Locale to emulate (e.g. "en-US"). */
-    locale?: string;
-    /** Public IP for WebRTC leak prevention. */
-    webrtcIp?: string;
-    /** Platform to emulate in fingerprint (e.g. "windows", "macos"). */
-    fingerprintPlatform?: string;
-    /** Enable humanized input (mouse/keyboard/scroll). Default: true. */
-    humanize?: boolean;
-    /** Humanize behavior preset. Default: 'careful'. */
-    humanPreset?: 'default' | 'careful';
-    /** Optional install/download progress callback (gateway SSE, CLI). */
-    onProgress?: (progress: BrowserInstallProgress) => void | Promise<void>;
-    /** Abort long-running install/download (client disconnect). */
-    signal?: AbortSignal;
-    /** When true, wait for CDP then return without connecting Playwright (settings "open browser"). */
-    skipPlaywrightConnect?: boolean;
-}
-/** Union of all backend connection modes. */
-export type BrowserBackend = {
-    mode: 'local';
-    headless: boolean;
-} | {
-    mode: 'cdp';
-    config: CdpConnectionConfig;
-} | {
-    mode: 'cloud';
-    config: CloudBrowserProviderConfig;
-} | {
-    mode: 'extension';
-    config?: ExtensionConnectionConfig;
-} | {
-    mode: 'cloakbrowser';
-    config?: CloakBrowserConfig;
-};

package/dist/src/browser/readiness.d.ts

@@ -1,33 +1,15 @@
-/**
- * Backend readiness preflight for the `browser_use` tool.
- *
- * Reuses the same doctor functions that power the Settings → Browser page so
- * the agent never tries to launch a backend that the UI already knows is
- * broken. Produces a structured signal the chat surface can render as a
- * "Setup browser" card instead of a bare error string.
- */
 import type { Config } from '../config/schema.js';
-export type BrowserBackendKind = 'extension' | 'local' | 'cloakbrowser' | 'cdp' | 'cloud';
-export type BrowserNotReadyReason = 'extension_not_installed' | 'extension_bridge_offline' | 'extension_not_connected' | 'local_chromium_missing' | 'cloakbrowser_not_installed' | 'cdp_unreachable' | 'cloud_api_key_missing';
+export type BrowserDriverKind = Config['browser']['driver']['kind'];
+export type BrowserNotReadyReason = 'extension_not_installed' | 'extension_not_connected' | 'chromium_missing' | 'cdp_unreachable' | 'remote_api_key_missing';
 export interface BrowserSetupHint {
-    backend: BrowserBackendKind;
+    driver: BrowserDriverKind;
     reason: BrowserNotReadyReason;
-    /** Raw probe diagnostic; surfaced behind a disclosure for debugging. */
     detail?: string;
-    /** Deep link into Settings → Browser focused on the right backend tab. */
     deepLink: string;
 }
 export declare class BrowserNotReadyError extends Error {
     readonly hint: BrowserSetupHint;
     constructor(hint: BrowserSetupHint);
 }
-/** Map backend → settings tab id (matches `BROWSER_BACKEND_TABS` on the web side). */
-export declare function buildBrowserSetupDeepLink(backend: BrowserBackendKind): string;
-/**
- * Probe the currently-configured browser backend. Returns `null` when ready.
- *
- * Probe budget is small (filesystem stats + loopback fetches with a 2s timeout)
- * so it's safe to call before every `browser_use` invocation — but callers
- * typically cache the result for a few seconds to handle bursts.
- */
+export declare function buildBrowserSetupDeepLink(driver: BrowserDriverKind): string;
 export declare function checkBrowserReadiness(cfg: Config | undefined): Promise<BrowserNotReadyError | null>;

package/dist/src/browser/readiness.js

@@ -1,136 +1,73 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { resolveBrowserBackendFromConfig } from "./backend-from-config.js";
+import { access } from "node:fs/promises";
 //#region src/browser/readiness.ts
 init_logger();
-const log = createLogger("browser-readiness");
+const log = createLogger("BrowserReadiness");
 var BrowserNotReadyError = class extends Error {
 	constructor(hint) {
-		super(`Browser backend "${hint.backend}" not ready: ${hint.reason}`);
+		super(`Browser driver "${hint.driver}" is not ready: ${hint.reason}`);
 		this.hint = hint;
 		this.name = "BrowserNotReadyError";
 	}
 };
-/** Map backend → settings tab id (matches `BROWSER_BACKEND_TABS` on the web side). */
-function buildBrowserSetupDeepLink(backend) {
-	return `/settings/agent-browser?tab=${backend}`;
+function buildBrowserSetupDeepLink(driver) {
+	return `/settings/agent-browser?driver=${driver}`;
 }
-function hint(backend, reason, detail) {
-	return {
-		backend,
-		reason,
-		detail,
-		deepLink: buildBrowserSetupDeepLink(backend)
-	};
-}
-async function checkExtension(config) {
-	try {
-		const { browserExtDoctor } = await import("./providers/browser-ext-install.js");
-		if (!(await browserExtDoctor()).installed) return hint("extension", "extension_not_installed", "extension artifacts not on disk");
-	} catch (e) {
-		return hint("extension", "extension_not_installed", e instanceof Error ? e.message : String(e));
-	}
-	const host = config?.host?.trim() || "127.0.0.1";
-	const port = typeof config?.port === "number" && config.port >= 1024 && config.port <= 65535 ? Math.floor(config.port) : 19820;
-	try {
-		const { getExtensionBrowserServerSnapshot } = await import("./providers/extension-ws-acquire.js");
-		if (getExtensionBrowserServerSnapshot().active) try {
-			if ((await (await fetch(`http://${host}:${port}/`, { signal: AbortSignal.timeout(2e3) })).json().catch(() => null))?.connected) return null;
-			return hint("extension", "extension_not_connected", "WS bridge is listening but no Chrome Extension client connected yet");
-		} catch {
-			return hint("extension", "extension_bridge_offline", `health probe failed on ${host}:${port}`);
-		}
-		return hint("extension", "extension_bridge_offline", `bridge not started on ${host}:${port}`);
-	} catch (e) {
-		return hint("extension", "extension_bridge_offline", e instanceof Error ? e.message : String(e));
-	}
-}
-async function checkLocal() {
-	try {
-		const { playwrightChromiumDoctor } = await import("./providers/playwright-doctor.js");
-		const doctor = await playwrightChromiumDoctor();
-		if (!doctor.installed) return hint("local", "local_chromium_missing", doctor.reason ?? "Chromium binary not found on disk");
-		return null;
-	} catch (e) {
-		return hint("local", "local_chromium_missing", e instanceof Error ? e.message : String(e));
-	}
-}
-async function checkCloak(config) {
-	try {
-		const { cloakBrowserDoctor } = await import("./providers/cloakbrowser.js");
-		const doctor = await cloakBrowserDoctor({
-			...config?.cacheDir ? { cacheDir: config.cacheDir } : {},
-			...config?.binaryPath ? { binaryPath: config.binaryPath } : {}
-		});
-		if (!doctor.installed) return hint("cloakbrowser", "cloakbrowser_not_installed", `CloakBrowser binary not found (cacheDir=${doctor.cacheDir})`);
-		return null;
-	} catch (e) {
-		return hint("cloakbrowser", "cloakbrowser_not_installed", e instanceof Error ? e.message : String(e));
-	}
-}
-async function checkCdp(cdpUrl) {
-	let httpBase;
-	try {
-		httpBase = new URL(cdpUrl);
-		httpBase.protocol = httpBase.protocol === "wss:" ? "https:" : "http:";
-		httpBase.pathname = "/json/version";
-		httpBase.search = "";
-		httpBase.hash = "";
-	} catch (e) {
-		return hint("cdp", "cdp_unreachable", `invalid cdpUrl: ${e instanceof Error ? e.message : String(e)}`);
-	}
-	try {
-		const res = await fetch(httpBase.toString(), { signal: AbortSignal.timeout(2e3) });
-		if (!res.ok) return hint("cdp", "cdp_unreachable", `HTTP ${res.status} from ${httpBase.toString()}`);
-		return null;
-	} catch (e) {
-		return hint("cdp", "cdp_unreachable", e instanceof Error ? e.message : String(e));
-	}
-}
-function checkCloud(params) {
-	if (params.apiKey?.trim()) return null;
-	if (params.providerType === "browserbase" ? process.env.BROWSERBASE_API_KEY?.trim() : process.env.BROWSER_USE_API_KEY?.trim()) return null;
-	return hint("cloud", "cloud_api_key_missing", `no API key configured for ${params.providerType}`);
-}
-/**
-* Probe the currently-configured browser backend. Returns `null` when ready.
-*
-* Probe budget is small (filesystem stats + loopback fetches with a 2s timeout)
-* so it's safe to call before every `browser_use` invocation — but callers
-* typically cache the result for a few seconds to handle bursts.
-*/
 async function checkBrowserReadiness(cfg) {
-	const backend = resolveBrowserBackendFromConfig(cfg);
-	let probe = null;
+	if (!cfg?.browser.enabled) return null;
+	const driver = cfg.browser.driver;
+	let detail = null;
+	let reason = null;
 	try {
-		switch (backend.mode) {
-			case "extension":
-				probe = await checkExtension(backend.config);
-				break;
-			case "local":
-				probe = await checkLocal();
-				break;
-			case "cloakbrowser":
-				probe = await checkCloak(backend.config);
-				break;
-			case "cdp":
-				probe = await checkCdp(backend.config.wsEndpoint);
-				break;
-			case "cloud":
-				probe = checkCloud({
-					providerType: backend.config.type,
-					apiKey: backend.config.apiKey
-				});
-				break;
+		if (driver.kind === "extension") {
+			const { browserExtDoctor } = await import("./providers/browser-ext-install.js");
+			if (!(await browserExtDoctor()).installed) {
+				reason = "extension_not_installed";
+				detail = "Chrome extension artifacts are not installed.";
+			}
+		} else if (driver.kind === "playwright") if (driver.executablePath) await access(driver.executablePath);
+		else {
+			const { playwrightChromiumDoctor } = await import("./providers/playwright-doctor.js");
+			const doctor = await playwrightChromiumDoctor();
+			if (!doctor.installed) {
+				reason = "chromium_missing";
+				detail = doctor.reason ?? "Chromium binary was not found.";
+			}
 		}
-	} catch (e) {
-		log.warn({
-			err: e,
-			backend: backend.mode
-		}, "Readiness probe threw unexpectedly");
-		return null;
+		else if (driver.kind === "cdp") {
+			const probe = new URL(driver.endpoint);
+			probe.protocol = probe.protocol === "wss:" ? "https:" : "http:";
+			probe.pathname = "/json/version";
+			probe.search = "";
+			probe.hash = "";
+			const response = await fetch(probe, { signal: AbortSignal.timeout(2e3) });
+			if (!response.ok) {
+				reason = "cdp_unreachable";
+				detail = `CDP endpoint returned HTTP ${response.status}.`;
+			}
+		} else {
+			const envKey = driver.provider === "browserbase" ? process.env.BROWSERBASE_API_KEY : process.env.BROWSER_USE_API_KEY;
+			if (!driver.apiKey?.trim() && !envKey?.trim()) {
+				reason = "remote_api_key_missing";
+				detail = `No API key is configured for ${driver.provider}.`;
+			}
+		}
+	} catch (error) {
+		log.debug({
+			err: error,
+			driver: driver.kind
+		}, "Browser readiness probe failed");
+		reason = driver.kind === "cdp" ? "cdp_unreachable" : driver.kind === "extension" ? "extension_not_connected" : "chromium_missing";
+		detail = error instanceof Error ? error.message : String(error);
 	}
-	return probe ? new BrowserNotReadyError(probe) : null;
+	if (!reason) return null;
+	return new BrowserNotReadyError({
+		driver: driver.kind,
+		reason,
+		detail: detail ?? void 0,
+		deepLink: buildBrowserSetupDeepLink(driver.kind)
+	});
 }
 //#endregion
 export { BrowserNotReadyError, buildBrowserSetupDeepLink, checkBrowserReadiness };

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

@@ -0,0 +1,30 @@
+import type { BrowserActionInput, BrowserControlResult } from '@xopcai/browser-control-contract';
+import type { Config } from '../../config/schema.js';
+import type { BrowserDriver } from '../drivers/browser-driver.js';
+export interface BrowserRuntimeOptions {
+    getConfig: () => Config['browser'];
+    createDriver: () => Promise<BrowserDriver>;
+    allowedUploadRoots?: string[];
+    emit?: (type: string, payload: unknown) => void;
+}
+export declare class BrowserRuntime {
+    private readonly options;
+    private driver;
+    private sessionsByTask;
+    constructor(options: BrowserRuntimeOptions);
+    execute(taskKey: string, input: BrowserActionInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    shutdown(): Promise<void>;
+    closeTaskSession(taskKey: string): Promise<void>;
+    private dispatch;
+    private executeSequence;
+    private authorize;
+    private validateUrl;
+    private validateRedirect;
+    private blockedRedirect;
+    private crossDomainPolicy;
+    private invalidUploadPath;
+    private resolveSession;
+    private getDriver;
+    private constrainResult;
+    private evictExpiredSessions;
+}