pi-browser-use 0.9.6 → 0.10.0

package/dist/mcp-server.d.ts

@@ -0,0 +1,47 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type BrowserRuntime, type BrowserRuntimeOptions } from './runtime.js';
+/** Only explicit host configuration is read; never .pi files or project settings. */
+export declare function loadPortableOptions(env?: NodeJS.ProcessEnv): BrowserRuntimeOptions;
+/** Low-level MCP adapter preserves the runtime's JSON schemas and curated tools. */
+export declare function createBrowserMcpServer(options?: {
+    runtime?: BrowserRuntime;
+    env?: NodeJS.ProcessEnv;
+}): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    close: () => Promise<void>;
+};
+export declare function runStdio(): Promise<void>;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.js

@@ -0,0 +1,218 @@
+import { mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, CallToolResultSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';
+import { createBrowserRuntime } from './runtime.js';
+import { expandHome } from './config.js';
+const validator = new AjvJsonSchemaValidator();
+const booleanOptions = [
+    'headed',
+    'headless',
+    'isolated',
+    'autoConnect',
+    'categoryPerformance',
+    'categoryNetwork',
+    'categoryEmulation',
+    'categoryExtensions',
+    'experimentalVision',
+    'experimentalScreencast',
+    'experimentalMemory',
+    'experimentalPageIdRouting',
+    'usageStatistics',
+    'performanceCrux',
+    'redactNetworkHeaders',
+    'acceptInsecureCerts',
+    'slim',
+];
+const stringOptions = [
+    'browserUrl',
+    'wsEndpoint',
+    'wsHeaders',
+    'executablePath',
+    'viewport',
+    'userDataDir',
+];
+const arrayOptions = ['allowedUrlPattern', 'blockedUrlPattern', 'chromeArgs', 'extraArgs'];
+const validateConfig = validator.getValidator({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ...Object.fromEntries(booleanOptions.map((key) => [key, { type: 'boolean' }])),
+        ...Object.fromEntries(stringOptions.map((key) => [key, { type: 'string', minLength: 1 }])),
+        ...Object.fromEntries(arrayOptions.map((key) => [key, { type: 'array', items: { type: 'string' } }])),
+        mode: { enum: ['fresh', 'persistent', 'existing'] },
+        sessionMode: { enum: ['isolated', 'persistent', 'existing'] },
+        channel: { enum: ['canary', 'dev', 'beta', 'stable'] },
+        tabBridgePort: { type: 'integer', minimum: 0, maximum: 65535 },
+    },
+});
+/** Only explicit host configuration is read; never .pi files or project settings. */
+export function loadPortableOptions(env = process.env) {
+    const dataDir = env.PI_BROWSER_USE_DATA_DIR ??
+        env.PLUGIN_DATA ??
+        join(homedir(), '.local', 'share', 'pi-browser-use');
+    if (!isAbsolute(dataDir))
+        throw new Error('Browser plugin data directory must be absolute.');
+    const configFile = env.PI_BROWSER_USE_CONFIG ?? join(dataDir, 'config.json');
+    if (!isAbsolute(configFile))
+        throw new Error('PI_BROWSER_USE_CONFIG must be an absolute path.');
+    let raw;
+    try {
+        raw = readFileSync(configFile, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || env.PI_BROWSER_USE_CONFIG)
+            throw error;
+    }
+    let parsed = {};
+    if (raw !== undefined) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            // JSON parse errors may include fragments of wsHeaders. Never echo those.
+            throw new Error('Browser plugin config.json is not valid JSON.', { cause: error });
+        }
+    }
+    const checked = validateConfig(parsed);
+    if (!checked.valid) {
+        throw new Error('Invalid browser plugin config.json. Use documented BrowserUseConfig fields; visionModel is Pi-only.');
+    }
+    const config = checked.data;
+    for (const key of ['userDataDir', 'executablePath']) {
+        if (config[key]) {
+            config[key] = expandHome(config[key]);
+            if (!isAbsolute(config[key]))
+                throw new Error(`${key} must be an absolute path (or start with ~/).`);
+        }
+    }
+    mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    return {
+        config,
+        defaultProfileDir: join(dataDir, 'browser-profile'),
+        artifactDir: join(dataDir, 'artifacts'),
+        lazyBrowser: true,
+        // Other hosts analyze returned screenshot images using their own model.
+        // No implicit Pi credentials, sampling calls, or extra model charges.
+        visionEnabled: false,
+    };
+}
+function packageVersion() {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+function reportFailure(error) {
+    console.error(`[pi-browser-use] MCP lifecycle failed (${error instanceof Error ? error.name : 'UnknownError'}).`);
+}
+/** Low-level MCP adapter preserves the runtime's JSON schemas and curated tools. */
+export function createBrowserMcpServer(options = {}) {
+    const runtime = options.runtime ?? createBrowserRuntime(loadPortableOptions(options.env));
+    const server = new Server({ name: 'pi-browser-use', version: packageVersion() }, { capabilities: { tools: {} } });
+    const validators = new Map();
+    let closePromise;
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = await runtime.start();
+        return {
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.parameters,
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        extra.signal.throwIfAborted();
+        const tools = await runtime.start();
+        extra.signal.throwIfAborted();
+        const tool = tools.find((candidate) => candidate.name === request.params.name);
+        if (!tool)
+            throw new McpError(ErrorCode.InvalidParams, `Unknown browser tool: ${request.params.name}`);
+        let validate = validators.get(tool.name);
+        if (!validate) {
+            validate = validator.getValidator(tool.parameters);
+            validators.set(tool.name, validate);
+        }
+        const checked = validate(request.params.arguments ?? {});
+        if (!checked.valid) {
+            // Do not echo argument values (forms may contain sensitive content).
+            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for ${tool.name}. Follow its inputSchema.`);
+        }
+        try {
+            const result = await tool.execute(checked.data, extra.signal);
+            return CallToolResultSchema.parse({
+                content: result.content ?? [],
+                ...(result.isError ? { isError: true } : {}),
+            });
+        }
+        catch (error) {
+            if (extra.signal.aborted)
+                throw error;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: error instanceof Error ? error.message : 'Browser operation failed.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    async function shutdown() {
+        try {
+            await runtime.stop();
+        }
+        finally {
+            await server.close();
+        }
+    }
+    function close() {
+        closePromise ??= shutdown();
+        return closePromise;
+    }
+    // MCP uses callback properties, not DOM EventTarget listeners.
+    // oxlint-disable-next-line unicorn/prefer-add-event-listener
+    server.onclose = () => {
+        void close().catch(reportFailure);
+    };
+    // oxlint-disable-next-line unicorn/prefer-add-event-listener
+    server.onerror = reportFailure;
+    return { server, close };
+}
+export async function runStdio() {
+    const app = createBrowserMcpServer();
+    const shutdown = () => {
+        void app.close().catch(reportFailure);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    process.stdin.once('end', shutdown);
+    try {
+        await app.server.connect(new StdioServerTransport());
+    }
+    catch (error) {
+        await app.close();
+        throw error;
+    }
+}
+// Canonical paths handle macOS /var vs /private/var aliases in packed installs.
+if (process.argv[1] &&
+    realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+    if (process.argv.includes('--help')) {
+        console.error('pi-browser-use MCP server (stdio). Configure ${PLUGIN_DATA}/config.json or PI_BROWSER_USE_CONFIG. No Pi installation is required.');
+    }
+    else if (process.argv.length > 2) {
+        console.error('Unknown argument. Use --help; browser configuration belongs in config.json.');
+        process.exitCode = 1;
+    }
+    else {
+        runStdio().catch((error) => {
+            console.error(`[pi-browser-use] ${error instanceof Error ? error.message : 'MCP server failed.'}`);
+            process.exitCode = 1;
+        });
+    }
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/persistent-backend.d.ts

@@ -89,7 +89,7 @@ export declare class PersistentBackend {
      */
     stop(): Promise<void>;
     /** Restart into the other visibility (headless <-> headed fallback). */
-    restart(headed: boolean): Promise<BrowserUseConfig>;
+    restart(headed: boolean, signal?: AbortSignal): Promise<BrowserUseConfig>;
 }
 /**
  * Persistent mode self-launches Pi-owned Chrome (§4) unless the legacy

package/dist/persistent-backend.js

@@ -160,6 +160,7 @@ export class PersistentBackend {
                 headless: !headed,
                 chromeArgs: this.options.config.chromeArgs,
                 executablePath: this.options.config.executablePath,
+                signal,
             });
         }
         catch (error) {
@@ -198,9 +199,14 @@ export class PersistentBackend {
      */
     attachConfig() {
         const browserUrl = this.effectiveBrowserUrl();
-        const { userDataDir: _userDataDir, isolated: _isolated, ...rest } = this.options.config;
+        const { userDataDir: _userDataDir, isolated: _isolated, executablePath: _executablePath, channel: _channel, chromeArgs: _chromeArgs, ...rest } = this.options.config;
         void _userDataDir;
         void _isolated;
+        void _executablePath;
+        void _channel;
+        void _chromeArgs;
+        // We already launched Chrome with these options. Upstream rejects an
+        // executable/channel combined with browserUrl; attach must not relaunch.
         return { ...rest, browserUrl, isolated: false };
     }
     running() {
@@ -257,14 +263,14 @@ export class PersistentBackend {
         }
     }
     /** Restart into the other visibility (headless <-> headed fallback). */
-    async restart(headed) {
+    async restart(headed, signal) {
         if (this.sharedAdvert) {
             throw new Error('Cannot restart a shared peer backend (owned by another live session). ' +
                 'Ask that session to switch visibility, or wait for it to exit.');
         }
         await this.stop();
         this.options.headed = headed;
-        return this.start();
+        return this.start(signal);
     }
 }
 /**
@@ -274,7 +280,6 @@ export class PersistentBackend {
 export function shouldSelfLaunch(config) {
     if (process.env['PI_BROWSER_USE_LEGACY_PERSISTENT'] === '1')
         return false;
-    void config;
-    return true;
+    return !config.browserUrl && !config.wsEndpoint && !config.autoConnect;
 }
 //# sourceMappingURL=persistent-backend.js.map

package/dist/profile-lock.js

@@ -102,7 +102,7 @@ export function acquireProfileLock(profileDir, options) {
     const holderPid = readLockPid(lockPath);
     const ageMs = readLockAgeMs(lockPath);
     const holderAlive = holderPid !== undefined && isPidAlive(holderPid);
-    const isStale = !holderAlive || (ageMs !== undefined && ageMs > staleMs);
+    const isStale = !holderAlive && (holderPid !== undefined || (ageMs !== undefined && ageMs > staleMs));
     if (isStale) {
         try {
             rmSync(lockPath, { force: true });

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+import { DevToolsClient } from './client.js';
+import { type BrowserUseConfig } from './config.js';
+import { PersistentBackend, type PersistentBackendOptions } from './persistent-backend.js';
+import { handleAnalyzeScreenshot } from './vision.js';
+type UpstreamResult = {
+    content?: Array<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+};
+/** Host-independent tool contract; Pi and MCP adapt only at their boundaries. */
+export type VisionCaller = Parameters<typeof handleAnalyzeScreenshot>[1];
+export interface BrowserToolContext {
+    callVision?: VisionCaller;
+}
+export interface BrowserToolDefinition {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute: (params: Record<string, unknown>, signal?: AbortSignal, context?: BrowserToolContext) => Promise<UpstreamResult>;
+}
+type BrowserClient = Pick<DevToolsClient, 'ensureReady' | 'listAllTools' | 'callTool' | 'close'>;
+type BrowserBackend = Pick<PersistentBackend, 'start' | 'stop' | 'running' | 'pid' | 'owned' | 'profileDir' | 'restart' | 'attachConfig'>;
+export interface BrowserRuntimeOptions {
+    config?: BrowserUseConfig;
+    defaultProfileDir?: string;
+    artifactDir?: string;
+    visionEnabled?: boolean;
+    /** Discover tools without launching Chrome. Native Pi keeps eager startup. */
+    lazyBrowser?: boolean;
+    createClient?: (config: BrowserUseConfig) => BrowserClient;
+    createBackend?: (options: PersistentBackendOptions) => BrowserBackend;
+}
+/** Shared browser lifecycle, policy, tools, and ownership. No Pi host is required. */
+export declare function createBrowserRuntime(options?: BrowserRuntimeOptions): {
+    start: () => Promise<BrowserToolDefinition[]>;
+    stop: () => Promise<void>;
+};
+export type BrowserRuntime = ReturnType<typeof createBrowserRuntime>;
+export {};
+//# sourceMappingURL=runtime.d.ts.map