pi-browser-use 0.9.5 → 0.10.0

package/README.md

@@ -1,5 +1,8 @@
 # pi-browser-use
 
+Native Pi extension **and Agent Plugins 1.0 / standalone MCP server**, sharing the same
+curated browser runtime. See [portable installation and configuration](docs/agent-plugins.md).
+
 Opinionated browser-use for the [Pi coding agent](https://pi.dev), powered by [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) — not Playwright.
 
 ## Why this exists
@@ -159,7 +162,7 @@ On startup the default persistent profile is checked for accessibility. A root-o
 
 `npm run bench` times the tool stack headless over 5 iterations (fixture setup excluded, matching vercel-labs/agent-browser's scenario set). Baseline on Apple Silicon: navigate ~1ms, snapshot ~3ms, screenshot ~37ms, evaluate ~206ms, full agent-loop cycle ~422ms. Re-run on your hardware before quoting numbers.
 
-`npm run perf:audit` reports cold-import memory/time plus published package and dependency footprint; `npm test` enforces the stable regression budgets. See [Performance audit and budgets](docs/performance.md) for the M0 measurements, thresholds, and reproducible local/CI commands.
+`npm run perf:audit` reports cold-import memory/time plus published package and dependency footprint; Code Foundry's dedicated performance job enforces the stable regression budgets with `npm run perf:check`. See [Performance audit and budgets](docs/performance.md) for the M0 measurements, thresholds, and reproducible local/CI commands.
 
 ## Bundled skills
 

package/dist/artifacts.d.ts

@@ -1,7 +1,7 @@
 export type ArtifactKind = 'screenshot' | 'html';
 export declare function defaultArtifactDir(): string;
 /** Resolve the destination file: explicit path wins, otherwise a timestamped file in the default dir. */
-export declare function resolveArtifactTarget(kind: ArtifactKind, path?: unknown): string;
+export declare function resolveArtifactTarget(kind: ArtifactKind, path?: unknown, directory?: string): string;
 /** Pick the first image payload out of MCP content, if any. */
 export declare function pickImageData(content: unknown): {
     data: string;

package/dist/artifacts.js

@@ -4,10 +4,10 @@ export function defaultArtifactDir() {
     return join(homedir(), '.pi', 'browser-artifacts');
 }
 /** Resolve the destination file: explicit path wins, otherwise a timestamped file in the default dir. */
-export function resolveArtifactTarget(kind, path) {
+export function resolveArtifactTarget(kind, path, directory = defaultArtifactDir()) {
     if (typeof path === 'string' && path.length > 0)
         return path;
-    return join(defaultArtifactDir(), `page-${Date.now()}.${kind === 'html' ? 'html' : 'png'}`);
+    return join(directory, `page-${Date.now()}.${kind === 'html' ? 'html' : 'png'}`);
 }
 /** Pick the first image payload out of MCP content, if any. */
 export function pickImageData(content) {

package/dist/chrome-launcher.d.ts

@@ -28,6 +28,7 @@ export interface ChromeLaunchOptions {
     executablePath?: string;
     /** How long to wait for the DevTools endpoint. Default 15s. */
     readyTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 export interface ChromeProcess {
     readonly pid: number | undefined;
@@ -68,6 +69,7 @@ export declare function buildChromeArgs(options: {
 export declare function waitForDevToolsEndpoint(port: number, options?: {
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
 }): Promise<{
     browserUrl: string;
     webSocketDebuggerUrl: string;
@@ -102,5 +104,6 @@ export declare function launchSetupBrowser(options: {
     profileDirectory?: string;
     executablePath?: string;
     chromeArgs?: string[];
+    signal?: AbortSignal;
 }): Promise<number | null>;
 //# sourceMappingURL=chrome-launcher.d.ts.map

package/dist/chrome-launcher.js

@@ -19,6 +19,7 @@
 import { execFileSync, spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
 /** Chrome/Chromium executable candidates by platform (stable first). */
 export function chromeExecutableCandidates() {
     if (process.platform === 'darwin') {
@@ -131,8 +132,11 @@ export async function waitForDevToolsEndpoint(port, options) {
     const deadline = Date.now() + timeoutMs;
     let lastError;
     while (Date.now() < deadline) {
+        options?.signal?.throwIfAborted();
         try {
-            const response = await fetchImpl(`${browserUrl}/json/version`);
+            const timeout = AbortSignal.timeout(Math.max(1, Math.min(1000, deadline - Date.now())));
+            const signal = options?.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+            const response = await fetchImpl(`${browserUrl}/json/version`, { signal });
             if (response.ok) {
                 const info = (await response.json());
                 return { browserUrl, webSocketDebuggerUrl: info.webSocketDebuggerUrl ?? '' };
@@ -140,9 +144,10 @@ export async function waitForDevToolsEndpoint(port, options) {
             lastError = new Error(`DevTools endpoint answered ${response.status}`);
         }
         catch (error) {
+            options?.signal?.throwIfAborted();
             lastError = error;
         }
-        await new Promise((resolve) => setTimeout(resolve, 100));
+        await delay(100, undefined, { signal: options?.signal });
     }
     throw new Error(`Timed out waiting for Chrome DevTools on ${browserUrl} (${lastError instanceof Error ? lastError.message : String(lastError)})`);
 }
@@ -199,6 +204,7 @@ class OwnedChromeProcess {
  * (see `profile-lock.ts`) for `userDataDir` before calling.
  */
 export async function launchChrome(options) {
+    options.signal?.throwIfAborted();
     const executable = findChromeExecutable(options.executablePath);
     const port = options.port ?? (await allocateEphemeralPort());
     const args = buildChromeArgs({
@@ -218,7 +224,10 @@ export async function launchChrome(options) {
         throw new Error(`Chrome exited immediately (code ${child.exitCode}).`);
     }
     try {
-        await waitForDevToolsEndpoint(port, { timeoutMs: options.readyTimeoutMs });
+        await waitForDevToolsEndpoint(port, {
+            timeoutMs: options.readyTimeoutMs,
+            signal: options.signal,
+        });
     }
     catch (error) {
         try {
@@ -284,6 +293,7 @@ export function buildFocusWindowScript(markerUrl) {
  * launched Chrome. Resolves when the user closes the window.
  */
 export async function launchSetupBrowser(options) {
+    options.signal?.throwIfAborted();
     const executable = findChromeExecutable(options.executablePath);
     const args = buildChromeArgs({
         userDataDir: options.userDataDir,
@@ -291,9 +301,32 @@ export async function launchSetupBrowser(options) {
         chromeArgs: options.chromeArgs,
     });
     const child = spawn(executable, args, { stdio: 'ignore', detached: false });
+    const browser = new OwnedChromeProcess(child, 0, '', options.userDataDir);
     return new Promise((resolve, reject) => {
-        child.on('error', reject);
-        child.on('exit', (code) => resolve(code));
+        const cleanup = () => options.signal?.removeEventListener('abort', abort);
+        const abort = () => {
+            void browser.shutdown().then(() => {
+                cleanup();
+                reject(options.signal?.reason ?? new Error('Browser setup aborted.'));
+            }, (error) => {
+                cleanup();
+                reject(error);
+            });
+        };
+        child.once('error', (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.once('exit', (code) => {
+            cleanup();
+            if (options.signal?.aborted)
+                reject(options.signal.reason);
+            else
+                resolve(code);
+        });
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
     });
 }
 //# sourceMappingURL=chrome-launcher.js.map

package/dist/client.js

@@ -89,6 +89,8 @@ export class DevToolsClient {
         });
         const client = new Client({ name: 'pi-browser-use', version: '0.1.0' }, { capabilities: {} });
         this.client = client;
+        // MCP transport implements callback properties, not EventTarget.
+        // oxlint-disable-next-line unicorn/prefer-add-event-listener
         transport.onerror = (error) => {
             if (generation !== this.generation)
                 return;
@@ -96,9 +98,10 @@ export class DevToolsClient {
             console.error(`[pi-browser-use] chrome-devtools-mcp transport error (${transportErrorCode ?? error.name})`);
             void this.disconnectUnhealthyClient(generation);
         };
+        // oxlint-disable-next-line unicorn/prefer-add-event-listener
         transport.onclose = () => this.markDisconnected(generation);
         try {
-            await client.connect(transport, signal ? { signal, timeout: MCP_TIMEOUT_MS } : { timeout: MCP_TIMEOUT_MS });
+            await client.connect(transport, signal ? { signal, timeout: MCP_TIMEOUT_MS } : { timeout: MCP_TIMEOUT_MS, signal });
             if (generation !== this.generation)
                 return;
             this.state = 'ready';
@@ -125,6 +128,8 @@ export class DevToolsClient {
                 : undefined;
             const diagnostic = summarizeFailure(stderr, errorName, transportErrorCode ?? errorCode);
             console.error(`[pi-browser-use] browser connection failed: ${diagnostic}`);
+            // Raw upstream causes can contain credentials; retain only the sanitized diagnostic.
+            // oxlint-disable-next-line preserve-caught-error
             throw new Error(`Browser connection failed. ${diagnostic}`);
         }
     }
@@ -181,6 +186,7 @@ export class DevToolsClient {
         do {
             const result = await client.listTools(cursor ? { cursor } : undefined, {
                 timeout: MCP_TIMEOUT_MS,
+                signal,
             });
             allTools.push(...result.tools.map((t) => ({
                 name: t.name,
@@ -197,20 +203,23 @@ export class DevToolsClient {
         if (!client)
             throw new Error('Client not connected');
         try {
-            return await client.callTool({ name, arguments: args }, undefined, { timeout: MCP_TIMEOUT_MS });
+            return await client.callTool({ name, arguments: args }, undefined, { timeout: MCP_TIMEOUT_MS, signal });
         }
         catch (error) {
             if (signal?.aborted)
                 throw error;
             if (this.state !== 'ready' || this.client !== client) {
+                // oxlint-disable-next-line preserve-caught-error -- upstream causes may contain secrets
                 throw new Error('Browser connection lost; retry the tool.');
             }
             const errorName = error instanceof Error ? error.name : 'UnknownError';
             console.error(`[pi-browser-use] upstream tool call failed (${errorName})`);
             // Existing mode fails most often on the consent gate: say so plainly.
             if (this.config.sessionMode === 'existing') {
+                // oxlint-disable-next-line preserve-caught-error -- upstream causes may contain secrets
                 throw new Error('Browser tool call failed. If Chrome is showing an "Allow remote debugging?" prompt, click Allow and retry.');
             }
+            // oxlint-disable-next-line preserve-caught-error -- upstream causes may contain secrets
             throw new Error('Browser tool call failed.');
         }
     }

package/dist/config.d.ts

@@ -62,11 +62,11 @@ export type BrowserMode = 'fresh' | 'persistent' | 'existing';
  * (headless unless headed is requested, so logins work without popups).
  * Attach fields never carry across modes.
  */
-export declare function resolveModeTarget(base: BrowserUseConfig, mode: BrowserMode, headed?: boolean): BrowserUseConfig;
+export declare function resolveModeTarget(base: BrowserUseConfig, mode: BrowserMode, headed?: boolean, defaultProfileDir?: string): BrowserUseConfig;
 /** Expand a leading ~/ in user-supplied paths (env interpolation covers ${} only). */
 export declare function expandHome(path: string): string;
 /** Merge user config over fresh-headless defaults. */
-export declare function resolveConfig(config?: BrowserUseConfig): BrowserUseConfig;
+export declare function resolveConfig(config?: BrowserUseConfig, defaultProfileDir?: string): BrowserUseConfig;
 /** Convert config into CLI flags for the chrome-devtools-mcp subprocess. */
 export declare function configToArgs(config: BrowserUseConfig): string[];
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -31,10 +31,11 @@ const DEFAULTS = {
  * (headless unless headed is requested, so logins work without popups).
  * Attach fields never carry across modes.
  */
-export function resolveModeTarget(base, mode, headed = false) {
-    const { browserUrl: _browserUrl, wsEndpoint: _wsEndpoint, autoConnect: _autoConnect, mode: _mode, headed: _headed, ...rest } = base;
+export function resolveModeTarget(base, mode, headed = false, defaultProfileDir = DEFAULT_PROFILE_DIR) {
+    const { browserUrl: _browserUrl, wsEndpoint: _wsEndpoint, wsHeaders: _wsHeaders, autoConnect: _autoConnect, mode: _mode, headed: _headed, ...rest } = base;
     void _browserUrl;
     void _wsEndpoint;
+    void _wsHeaders;
     void _autoConnect;
     void _mode;
     void _headed;
@@ -44,11 +45,14 @@ export function resolveModeTarget(base, mode, headed = false) {
         return { ...freshRest, sessionMode: 'isolated', headless: !headed, isolated: true };
     }
     if (mode === 'existing') {
-        // Attach to the user's running Chrome: drop Pi-owned launch fields so
-        // MCP auto-connects instead of starting its own browser.
-        const { userDataDir: _userDataDir, isolated: _isolated, ...existingRest } = rest;
+        // Attach to the user's running Chrome: drop launch-only fields so MCP
+        // auto-connects instead of trying to start or reconfigure its browser.
+        const { userDataDir: _userDataDir, isolated: _isolated, executablePath: _executablePath, chromeArgs: _chromeArgs, viewport: _viewport, ...existingRest } = rest;
         void _userDataDir;
         void _isolated;
+        void _executablePath;
+        void _chromeArgs;
+        void _viewport;
         // Existing attaches to the user's visible Chrome: always headed.
         return { ...existingRest, sessionMode: 'existing', headless: false, autoConnect: true };
     }
@@ -57,7 +61,7 @@ export function resolveModeTarget(base, mode, headed = false) {
         sessionMode: 'persistent',
         headless: !headed,
         isolated: false,
-        userDataDir: base.userDataDir ?? DEFAULT_PROFILE_DIR,
+        userDataDir: base.userDataDir ?? defaultProfileDir,
     };
 }
 /** Expand a leading ~/ in user-supplied paths (env interpolation covers ${} only). */
@@ -65,7 +69,7 @@ export function expandHome(path) {
     return path === '~' ? homedir() : path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
 }
 /** Merge user config over fresh-headless defaults. */
-export function resolveConfig(config) {
+export function resolveConfig(config, defaultProfileDir = DEFAULT_PROFILE_DIR) {
     const { mode, headed, ...rest } = config ?? {};
     const resolved = { ...DEFAULTS, ...rest };
     if (typeof resolved.userDataDir === 'string')
@@ -116,7 +120,7 @@ export function resolveConfig(config) {
             break;
         default:
             if (!resolved.userDataDir && !resolved.browserUrl && !resolved.wsEndpoint) {
-                resolved.userDataDir = DEFAULT_PROFILE_DIR;
+                resolved.userDataDir = defaultProfileDir;
             }
             break;
     }

package/dist/existing-flow.js

@@ -78,7 +78,9 @@ export function parseMcpPageList(result) {
             const title = (match[2] ?? '').trim();
             if (title)
                 entry.title = title;
-            const url = (match[3] ?? '').trim();
+            // chrome-devtools-mcp 1.8 emits `N: URL [selected]`; retain support
+            // for the older `N: title (URL)` form as well.
+            const url = (match[3] ?? (/^(https?:|about:|file:|data:)/.test(title) ? title : '')).trim();
             if (url)
                 entry.url = url;
             entries.push(entry);
@@ -113,7 +115,7 @@ export async function openExistingPage(url, deps, options) {
     }
     catch (error) {
         throw new Error(`Pi extension did not open the tab (token ${token}). ` +
-            `Is the extension installed and polling the tab bridge? (${error instanceof Error ? error.message : String(error)})`);
+            `Is the extension installed and polling the tab bridge? (${error instanceof Error ? error.message : String(error)})`, { cause: error });
     }
     let pageId;
     try {

package/dist/index.d.ts

@@ -1,47 +1,20 @@
+import { createRegistryVisionCaller } from './vision.js';
 export { configToArgs, resolveConfig } from './config.js';
-interface ModelRegistry {
-    find(provider: string, modelId: string): unknown;
-    getApiKeyAndHeaders(model: unknown): Promise<{
-        ok: true;
-        apiKey?: string;
-        headers?: Record<string, string>;
-    } | {
-        ok: false;
-        error: string;
-    }>;
-}
-interface PiToolContext {
-    modelRegistry?: ModelRegistry;
-}
+type ModelRegistry = Parameters<typeof createRegistryVisionCaller>[1];
 interface Pi {
-    registerTool(def: {
+    registerTool(definition: {
         name: string;
         label: string;
         description: string;
         parameters: unknown;
-        execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal, onUpdate?: unknown, ctx?: PiToolContext) => Promise<{
-            content: Array<{
-                type: string;
-                text?: string;
-                data?: string;
-                mimeType?: string;
-            }>;
-            isError?: boolean;
-            details?: undefined;
-        }>;
+        execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal, onUpdate?: unknown, context?: {
+            modelRegistry?: ModelRegistry;
+        }) => Promise<unknown>;
     }): void;
-    on(event: string, handler: (event: unknown, ctx: {
+    on(event: string, handler: (event: unknown, context: {
         cwd: string;
     } & Record<string, unknown>) => Promise<void>): void;
 }
-/**
- * Pi extension entry point. On session_start spawns chrome-devtools-mcp,
- * discovers upstream tools, and registers each as browser_*. On
- * session_shutdown tears the subprocess down. Nothing runs persistently.
- *
- * Defaults are persistent headless (Pi-owned profile, no window, no consent
- * popups). Set mode "fresh" for an isolated clean room, or "existing" with
- * autoConnect/browserUrl to drive an already-running Chrome.
- */
+/** Native Pi owns settings/trust and model credentials, not browser behavior. */
 export default function browserUseExtension(pi: Pi): void;
 //# sourceMappingURL=index.d.ts.map