pi-browser-use 0.10.1 → 0.11.1

package/dist/annotate.d.ts

@@ -1,12 +1,3 @@
-/**
- * Numbered-badge annotation for screenshots (adapted from the technique
- * popularized by vercel-labs/agent-browser).
- *
- * Badges are injected around visible interactive elements, screenshotted,
- * then removed. The returned coordinate map pairs each badge number with a
- * viewport center point for coordinate click tools, plus a short label so
- * vision models can resolve "click the blue submit button" to (x, y).
- */
 export interface AnnotatedElement {
     n: number;
     x: number;
@@ -17,11 +8,6 @@ export interface AnnotatedElement {
 export declare const ANNOTATE_MARKER = "data-pi-annotate";
 export declare const INJECT_ANNOTATIONS = "() => {\n  document.querySelectorAll('[data-pi-annotate]').forEach((el) => el.remove());\n  const els = [...document.querySelectorAll('a, button, input, select, textarea, [role=\"button\"], [role=\"link\"], [role=\"checkbox\"], [role=\"switch\"]')].filter((el) => {\n    const r = el.getBoundingClientRect();\n    return r.width > 0 && r.height > 0 && r.top >= 0 && r.left >= 0 && r.top < window.innerHeight && r.left < window.innerWidth;\n  }).slice(0, 50);\n  return els.map((el, i) => {\n    const r = el.getBoundingClientRect();\n    const badge = document.createElement('div');\n    badge.setAttribute('data-pi-annotate', '1');\n    badge.textContent = String(i + 1);\n    badge.style.cssText = 'position:fixed;left:' + r.left + 'px;top:' + r.top + 'px;z-index:2147483647;background:#7c3aed;color:#fff;font:12px/1.4 monospace;padding:1px 5px;border-radius:3px;pointer-events:none;';\n    document.body.appendChild(badge);\n    const label = el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '';\n    return { n: i + 1, x: Math.round(r.left + r.width / 2), y: Math.round(r.top + r.height / 2), tag: el.tagName.toLowerCase(), text: String(label).replace(/\\s+/g, ' ').slice(0, 60) };\n  });\n}";
 export declare const CLEANUP_ANNOTATIONS = "() => {\n  const badges = document.querySelectorAll('[data-pi-annotate]');\n  const count = badges.length;\n  badges.forEach((el) => el.remove());\n  return count;\n}";
-/**
- * Upstream evaluate_script wraps results as prose around a ```json fence.
- * Extract the payload array robustly.
- */
 export declare function parseAnnotatedElements(text: string): AnnotatedElement[];
-/** Render the coordinate map as compact text for tool results. */
 export declare function formatAnnotatedMap(elements: AnnotatedElement[]): string;
 //# sourceMappingURL=annotate.d.ts.map

package/dist/annotate.js

@@ -1,12 +1,3 @@
-/**
- * Numbered-badge annotation for screenshots (adapted from the technique
- * popularized by vercel-labs/agent-browser).
- *
- * Badges are injected around visible interactive elements, screenshotted,
- * then removed. The returned coordinate map pairs each badge number with a
- * viewport center point for coordinate click tools, plus a short label so
- * vision models can resolve "click the blue submit button" to (x, y).
- */
 export const ANNOTATE_MARKER = 'data-pi-annotate';
 export const INJECT_ANNOTATIONS = `() => {
   document.querySelectorAll('[${ANNOTATE_MARKER}]').forEach((el) => el.remove());
@@ -31,10 +22,6 @@ export const CLEANUP_ANNOTATIONS = `() => {
   badges.forEach((el) => el.remove());
   return count;
 }`;
-/**
- * Upstream evaluate_script wraps results as prose around a ```json fence.
- * Extract the payload array robustly.
- */
 export function parseAnnotatedElements(text) {
     const start = text.indexOf('[');
     const end = text.lastIndexOf(']');
@@ -62,7 +49,6 @@ export function parseAnnotatedElements(text) {
         return [];
     }
 }
-/** Render the coordinate map as compact text for tool results. */
 export function formatAnnotatedMap(elements) {
     if (elements.length === 0)
         return 'No interactive elements annotated.';

package/dist/artifacts.d.ts

@@ -1,8 +1,6 @@
 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, directory?: string): string;
-/** Pick the first image payload out of MCP content, if any. */
 export declare function pickImageData(content: unknown): {
     data: string;
     mimeType: string;

package/dist/artifacts.js

@@ -3,13 +3,11 @@ import { join } from 'node:path';
 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, directory = defaultArtifactDir()) {
     if (typeof path === 'string' && path.length > 0)
         return path;
     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) {
     if (!Array.isArray(content))
         return undefined;

package/dist/auth-verifiers.d.ts

@@ -1,26 +1,7 @@
-/**
- * Skill-level site authentication verifiers (spec section 6).
- *
- * There is intentionally no generic `isAuthenticated()` heuristic: each site
- * presents different authenticated and unauthenticated states, so detection
- * lives here per site. The browser subsystem only handles the resulting
- * BrowserAuthRequired by switching Persistent into reauthentication.
- *
- * A verifier declares:
- * - destination URL (where to check),
- * - authenticated-state check,
- * - login/challenge-state check.
- * `ensureSiteAuthenticated` runs them against snapshot text and throws
- * BrowserAuthRequired when a login/challenge is detected.
- */
 export interface SiteAuthVerifier {
-    /** Stable provider id used in BrowserAuthRequired + status UX. */
     provider: string;
-    /** Page to open for the auth check. */
     destinationUrl: string;
-    /** True when the snapshot shows the authenticated state. */
     isAuthenticated: (snapshotText: string, url: string) => boolean;
-    /** True when the snapshot shows a login/challenge wall. */
     isLoginOrChallenge: (snapshotText: string, url: string) => boolean;
 }
 export interface AuthCheckPage {
@@ -36,14 +17,9 @@ export type AuthCheckResult = {
 } | {
     status: 'unknown';
 };
-/** Classify one snapshot without side effects. */
 export declare function checkSiteAuth(verifier: SiteAuthVerifier, page: AuthCheckPage): AuthCheckResult;
-/** Gmail: inbox DOM vs Google login/challenge (never conflate Chrome-profile
- * sign-in with a mail.google.com session — they are different states). */
 export declare const gmailVerifier: SiteAuthVerifier;
-/** GitHub: settings/profile page shows the username when signed in. */
 export declare const githubVerifier: SiteAuthVerifier;
-/** Registry of built-in verifiers, keyed by provider id. */
 export declare const BUILTIN_VERIFIERS: Record<string, SiteAuthVerifier>;
 export interface AuthBrowser {
     openPage(url: string): Promise<{
@@ -51,10 +27,5 @@ export interface AuthBrowser {
         snapshotText: string;
     }>;
 }
-/**
- * Open the verifier destination, classify, and either return or throw
- * BrowserAuthRequired. `unknown` is returned (not thrown) so callers can
- * decide — an unrecognized page is not proof of a login wall.
- */
 export declare function ensureSiteAuthenticated(browser: AuthBrowser, verifier: SiteAuthVerifier): Promise<AuthCheckResult>;
 //# sourceMappingURL=auth-verifiers.d.ts.map

package/dist/auth-verifiers.js

@@ -1,20 +1,4 @@
-/**
- * Skill-level site authentication verifiers (spec section 6).
- *
- * There is intentionally no generic `isAuthenticated()` heuristic: each site
- * presents different authenticated and unauthenticated states, so detection
- * lives here per site. The browser subsystem only handles the resulting
- * BrowserAuthRequired by switching Persistent into reauthentication.
- *
- * A verifier declares:
- * - destination URL (where to check),
- * - authenticated-state check,
- * - login/challenge-state check.
- * `ensureSiteAuthenticated` runs them against snapshot text and throws
- * BrowserAuthRequired when a login/challenge is detected.
- */
 import { BrowserAuthRequired } from './session.js';
-/** Classify one snapshot without side effects. */
 export function checkSiteAuth(verifier, page) {
     if (verifier.isAuthenticated(page.snapshotText, page.url))
         return { status: 'authenticated' };
@@ -26,13 +10,7 @@ export function checkSiteAuth(verifier, page) {
 const GOOGLE_LOGIN_URL = /accounts\.google\.com\/(v\d+\/)?(signin|ServiceLogin|challenge|password|otp|verification)/i;
 const GOOGLE_LOGIN_QUERY = /[?&](flowEntry=ServiceLogin|flowName=WebLiteSignIn|service=mail)/i;
 const GOOGLE_CHALLENGE_COPY = /verify it'?s you|2-step verification|two-factor|enter your password|choose an account to continue|sign in to continue to gmail|to continue to gmail/i;
-/** Raw-DOM login redirect: Gmail serves a JS hop to accounts.google.com. */
 const GMAIL_LOGIN_BASE = /<base\s+href="https:\/\/accounts\.google\.com/i;
-/**
- * Inbox markers. Deliberately excludes bare "primary": Google login pages
- * embed it in CSS custom properties (--gm3-sys-color-primary), which caused
- * a false authenticated verdict on real sign-in HTML (live-tested 2026-09).
- */
 const GMAIL_INBOX_MARKERS = [
     /inbox/i,
     /compose/i,
@@ -41,8 +19,6 @@ const GMAIL_INBOX_MARKERS = [
     /sent mail/i,
     /\bdrafts\b/i,
 ];
-/** Gmail: inbox DOM vs Google login/challenge (never conflate Chrome-profile
- * sign-in with a mail.google.com session — they are different states). */
 export const gmailVerifier = {
     provider: 'google',
     destinationUrl: 'https://mail.google.com/',
@@ -61,7 +37,6 @@ export const gmailVerifier = {
         GOOGLE_CHALLENGE_COPY.test(text),
 };
 const GITHUB_LOGIN_URL = /(^|\/)((login|session|auth)(\/|$|[?#]))/i;
-/** GitHub: settings/profile page shows the username when signed in. */
 export const githubVerifier = {
     provider: 'github',
     destinationUrl: 'https://github.com/settings/profile',
@@ -71,16 +46,10 @@ export const githubVerifier = {
         GITHUB_LOGIN_URL.test(url) ||
         (/sign in to github/i.test(text) && /username or email|password/i.test(text)),
 };
-/** Registry of built-in verifiers, keyed by provider id. */
 export const BUILTIN_VERIFIERS = {
     google: gmailVerifier,
     github: githubVerifier,
 };
-/**
- * Open the verifier destination, classify, and either return or throw
- * BrowserAuthRequired. `unknown` is returned (not thrown) so callers can
- * decide — an unrecognized page is not proof of a login wall.
- */
 export async function ensureSiteAuthenticated(browser, verifier) {
     const page = await browser.openPage(verifier.destinationUrl);
     const result = checkSiteAuth(verifier, page);

package/dist/chrome-launcher.d.ts

@@ -1,32 +1,10 @@
-/**
- * Pi-owned Chrome process management (spec sections 3 and 4).
- *
- * Normal automation launches Chrome directly with the Pi profile and an
- * ephemeral loopback remote-debugging port, then MCP attaches via
- * `--browser-url`. This keeps one Chrome process per profile and avoids the
- * default WebDriver launch path where authentication often breaks:
- *
- * ```text
- * Google Chrome --user-data-dir="<pi-profile>"
- *   --remote-debugging-port=<ephemeral> [--headless]
- *        ↕
- * chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>
- * ```
- *
- * Bootstrap (first-run auth) launches headed Chrome *without* MCP/Puppeteer
- * so it looks like an ordinary manually launched browser.
- */
 export interface ChromeLaunchOptions {
     userDataDir: string;
-    /** Named profile directory inside userDataDir (e.g. pi-browser-use). */
     profileDirectory?: string;
-    /** Ephemeral loopback port. Allocated automatically when omitted. */
     port?: number;
     headless?: boolean;
-    /** Extra Chrome flags appended after the managed ones. */
     chromeArgs?: string[];
     executablePath?: string;
-    /** How long to wait for the DevTools endpoint. Default 15s. */
     readyTimeoutMs?: number;
     signal?: AbortSignal;
 }
@@ -35,29 +13,14 @@ export interface ChromeProcess {
     readonly port: number;
     readonly browserUrl: string;
     readonly userDataDir: string;
-    /** True once the process has exited. */
     readonly exited: boolean;
-    /** Resolves when the process exits (bootstrap uses this: close → READY). */
     waitForExit(): Promise<number | null>;
-    /** SIGTERM, then SIGKILL after `graceMs` if still alive. */
     shutdown(graceMs?: number): Promise<void>;
 }
-/** Chrome/Chromium executable candidates by platform (stable first). */
 export declare function chromeExecutableCandidates(): string[];
-/** Resolve the Chrome executable: explicit path wins, else first candidate. */
 export declare function findChromeExecutable(executablePath?: string): string;
-/**
- * Parse `ps -eo pid,command` output for Pi-managed Chromes on a profile
- * root: processes carrying our user-data-dir AND the named-profile marker.
- * Pure (testable): the ps text is injected.
- */
 export declare function findManagedChromePids(psOutput: string, userDataDir: string, keepPid?: number): number[];
-/** Allocate a free loopback port (never hardcode 9222). */
 export declare function allocateEphemeralPort(): Promise<number>;
-/**
- * Managed Chrome flags. Headed bootstrap omits `--headless` and debugging
- * entirely when `debugPort` is 0 (plain manual browser, spec section 3).
- */
 export declare function buildChromeArgs(options: {
     userDataDir: string;
     profileDirectory?: string;
@@ -65,7 +28,6 @@ export declare function buildChromeArgs(options: {
     headless?: boolean;
     chromeArgs?: string[];
 }): string[];
-/** Poll the DevTools `/json/version` endpoint until it answers or times out. */
 export declare function waitForDevToolsEndpoint(port: number, options?: {
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
@@ -74,31 +36,10 @@ export declare function waitForDevToolsEndpoint(port: number, options?: {
     browserUrl: string;
     webSocketDebuggerUrl: string;
 }>;
-/**
- * Launch Pi-owned Chrome. The caller must hold the profile lock
- * (see `profile-lock.ts`) for `userDataDir` before calling.
- */
 export declare function launchChrome(options: ChromeLaunchOptions): Promise<ChromeProcess>;
-/**
- * AppleScript that raises the exact Chrome process by pid. Unlike app-level
- * `activate` (which may front the user's daily windows instead), this targets
- * Pi-owned Chrome only. Foreground is reserved for explicit user-requested
- * views and auth handoffs — never automation.
- */
 export declare function buildFrontProcessScript(pid: number): string;
-/** Best-effort fronting of Pi-owned Chrome (macOS only). Returns success. */
 export declare function frontProcessByPid(pid: number | undefined, runner?: (cmd: string, args: string[]) => void): boolean;
-/**
- * AppleScript that raises the Chrome window holding the marker URL.
- * Pure (testable): execution lives with the caller. Foreground is reserved
- * for explicit user-requested views and auth handoffs — never automation.
- */
 export declare function buildFocusWindowScript(markerUrl: string): string;
-/**
- * Launch the headed first-run/setup browser (spec section 3): same Pi
- * profile, no MCP, no Puppeteer, no remote debugging — an ordinary manually
- * launched Chrome. Resolves when the user closes the window.
- */
 export declare function launchSetupBrowser(options: {
     userDataDir: string;
     profileDirectory?: string;

package/dist/chrome-launcher.js

@@ -1,26 +1,7 @@
-/**
- * Pi-owned Chrome process management (spec sections 3 and 4).
- *
- * Normal automation launches Chrome directly with the Pi profile and an
- * ephemeral loopback remote-debugging port, then MCP attaches via
- * `--browser-url`. This keeps one Chrome process per profile and avoids the
- * default WebDriver launch path where authentication often breaks:
- *
- * ```text
- * Google Chrome --user-data-dir="<pi-profile>"
- *   --remote-debugging-port=<ephemeral> [--headless]
- *        ↕
- * chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>
- * ```
- *
- * Bootstrap (first-run auth) launches headed Chrome *without* MCP/Puppeteer
- * so it looks like an ordinary manually launched browser.
- */
 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') {
         return [
@@ -44,7 +25,6 @@ export function chromeExecutableCandidates() {
         '/snap/bin/chromium',
     ];
 }
-/** Resolve the Chrome executable: explicit path wins, else first candidate. */
 export function findChromeExecutable(executablePath) {
     if (executablePath && executablePath.length > 0) {
         if (!existsSync(executablePath)) {
@@ -61,11 +41,6 @@ export function findChromeExecutable(executablePath) {
     }
     throw new Error('Chrome executable was not found. Install Google Chrome Stable or set executablePath.');
 }
-/**
- * Parse `ps -eo pid,command` output for Pi-managed Chromes on a profile
- * root: processes carrying our user-data-dir AND the named-profile marker.
- * Pure (testable): the ps text is injected.
- */
 export function findManagedChromePids(psOutput, userDataDir, keepPid) {
     const pids = [];
     for (const line of psOutput.split('\n')) {
@@ -86,7 +61,6 @@ export function findManagedChromePids(psOutput, userDataDir, keepPid) {
     }
     return pids;
 }
-/** Allocate a free loopback port (never hardcode 9222). */
 export function allocateEphemeralPort() {
     return new Promise((resolve, reject) => {
         const server = createServer();
@@ -103,10 +77,6 @@ export function allocateEphemeralPort() {
         });
     });
 }
-/**
- * Managed Chrome flags. Headed bootstrap omits `--headless` and debugging
- * entirely when `debugPort` is 0 (plain manual browser, spec section 3).
- */
 export function buildChromeArgs(options) {
     const args = [
         `--user-data-dir=${options.userDataDir}`,
@@ -124,7 +94,6 @@ export function buildChromeArgs(options) {
     args.push(...(options.chromeArgs ?? []));
     return args;
 }
-/** Poll the DevTools `/json/version` endpoint until it answers or times out. */
 export async function waitForDevToolsEndpoint(port, options) {
     const timeoutMs = options?.timeoutMs ?? 15_000;
     const fetchImpl = options?.fetchImpl ?? fetch;
@@ -179,7 +148,7 @@ class OwnedChromeProcess {
     waitForExit() {
         return this.exitPromise;
     }
-    async shutdown(graceMs = 3_000) {
+    async shutdown(graceMs = 10_000) {
         if (this.exited)
             return;
         this.child.kill('SIGTERM');
@@ -199,10 +168,6 @@ class OwnedChromeProcess {
         }
     }
 }
-/**
- * Launch Pi-owned Chrome. The caller must hold the profile lock
- * (see `profile-lock.ts`) for `userDataDir` before calling.
- */
 export async function launchChrome(options) {
     options.signal?.throwIfAborted();
     const executable = findChromeExecutable(options.executablePath);
@@ -217,7 +182,6 @@ export async function launchChrome(options) {
     const child = spawn(executable, args, { stdio: 'ignore', detached: false });
     await new Promise((resolve, reject) => {
         child.on('error', reject);
-        // Give spawn a tick to surface ENOENT-style failures before probing.
         setTimeout(resolve, 50);
     });
     if (child.exitCode !== null) {
@@ -234,18 +198,11 @@ export async function launchChrome(options) {
             child.kill('SIGKILL');
         }
         catch {
-            // Already gone; the endpoint error below is what matters.
         }
         throw error;
     }
     return new OwnedChromeProcess(child, port, `http://127.0.0.1:${port}`, options.userDataDir);
 }
-/**
- * AppleScript that raises the exact Chrome process by pid. Unlike app-level
- * `activate` (which may front the user's daily windows instead), this targets
- * Pi-owned Chrome only. Foreground is reserved for explicit user-requested
- * views and auth handoffs — never automation.
- */
 export function buildFrontProcessScript(pid) {
     return [
         'tell application "System Events"',
@@ -253,7 +210,6 @@ export function buildFrontProcessScript(pid) {
         'end tell',
     ].join('\n');
 }
-/** Best-effort fronting of Pi-owned Chrome (macOS only). Returns success. */
 export function frontProcessByPid(pid, runner) {
     if (pid === undefined || process.platform !== 'darwin')
         return false;
@@ -266,11 +222,6 @@ export function frontProcessByPid(pid, runner) {
         return false;
     }
 }
-/**
- * AppleScript that raises the Chrome window holding the marker URL.
- * Pure (testable): execution lives with the caller. Foreground is reserved
- * for explicit user-requested views and auth handoffs — never automation.
- */
 export function buildFocusWindowScript(markerUrl) {
     const needle = markerUrl.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     return [
@@ -287,11 +238,6 @@ export function buildFocusWindowScript(markerUrl) {
         'end tell',
     ].join('\n');
 }
-/**
- * Launch the headed first-run/setup browser (spec section 3): same Pi
- * profile, no MCP, no Puppeteer, no remote debugging — an ordinary manually
- * launched Chrome. Resolves when the user closes the window.
- */
 export async function launchSetupBrowser(options) {
     options.signal?.throwIfAborted();
     const executable = findChromeExecutable(options.executablePath);

package/dist/client.d.ts

@@ -1,8 +1,4 @@
 import { type BrowserUseConfig } from './config.js';
-/**
- * MCP client that spawns chrome-devtools-mcp as a per-session subprocess over
- * stdio. Nothing runs persistently: connect() starts it, close() kills it.
- */
 export declare class DevToolsClient {
     private client;
     private config;

package/dist/client.js

@@ -8,7 +8,6 @@ const MCP_STDERR_LIMIT = 4_096;
 const MCP_SYSTEM_ERROR_CODE_PATTERN = /^(?:EACCES|EADDRINUSE|ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENOENT|ENOTEMPTY|ENOTFOUND|EPERM|ETIMEDOUT)$/;
 const require = createRequire(import.meta.url);
 const chromeDevToolsMcpPackagePath = require.resolve('chrome-devtools-mcp/package.json');
-// oxlint-disable-next-line no-unsafe-read -- package.json of a pinned dependency
 const chromeDevToolsMcpPackage = require(chromeDevToolsMcpPackagePath);
 const chromeDevToolsMcpBin = chromeDevToolsMcpPackage.bin?.['chrome-devtools-mcp'];
 if (!chromeDevToolsMcpBin) {
@@ -40,10 +39,6 @@ function summarizeFailure(stderr, errorName, errorCode) {
     const safeName = /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(errorName) ? errorName : 'UnknownError';
     return `MCP transport failed (${safeName}).`;
 }
-/**
- * MCP client that spawns chrome-devtools-mcp as a per-session subprocess over
- * stdio. Nothing runs persistently: connect() starts it, close() kills it.
- */
 export class DevToolsClient {
     client = null;
     config;
@@ -72,8 +67,6 @@ export class DevToolsClient {
     }
     async openConnection(signal) {
         this.state = this.hasConnected ? 'reconnecting' : 'connecting';
-        // Keep the MCP SDK off the extension's eager module-evaluation path and
-        // pay its cost only when session initialization opens a connection.
         const { Client, StdioClientTransport } = await loadMcpRuntime();
         const args = configToArgs(this.config);
         const generation = ++this.generation;
@@ -89,8 +82,6 @@ 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;
@@ -98,7 +89,6 @@ 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, signal });
@@ -118,7 +108,6 @@ export class DevToolsClient {
                 await client.close();
             }
             catch {
-                // The failed transport may already be closed.
             }
             if (signal?.aborted)
                 throw error;
@@ -128,8 +117,6 @@ 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}`);
         }
     }
@@ -209,17 +196,13 @@ export class DevToolsClient {
             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

@@ -1,24 +1,12 @@
 export declare const DEFAULT_PROFILE_DIR: string;
 export type BrowserSessionMode = 'persistent' | 'isolated' | 'existing';
-/** Vision model used by the optional analyze_screenshot tool. Must already exist in Pi's model registry. */
 export interface VisionModelConfig {
     provider: string;
     model: string;
 }
-/** Simple mode selector. Takes precedence over sessionMode/headless when set. */
 export type BrowserModeOption = 'fresh' | 'persistent' | 'existing';
-/** Configuration for the chrome-devtools-mcp subprocess. Same settings key as before: "pi-browser-use". */
 export interface BrowserUseConfig {
-    /**
-     * Simple facade: fresh (isolated clean room), persistent (saved profile
-     * with your logins), existing (attach to your running Chrome). Overrides
-     * sessionMode and headless/headed below when present.
-     */
     mode?: BrowserModeOption;
-    /**
-     * Show the browser window. Default false (headless) for fresh and persistent;
-     * existing is always headed. Overrides headless below when present.
-     */
     headed?: boolean;
     sessionMode?: BrowserSessionMode;
     headless?: boolean;
@@ -47,26 +35,13 @@ export interface BrowserUseConfig {
     allowedUrlPattern?: string[];
     blockedUrlPattern?: string[];
     slim?: boolean;
-    /** Loopback port for the Existing-mode tab-broker bridge. Default 31973; set 0 to disable the bridge. */
     tabBridgePort?: number;
-    /** First-class Chrome flags, forwarded as --chrome-arg=<flag>. Only applies when Chrome is launched by chrome-devtools-mcp (not with autoConnect/browserUrl). */
     chromeArgs?: string[];
-    /** Raw escape hatch: extra CLI flags forwarded verbatim to chrome-devtools-mcp. */
     extraArgs?: string[];
 }
-/** In-session backend target for browser_switch_mode. */
 export type BrowserMode = 'fresh' | 'persistent' | 'existing';
-/**
- * Build the config for a mode switch from the session base config.
- * fresh means an isolated clean room; persistent means the saved profile
- * (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, 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, 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