pi-browser-use 0.10.1 → 0.11.1

package/dist/runtime.js

@@ -19,12 +19,10 @@ import { runBootstrap, runReauth } from './setup-flow.js';
 import { normalizeOrigin, rememberExecutionPreference, resolveExecutionForOrigin, } from './session-manager.js';
 import { DEFAULT_BRIDGE_PORT, TabBridge } from './tab-bridge.js';
 import { handleAnalyzeScreenshot } from './vision.js';
-// All upstream tools are re-exported with this prefix to avoid name collisions.
 const TOOL_PREFIX = 'browser_';
 async function callUpstream(client, name, params, signal) {
     return (await client.callTool(name, params, signal));
 }
-// Noisy, slow, or privileged upstream tools; skipped during registration.
 const EXCLUDED_TOOLS = new Set([
     'lighthouse_audit',
     'performance_analyze_insight',
@@ -74,12 +72,10 @@ function toToolContent(result, originalName) {
         content.push({ type: 'text', text: '' });
     return result.isError ? { content, isError: true } : { content };
 }
-/** Shared browser lifecycle, policy, tools, and ownership. No Pi host is required. */
 export function createBrowserRuntime(options = {}) {
     const defaultProfileDir = options.defaultProfileDir ?? DEFAULT_PROFILE_DIR;
     const artifactDir = options.artifactDir ?? defaultArtifactDir();
     let config = resolveConfig(options.config, defaultProfileDir);
-    // Remember identity even when a fresh/existing backend deliberately drops userDataDir.
     const identityProfileDir = config.userDataDir ?? defaultProfileDir;
     if (config.sessionMode === 'isolated')
         config.userDataDir = undefined;
@@ -106,27 +102,18 @@ export function createBrowserRuntime(options = {}) {
                     combined.throwIfAborted();
                     return tool.execute(params, combined, context);
                 });
-                // Serializing calls prevents mode switches/reauth racing in-flight page actions.
                 operations = result.then(ignoreResult, ignoreResult);
                 return result;
             },
         });
     }
-    // Plugin-owned persistent Chrome (self-launched, MCP attached via browserUrl).
-    // Set only for persistent mode when the legacy MCP-launch path is off.
     let ownBackend;
-    // Existing-mode tab broker bridge. Lazy; lives for the whole session.
     let bridge;
-    // Last navigated origin: drives the per-origin headed-background fallback.
     let lastOrigin;
-    // URLs this session opened or navigated to in Existing mode (raw + normalized): the
-    // only close_page targets allowed there without explicit force:true.
     const ownedUrls = new Set();
-    // This extension load's agent-session identity for the shared registry.
     const sessionId = newSessionId();
     const myOwner = { sessionId, pid: process.pid };
     const shortSession = sessionId.slice(0, 8);
-    /** Registry home: the persistent profile, or the default home for existing. */
     function registryDir() {
         return currentMode === 'persistent' ? persistentProfileDir(config ?? {}) : defaultProfileDir;
     }
@@ -134,8 +121,6 @@ export function createBrowserRuntime(options = {}) {
         ownedUrls.add(url);
         ownedUrls.add(normalizeTabUrl(url));
     }
-    // Tracks which identity the live backend holds, so results can suggest
-    // escalation. 'custom' covers user-configured attach setups we did not pick.
     let currentMode = describeMode();
     function describeMode() {
         if (config.sessionMode === 'existing')
@@ -153,7 +138,6 @@ export function createBrowserRuntime(options = {}) {
     function persistentProfileDir(cfg) {
         return cfg.userDataDir ?? identityProfileDir;
     }
-    /** Close the MCP transport and any Plugin-owned Chrome. The bridge survives. */
     async function teardownBackend() {
         backendInitialized = false;
         if (client) {
@@ -161,7 +145,6 @@ export function createBrowserRuntime(options = {}) {
                 await client.close();
             }
             catch {
-                // A half-dead transport must not block the switch.
             }
             client = undefined;
         }
@@ -170,8 +153,6 @@ export function createBrowserRuntime(options = {}) {
                 await ownBackend.stop();
             }
             catch {
-                // Shutdown is best-effort; the profile lock release inside never
-                // throws fatally, so a new backend can still start.
             }
             ownBackend = undefined;
         }
@@ -183,14 +164,6 @@ export function createBrowserRuntime(options = {}) {
         saveSitePreferences(profileDir, prefs);
         return true;
     }
-    /**
-     * Rebuild the backend for a mode switch. Shared by the switch tool and
-     * automatic escalation so both paths behave identically. Persistent
-     * self-launches Plugin-owned Chrome (MCP attaches via browserUrl) unless
-     * PI_BROWSER_USE_LEGACY_PERSISTENT=1. A per-origin headed-background pin
-     * wins over a headless request so one headless-hostile site never
-     * downgrades every site.
-     */
     async function switchBackend(mode, headed, signal, opts) {
         const next = resolveConfig(resolveModeTarget(config, mode, headed, identityProfileDir), defaultProfileDir);
         await teardownBackend();
@@ -221,8 +194,6 @@ export function createBrowserRuntime(options = {}) {
                 client = createClient(next);
             }
             await client.ensureReady(signal);
-            // Record what actually launched (a per-origin pin may have upgraded
-            // headless to headed-background) so status/doctor tell the truth.
             next.headless = !effectiveHeaded;
             config = next;
             currentMode = mode;
@@ -234,7 +205,6 @@ export function createBrowserRuntime(options = {}) {
             throw error;
         }
     }
-    /** Start the Existing-mode tab broker bridge on demand. */
     async function ensureBridge() {
         if (bridge)
             return bridge;
@@ -252,17 +222,6 @@ export function createBrowserRuntime(options = {}) {
             return '';
         return '\n\nHint: this looks like a login wall in a fresh (logged-out) session. If the page needs your identity, call browser_switch_mode({"mode": "persistent"}) — a human must complete any SSO, 2FA, or passkey step, ideally headed.';
     }
-    /**
-     * Automatic escalation for hard blocks the agent cannot clear alone.
-     * Returns prompt text for the agent to relay, or empty when nothing
-     * applies. Escalates at most once per call; never loops, never retries
-     * a challenge page, and never switches away from an attached session.
-     *
-     * Challenges only escalate with navigation context: a stale "Just a
-     * moment..." shortcut tile on a New Tab snapshot must not rebuild the
-     * backend, and a challenge on another origin than requested means the
-     * navigation never landed there.
-     */
     async function escalateBlockedPage(url, text, signal, context) {
         const state = classifyPageState(url, text);
         if (state === 'ok')
@@ -271,8 +230,6 @@ export function createBrowserRuntime(options = {}) {
             if (context?.tool !== 'navigate_page')
                 return '';
             if (context.requestedUrl && url && !sameOrigin(context.requestedUrl, url)) {
-                // Challenge-provider handoffs (dedicated challenge domains) still
-                // count; anything else means the navigation never landed there.
                 const host = (() => {
                     try {
                         return new URL(url).hostname;
@@ -296,8 +253,6 @@ export function createBrowserRuntime(options = {}) {
             }
             return await escalateToHeaded(url ?? 'this page', signal);
         }
-        // Challenge (bot check): identity never helps; only a human-gated
-        // headed window can clear it. Stay in the same mode.
         if (config?.headless === false) {
             return '\n\nA bot challenge is blocking this page and the browser is already visible. Complete the challenge in the window, then retry.';
         }
@@ -306,13 +261,6 @@ export function createBrowserRuntime(options = {}) {
         }
         return await escalateToHeaded(url ?? 'this page', signal);
     }
-    /**
-     * Rebuild the current backend headed so a human can act (log in, clear
-     * a challenge), then tell the agent exactly what to relay. Attach
-     * sessions are already visible and owned by the user: prompt only. The
-     * headed window is navigated to the blocked page and fronted: auth
-     * handoff is the one case where taking foreground is the job, not a bug.
-     */
     async function escalateToHeaded(url, signal) {
         const mode = currentMode === 'persistent' ? 'persistent' : 'fresh';
         try {
@@ -322,16 +270,12 @@ export function createBrowserRuntime(options = {}) {
             return `\n\nBlocked on ${url} and the headed browser failed to launch (${error instanceof Error ? error.message : String(error)}). Ask the user to proceed manually.`;
         }
         if (/^https?:\/\//.test(url)) {
-            // Best effort: the window is already open for manual navigation.
             try {
                 await callUpstream(client, 'new_page', { url, background: false }, signal);
             }
             catch {
-                // Manual navigation in the opened window covers this.
             }
         }
-        // Front Plugin-owned Chrome so the handoff window is actually visible.
-        // Fresh MCP-launched Chrome fronts itself; only Plugin-owned needs help.
         if (ownBackend)
             frontProcessByPid(ownBackend.pid());
         return `\n\nBlocked on ${url}: a browser window just opened on that page (same ${mode} session — previous tabs are gone, re-list pages after). Please complete the login or challenge in that window, then tell the agent to continue. Do not close the window until done.`;
@@ -339,6 +283,9 @@ export function createBrowserRuntime(options = {}) {
     async function ensureConnected(signal) {
         signal?.throwIfAborted();
         try {
+            if (backendInitialized && ownBackend && !ownBackend.running()) {
+                await teardownBackend();
+            }
             if (!backendInitialized) {
                 await client?.close();
                 if (currentMode === 'persistent' && shouldSelfLaunch(config)) {
@@ -366,8 +313,6 @@ export function createBrowserRuntime(options = {}) {
             const prefixedName = `${TOOL_PREFIX}${tool.name}`;
             const originalName = tool.name;
             const description = augmentToolDescription(prefixedName, tool.description ?? '');
-            // close_page carries an extra force gate so Existing mode can refuse
-            // to close tabs this session did not open (spec 19); stripped before upstream.
             const parameters = originalName === 'close_page'
                 ? Type.Object({
                     pageId: Type.Number({
@@ -386,9 +331,6 @@ export function createBrowserRuntime(options = {}) {
                 async execute(params, signal) {
                     await ensureConnected(signal);
                     const browser = client;
-                    // Focus policy (headed-background / existing): Agent-created pages
-                    // open in the background and selections never take foreground
-                    // unless the caller explicitly asked. Explicit values always win.
                     const effectiveParams = originalName === 'new_page'
                         ? applyNewPageDefaults(params)
                         : originalName === 'select_page'
@@ -396,15 +338,9 @@ export function createBrowserRuntime(options = {}) {
                             : params;
                     if ((originalName === 'navigate_page' || originalName === 'new_page') &&
                         typeof effectiveParams.url === 'string') {
-                        // Remember the origin for the per-origin headed-background
-                        // fallback; normalizeOrigin never throws (falls back to raw).
                         lastOrigin = normalizeOrigin(effectiveParams.url);
-                        // In Existing mode an agent-driven navigation marks the destination
-                        // as agent-touched for the close guard below.
                         if (currentMode === 'existing' && originalName === 'navigate_page')
                             trackUrl(effectiveParams.url);
-                        // Claim navigated pages for this session so peer agents in a
-                        // shared browser can tell ours apart (best effort, never fatal).
                         if (originalName === 'navigate_page' &&
                             (currentMode === 'persistent' || currentMode === 'existing') &&
                             typeof effectiveParams.pageId === 'number') {
@@ -412,13 +348,9 @@ export function createBrowserRuntime(options = {}) {
                                 claimPage(registryDir(), { pageId: effectiveParams.pageId, url: effectiveParams.url }, myOwner);
                             }
                             catch {
-                                // Ownership is coordination metadata, not the task itself.
                             }
                         }
                     }
-                    // Never close another session's tabs: Existing mode checks Pi URL
-                    // ownership (spec 19); a shared persistent backend checks the page
-                    // registry instead. Both yield to explicit force:true.
                     if (originalName === 'close_page') {
                         const { force: _force, ...closeArgs } = effectiveParams;
                         void _force;
@@ -448,13 +380,10 @@ export function createBrowserRuntime(options = {}) {
                                 releasePages(registryDir(), { pageId: effectiveParams.pageId });
                             }
                             catch {
-                                // Registry hygiene never fails the close itself.
                             }
                         }
                         return { ...toToolContent(result, originalName) };
                     }
-                    // Correlate a newly opened page by ID, never by URL: other agents
-                    // may have the same URL open. Ambiguous results are left unclaimed.
                     let before;
                     if (originalName === 'new_page' &&
                         (currentMode === 'persistent' || currentMode === 'existing')) {
@@ -469,9 +398,6 @@ export function createBrowserRuntime(options = {}) {
                     if (result.isError &&
                         OVERLAY_RECOVERABLE.has(originalName) &&
                         looksOverlayBlocked(extractTextContent(result.content))) {
-                        // One recovery attempt: dismiss the overlay, then retry the
-                        // original call. Any failure here falls through to the
-                        // original error, which already carries a hint.
                         try {
                             const escapeArgs = typeof effectiveParams.pageId === 'number'
                                 ? { pageId: effectiveParams.pageId, key: 'Escape' }
@@ -480,7 +406,6 @@ export function createBrowserRuntime(options = {}) {
                             result = await callUpstream(browser, originalName, effectiveParams, signal);
                         }
                         catch {
-                            // Fall through to the original result below.
                         }
                     }
                     if (!result.isError && before) {
@@ -493,15 +418,12 @@ export function createBrowserRuntime(options = {}) {
                                 claimPage(registryDir(), opened, myOwner);
                             }
                             catch {
-                                // Ownership is coordination metadata, not the task itself.
                             }
                         }
                     }
                     const toolContent = toToolContent(result, originalName);
                     if (!toolContent.isError &&
                         (originalName === 'navigate_page' || originalName === 'take_snapshot')) {
-                        // Prefer the page's real URL from the snapshot; fall back to the
-                        // requested URL only when the snapshot carries none.
                         const snapshotUrl = pageUrlFromSnapshot(extractTextContent(result.content));
                         const requestedUrl = originalName === 'navigate_page' && typeof effectiveParams.url === 'string'
                             ? effectiveParams.url
@@ -591,7 +513,6 @@ export function createBrowserRuntime(options = {}) {
                             }, signal);
                         }
                         catch {
-                            // Badges are pointer-events:none and harmless if cleanup fails.
                         }
                     }
                 }
@@ -667,7 +588,6 @@ export function createBrowserRuntime(options = {}) {
                         ],
                     };
                 }
-                // No Chrome may hold the profile while the setup window runs.
                 await teardownBackend();
                 await withProfileLock(profileDir, () => runBootstrap({
                     profileDir,
@@ -772,7 +692,6 @@ export function createBrowserRuntime(options = {}) {
                     };
                 }
                 if (!ownBackend && !shouldSelfLaunch(config)) {
-                    // Legacy MCP-launched persistent: headed switch is the reauth path.
                     await switchBackend('persistent', true, signal);
                     return {
                         content: [
@@ -783,7 +702,6 @@ export function createBrowserRuntime(options = {}) {
                         ],
                     };
                 }
-                // Spec §7: close headless Chrome cleanly before any headed reauth.
                 await teardownBackend();
                 const backend = createBackend({
                     config: config ?? {},
@@ -802,7 +720,6 @@ export function createBrowserRuntime(options = {}) {
                 });
                 const message = variant === 'plain' ? await withProfileLock(backend.profileDir(), reauth) : await reauth();
                 if (variant === 'plain') {
-                    // Plain window closed by the human: resume headless automation.
                     const attach = await backend.restart(false, signal);
                     client = createClient(attach);
                     await client.ensureReady(signal);
@@ -875,7 +792,6 @@ export function createBrowserRuntime(options = {}) {
                         claimPage(registryDir(), { pageId: result.pageId, url: params.url }, myOwner);
                     }
                     catch {
-                        // Ownership is coordination metadata, not the task itself.
                     }
                 }
                 const selectHint = result.pageId !== undefined
@@ -947,8 +863,6 @@ export function createBrowserRuntime(options = {}) {
     }
     async function initialize() {
         if (options.lazyBrowser) {
-            // Tool discovery is browser-free even when the chosen identity is persistent.
-            // The upstream server launches/attaches Chrome only on its first browser call.
             client = createClient({
                 ...config,
                 sessionMode: 'isolated',
@@ -991,13 +905,11 @@ export function createBrowserRuntime(options = {}) {
         lifetime.abort(new Error('Browser runtime is stopped.'));
         await Promise.allSettled([startPromise, operations]);
         await teardownBackend();
-        // Release only this runtime's claims; never terminate a borrowed browser.
         for (const scope of new Set([identityProfileDir, defaultProfileDir])) {
             try {
                 releasePages(scope, { sessionId });
             }
             catch {
-                // Best effort.
             }
         }
         if (bridge) {
@@ -1005,7 +917,6 @@ export function createBrowserRuntime(options = {}) {
                 await bridge.stop();
             }
             catch {
-                // Session teardown is best-effort.
             }
             bridge = undefined;
         }

package/dist/session-manager.d.ts

@@ -1,32 +1,11 @@
-/**
- * BrowserSessionManager: mode-specific behavior behind one stable API
- * (spec sections 1, 8, 21, 24, 25).
- *
- * ```text
- * Pi Skills / Agent → BrowserSessionManager → Fresh | Persistent | Existing
- * ```
- *
- * - Fresh: temporary profile, headless, deleted afterwards (spec 12).
- * - Persistent: Pi-owned profile with headless-first automation and a
- *   headed-background fallback per origin (spec 2, 4, 7, 8, 24).
- * - Existing: the user's own Chrome via autoConnect; Pi tabs are brokered by
- *   the Pi extension into the collapsed `pi-browser-use` group (spec 13-20).
- *
- * This module holds the state machines, capability resolution, and fallback
- * hierarchies. Process launching (chrome-launcher), locking (profile-lock),
- * and durable metadata (persistent-store) are injected collaborators so the
- * logic stays unit-testable without a real Chrome.
- */
 import type { BrowserCapabilityRequest, BrowserSession, BrowserSessionMode, BrowserStatus, PageHandle, PersistentBrowserMetadata, PersistentExecutionMode, PersistentState, SiteBrowserPreference } from './session.js';
 export type { BrowserSession, BrowserStatus, PageHandle } from './session.js';
-/** Minimal transport SPI a session uses to drive pages (MCP/CDP/extension). */
 export interface SessionTransport {
     openPage(url: string): Promise<PageHandle>;
     listPages(): Promise<PageHandle[]>;
     closePage(page: PageHandle): Promise<void>;
     requestVisibleBrowser?(reason: string): Promise<void>;
 }
-/** In-memory transport for tests and for wiring custom backends. */
 export declare function createMemoryTransport(): SessionTransport & {
     pages: PageHandle[];
 };
@@ -42,20 +21,14 @@ declare abstract class BaseSession implements BrowserSession {
     abstract getStatus(): Promise<BrowserStatus>;
     shutdown(): Promise<void>;
 }
-/** Fresh: anonymous, stateless, headless. Never inherits auth (spec 12). */
 export declare class FreshSession extends BaseSession {
     constructor(transport: SessionTransport);
     getStatus(): Promise<BrowserStatus>;
 }
-/** Events driving the Persistent state machine (spec section 2). */
 export type PersistentEvent = 'bootstrap-needed' | 'bootstrap-opened' | 'bootstrap-closed' | 'automation-started' | 'automation-succeeded' | 'auth-required' | 'reauth-opened' | 'reauth-completed' | 'headless-incompatible';
-/** Pure Persistent lifecycle transition. Returns the state unchanged for unknown events. */
 export declare function nextPersistentState(state: PersistentState, event: PersistentEvent): PersistentState;
-/** Normalize a URL or origin to a bare origin for preference lookup. */
 export declare function normalizeOrigin(urlOrOrigin: string): string;
-/** Resolve the execution mode for an origin or full URL (spec section 8). */
 export declare function resolveExecutionForOrigin(preferences: SiteBrowserPreference[], urlOrOrigin: string, fallback?: PersistentExecutionMode): PersistentExecutionMode;
-/** Remember/overwrite the per-origin preference; never downgrades globally. */
 export declare function rememberExecutionPreference(preferences: SiteBrowserPreference[], urlOrOrigin: string, executionMode: PersistentExecutionMode): SiteBrowserPreference[];
 export interface PersistentSessionOptions {
     transport: SessionTransport;
@@ -64,10 +37,6 @@ export interface PersistentSessionOptions {
     executionMode?: PersistentExecutionMode;
     sitePreferences?: SiteBrowserPreference[];
 }
-/**
- * Persistent: Pi's browser identity. Headless first; per-origin
- * headed-background fallback; reauth via headed browser (spec 2, 7, 8).
- */
 export declare class PersistentSession extends BaseSession {
     private persistentState;
     private executionMode;
@@ -79,15 +48,9 @@ export declare class PersistentSession extends BaseSession {
     get preferences(): SiteBrowserPreference[];
     send(event: PersistentEvent): PersistentState;
     executionFor(urlOrOrigin: string): PersistentExecutionMode;
-    /** A site failed headless while headed works: pin headed-background there. */
     markHeadlessIncompatible(urlOrOrigin: string): void;
     getStatus(): Promise<BrowserStatus>;
 }
-/**
- * Existing: the user's browser identity via autoConnect (spec 13).
- * All Pi-created tabs must go through the extension broker into the
- * collapsed `pi-browser-use` group — never raw foreground tabs.
- */
 export declare class ExistingSession extends BaseSession {
     constructor(transport: SessionTransport);
     getStatus(): Promise<BrowserStatus>;
@@ -97,19 +60,9 @@ export interface ManagedSessions {
     persistent: BrowserSession;
     existing: BrowserSession;
 }
-/**
- * Resolve a capability request to a mode (spec section 21):
- * persistence/auth → persistent; explicit existing opt-in → existing;
- * otherwise fresh. Callers escalate along the fallback hierarchies
- * (sections 24/25) when the resolved mode cannot serve.
- */
 export declare function resolveModeForCapabilities(request: BrowserCapabilityRequest, persistentInitialized: boolean): BrowserSessionMode;
-/** Persistent escalation sequence (spec section 24). */
 export type PersistentEscalation = 'headless' | 'headed-auth-then-headless' | 'headed-background' | 'suggest-existing';
-/** Next step when persistent headless cannot proceed. */
 export declare function nextPersistentEscalation(reason: 'works' | 'login-needed' | 'headless-incompatible'): PersistentEscalation;
-/** Existing-mode creation contract (spec section 25): fail loudly when the
- * extension broker is unavailable rather than opening unmanaged tabs. */
 export declare function assertExistingBrokerAvailable(available: boolean): void;
 export declare class BrowserSessionManager {
     private readonly sessions;
@@ -118,7 +71,6 @@ export declare class BrowserSessionManager {
     getMode(): BrowserSessionMode;
     getSession(mode?: BrowserSessionMode): BrowserSession;
     switchTo(mode: BrowserSessionMode): Promise<BrowserSession>;
-    /** Capability-based selection (spec 21): skills ask, manager resolves. */
     require(request: BrowserCapabilityRequest): Promise<BrowserSession>;
     shutdownAll(): Promise<void>;
 }

package/dist/session-manager.js

@@ -1,24 +1,4 @@
-/**
- * BrowserSessionManager: mode-specific behavior behind one stable API
- * (spec sections 1, 8, 21, 24, 25).
- *
- * ```text
- * Pi Skills / Agent → BrowserSessionManager → Fresh | Persistent | Existing
- * ```
- *
- * - Fresh: temporary profile, headless, deleted afterwards (spec 12).
- * - Persistent: Pi-owned profile with headless-first automation and a
- *   headed-background fallback per origin (spec 2, 4, 7, 8, 24).
- * - Existing: the user's own Chrome via autoConnect; Pi tabs are brokered by
- *   the Pi extension into the collapsed `pi-browser-use` group (spec 13-20).
- *
- * This module holds the state machines, capability resolution, and fallback
- * hierarchies. Process launching (chrome-launcher), locking (profile-lock),
- * and durable metadata (persistent-store) are injected collaborators so the
- * logic stays unit-testable without a real Chrome.
- */
 import { PI_GROUP_TITLE } from './focus-policy.js';
-/** In-memory transport for tests and for wiring custom backends. */
 export function createMemoryTransport() {
     const pages = [];
     let counter = 0;
@@ -62,7 +42,6 @@ class BaseSession {
     }
     async shutdown() { }
 }
-/** Fresh: anonymous, stateless, headless. Never inherits auth (spec 12). */
 export class FreshSession extends BaseSession {
     constructor(transport) {
         super('fresh', transport);
@@ -93,11 +72,9 @@ const PERSISTENT_TRANSITIONS = {
     REAUTH_REQUIRED: { 'reauth-opened': 'REAUTH_HEADFUL' },
     REAUTH_HEADFUL: { 'reauth-completed': 'READY' },
 };
-/** Pure Persistent lifecycle transition. Returns the state unchanged for unknown events. */
 export function nextPersistentState(state, event) {
     return PERSISTENT_TRANSITIONS[state][event] ?? state;
 }
-/** Normalize a URL or origin to a bare origin for preference lookup. */
 export function normalizeOrigin(urlOrOrigin) {
     try {
         return new URL(urlOrOrigin).origin;
@@ -106,23 +83,17 @@ export function normalizeOrigin(urlOrOrigin) {
         return urlOrOrigin;
     }
 }
-/** Resolve the execution mode for an origin or full URL (spec section 8). */
 export function resolveExecutionForOrigin(preferences, urlOrOrigin, fallback = 'headless') {
     const origin = normalizeOrigin(urlOrOrigin);
     const match = preferences.find((p) => normalizeOrigin(p.origin) === origin);
     return match?.executionMode ?? fallback;
 }
-/** Remember/overwrite the per-origin preference; never downgrades globally. */
 export function rememberExecutionPreference(preferences, urlOrOrigin, executionMode) {
     const origin = normalizeOrigin(urlOrOrigin);
     const next = preferences.filter((p) => normalizeOrigin(p.origin) !== origin);
     next.push({ origin, executionMode });
     return next;
 }
-/**
- * Persistent: Pi's browser identity. Headless first; per-origin
- * headed-background fallback; reauth via headed browser (spec 2, 7, 8).
- */
 export class PersistentSession extends BaseSession {
     persistentState;
     executionMode;
@@ -158,14 +129,12 @@ export class PersistentSession extends BaseSession {
             return this.executionMode;
         }
     }
-    /** A site failed headless while headed works: pin headed-background there. */
     markHeadlessIncompatible(urlOrOrigin) {
         try {
             const origin = new URL(urlOrOrigin).origin;
             this.sitePreferences = rememberExecutionPreference(this.sitePreferences, origin, 'headed-background');
         }
         catch {
-            // Non-URL input: fall back to the session default without pinning.
             this.executionMode = 'headed-background';
         }
         this.send('headless-incompatible');
@@ -186,11 +155,6 @@ export class PersistentSession extends BaseSession {
         };
     }
 }
-/**
- * Existing: the user's browser identity via autoConnect (spec 13).
- * All Pi-created tabs must go through the extension broker into the
- * collapsed `pi-browser-use` group — never raw foreground tabs.
- */
 export class ExistingSession extends BaseSession {
     constructor(transport) {
         super('existing', transport);
@@ -204,12 +168,6 @@ export class ExistingSession extends BaseSession {
         };
     }
 }
-/**
- * Resolve a capability request to a mode (spec section 21):
- * persistence/auth → persistent; explicit existing opt-in → existing;
- * otherwise fresh. Callers escalate along the fallback hierarchies
- * (sections 24/25) when the resolved mode cannot serve.
- */
 export function resolveModeForCapabilities(request, persistentInitialized) {
     if (request.persistence === true || request.authentication) {
         return 'persistent';
@@ -219,7 +177,6 @@ export function resolveModeForCapabilities(request, persistentInitialized) {
     }
     return 'fresh';
 }
-/** Next step when persistent headless cannot proceed. */
 export function nextPersistentEscalation(reason) {
     if (reason === 'works')
         return 'headless';
@@ -227,8 +184,6 @@ export function nextPersistentEscalation(reason) {
         return 'headed-auth-then-headless';
     return 'headed-background';
 }
-/** Existing-mode creation contract (spec section 25): fail loudly when the
- * extension broker is unavailable rather than opening unmanaged tabs. */
 export function assertExistingBrokerAvailable(available) {
     if (!available) {
         throw new Error(`Existing-mode tab broker unavailable: refusing to open unmanaged tabs. ` +
@@ -256,7 +211,6 @@ export class BrowserSessionManager {
         await session.ensureReady();
         return session;
     }
-    /** Capability-based selection (spec 21): skills ask, manager resolves. */
     async require(request) {
         const persistent = this.sessions.persistent;
         let initialized = false;