pi-browser-use 0.11.0 → 0.11.2

package/dist/persistent-backend.js

@@ -1,27 +1,3 @@
-/**
- * Pi-owned Persistent Chrome backend (spec sections 2 and 4).
- *
- * Normal automation launches Chrome directly with the Pi profile and an
- * ephemeral loopback remote-debugging port, then MCP attaches via
- * `--browser-url` — instead of asking MCP/Puppeteer to create the browser:
- *
- * ```text
- * Google Chrome --user-data-dir="<pi-profile>"
- *   --remote-debugging-port=<ephemeral> [--headless]
- *        ↕
- * chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>
- * ```
- *
- * Invariants:
- * - one Chrome process <-> one persistent profile (profile lock held for the
- *   whole backend lifetime, acquired on start, released on stop);
- * - dynamically allocated localhost port, never hardcoded 9222;
- * - clean shutdown (SIGTERM, then SIGKILL) before any relaunch, so headed and
- *   headless instances never overlap on the same user-data-dir.
- *
- * The launcher and MCP-client factory are injectable so the lifecycle is
- * unit-testable without a real Chrome.
- */
 import { findManagedChromePids, launchChrome, } from './chrome-launcher.js';
 import { execFileSync } from 'node:child_process';
 import { ensureNamedProfile, PI_PROFILE_NAME } from './named-profile.js';
@@ -46,7 +22,6 @@ export class PersistentBackend {
         this.attachClient = options.attachClient;
         this.sessionId = options.sessionId ?? newSessionId();
     }
-    /** True when this session owns the Chrome process (may restart it). */
     get owned() {
         return this.sharedAdvert === undefined;
     }
@@ -64,15 +39,34 @@ export class PersistentBackend {
     attached() {
         return this.client;
     }
-    /** OS pid of the owned Chrome process, for explicit user-facing fronting. */
     pid() {
         return this.chrome?.pid;
     }
-    /**
-     * Kill leftover Pi-managed Chromes on this profile (crashed sessions).
-     * Only processes carrying our managed flags; skips our own pid and
-     * manually opened windows. Injectable runner for tests.
-     */
+    onChromeExit(chrome) {
+        if (this.chrome !== chrome)
+            return;
+        this.chrome = undefined;
+        const lock = this.lock;
+        this.lock = undefined;
+        try {
+            lock?.release();
+        }
+        catch {
+        }
+        withdrawAdvert(this.profileDir(), this.sessionId);
+        const client = this.client;
+        this.client = undefined;
+        if (client)
+            void client.close().catch(() => { });
+    }
+    watchChrome(chrome) {
+        try {
+            void chrome.waitForExit().then(() => this.onChromeExit(chrome), () => this.onChromeExit(chrome));
+        }
+        catch {
+            this.onChromeExit(chrome);
+        }
+    }
     reapOrphans(profileDir, runner) {
         const run = runner ?? {
             ps: () => {
@@ -88,7 +82,6 @@ export class PersistentBackend {
                     process.kill(pid, 'SIGTERM');
                 }
                 catch {
-                    // Already gone; the endpoint check below confirms.
                 }
             },
         };
@@ -106,17 +99,13 @@ export class PersistentBackend {
                 reaped.push(pid);
             }
             catch {
-                // One stubborn process must not block the launch.
             }
         }
         return reaped;
     }
-    /**
-     * Start Pi-owned Chrome and prepare the MCP attach config. When an
-     * `attachClient` factory was injected, the client is created here;
-     * otherwise the caller builds its DevToolsClient from `attachConfig()`.
-     */
     async start(signal) {
+        if (this.chrome?.exited)
+            this.onChromeExit(this.chrome);
         if (this.running())
             return this.attachConfig();
         if (signal?.aborted)
@@ -126,8 +115,6 @@ export class PersistentBackend {
             this.lock = this.acquireLock(profileDir);
         }
         catch (error) {
-            // A live peer owns Chrome: share it instead of failing. No lock, no
-            // kill rights — this session only borrows pages.
             if (error instanceof ProfileLockedError) {
                 const advert = readLiveAdvert(profileDir);
                 if (advert) {
@@ -141,20 +128,14 @@ export class PersistentBackend {
             throw error;
         }
         try {
-            // Self-healing: reap Pi-managed orphans from crashed sessions before
-            // launching (same user-data-dir + debugging flags, never our pid,
-            // never a manually opened window). Best effort, never fatal.
             const reaped = this.reapOrphans(profileDir);
             if (reaped.length > 0) {
                 await new Promise((resolve) => setTimeout(resolve, 2000));
             }
             prepareBrowserProfile({ ...this.options.config, userDataDir: profileDir });
-            // Pin the named Pi profile; migrate legacy layouts once, under lock.
             ensureNamedProfile(profileDir);
-            // Explicit headed wins; otherwise infer from config (headless:false
-            // means headed) so direct construction can't silently go headless.
             const headed = this.options.headed ?? this.options.config.headless === false;
-            this.chrome = await this.launch({
+            const chrome = await this.launch({
                 userDataDir: profileDir,
                 profileDirectory: PI_PROFILE_NAME,
                 headless: !headed,
@@ -162,6 +143,8 @@ export class PersistentBackend {
                 executablePath: this.options.config.executablePath,
                 signal,
             });
+            this.chrome = chrome;
+            this.watchChrome(chrome);
         }
         catch (error) {
             this.lock.release();
@@ -184,7 +167,6 @@ export class PersistentBackend {
             this.client = this.attachClient(attach);
         return attach;
     }
-    /** Effective browser URL: owned Chrome or the shared peer's. */
     effectiveBrowserUrl() {
         if (this.chrome)
             return this.chrome.browserUrl;
@@ -192,11 +174,6 @@ export class PersistentBackend {
             return this.sharedAdvert.browserUrl;
         throw new Error('Persistent backend is not running.');
     }
-    /**
-     * MCP attach config: same session options, but pointed at Pi-owned Chrome
-     * (or the shared peer's). `userDataDir`/`isolated` are stripped — MCP
-     * must attach, not launch.
-     */
     attachConfig() {
         const browserUrl = this.effectiveBrowserUrl();
         const { userDataDir: _userDataDir, isolated: _isolated, executablePath: _executablePath, channel: _channel, chromeArgs: _chromeArgs, ...rest } = this.options.config;
@@ -205,8 +182,6 @@ export class PersistentBackend {
         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() {
@@ -214,11 +189,6 @@ export class PersistentBackend {
             return true;
         return this.chrome !== undefined && !this.chrome.exited;
     }
-    /**
-     * Clean shutdown. Owned: close client, quit Chrome, release lock,
-     * withdraw advert. Shared: close only our own MCP client — never touch
-     * the peer's browser.
-     */
     async stop() {
         const errors = [];
         if (this.client) {
@@ -262,7 +232,6 @@ export class PersistentBackend {
                 .join('; ')}`);
         }
     }
-    /** Restart into the other visibility (headless <-> headed fallback). */
     async restart(headed, signal) {
         if (this.sharedAdvert) {
             throw new Error('Cannot restart a shared peer backend (owned by another live session). ' +
@@ -273,10 +242,6 @@ export class PersistentBackend {
         return this.start(signal);
     }
 }
-/**
- * Persistent mode self-launches Pi-owned Chrome (§4) unless the legacy
- * escape hatch is set (MCP launches Chrome itself, pre-Phase-2 behavior).
- */
 export function shouldSelfLaunch(config) {
     if (process.env['PI_BROWSER_USE_LEGACY_PERSISTENT'] === '1')
         return false;

package/dist/persistent-store.d.ts

@@ -1,35 +1,11 @@
-/**
- * Durable Persistent-mode metadata (spec section 2).
- *
- * Only durable state is persisted: initialization flag, profile path, last
- * working launch mode, and last bootstrap timestamp. Passwords, cookies,
- * tokens, or copied browser credentials must never be stored here — Chrome
- * owns those inside its profile directory.
- *
- * Default location is a sibling of the profile directory:
- * `<profileDir>.meta.json` (e.g. `~/.pi/browser-profile.meta.json`), so a
- * profile move/rename never orphans its metadata.
- */
 import type { PersistentBrowserMetadata, SiteBrowserPreference } from './session.js';
 export declare function metadataPathFor(profileDir?: string): string;
 export declare function defaultMetadata(profileDir?: string): PersistentBrowserMetadata;
-/** Load metadata; returns uninitialized defaults when absent or corrupt. */
 export declare function loadPersistentMetadata(profileDir?: string): PersistentBrowserMetadata;
-/** Atomically persist metadata (write-then-rename via temp file). */
 export declare function savePersistentMetadata(meta: PersistentBrowserMetadata): void;
-/** Record a completed bootstrap: initialized now, timestamped. */
 export declare function markBootstrapped(profileDir?: string, at?: string): PersistentBrowserMetadata;
-/** Record which launch mode last automated successfully. */
 export declare function markAutomationResult(profileDir: string, mode: 'headless' | 'headed'): PersistentBrowserMetadata;
-/**
- * Per-origin headed-background preferences (spec section 8). Stored beside
- * the metadata file (`<profileDir>.sites.json`); origins only, never
- * credentials. A site pinned here starts headed-background instead of
- * globally downgrading Persistent because one site rejects headless.
- */
 export declare function sitePreferencesPathFor(profileDir?: string): string;
-/** Load per-origin preferences; empty when absent or corrupt. */
 export declare function loadSitePreferences(profileDir?: string): SiteBrowserPreference[];
-/** Persist per-origin preferences. */
 export declare function saveSitePreferences(profileDir: string, preferences: SiteBrowserPreference[]): void;
 //# sourceMappingURL=persistent-store.d.ts.map

package/dist/persistent-store.js

@@ -1,15 +1,3 @@
-/**
- * Durable Persistent-mode metadata (spec section 2).
- *
- * Only durable state is persisted: initialization flag, profile path, last
- * working launch mode, and last bootstrap timestamp. Passwords, cookies,
- * tokens, or copied browser credentials must never be stored here — Chrome
- * owns those inside its profile directory.
- *
- * Default location is a sibling of the profile directory:
- * `<profileDir>.meta.json` (e.g. `~/.pi/browser-profile.meta.json`), so a
- * profile move/rename never orphans its metadata.
- */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { DEFAULT_PROFILE_DIR } from './config.js';
@@ -19,7 +7,6 @@ export function metadataPathFor(profileDir = DEFAULT_PROFILE_DIR) {
 export function defaultMetadata(profileDir = DEFAULT_PROFILE_DIR) {
     return { initialized: false, profilePath: profileDir };
 }
-/** Load metadata; returns uninitialized defaults when absent or corrupt. */
 export function loadPersistentMetadata(profileDir = DEFAULT_PROFILE_DIR) {
     const path = metadataPathFor(profileDir);
     try {
@@ -37,13 +24,11 @@ export function loadPersistentMetadata(profileDir = DEFAULT_PROFILE_DIR) {
         return defaultMetadata(profileDir);
     }
 }
-/** Atomically persist metadata (write-then-rename via temp file). */
 export function savePersistentMetadata(meta) {
     const path = metadataPathFor(meta.profilePath);
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
 }
-/** Record a completed bootstrap: initialized now, timestamped. */
 export function markBootstrapped(profileDir = DEFAULT_PROFILE_DIR, at = new Date().toISOString()) {
     const meta = {
         ...loadPersistentMetadata(profileDir),
@@ -54,7 +39,6 @@ export function markBootstrapped(profileDir = DEFAULT_PROFILE_DIR, at = new Date
     savePersistentMetadata(meta);
     return meta;
 }
-/** Record which launch mode last automated successfully. */
 export function markAutomationResult(profileDir, mode) {
     const meta = {
         ...loadPersistentMetadata(profileDir),
@@ -64,16 +48,9 @@ export function markAutomationResult(profileDir, mode) {
     savePersistentMetadata(meta);
     return meta;
 }
-/**
- * Per-origin headed-background preferences (spec section 8). Stored beside
- * the metadata file (`<profileDir>.sites.json`); origins only, never
- * credentials. A site pinned here starts headed-background instead of
- * globally downgrading Persistent because one site rejects headless.
- */
 export function sitePreferencesPathFor(profileDir = DEFAULT_PROFILE_DIR) {
     return `${profileDir}.sites.json`;
 }
-/** Load per-origin preferences; empty when absent or corrupt. */
 export function loadSitePreferences(profileDir = DEFAULT_PROFILE_DIR) {
     try {
         const raw = JSON.parse(readFileSync(sitePreferencesPathFor(profileDir), 'utf8'));
@@ -89,7 +66,6 @@ export function loadSitePreferences(profileDir = DEFAULT_PROFILE_DIR) {
         return [];
     }
 }
-/** Persist per-origin preferences. */
 export function saveSitePreferences(profileDir, preferences) {
     const path = sitePreferencesPathFor(profileDir);
     mkdirSync(dirname(path), { recursive: true });

package/dist/profile-lock.d.ts

@@ -1,17 +1,3 @@
-/**
- * Single-process guard for a Chrome user-data directory (spec section 4).
- *
- * Chrome corrupts state when two processes share one user-data-dir, so every
- * Pi-owned launch/shutdown path must hold this lock:
- *
- * ```text
- * one Chrome process <-> one persistent profile
- * ```
- *
- * Implemented as a sibling `<profileDir>.lock` file holding `{ pid,
- * createdAt }`. Stale locks (dead pid or age beyond `staleMs`) are reclaimed;
- * live locks throw {@link ProfileLockedError}.
- */
 export declare class ProfileLockedError extends Error {
     readonly profileDir: string;
     readonly holderPid?: number;
@@ -25,16 +11,9 @@ export interface ProfileLockHandle {
 }
 export declare function lockPathFor(profileDir: string): string;
 export interface AcquireLockOptions {
-    /** Locks older than this with a dead holder are reclaimed. Default 5 min. */
     staleMs?: number;
 }
-/**
- * Acquire the exclusive lock for `profileDir`. Throws ProfileLockedError when
- * a live Chrome (or another Pi process) holds it.
- */
 export declare function acquireProfileLock(profileDir: string, options?: AcquireLockOptions): ProfileLockHandle;
-/** True when a live holder currently owns the profile lock. */
 export declare function isProfileLocked(profileDir: string): boolean;
-/** Run `fn` while holding the profile lock, always releasing afterwards. */
 export declare function withProfileLock<T>(profileDir: string, fn: (lock: ProfileLockHandle) => Promise<T>, options?: AcquireLockOptions): Promise<T>;
 //# sourceMappingURL=profile-lock.d.ts.map

package/dist/profile-lock.js

@@ -1,17 +1,3 @@
-/**
- * Single-process guard for a Chrome user-data directory (spec section 4).
- *
- * Chrome corrupts state when two processes share one user-data-dir, so every
- * Pi-owned launch/shutdown path must hold this lock:
- *
- * ```text
- * one Chrome process <-> one persistent profile
- * ```
- *
- * Implemented as a sibling `<profileDir>.lock` file holding `{ pid,
- * createdAt }`. Stale locks (dead pid or age beyond `staleMs`) are reclaimed;
- * live locks throw {@link ProfileLockedError}.
- */
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 export class ProfileLockedError extends Error {
@@ -77,24 +63,17 @@ function tryCreateLockFile(lockPath) {
                 closeSync(fd);
             }
             catch {
-                // Best effort; the lock content is already written.
             }
         }
     }
 }
-/**
- * Acquire the exclusive lock for `profileDir`. Throws ProfileLockedError when
- * a live Chrome (or another Pi process) holds it.
- */
 export function acquireProfileLock(profileDir, options) {
     const staleMs = options?.staleMs ?? 5 * 60 * 1000;
     const lockPath = lockPathFor(profileDir);
-    // Ensure the parent exists so the sibling lock file can be created.
     try {
         mkdirSync(dirname(lockPath), { recursive: true });
     }
     catch {
-        // Parent creation failure surfaces on lock creation below.
     }
     if (tryCreateLockFile(lockPath)) {
         return makeHandle(profileDir, lockPath);
@@ -108,7 +87,6 @@ export function acquireProfileLock(profileDir, options) {
             rmSync(lockPath, { force: true });
         }
         catch {
-            // Fall through to the error below if removal failed.
         }
         if (tryCreateLockFile(lockPath)) {
             return makeHandle(profileDir, lockPath);
@@ -129,19 +107,15 @@ function makeHandle(profileDir, lockPath) {
                 rmSync(lockPath, { force: true });
             }
             catch {
-                // Lock files are best-effort on shutdown.
             }
         },
     };
     return handle;
 }
-/** True when a live holder currently owns the profile lock. */
 export function isProfileLocked(profileDir) {
     const lockPath = lockPathFor(profileDir);
     const holderPid = readLockPid(lockPath);
     if (holderPid === undefined) {
-        // Unparseable/missing lock file: treat a present file as locked to stay
-        // safe, absent as unlocked.
         try {
             readFileSync(lockPath);
             return true;
@@ -152,7 +126,6 @@ export function isProfileLocked(profileDir) {
     }
     return isPidAlive(holderPid);
 }
-/** Run `fn` while holding the profile lock, always releasing afterwards. */
 export async function withProfileLock(profileDir, fn, options) {
     const lock = acquireProfileLock(profileDir, options);
     try {

package/dist/profile.d.ts

@@ -1,13 +1,3 @@
 import { type BrowserUseConfig } from './config.js';
-/**
- * Guard the browser profile before launch. A default profile that exists but
- * cannot be read/written (typically root-owned after running under sudo) is
- * moved aside so Chrome starts fresh instead of showing a "can't read your
- * preferences" dialog on every launch. An explicit custom userDataDir in the
- * same state fails fast with a remediation hint instead of silently
- * discarding the user's data. Persistent launches additionally pin the named
- * `pi-browser-use` profile (one-time legacy migration, refuses while an
- * external Chrome holds the root).
- */
 export declare function prepareBrowserProfile(config: BrowserUseConfig): void;
 //# sourceMappingURL=profile.d.ts.map

package/dist/profile.js

@@ -20,21 +20,9 @@ function isUnusableDir(path) {
         return false;
     }
     catch (error) {
-        // A missing directory is fine (Chrome creates it); anything else means
-        // the profile cannot be used.
         return error.code !== 'ENOENT';
     }
 }
-/**
- * Guard the browser profile before launch. A default profile that exists but
- * cannot be read/written (typically root-owned after running under sudo) is
- * moved aside so Chrome starts fresh instead of showing a "can't read your
- * preferences" dialog on every launch. An explicit custom userDataDir in the
- * same state fails fast with a remediation hint instead of silently
- * discarding the user's data. Persistent launches additionally pin the named
- * `pi-browser-use` profile (one-time legacy migration, refuses while an
- * external Chrome holds the root).
- */
 export function prepareBrowserProfile(config) {
     if (config.browserUrl || config.wsEndpoint || config.autoConnect)
         return;
@@ -58,8 +46,6 @@ export function prepareBrowserProfile(config) {
                 `Fix ownership with: sudo chown -R $(id -un):$(id -gn) ${JSON.stringify(dir)}`);
         }
     }
-    // Pin the named Pi profile for persistent launches (fresh migrations
-    // happen here, under no running Chrome by construction of the callers).
     if (config.sessionMode === 'persistent') {
         ensureNamedProfile(dir);
     }

package/dist/runtime.d.ts

@@ -11,7 +11,6 @@ type UpstreamResult = {
     }>;
     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;
@@ -30,12 +29,10 @@ export interface BrowserRuntimeOptions {
     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>;