@xopcai/xopc 0.0.266 → 0.0.267

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

@@ -6,7 +6,7 @@ import { BrowserAutomationService } from "./service.js";
 function createRuntimeBrowserAutomationService(deps) {
 	const runtime = new BrowserRuntime({
 		getConfig: () => deps.getConfig().browser,
-		createDriver: () => createBrowserDriver(deps.getConfig().browser),
+		createDriver: () => createBrowserDriver(deps.getConfig().browser, deps.endpointTools),
 		allowedUploadRoots: [process.cwd()],
 		emit: deps.emit
 	});

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

@@ -1,3 +1,4 @@
 import type { Config } from '../../config/schema.js';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
 import type { BrowserDriver } from './browser-driver.js';
-export declare function createBrowserDriver(config: Config['browser']): Promise<BrowserDriver>;
+export declare function createBrowserDriver(config: Config['browser'], endpointTools: EndpointToolRuntime): Promise<BrowserDriver>;

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

@@ -3,22 +3,20 @@ import { init_logger } from "../../utils/logger.js";
 import { loadPlaywrightCoreModule } from "../providers/playwright-doctor.js";
 import { BrowserbaseProvider } from "../providers/browserbase.js";
 import { BrowserUseProvider } from "../providers/browser-use.js";
-import { acquireExtensionBrowserServer } from "../providers/extension-ws-acquire.js";
+import { RealtimeExtensionBrowserProvider } from "../providers/realtime-extension.js";
 import { ExtensionDriver } from "./extension-driver.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
 //#region src/browser/drivers/create-driver.ts
 init_logger();
 const log = createLogger("BrowserDriverFactory");
-async function createBrowserDriver(config) {
+async function createBrowserDriver(config, endpointTools) {
 	const limits = config.limits;
 	if (config.driver.kind === "extension") {
-		const { provider, release } = await acquireExtensionBrowserServer({
-			host: "127.0.0.1",
-			port: 19820,
+		const provider = new RealtimeExtensionBrowserProvider(endpointTools, {
 			connectionTimeout: limits.actionTimeoutMs,
 			commandTimeout: limits.actionTimeoutMs
 		});
-		return new ExtensionDriver(provider, limits.actionTimeoutMs, config.observation.visualFallback, release);
+		return new ExtensionDriver(provider, limits.actionTimeoutMs, config.observation.visualFallback, () => provider.shutdown());
 	}
 	const driver = config.driver;
 	return new PlaywrightDriver({

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

@@ -1,13 +1,17 @@
 import type { BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
-import type { ExtensionBrowserProvider } from '../providers/extension.js';
 import type { BrowserDriver, BrowserPrimitiveInput } from './browser-driver.js';
+type ExtensionProvider = {
+    start(): Promise<void>;
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    send(input: import('@xopcai/browser-control-contract').BrowserActionInput, timeoutMs?: number, visualFallback?: boolean): Promise<import('@xopcai/browser-control-contract').BrowserWireResult>;
+};
 export declare class ExtensionDriver implements BrowserDriver {
     private readonly provider;
     private readonly timeoutMs;
     private readonly visualFallback;
     private readonly release;
     readonly kind: "extension";
-    constructor(provider: ExtensionBrowserProvider, timeoutMs: number, visualFallback: boolean, release: () => Promise<void>);
+    constructor(provider: ExtensionProvider, timeoutMs: number, visualFallback: boolean, release: () => Promise<void>);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     createSession(_sessionId: string): Promise<void>;
@@ -18,3 +22,4 @@ export declare class ExtensionDriver implements BrowserDriver {
     tabs(sessionId: string, input: BrowserTabsInput): Promise<BrowserControlResult>;
     private send;
 }
+export {};

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

@@ -0,0 +1,8 @@
+export type BrowserEnrollmentPublicKeyJwk = {
+    kty: 'EC';
+    crv: 'P-256';
+    x: string;
+    y: string;
+};
+export declare function parseBrowserEnrollmentPublicKeyJwk(value: unknown): BrowserEnrollmentPublicKeyJwk;
+export declare function browserEnrollmentPublicKeyThumbprint(value: unknown): string;

package/dist/src/browser/enrollment.js

@@ -0,0 +1,25 @@
+import crypto from "node:crypto";
+//#region src/browser/enrollment.ts
+function parseBrowserEnrollmentPublicKeyJwk(value) {
+	if (!value || typeof value !== "object") throw new Error("Browser enrollment public key is missing");
+	const key = value;
+	if (key.kty !== "EC" || key.crv !== "P-256" || typeof key.x !== "string" || !key.x || typeof key.y !== "string" || !key.y) throw new Error("Browser enrollment public key is invalid");
+	return {
+		kty: "EC",
+		crv: "P-256",
+		x: key.x,
+		y: key.y
+	};
+}
+function browserEnrollmentPublicKeyThumbprint(value) {
+	const key = parseBrowserEnrollmentPublicKeyJwk(value);
+	const canonical = JSON.stringify({
+		crv: key.crv,
+		kty: key.kty,
+		x: key.x,
+		y: key.y
+	});
+	return crypto.createHash("sha256").update(canonical).digest("base64url");
+}
+//#endregion
+export { browserEnrollmentPublicKeyThumbprint, parseBrowserEnrollmentPublicKeyJwk };

package/dist/src/browser/extension-identity.d.ts

@@ -0,0 +1,2 @@
+export declare const BROWSER_NATIVE_HOST_NAME = "ai.xopc.browser";
+export declare const BROWSER_EXTENSION_ID = "gopbfhaojnnhiheiikblejnpgmfmkmgd";

package/dist/src/browser/extension-identity.js

@@ -0,0 +1,5 @@
+//#region src/browser/extension-identity.ts
+const BROWSER_NATIVE_HOST_NAME = "ai.xopc.browser";
+const BROWSER_EXTENSION_ID = "gopbfhaojnnhiheiikblejnpgmfmkmgd";
+//#endregion
+export { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME };

package/dist/src/browser/native-messaging-host.d.ts

@@ -1,7 +1,10 @@
-export declare const BROWSER_NATIVE_HOST_NAME = "ai.xopc.browser";
-export declare const BROWSER_EXTENSION_ID = "gopbfhaojnnhiheiikblejnpgmfmkmgd";
+export { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME } from './extension-identity.js';
 export type BrowserNativeBootstrap = {
     type: 'bootstrap';
+    extensionId: string;
+    publicKeyJwk: unknown;
+    publicKeyThumbprint: string;
+    nonce: string;
 };
 export type BrowserNativeBootstrapResult = {
     ok: true;
@@ -11,5 +14,5 @@ export type BrowserNativeBootstrapResult = {
 };
 export declare function encodeNativeMessage(value: unknown): Buffer;
 export declare function decodeNativeMessage(buffer: Buffer): unknown;
-export declare function createBrowserNativeBootstrap(configPath: string): BrowserNativeBootstrapResult;
+export declare function createBrowserNativeBootstrap(configPath: string, request: Omit<BrowserNativeBootstrap, 'type'>): BrowserNativeBootstrapResult;
 export declare function runBrowserNativeMessagingHost(configPath: string): Promise<void>;

package/dist/src/browser/native-messaging-host.js

@@ -2,11 +2,11 @@ import { closeXopcDatabase, openXopcDatabase } from "../storage/sqlite/connectio
 import { getGatewayIdentityPublicKeyRaw, getOrCreateGatewayIdentity } from "../storage/sqlite/gateway-identity-repository.js";
 import { createDevicePairingSetup } from "../storage/sqlite/device-pairing-repository.js";
 import { init_loader, loadConfig } from "../config/loader.js";
+import { browserEnrollmentPublicKeyThumbprint } from "./enrollment.js";
+import { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME } from "./extension-identity.js";
 import os from "node:os";
 //#region src/browser/native-messaging-host.ts
 init_loader();
-const BROWSER_NATIVE_HOST_NAME = "ai.xopc.browser";
-const BROWSER_EXTENSION_ID = "gopbfhaojnnhiheiikblejnpgmfmkmgd";
 function gatewayLoopbackUrl(port) {
 	return `http://127.0.0.1:${port}`;
 }
@@ -22,7 +22,11 @@ function decodeNativeMessage(buffer) {
 	if (length === 0 || length > 1024 * 1024 || buffer.length !== length + 4) throw new Error("Native message length is invalid");
 	return JSON.parse(buffer.subarray(4).toString("utf8"));
 }
-function createBrowserNativeBootstrap(configPath) {
+function createBrowserNativeBootstrap(configPath, request) {
+	if (request.extensionId !== "gopbfhaojnnhiheiikblejnpgmfmkmgd") throw new Error("Browser extension identity is not trusted");
+	if (!/^[A-Za-z0-9_-]{24,160}$/.test(request.nonce)) throw new Error("Browser enrollment nonce is invalid");
+	const publicKeyThumbprint = browserEnrollmentPublicKeyThumbprint(request.publicKeyJwk);
+	if (request.publicKeyThumbprint !== publicKeyThumbprint) throw new Error("Browser enrollment key does not match");
 	const gatewayUrl = gatewayLoopbackUrl(loadConfig(configPath).gateway.port ?? 18790);
 	openXopcDatabase();
 	try {
@@ -31,7 +35,15 @@ function createBrowserNativeBootstrap(configPath) {
 			kind: "local-browser",
 			url: gatewayUrl
 		};
-		const setup = createDevicePairingSetup([route], Date.now(), 3);
+		const setup = createDevicePairingSetup([route], Date.now(), 3, {
+			ttlMs: 6e4,
+			enrollment: {
+				issuer: "browser-native-host",
+				extensionId: request.extensionId,
+				publicKeyThumbprint,
+				nonce: request.nonce
+			}
+		});
 		const identity = getOrCreateGatewayIdentity();
 		return {
 			ok: true,
@@ -93,7 +105,13 @@ async function runBrowserNativeMessagingHost(configPath) {
 	try {
 		const request = decodeNativeMessage(await readOneNativeMessage(process.stdin));
 		if (!request || typeof request !== "object" || request.type !== "bootstrap") throw new Error("Unsupported native messaging request");
-		process.stdout.write(encodeNativeMessage(createBrowserNativeBootstrap(configPath)));
+		const bootstrap = request;
+		process.stdout.write(encodeNativeMessage(createBrowserNativeBootstrap(configPath, {
+			extensionId: bootstrap.extensionId,
+			publicKeyJwk: bootstrap.publicKeyJwk,
+			publicKeyThumbprint: bootstrap.publicKeyThumbprint,
+			nonce: bootstrap.nonce
+		})));
 	} catch (error) {
 		process.stdout.write(encodeNativeMessage({
 			ok: false,

package/dist/src/browser/providers/browser-ext-install.d.ts

@@ -26,6 +26,7 @@ export interface BrowserExtDoctor {
     needsChromeReload?: boolean;
     bundledFrom?: BrowserExtBundledFrom;
     runtimeExtensionVersion?: string;
+    nativeHost: BrowserNativeHostInstallResult;
 }
 export interface EnsureBrowserExtResult {
     extensionDir: string;
@@ -65,17 +66,19 @@ export declare function ensureBrowserExtensionArtifacts(opts?: {
     cacheDir?: string;
 }): Promise<EnsureBrowserExtResult>;
 export declare function browserNativeManifestDirectories(platform?: NodeJS.Platform, home?: string): string[];
+export declare function browserNativeHostDoctor(platform?: NodeJS.Platform, home?: string): BrowserNativeHostInstallResult;
 /** Install the local-only bootstrap host used to discover and pair with a Gateway. */
 export declare function installBrowserNativeMessagingHost(opts?: {
     cacheDir?: string;
     cliPath?: string;
     nodePath?: string;
+    tsxCliPath?: string;
     platform?: NodeJS.Platform;
     home?: string;
     configPath?: string;
     stateDir?: string;
 }): Promise<BrowserNativeHostInstallResult>;
-/** Gateway startup hook: ensure artifacts only while the extension driver is active. */
+/** Gateway startup hook: install/repair extension artifacts and its local enrollment host. */
 export declare function ensureBrowserExtensionOnStartup(config: Config | undefined): Promise<void>;
 export declare function readInstalledExtensionDir(cacheDir?: string): Promise<string | null>;
 export type BrowserExtensionOpenAction = 'chrome' | 'folder' | 'both';

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

@@ -5,10 +5,11 @@ import { init_logger } from "../../utils/logger.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 "../native-messaging-host.js";
+import { BROWSER_EXTENSION_ID, BROWSER_NATIVE_HOST_NAME } from "../extension-identity.js";
+import "../native-messaging-host.js";
 import { resolvePackageRoot } from "../../infra/update-check.js";
 import { dirname, join } from "node:path";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -240,7 +241,8 @@ async function browserExtDoctor(opts) {
 		needsRefresh,
 		needsChromeReload,
 		bundledFrom: bundled?.bundledFrom,
-		runtimeExtensionVersion: runtimeVer
+		runtimeExtensionVersion: runtimeVer,
+		nativeHost: browserNativeHostDoctor()
 	};
 }
 async function ensureBrowserExtensionArtifacts(opts) {
@@ -302,33 +304,68 @@ function browserNativeManifestDirectories(platform = process.platform, home = pr
 	if (!home) return [];
 	if (platform === "darwin") return [
 		join(home, "Library/Application Support/Google/Chrome/NativeMessagingHosts"),
+		join(home, "Library/Application Support/Google/ChromeForTesting/NativeMessagingHosts"),
 		join(home, "Library/Application Support/Chromium/NativeMessagingHosts"),
 		join(home, "Library/Application Support/Microsoft Edge/NativeMessagingHosts"),
 		join(home, "Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts")
 	];
 	if (platform === "linux") return [
 		join(home, ".config/google-chrome/NativeMessagingHosts"),
+		join(home, ".config/google-chrome-for-testing/NativeMessagingHosts"),
 		join(home, ".config/chromium/NativeMessagingHosts"),
 		join(home, ".config/microsoft-edge/NativeMessagingHosts"),
 		join(home, ".config/BraveSoftware/Brave-Browser/NativeMessagingHosts")
 	];
 	return [];
 }
+function browserNativeHostDoctor(platform = process.platform, home = process.env.HOME || process.env.USERPROFILE || "") {
+	const directories = browserNativeManifestDirectories(platform, home);
+	if (directories.length === 0) return {
+		installed: false,
+		manifestPaths: [],
+		reason: "Automatic local Gateway discovery is supported on macOS and Linux"
+	};
+	const manifestPaths = directories.map((directory) => join(directory, `${BROWSER_NATIVE_HOST_NAME}.json`)).filter((manifestPath) => {
+		try {
+			const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+			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;
+		}
+	});
+	return {
+		installed: manifestPaths.length > 0,
+		manifestPaths,
+		...manifestPaths.length === 0 ? { reason: "Browser native enrollment host is not installed" } : {}
+	};
+}
 /** Install the local-only bootstrap host used to discover and pair with a Gateway. */
 async function installBrowserNativeMessagingHost(opts) {
 	const directories = browserNativeManifestDirectories(opts?.platform ?? process.platform, opts?.home);
 	if (directories.length === 0) return {
 		installed: false,
 		manifestPaths: [],
-		reason: "Native bootstrap installation is supported on macOS and Linux"
+		reason: "Automatic local Gateway discovery is supported on macOS and Linux"
 	};
 	const cliPath = opts?.cliPath ?? process.argv[1];
 	if (!cliPath) throw new Error("Unable to resolve the xopc CLI entry point");
+	const executablePath = opts?.nodePath ?? process.execPath;
+	let executableArgs = [
+		cliPath,
+		"browser",
+		"extension",
+		"native-host"
+	];
+	if (cliPath.endsWith(".ts")) {
+		const tsxPath = opts?.tsxCliPath ?? join(process.cwd(), "node_modules", "tsx", "dist", "cli.mjs");
+		if (!existsSync(tsxPath)) throw new Error("Unable to install the browser native host in development: the tsx CLI entry was not found");
+		executableArgs = [realpathSync(tsxPath), ...executableArgs];
+	}
 	const hostPath = join((opts?.cacheDir?.trim() ? assertCacheDir(opts.cacheDir) : resolveBinDir()) || resolveBinDir(), "browser-native-host");
 	mkdirSync(dirname(hostPath), { recursive: true });
 	const stateDir = opts?.stateDir ?? resolveStateDir();
 	const configPath = opts?.configPath ?? resolveConfigPath();
-	await writeTextAtomic(hostPath, `#!/bin/sh\nexec env XOPC_STATE_DIR=${shellQuote(stateDir)} XOPC_CONFIG_PATH=${shellQuote(configPath)} XOPC_LOG_CONSOLE=false ${shellQuote(opts?.nodePath ?? process.execPath)} ${shellQuote(cliPath)} browser extension native-host\n`);
+	await writeTextAtomic(hostPath, `#!/bin/sh\nexec env ELECTRON_RUN_AS_NODE=1 XOPC_STATE_DIR=${shellQuote(stateDir)} XOPC_CONFIG_PATH=${shellQuote(configPath)} XOPC_LOG_CONSOLE=false ${shellQuote(executablePath)} ${executableArgs.map(shellQuote).join(" ")}\n`);
 	chmodSync(hostPath, 493);
 	const manifest = JSON.stringify({
 		name: BROWSER_NATIVE_HOST_NAME,
@@ -349,10 +386,12 @@ async function installBrowserNativeMessagingHost(opts) {
 		manifestPaths
 	};
 }
-/** Gateway startup hook: ensure artifacts only while the extension driver is active. */
+/** Gateway startup hook: install/repair extension artifacts and its local enrollment host. */
 async function ensureBrowserExtensionOnStartup(config) {
 	if (config?.browser.enabled === false || config?.browser.driver.kind !== "extension") return;
 	await ensureBrowserExtensionArtifacts();
+	const nativeHost = await installBrowserNativeMessagingHost();
+	if (!nativeHost.installed) log.warn({ reason: nativeHost.reason }, "Browser native enrollment host was not installed");
 }
 async function readInstalledExtensionDir(cacheDir) {
 	const resolved = (cacheDir?.trim() ? assertCacheDir(cacheDir) : resolveBinDir()) || resolveBinDir();
@@ -432,4 +471,4 @@ async function openBrowserExtensionInstallUi(opts) {
 	};
 }
 //#endregion
-export { BROWSER_EXT_REQUIRED_FILES, browserExtContentHash, browserExtDoctor, browserNativeManifestDirectories, computeNeedsRefresh, ensureBrowserExtensionArtifacts, ensureBrowserExtensionOnStartup, installBrowserNativeMessagingHost, openBrowserExtensionInstallUi, readInstalledExtensionDir, resolveBundledBrowserExtDir, resolveInstalledExtensionPath, resolveWindowsExtensionManager, validateBrowserExtLayout };
+export { BROWSER_EXT_REQUIRED_FILES, browserExtContentHash, browserExtDoctor, browserNativeHostDoctor, browserNativeManifestDirectories, computeNeedsRefresh, ensureBrowserExtensionArtifacts, ensureBrowserExtensionOnStartup, installBrowserNativeMessagingHost, openBrowserExtensionInstallUi, readInstalledExtensionDir, resolveBundledBrowserExtDir, resolveInstalledExtensionPath, resolveWindowsExtensionManager, validateBrowserExtLayout };

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

@@ -2,8 +2,8 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { deleteBrowserTabBindingsByPrincipal, getBrowserTabBindingById } from "../../storage/sqlite/browser-tab-binding-repository.js";
 import { getDevice } from "../../storage/sqlite/device-access-repository.js";
-import { isChromeExtensionOrigin } from "../../gateway/security/origin-check.js";
 import { browserWireAuthenticationPayload } from "../../../packages/browser-control-contract/src/index.js";
+import { isChromeExtensionOrigin } from "../../gateway/security/origin-check.js";
 import crypto from "node:crypto";
 //#region src/browser/providers/extension.ts
 /**

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

@@ -0,0 +1,29 @@
+import { type BrowserActionInput, type BrowserWireResult } from '@xopcai/browser-control-contract';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
+export interface RealtimeExtensionProviderConfig {
+    connectionTimeout?: number;
+    commandTimeout?: number;
+}
+export declare class RealtimeExtensionBrowserProvider {
+    private readonly runtime;
+    readonly name = "extension";
+    private readonly connectionTimeout;
+    private readonly commandTimeout;
+    constructor(runtime: EndpointToolRuntime, config?: RealtimeExtensionProviderConfig);
+    start(): Promise<void>;
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    send(input: BrowserActionInput, timeoutMs?: number, visualFallback?: boolean): Promise<BrowserWireResult>;
+    isConnected(): boolean;
+    getConnectionStatus(): {
+        socketConnected: boolean;
+        connected: boolean;
+        protocolVersion: number;
+        expectedProtocolVersion: number;
+        extensionVersion: string;
+        principalId: string;
+        transport: "gateway-realtime";
+    };
+    shutdown(): Promise<void>;
+    private endpointForInput;
+    private currentEndpoint;
+}

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

@@ -0,0 +1,83 @@
+import { getBrowserTabBindingById } from "../../storage/sqlite/browser-tab-binding-repository.js";
+import { BROWSER_CONTROL_ENDPOINT_TOOL_NAME } from "../../../packages/browser-control-contract/src/index.js";
+import crypto from "node:crypto";
+//#region src/browser/providers/realtime-extension.ts
+var RealtimeExtensionBrowserProvider = class {
+	name = "extension";
+	connectionTimeout;
+	commandTimeout;
+	constructor(runtime, config = {}) {
+		this.runtime = runtime;
+		this.connectionTimeout = config.connectionTimeout ?? 3e4;
+		this.commandTimeout = config.commandTimeout ?? 3e4;
+	}
+	async start() {}
+	async waitForConnection(timeoutMs = this.connectionTimeout) {
+		const deadline = Date.now() + timeoutMs;
+		while (!this.currentEndpoint()) {
+			if (Date.now() >= deadline) throw new Error(`Extension connection timeout after ${timeoutMs}ms. Open the xopc Chrome extension and connect it to this Gateway.`);
+			await new Promise((resolve) => setTimeout(resolve, 200));
+		}
+	}
+	async send(input, timeoutMs = this.commandTimeout, visualFallback = true) {
+		const endpoint = this.endpointForInput(input);
+		if (!endpoint) throw new Error("Extension not connected to this Gateway. Open the xopc Chrome extension and connect it first.");
+		const tool = this.runtime.registry.getTool(endpoint.endpointId, BROWSER_CONTROL_ENDPOINT_TOOL_NAME);
+		if (!tool) throw new Error("Connected browser extension does not support authenticated Realtime browser control. Reload or update the extension.");
+		const id = crypto.randomUUID();
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const value = (await this.runtime.invocations.invoke({
+				endpointId: endpoint.endpointId,
+				toolCallId: `browser-control:${id}`,
+				toolName: tool.descriptor.name,
+				arguments: {
+					input,
+					timeoutMs,
+					visualFallback
+				},
+				descriptorRevision: tool.revision,
+				signal: controller.signal
+			})).content.find((item) => item.type === "json");
+			if (!value || !value.value || typeof value.value !== "object") throw new Error("Browser extension returned an invalid Realtime result");
+			return {
+				id,
+				connectionId: endpoint.endpointId,
+				result: value.value
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	isConnected() {
+		return Boolean(this.currentEndpoint());
+	}
+	getConnectionStatus() {
+		const endpoint = this.currentEndpoint();
+		return {
+			socketConnected: Boolean(endpoint),
+			connected: Boolean(endpoint),
+			protocolVersion: endpoint ? 4 : null,
+			expectedProtocolVersion: 4,
+			extensionVersion: endpoint?.appVersion ?? null,
+			principalId: endpoint?.principalId ?? null,
+			transport: "gateway-realtime"
+		};
+	}
+	async shutdown() {}
+	endpointForInput(input) {
+		if (input.target?.kind === "attached_tab") {
+			const binding = getBrowserTabBindingById(input.target.bindingId);
+			const endpoint = binding ? this.runtime.registry.get(binding.endpointId) : void 0;
+			if (!binding || !endpoint || endpoint.principalId !== binding.principalId) return void 0;
+			return endpoint;
+		}
+		return this.currentEndpoint();
+	}
+	currentEndpoint() {
+		return this.runtime.registry.list().filter((endpoint) => endpoint.kind === "browser" && endpoint.tools.some((tool) => tool.descriptor.name === "browser.control")).sort((left, right) => right.lastHeartbeatAt - left.lastHeartbeatAt)[0];
+	}
+};
+//#endregion
+export { RealtimeExtensionBrowserProvider };

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

@@ -52,7 +52,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${status.dbVersion} (current release v156).`,
+		message: `SQLite schema v${status.dbVersion} (current release v158).`,
 		hints: []
 	};
 }

package/dist/src/endpoint-tools/policy.js

@@ -1,11 +1,13 @@
 import { ENDPOINT_CONTACT_LIST_OUTPUT_SCHEMA, ENDPOINT_CONTACT_OUTPUT_SCHEMA, ENDPOINT_FILE_OUTPUT_SCHEMA, ENDPOINT_TEXT_OUTPUT_SCHEMA, canonicalJson } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { BROWSER_CONTROL_ENDPOINT_INPUT_SCHEMA, BROWSER_CONTROL_ENDPOINT_OUTPUT_SCHEMA } from "../../packages/browser-control-contract/src/index.js";
 import Ajv2020 from "ajv/dist/2020.js";
 //#region src/endpoint-tools/policy.ts
 var EndpointToolPolicyError = class extends Error {};
-function contract(policyId, outputSchema, resultKinds, permissions, legacyPolicyIds = []) {
+function contract(policyId, outputSchema, resultKinds, permissions, legacyPolicyIds = [], inputSchema) {
 	return {
 		policyId,
 		legacyPolicyIds,
+		inputSchema,
 		outputSchema,
 		resultKinds,
 		permissions
@@ -31,7 +33,8 @@ const POLICY_BY_TOOL = {
 	"mobile.notification.show": contract("user.foreground-write", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], ["notifications"]),
 	"mobile.device.get_info": contract("public.background-read", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], []),
 	"mobile.clipboard.write": contract("user.foreground-write", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], ["clipboard-write"]),
-	"mobile.app.open_url": contract("user.foreground-write", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], ["open-external-url"])
+	"mobile.app.open_url": contract("user.foreground-write", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], ["open-external-url"]),
+	"browser.control": contract("browser.control", BROWSER_CONTROL_ENDPOINT_OUTPUT_SCHEMA, ["json"], ["browser-control"], [], BROWSER_CONTROL_ENDPOINT_INPUT_SCHEMA)
 };
 var EndpointToolPolicy = class {
 	ajv = new Ajv2020({
@@ -43,7 +46,7 @@ var EndpointToolPolicy = class {
 		const contract = POLICY_BY_TOOL[descriptor.name];
 		if (!contract) throw new EndpointToolPolicyError(`Tool ${descriptor.name} has no trusted server policy`);
 		if (descriptor.policyId !== contract.policyId && !contract.legacyPolicyIds.includes(descriptor.policyId)) throw new EndpointToolPolicyError(`Tool ${descriptor.name} does not match its trusted server policy`);
-		if (canonicalJson(descriptor.outputSchema) !== canonicalJson(contract.outputSchema) || canonicalJson(descriptor.resultKinds) !== canonicalJson(contract.resultKinds) || canonicalJson([...descriptor.requiredPermissions].sort()) !== canonicalJson([...contract.permissions].sort())) throw new EndpointToolPolicyError(`Tool ${descriptor.name} does not match its trusted server contract`);
+		if (contract.inputSchema && canonicalJson(descriptor.inputSchema) !== canonicalJson(contract.inputSchema) || canonicalJson(descriptor.outputSchema) !== canonicalJson(contract.outputSchema) || canonicalJson(descriptor.resultKinds) !== canonicalJson(contract.resultKinds) || canonicalJson([...descriptor.requiredPermissions].sort()) !== canonicalJson([...contract.permissions].sort())) throw new EndpointToolPolicyError(`Tool ${descriptor.name} does not match its trusted server contract`);
 		this.validatePolicyFields(descriptor);
 		try {
 			this.ajv.compile(descriptor.outputSchema);
@@ -79,6 +82,10 @@ var EndpointToolPolicy = class {
 				if (descriptor.effect === "read") throw new EndpointToolPolicyError(`Mutating tool ${descriptor.name} cannot declare a read effect`);
 				if (descriptor.confirmation !== "always" || !descriptor.requiresForeground || descriptor.sensitivity !== "personal" || descriptor.requiredPermissions.length === 0) throw new EndpointToolPolicyError(`Mutating tool ${descriptor.name} violates its trusted policy`);
 				return;
+			case "browser.control":
+				this.assertFields(descriptor, "write", "never", false, "personal");
+				if (descriptor.requiredPermissions.length !== 1 || descriptor.requiredPermissions[0] !== "browser-control" || descriptor.timeoutMs !== 12e4 || descriptor.maxConcurrency !== 4 || descriptor.supportsCancellation !== true || descriptor.idempotent !== false) throw new EndpointToolPolicyError(`Browser tool ${descriptor.name} violates its trusted policy`);
+				return;
 			default: throw new EndpointToolPolicyError(`Unknown endpoint policy: ${descriptor.policyId}`);
 		}
 	}

package/dist/src/gateway/hono/app.js

@@ -5,6 +5,7 @@ import { resolveAllowedBrowserOrigins, resolveGatewayServiceListenPort } from ".
 import { resolveGatewayEffectiveHost } from "../../config/gateway-bind.js";
 import { loadTunnelState } from "../../tunnel/tunnel-state.js";
 import { resolveReverseProxyPublicUrl } from "../public-url.js";
+import { BROWSER_EXTENSION_ID } from "../../browser/extension-identity.js";
 import { maxSessionInputRequestBodyBytes } from "../chat-limits.js";
 import { isLoopbackIpAddress, isTrustedProxyAddress } from "../client-ip.js";
 import { buildGatewayConsoleCspHeader } from "../security/csp.js";
@@ -65,7 +66,11 @@ function createHonoApp(config) {
 			return [];
 		}
 	};
-	const resolveAllBrowserOrigins = () => [...resolveBrowserOrigins(), ...resolvePairedBrowserExtensionOrigins()];
+	const resolveAllBrowserOrigins = () => [
+		...resolveBrowserOrigins(),
+		`chrome-extension://${BROWSER_EXTENSION_ID}`,
+		...resolvePairedBrowserExtensionOrigins()
+	];
 	/**
 	* TCP source for the in-flight request, normalized for trusted-proxy checks.
 	* Returns undefined when the runtime doesn't expose conninfo (tests, mocks).