pi-browser-use 0.11.0 → 0.11.2

package/dist/session.d.ts

@@ -1,31 +1,13 @@
-/**
- * Stable internal browser API shared by all Pi browser modes.
- *
- * Skills talk to {@link BrowserSession} only. They must never deal with
- * Chrome process flags, profile directories, CDP endpoints, tab-group IDs,
- * or focus behavior directly — that translation lives in
- * `BrowserSessionManager` (see `session-manager.ts`).
- *
- * Spec sections: 1 (core architecture), 2 (persistent metadata),
- * 6 (skill-owned auth detection), 8 (execution modes), 21 (capabilities),
- * 23 (status UX).
- */
 export type BrowserSessionMode = 'fresh' | 'persistent' | 'existing';
-/** Opaque handle to an open page/tab. Backends resolve it to MCP/CDP state. */
 export interface PageHandle {
-    /** Backend page identifier (MCP pageId, CDP target id, ...). */
     id: string;
     url?: string;
     title?: string;
 }
-/** User-facing browser status. Never expose CDP/MCP terminology here. */
 export interface BrowserStatus {
     mode: BrowserSessionMode;
-    /** Plain-language state, e.g. "Running privately in background". */
     state: string;
-    /** e.g. "Ready", "Setup required", "Authentication required". */
     profile: string;
-    /** e.g. "Headless", "Visible fallback", "Using your existing Chrome". */
     execution: string;
 }
 export interface BrowserSession {
@@ -34,21 +16,10 @@ export interface BrowserSession {
     openPage(url: string): Promise<PageHandle>;
     listPages(): Promise<PageHandle[]>;
     closePage(page: PageHandle): Promise<void>;
-    /**
-     * Ask to make the browser visible (auth handoff, explicit "show me").
-     * Implementations may no-op when already visible or when the mode is
-     * headless-only.
-     */
     requestVisibleBrowser(reason: string): Promise<void>;
     getStatus(): Promise<BrowserStatus>;
     shutdown(): Promise<void>;
 }
-/**
- * Thrown by skill-level auth verifiers when a page needs a human
- * (sign-in, 2FA, passkey, CAPTCHA, SSO). The browser subsystem catches this
- * and moves the Persistent session into reauthentication; skills define the
- * destination URL and the authenticated/challenge checks.
- */
 export declare class BrowserAuthRequired extends Error {
     readonly provider: string;
     readonly url?: string;
@@ -58,35 +29,22 @@ export declare class BrowserAuthRequired extends Error {
         message?: string;
     });
 }
-/** Two automation execution modes inside Persistent (spec section 8). */
 export type PersistentExecutionMode = 'headless' | 'headed-background';
-/** Persistent lifecycle state machine (spec section 2). */
 export type PersistentState = 'UNINITIALIZED' | 'SETUP_REQUIRED' | 'SETUP_HEADFUL' | 'READY' | 'AUTOMATING_HEADLESS' | 'AUTOMATING_HEADFUL' | 'REAUTH_REQUIRED' | 'REAUTH_HEADFUL';
-/**
- * Durable Persistent state. Passwords, cookies, tokens, and copied browser
- * credentials must never be stored here — Chrome owns those inside its
- * profile directory.
- */
 export interface PersistentBrowserMetadata {
     initialized: boolean;
     profilePath: string;
     lastSuccessfulMode?: 'headless' | 'headed';
     lastBootstrapAt?: string;
 }
-/** Optional per-origin headed-background preference (spec section 8). */
 export interface SiteBrowserPreference {
     origin: string;
     executionMode: PersistentExecutionMode;
 }
-/** Capability intent from a skill (spec section 21). */
 export interface BrowserCapabilityRequest {
-    /** True when cookies/sessions must survive restarts. */
     persistence?: boolean;
-    /** e.g. "gmail", "github" — informational, used for status/reauth UX. */
     authentication?: string;
-    /** Default: prefer headless, fall back to headed-background per origin. */
     visibility?: 'prefer-headless' | 'require-headless' | 'allow-visible';
-    /** Whether falling back to the user's own Chrome is acceptable. */
     supportsExisting?: boolean;
 }
 //# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -1,21 +1,3 @@
-/**
- * Stable internal browser API shared by all Pi browser modes.
- *
- * Skills talk to {@link BrowserSession} only. They must never deal with
- * Chrome process flags, profile directories, CDP endpoints, tab-group IDs,
- * or focus behavior directly — that translation lives in
- * `BrowserSessionManager` (see `session-manager.ts`).
- *
- * Spec sections: 1 (core architecture), 2 (persistent metadata),
- * 6 (skill-owned auth detection), 8 (execution modes), 21 (capabilities),
- * 23 (status UX).
- */
-/**
- * Thrown by skill-level auth verifiers when a page needs a human
- * (sign-in, 2FA, passkey, CAPTCHA, SSO). The browser subsystem catches this
- * and moves the Persistent session into reauthentication; skills define the
- * destination URL and the authenticated/challenge checks.
- */
 export class BrowserAuthRequired extends Error {
     provider;
     url;

package/dist/settings.d.ts

@@ -1,9 +1,4 @@
 import type { BrowserUseConfig } from './config.js';
-/**
- * Load the "pi-browser-use" section. Priority: user settings, then trusted
- * project settings (<cwd>/.pi/settings.json, no env expansion). Project
- * settings apply only when the session trusts the project.
- */
 export declare function loadConfig(options?: {
     cwd?: string;
     projectTrusted?: boolean;

package/dist/settings.js

@@ -29,11 +29,6 @@ function readSection(filePath, expand) {
         throw error;
     }
 }
-/**
- * Load the "pi-browser-use" section. Priority: user settings, then trusted
- * project settings (<cwd>/.pi/settings.json, no env expansion). Project
- * settings apply only when the session trusts the project.
- */
 export function loadConfig(options) {
     const user = readSection(join(homedir(), '.pi', 'agent', 'settings.json'), true);
     const cwd = options?.cwd ?? process.cwd();

package/dist/setup-flow.d.ts

@@ -1,40 +1,13 @@
-/**
- * Persistent bootstrap and reauthentication flows (spec sections 3 and 7).
- *
- * Bootstrap (first run): launch a real headed Chrome on the Pi profile with
- * no MCP/Puppeteer/CDP — an ordinary manually launched browser. The user
- * signs into Chrome/Google and any sites, completes 2FA/passkeys/SSO, then
- * closes the window. Close means SETUP_HEADFUL → READY; it initializes the
- * *profile*, it does not prove every site is authenticated (auth stays
- * site-specific, verified by skill-level verifiers).
- *
- * Reauthentication: when a skill raises BrowserAuthRequired, shut the
- * headless backend down cleanly, then reauth in one of two variants:
- * - Variant B (default): Pi-owned headed Chrome *with* CDP, so Pi can
- *   navigate to the login page before handing control to the user.
- * - Variant A (fallback): plain headed Chrome with no MCP/CDP, for login
- *   providers that reject instrumented browsers.
- * Afterwards the backend restarts headless and automation resumes.
- *
- * Launchers are injectable so the orchestration is unit-testable.
- */
 import type { PersistentBackend } from './persistent-backend.js';
 export type ReauthVariant = 'instrumented' | 'plain';
 export interface SetupFlowEvents {
-    /** Human-facing instruction shown before the setup window opens. */
     onSetupNeeded?: (message: string) => void;
-    /** Fired when the setup browser exits and the profile is marked ready. */
     onSetupComplete?: (profileDir: string) => void;
     onReauthNeeded?: (message: string) => void;
     onReauthComplete?: (profileDir: string) => void;
 }
 export declare const SETUP_INSTRUCTIONS: string;
 export declare function reauthInstructions(url: string, variant: ReauthVariant): string;
-/**
- * First-run bootstrap. Holds no locks itself — the caller (browser_setup
- * tool) must ensure no backend is running on the profile. Resolves with the
- * window exit code after marking the profile initialized.
- */
 export declare function runBootstrap(options: {
     profileDir?: string;
     executablePath?: string;
@@ -50,13 +23,11 @@ export declare function runBootstrap(options: {
 }, events?: SetupFlowEvents): Promise<number | null>;
 export interface ReauthOptions {
     backend: Pick<PersistentBackend, 'profileDir' | 'restart'>;
-    /** Page that needs auth (used for messaging + Variant B navigation hint). */
     url: string;
     variant?: ReauthVariant;
     signal?: AbortSignal;
     executablePath?: string;
     chromeArgs?: string[];
-    /** Plain-variant launcher (no CDP). Defaults to launchSetupBrowser. */
     launchPlain?: (options: {
         userDataDir: string;
         profileDirectory?: string;
@@ -64,21 +35,9 @@ export interface ReauthOptions {
         chromeArgs?: string[];
         signal?: AbortSignal;
     }) => Promise<number | null>;
-    /** Restart the backend headed/headless (Variant B + resume). */
     restartBackend?: (headed: boolean) => Promise<unknown>;
     events?: SetupFlowEvents;
 }
-/**
- * Run reauthentication against a stopped backend: the caller must have
- * already shut the headless backend down (or pass a backend whose
- * restartBackend handles it). Variant B restarts headed with CDP and leaves
- * the headed backend running for the handoff; Variant A opens a plain window
- * and waits for close. Returns the user-facing instruction to relay.
- */
 export declare function runReauth(options: ReauthOptions): Promise<string>;
-/**
- * Resume headless automation after reauth: restart the backend headless.
- * Returns true when the backend reports running afterwards.
- */
 export declare function resumeHeadless(backend: PersistentBackend): Promise<boolean>;
 //# sourceMappingURL=setup-flow.d.ts.map

package/dist/setup-flow.js

@@ -1,23 +1,3 @@
-/**
- * Persistent bootstrap and reauthentication flows (spec sections 3 and 7).
- *
- * Bootstrap (first run): launch a real headed Chrome on the Pi profile with
- * no MCP/Puppeteer/CDP — an ordinary manually launched browser. The user
- * signs into Chrome/Google and any sites, completes 2FA/passkeys/SSO, then
- * closes the window. Close means SETUP_HEADFUL → READY; it initializes the
- * *profile*, it does not prove every site is authenticated (auth stays
- * site-specific, verified by skill-level verifiers).
- *
- * Reauthentication: when a skill raises BrowserAuthRequired, shut the
- * headless backend down cleanly, then reauth in one of two variants:
- * - Variant B (default): Pi-owned headed Chrome *with* CDP, so Pi can
- *   navigate to the login page before handing control to the user.
- * - Variant A (fallback): plain headed Chrome with no MCP/CDP, for login
- *   providers that reject instrumented browsers.
- * Afterwards the backend restarts headless and automation resumes.
- *
- * Launchers are injectable so the orchestration is unit-testable.
- */
 import { launchSetupBrowser } from './chrome-launcher.js';
 import { ensureNamedProfile, PI_PROFILE_NAME } from './named-profile.js';
 import { markBootstrapped } from './persistent-store.js';
@@ -38,16 +18,10 @@ export function reauthInstructions(url, variant) {
         'When you are done, close the window (plain variant) or tell the agent to continue.',
     ].join('\n');
 }
-/**
- * First-run bootstrap. Holds no locks itself — the caller (browser_setup
- * tool) must ensure no backend is running on the profile. Resolves with the
- * window exit code after marking the profile initialized.
- */
 export async function runBootstrap(options, events) {
     options.signal?.throwIfAborted();
     const profileDir = options.profileDir ?? DEFAULT_PROFILE_DIR;
     events?.onSetupNeeded?.(SETUP_INSTRUCTIONS);
-    // Same named identity automation uses: sign in here, automate there.
     ensureNamedProfile(profileDir);
     const launch = options.launch ?? launchSetupBrowser;
     const code = await launch({
@@ -64,13 +38,6 @@ export async function runBootstrap(options, events) {
     events?.onSetupComplete?.(profileDir);
     return code;
 }
-/**
- * Run reauthentication against a stopped backend: the caller must have
- * already shut the headless backend down (or pass a backend whose
- * restartBackend handles it). Variant B restarts headed with CDP and leaves
- * the headed backend running for the handoff; Variant A opens a plain window
- * and waits for close. Returns the user-facing instruction to relay.
- */
 export async function runReauth(options) {
     options.signal?.throwIfAborted();
     const variant = options.variant ?? 'instrumented';
@@ -102,10 +69,6 @@ export async function runReauth(options) {
     options.events?.onReauthComplete?.(profileDir);
     return message;
 }
-/**
- * Resume headless automation after reauth: restart the backend headless.
- * Returns true when the backend reports running afterwards.
- */
 export async function resumeHeadless(backend) {
     await backend.restart(false);
     return backend.running();

package/dist/shared-backend.d.ts

@@ -1,20 +1,3 @@
-/**
- * Shared-backend registry + per-agent page ownership (multi-agent support).
- *
- * Many Pi agents share one Pi-owned Chrome: the first backend writes
- * `<profile>.backend.json` ({ pid, browserUrl, sessionId, startedAt });
- * latecomers attach to that browserUrl instead of launching a second Chrome
- * (the profile lock still forbids two processes — sharing is by attach).
- *
- * Tab separation is by ownership, not visuals: every page a Pi session opens
- * (or Pi-navigates, in shared modes) is recorded in `<profile>.pages.json`
- * with its owner session. Entries whose owner pid is dead are pruned
- * lazily. The close guard refuses pages owned by another *live* session.
- *
- * Page-id routing (upstream `experimentalPageIdRouting`) plus explicit
- * pageIds on every call keeps agents from driving each other's tabs; this
- * registry adds the missing pieces: discovery, ownership, and cleanup scope.
- */
 import type { McpPageEntry } from './existing-flow.js';
 export interface BackendAdvert {
     pid: number;
@@ -24,13 +7,9 @@ export interface BackendAdvert {
     startedAt: string;
 }
 export declare function backendAdvertPathFor(profileDir: string): string;
-/** This process's agent-session identity (one per extension load). */
 export declare function newSessionId(): string;
-/** Publish this backend for peer agents. Overwrites stale entries. */
 export declare function advertiseBackend(profileDir: string, advert: BackendAdvert): void;
-/** Read a live peer advert, or undefined (absent/corrupt/dead owner). */
 export declare function readLiveAdvert(profileDir: string): BackendAdvert | undefined;
-/** Withdraw our advert (backend shutdown). Best effort. */
 export declare function withdrawAdvert(profileDir: string, sessionId: string): void;
 export interface PageOwner {
     sessionId: string;
@@ -44,16 +23,12 @@ export interface OwnedPage {
     openedAt: string;
 }
 export declare function pageRegistryPathFor(profileDir: string): string;
-/** Drop entries whose owner process is gone. */
 export declare function pruneDeadOwners(profileDir: string): OwnedPage[];
-/** Claim a page for a session (open or Pi-navigate). */
 export declare function claimPage(profileDir: string, page: McpPageEntry, owner: PageOwner, at?: string): void;
-/** Release one page (closed) or all of a session's pages (shutdown). */
 export declare function releasePages(profileDir: string, filter: {
     pageId?: number;
     sessionId?: string;
 }): void;
-/** Live sessions currently holding pages (peers to avoid disturbing). */
 export declare function livePeerSessions(profileDir: string): PageOwner[];
 export type CloseVerdict = {
     ok: true;
@@ -61,10 +36,5 @@ export type CloseVerdict = {
     ok: false;
     reason: string;
 };
-/**
- * Shared-mode close verdict: our own or unclaimed pages may close; pages
- * owned by another live session need explicit force. Stale ids fail safe
- * with a re-list hint (ids shift when tabs close).
- */
 export declare function checkSharedCloseAllowed(entries: McpPageEntry[], pageId: number, profileDir: string, self: PageOwner, ownedUrls: ReadonlySet<string>): CloseVerdict;
 //# sourceMappingURL=shared-backend.d.ts.map

package/dist/shared-backend.js

@@ -1,20 +1,3 @@
-/**
- * Shared-backend registry + per-agent page ownership (multi-agent support).
- *
- * Many Pi agents share one Pi-owned Chrome: the first backend writes
- * `<profile>.backend.json` ({ pid, browserUrl, sessionId, startedAt });
- * latecomers attach to that browserUrl instead of launching a second Chrome
- * (the profile lock still forbids two processes — sharing is by attach).
- *
- * Tab separation is by ownership, not visuals: every page a Pi session opens
- * (or Pi-navigates, in shared modes) is recorded in `<profile>.pages.json`
- * with its owner session. Entries whose owner pid is dead are pruned
- * lazily. The close guard refuses pages owned by another *live* session.
- *
- * Page-id routing (upstream `experimentalPageIdRouting`) plus explicit
- * pageIds on every call keeps agents from driving each other's tabs; this
- * registry adds the missing pieces: discovery, ownership, and cleanup scope.
- */
 import { readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -30,16 +13,13 @@ function isPidAlive(pid) {
         return false;
     }
 }
-/** This process's agent-session identity (one per extension load). */
 export function newSessionId() {
     return randomUUID();
 }
-/** Publish this backend for peer agents. Overwrites stale entries. */
 export function advertiseBackend(profileDir, advert) {
     mkdirSync(dirname(backendAdvertPathFor(profileDir)), { recursive: true });
     writeFileSync(backendAdvertPathFor(profileDir), `${JSON.stringify(advert, null, 2)}\n`, 'utf8');
 }
-/** Read a live peer advert, or undefined (absent/corrupt/dead owner). */
 export function readLiveAdvert(profileDir) {
     try {
         const advert = JSON.parse(readFileSync(backendAdvertPathFor(profileDir), 'utf8'));
@@ -54,7 +34,6 @@ export function readLiveAdvert(profileDir) {
         return undefined;
     }
 }
-/** Withdraw our advert (backend shutdown). Best effort. */
 export function withdrawAdvert(profileDir, sessionId) {
     try {
         const raw = JSON.parse(readFileSync(backendAdvertPathFor(profileDir), 'utf8'));
@@ -62,7 +41,6 @@ export function withdrawAdvert(profileDir, sessionId) {
             rmSync(backendAdvertPathFor(profileDir), { force: true });
     }
     catch {
-        // Another backend already replaced it; leave it alone.
     }
 }
 export function pageRegistryPathFor(profileDir) {
@@ -87,19 +65,16 @@ function writeRegistry(profileDir, pages) {
     mkdirSync(dirname(pageRegistryPathFor(profileDir)), { recursive: true });
     writeFileSync(pageRegistryPathFor(profileDir), `${JSON.stringify(pages, null, 2)}\n`, 'utf8');
 }
-/** Drop entries whose owner process is gone. */
 export function pruneDeadOwners(profileDir) {
     const live = readRegistry(profileDir).filter((entry) => isPidAlive(entry.owner.pid));
     writeRegistry(profileDir, live);
     return live;
 }
-/** Claim a page for a session (open or Pi-navigate). */
 export function claimPage(profileDir, page, owner, at = new Date().toISOString()) {
     const pages = pruneDeadOwners(profileDir).filter((entry) => entry.pageId !== page.pageId);
     pages.push({ pageId: page.pageId, url: page.url, title: page.title, owner, openedAt: at });
     writeRegistry(profileDir, pages);
 }
-/** Release one page (closed) or all of a session's pages (shutdown). */
 export function releasePages(profileDir, filter) {
     const pages = pruneDeadOwners(profileDir).filter((entry) => {
         if (filter.pageId !== undefined && entry.pageId === filter.pageId)
@@ -110,7 +85,6 @@ export function releasePages(profileDir, filter) {
     });
     writeRegistry(profileDir, pages);
 }
-/** Live sessions currently holding pages (peers to avoid disturbing). */
 export function livePeerSessions(profileDir) {
     const seen = new Map();
     for (const entry of pruneDeadOwners(profileDir)) {
@@ -119,11 +93,6 @@ export function livePeerSessions(profileDir) {
     }
     return [...seen.values()];
 }
-/**
- * Shared-mode close verdict: our own or unclaimed pages may close; pages
- * owned by another live session need explicit force. Stale ids fail safe
- * with a re-list hint (ids shift when tabs close).
- */
 export function checkSharedCloseAllowed(entries, pageId, profileDir, self, ownedUrls) {
     const target = entries.find((entry) => entry.pageId === pageId);
     if (!target) {

package/dist/tab-bridge.d.ts

@@ -1,25 +1,3 @@
-/**
- * Existing-mode tab broker bridge (spec section 18).
- *
- * Pi cannot drive the extension directly, and raw MCP `new_page` calls would
- * create unmanaged foreground tabs — so tab creation goes through a tiny
- * loopback HTTP bridge the extension polls:
- *
- * ```text
- * Agent → BrowserSession.openPage(url) → ExistingSession
- *   → POST /v1/request {url} → token
- *   → extension polls GET /v1/pending → openPiTab(url) (inactive, grouped)
- *   → extension POSTs /v1/complete {token, tabId}
- *   → Pi waits for the token, then MCP selects the tab — never activating it
- * ```
- *
- * Correlation is by unique token, never "first tab whose URL matches"
- * (duplicate Gmail/GitHub tabs are common). Requests expire (default 2 min)
- * so a dead extension cannot leak queue entries. Only Pi-owned tabs are
- * tracked, so session-end cleanup never touches user tabs (spec 19).
- *
- * Security: binds 127.0.0.1 only and rejects non-loopback remotes.
- */
 export declare const DEFAULT_BRIDGE_PORT = 31973;
 export interface TabRequest {
     url: string;
@@ -35,9 +13,7 @@ export interface TabCompletion {
 }
 export interface TabBridgeOptions {
     port?: number;
-    /** Pending requests older than this are dropped. Default 2 minutes. */
     requestTtlMs?: number;
-    /** Completed entries kept for late waiters. Default 5 minutes. */
     completionTtlMs?: number;
 }
 export declare class TabBridge {
@@ -53,15 +29,12 @@ export declare class TabBridge {
     baseUrl(): string;
     start(): Promise<string>;
     stop(): Promise<void>;
-    /** Enqueue an open-tab request; returns the correlation token. */
     requestTab(url: string, token?: string): string;
-    /** Wait for the extension to complete `token` (throws on timeout/error). */
     waitForTab(token: string, options?: {
         timeoutMs?: number;
         pollMs?: number;
         signal?: AbortSignal;
     }): Promise<TabCompletion>;
-    /** Tab IDs Pi created and still owns (session-end cleanup scope). */
     ownedTabIds(): number[];
     pendingCount(): number;
     private sweep;

package/dist/tab-bridge.js

@@ -1,25 +1,3 @@
-/**
- * Existing-mode tab broker bridge (spec section 18).
- *
- * Pi cannot drive the extension directly, and raw MCP `new_page` calls would
- * create unmanaged foreground tabs — so tab creation goes through a tiny
- * loopback HTTP bridge the extension polls:
- *
- * ```text
- * Agent → BrowserSession.openPage(url) → ExistingSession
- *   → POST /v1/request {url} → token
- *   → extension polls GET /v1/pending → openPiTab(url) (inactive, grouped)
- *   → extension POSTs /v1/complete {token, tabId}
- *   → Pi waits for the token, then MCP selects the tab — never activating it
- * ```
- *
- * Correlation is by unique token, never "first tab whose URL matches"
- * (duplicate Gmail/GitHub tabs are common). Requests expire (default 2 min)
- * so a dead extension cannot leak queue entries. Only Pi-owned tabs are
- * tracked, so session-end cleanup never touches user tabs (spec 19).
- *
- * Security: binds 127.0.0.1 only and rejects non-loopback remotes.
- */
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 export const DEFAULT_BRIDGE_PORT = 31973;
@@ -96,7 +74,6 @@ export class TabBridge {
         this.server = undefined;
         await new Promise((resolve) => server.close(() => resolve()));
     }
-    /** Enqueue an open-tab request; returns the correlation token. */
     requestTab(url, token = randomUUID()) {
         if (typeof url !== 'string' || url.length === 0)
             throw new Error('Tab URL is required.');
@@ -104,15 +81,12 @@ export class TabBridge {
         this.pending.set(token, { url, token, createdAt: Date.now() });
         return token;
     }
-    /** Wait for the extension to complete `token` (throws on timeout/error). */
     async waitForTab(token, options) {
         const timeoutMs = options?.timeoutMs ?? 30_000;
         const pollMs = options?.pollMs ?? 100;
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (options?.signal?.aborted) {
-                // Do not leave a cancelled request for the extension to consume; it
-                // would create an unmanaged tab after the caller has given up.
                 this.pending.delete(token);
                 throw new Error('Tab wait aborted.');
             }
@@ -128,7 +102,6 @@ export class TabBridge {
         this.pending.delete(token);
         throw new Error(`Timed out waiting for the extension to open the tab (token ${token}).`);
     }
-    /** Tab IDs Pi created and still owns (session-end cleanup scope). */
     ownedTabIds() {
         return [...this.completed.values()]
             .filter((c) => c.tabId !== undefined && !c.error)

package/dist/tool-augment.d.ts

@@ -2,17 +2,8 @@ export declare function augmentToolDescription(prefixedName: string, description
 export declare function postProcessToolResult(originalName: string, text: string): string;
 export declare const OVERLAY_RECOVERABLE: Set<string>;
 export declare function looksOverlayBlocked(text: string): boolean;
-/**
- * Conservative login-wall detection: URL match, or at least two independent
- * content signals (a lone "Sign in" link on a homepage must not trigger).
- */
 export declare function looksLikeLoginWall(url: string | undefined, text: string): boolean;
 export type PageState = 'ok' | 'login-wall' | 'challenge';
-/**
- * Classify what kind of gate (if any) a page presents. Login walls need an
- * identity; challenges (bot checks) may clear on their own and never need
- * one — escalating identity for a challenge is wrong.
- */
 export declare function classifyPageState(url: string | undefined, text: string): PageState;
 export declare function extractTextContent(content: unknown): string;
 //# sourceMappingURL=tool-augment.d.ts.map

package/dist/tool-augment.js

@@ -18,8 +18,6 @@ export function postProcessToolResult(originalName, text) {
     }
     return text;
 }
-// Click-family tools worth one automatic recovery attempt when an overlay
-// blocks them: dismiss with Escape, then retry once.
 export const OVERLAY_RECOVERABLE = new Set([
     'click',
     'click_at',
@@ -34,9 +32,6 @@ export function looksOverlayBlocked(text) {
     return /overlay|obscured|intercept|behind another element|not clickable|not visible/i.test(text);
 }
 const LOGIN_URL = /(^|\/)(login|log-in|signin|sign-in|auth|authenticate|challenge|verify|2fa|totp|sso)(\/|$|[?#])/i;
-// Identity-specific phrases only. Bot-check vocabulary (Turnstile, "just a
-// moment") belongs to CHALLENGE below — mixing them makes one interstitial
-// count twice and misclassify challenges as login walls.
 const LOGIN_CONTENT = [
     /log in to continue/i,
     /sign in to continue/i,
@@ -44,21 +39,12 @@ const LOGIN_CONTENT = [
     /2-step verification/i,
     /enter your password/i,
 ];
-/**
- * Conservative login-wall detection: URL match, or at least two independent
- * content signals (a lone "Sign in" link on a homepage must not trigger).
- */
 export function looksLikeLoginWall(url, text) {
     if (url && LOGIN_URL.test(url))
         return true;
     return LOGIN_CONTENT.filter((pattern) => pattern.test(text)).length >= 2;
 }
 const CHALLENGE = /just a moment|verifying you are human|cf-turnstile|attention required|security check|prove you are human/i;
-/**
- * Classify what kind of gate (if any) a page presents. Login walls need an
- * identity; challenges (bot checks) may clear on their own and never need
- * one — escalating identity for a challenge is wrong.
- */
 export function classifyPageState(url, text) {
     if (looksLikeLoginWall(url, text))
         return 'login-wall';

package/dist/vision.d.ts

@@ -1,14 +1,3 @@
-/**
- * Optional vision-model integration.
- *
- * Captures a screenshot via the upstream take_screenshot tool and sends it
- * to a vision model from Pi's model registry. This lets the agent identify
- * elements by visual attributes (color, layout, coordinates) when the
- * accessibility tree is insufficient, e.g. canvas/WebGL scenes.
- *
- * The pi-ai host module is loaded lazily so the extension runs on hosts
- * without it; only the vision tool requires it.
- */
 export interface VisionModelConfig {
     provider: string;
     model: string;
@@ -29,12 +18,6 @@ export declare function createRegistryVisionCaller(visionConfig: VisionModelConf
 interface BrowserClient {
     callTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
 }
-/**
- * Capture a screenshot through the browser client and analyze it with the
- * provided vision caller. Returns MCP-style content, never throws except on
- * abort: failures degrade to actionable error text pointing at the
- * accessibility tree instead.
- */
 export declare function handleAnalyzeScreenshot(client: BrowserClient, callVision: (instruction: string, imageBase64: string, mimeType: string, signal?: AbortSignal) => Promise<string>, args: {
     instruction?: string;
     pageId?: number;

package/dist/vision.js

@@ -1,14 +1,3 @@
-/**
- * Optional vision-model integration.
- *
- * Captures a screenshot via the upstream take_screenshot tool and sends it
- * to a vision model from Pi's model registry. This lets the agent identify
- * elements by visual attributes (color, layout, coordinates) when the
- * accessibility tree is insufficient, e.g. canvas/WebGL scenes.
- *
- * The pi-ai host module is loaded lazily so the extension runs on hosts
- * without it; only the vision tool requires it.
- */
 export const VISUAL_SYSTEM_PROMPT = `You are a visual analysis assistant for browser automation. You receive a screenshot of a web page and an instruction.
 
 COORDINATES:
@@ -70,12 +59,6 @@ export function createRegistryVisionCaller(visionConfig, registry) {
             .join('');
     };
 }
-/**
- * Capture a screenshot through the browser client and analyze it with the
- * provided vision caller. Returns MCP-style content, never throws except on
- * abort: failures degrade to actionable error text pointing at the
- * accessibility tree instead.
- */
 export async function handleAnalyzeScreenshot(client, callVision, args, signal) {
     const instruction = String(args.instruction ?? '');
     const screenshotArgs = typeof args.pageId === 'number' ? { pageId: args.pageId } : {};

package/docs/performance.md

@@ -41,6 +41,8 @@ Budgets live in [`performance-budgets.json`](../performance-budgets.json). They
 | Published map files               |             0 |
 | Production dependency closure     |  140 packages |
 
+The published artifact stays byte-lean by design: `tsconfig.json` sets `removeComments` so emitted JavaScript and declarations carry no comment bytes, and build maps never ship. Source commentary lives in the repository, not in the installed package.
+
 ## Reproduce locally and in CI
 
 ```sh