pi-browser-use 0.6.0 → 0.7.0

package/dist/index.js

@@ -3,13 +3,21 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { Type } from 'typebox';
 import { DevToolsClient } from './client.js';
-import { resolveConfig, resolveModeTarget, } from './config.js';
+import { DEFAULT_PROFILE_DIR, resolveConfig, resolveModeTarget, } from './config.js';
 import { isProjectTrusted, loadConfig } from './settings.js';
 import { augmentToolDescription, classifyPageState, extractTextContent, looksLikeLoginWall, looksOverlayBlocked, OVERLAY_RECOVERABLE, postProcessToolResult, } from './tool-augment.js';
 import { pickImageData, resolveArtifactTarget } from './artifacts.js';
 import { CLEANUP_ANNOTATIONS, formatAnnotatedMap, INJECT_ANNOTATIONS, parseAnnotatedElements, } from './annotate.js';
 import { diagnose, formatDoctorReport } from './doctor.js';
+import { checkExistingCloseAllowed, normalizeTabUrl, openExistingPage, parseMcpPageList, } from './existing-flow.js';
+import { applyNewPageDefaults, applySelectPageDefaults } from './focus-policy.js';
+import { frontProcessByPid } from './chrome-launcher.js';
+import { PersistentBackend, shouldSelfLaunch } from './persistent-backend.js';
+import { loadPersistentMetadata, loadSitePreferences, markAutomationResult, saveSitePreferences, } from './persistent-store.js';
 import { prepareBrowserProfile } from './profile.js';
+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 { createRegistryVisionCaller, handleAnalyzeScreenshot, } from './vision.js';
 export { configToArgs, resolveConfig } from './config.js';
 // All upstream tools are re-exported with this prefix to avoid name collisions.
@@ -60,13 +68,27 @@ function toToolContent(result, originalName) {
  * discovers upstream tools, and registers each as browser_*. On
  * session_shutdown tears the subprocess down. Nothing runs persistently.
  *
- * Defaults are fresh headless (isolated ephemeral profile, no window). Set
- * sessionMode "persistent" for the authenticated profile, or "existing" with
+ * Defaults are persistent headless (Pi-owned profile, no window, no consent
+ * popups). Set mode "fresh" for an isolated clean room, or "existing" with
  * autoConnect/browserUrl to drive an already-running Chrome.
  */
 export default function browserUseExtension(pi) {
     let config;
     let client;
+    // Pi-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 Pi opened or navigated to in Existing mode (raw + normalized): the
+    // only close_page targets allowed there without explicit force:true.
+    const piOwnedUrls = new Set();
+    function trackPiUrl(url) {
+        piOwnedUrls.add(url);
+        piOwnedUrls.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 = 'fresh';
@@ -75,14 +97,15 @@ export default function browserUseExtension(pi) {
             return 'fresh';
         if (config?.sessionMode === 'persistent')
             return 'persistent';
+        if (config?.sessionMode === 'existing')
+            return 'existing';
         return 'custom';
     }
-    /**
-     * Rebuild the backend for a mode switch. Shared by the switch tool and
-     * automatic escalation so both paths behave identically.
-     */
-    async function switchBackend(mode, headed, signal) {
-        const next = resolveConfig(resolveModeTarget(config ?? {}, mode, headed));
+    function persistentProfileDir(cfg) {
+        return cfg.userDataDir ?? DEFAULT_PROFILE_DIR;
+    }
+    /** Close the MCP transport and any Pi-owned Chrome. The bridge survives. */
+    async function teardownBackend() {
         if (client) {
             try {
                 await client.close();
@@ -92,12 +115,78 @@ export default function browserUseExtension(pi) {
             }
             client = undefined;
         }
-        prepareBrowserProfile(next);
-        client = new DevToolsClient(next);
+        if (ownBackend) {
+            try {
+                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;
+        }
+    }
+    function pinCurrentSite(profileDir, headed) {
+        if (!lastOrigin)
+            return false;
+        const prefs = rememberExecutionPreference(loadSitePreferences(profileDir), lastOrigin, headed ? 'headed-background' : 'headless');
+        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 Pi-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));
+        await teardownBackend();
+        let effectiveHeaded = headed;
+        let backendNote = '';
+        if (mode === 'persistent' && shouldSelfLaunch(next)) {
+            const profileDir = persistentProfileDir(next);
+            if (opts?.rememberSite === true)
+                pinCurrentSite(profileDir, headed);
+            if (!headed && lastOrigin) {
+                const pinned = resolveExecutionForOrigin(loadSitePreferences(profileDir), lastOrigin, 'headless');
+                if (pinned === 'headed-background') {
+                    effectiveHeaded = true;
+                    backendNote = ` (${normalizeOrigin(lastOrigin)} prefers the visible fallback)`;
+                }
+            }
+            ownBackend = new PersistentBackend({ config: next, headed: effectiveHeaded });
+            const attach = await ownBackend.start(signal);
+            client = new DevToolsClient(attach);
+            markAutomationResult(profileDir, effectiveHeaded ? 'headed' : 'headless');
+        }
+        else {
+            if (mode === 'persistent' && opts?.rememberSite === true) {
+                pinCurrentSite(persistentProfileDir(next), headed);
+            }
+            prepareBrowserProfile(next);
+            client = new DevToolsClient(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;
-        return next;
+        return { next, effectiveHeaded, backendNote };
+    }
+    /** Start the Existing-mode tab broker bridge on demand. */
+    async function ensureBridge() {
+        if (bridge)
+            return bridge;
+        const port = config?.tabBridgePort ?? DEFAULT_BRIDGE_PORT;
+        if (port === 0)
+            throw new Error('The tab bridge is disabled (tabBridgePort: 0).');
+        bridge = new TabBridge({ port });
+        await bridge.start();
+        return bridge;
     }
     function loginWallHint(url, text) {
         if (currentMode !== 'fresh')
@@ -106,22 +195,58 @@ export default function browserUseExtension(pi) {
             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.';
     }
+    function sameOrigin(a, b) {
+        try {
+            if (!a || !b)
+                return false;
+            return new URL(a).origin === new URL(b).origin;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * 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) {
+    async function escalateBlockedPage(url, text, signal, context) {
         const state = classifyPageState(url, text);
         if (state === 'ok')
             return '';
+        if (state === 'challenge') {
+            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;
+                    }
+                    catch {
+                        return '';
+                    }
+                })();
+                if (!/challenge|turnstile|captcha|cf-chl|kasada|perimeterx|datadome/i.test(host))
+                    return '';
+            }
+        }
         if (state === 'login-wall') {
             if (currentMode === 'fresh')
                 return loginWallHint(url, text);
-            if (currentMode === 'custom') {
+            if (currentMode === 'custom' || currentMode === 'existing') {
                 return '\n\nThis page needs an identity this session does not have. Sign in is required — complete it in the visible browser, then retry.';
             }
+            if (config?.headless === false) {
+                return '\n\nThis page needs a login and the browser is already visible. Sign in in that window, then retry — no relaunch, nothing closed.';
+            }
             return await escalateToHeaded(url ?? 'this page');
         }
         // Challenge (bot check): identity never helps; only a human-gated
@@ -129,7 +254,7 @@ export default function browserUseExtension(pi) {
         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.';
         }
-        if (currentMode === 'custom') {
+        if (currentMode === 'custom' || currentMode === 'existing') {
             return '\n\nA bot challenge is blocking this page. Complete it in the visible browser, then retry — do not loop against the challenge.';
         }
         return await escalateToHeaded(url ?? 'this page');
@@ -137,7 +262,9 @@ export default function browserUseExtension(pi) {
     /**
      * 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.
+     * 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';
@@ -147,11 +274,28 @@ export default function browserUseExtension(pi) {
         catch (error) {
             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.`;
         }
-        return `\n\nBlocked on ${url}: a browser window just opened (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.`;
+        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 Pi-owned Chrome so the handoff window is actually visible.
+        // Fresh MCP-launched Chrome fronts itself; only Pi-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.`;
     }
     function pageUrlFromSnapshot(text) {
         return text.match(/\burl="([^"]+)"/)?.[1];
     }
+    /** Best-effort MCP page list → entries (shared parser, never throws). */
+    function mcpPageEntries(result) {
+        return parseMcpPageList(result);
+    }
     async function ensureConnected(signal) {
         if (!client)
             throw new Error('browser-use: session not started');
@@ -166,15 +310,71 @@ export default function browserUseExtension(pi) {
             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 Pi did not open (spec 19); stripped before upstream.
+            const parameters = originalName === 'close_page'
+                ? Type.Object({
+                    pageId: Type.Number({
+                        description: 'The ID of the page to close. Call browser_list_pages first; IDs shift when tabs close.',
+                    }),
+                    force: Type.Optional(Type.Boolean({
+                        description: 'Existing mode only: Pi refuses to close tabs it did not open unless force is true and the user explicitly asked for that exact tab.',
+                    })),
+                })
+                : Type.Unsafe(tool.inputSchema);
             pi.registerTool({
                 name: prefixedName,
                 label: prefixedName,
                 description,
-                parameters: Type.Unsafe(tool.inputSchema),
+                parameters,
                 async execute(_toolCallId, params, signal) {
                     await ensureConnected(signal);
                     const browser = client;
-                    let result = await callUpstream(browser, originalName, params, signal);
+                    // Focus policy (headed-background / existing): Pi-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'
+                            ? applySelectPageDefaults(params)
+                            : 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 a Pi-driven navigation marks the destination
+                        // as Pi-touched for the close guard below.
+                        if (currentMode === 'existing')
+                            trackPiUrl(effectiveParams.url);
+                    }
+                    // Existing mode never closes user tabs: close_page carries a
+                    // force gate and a Pi-ownership check (spec 19).
+                    if (originalName === 'close_page') {
+                        const { force: _force, ...closeArgs } = effectiveParams;
+                        void _force;
+                        if (currentMode === 'existing' && effectiveParams.force !== true) {
+                            if (typeof effectiveParams.pageId !== 'number') {
+                                return {
+                                    content: [{ type: 'text', text: 'close_page needs a numeric pageId.' }],
+                                    isError: true,
+                                    details: undefined,
+                                };
+                            }
+                            const entries = parseMcpPageList(await callUpstream(browser, 'list_pages', {}, signal));
+                            const verdict = checkExistingCloseAllowed(entries, effectiveParams.pageId, piOwnedUrls);
+                            if (!verdict.ok) {
+                                return {
+                                    content: [{ type: 'text', text: verdict.reason }],
+                                    isError: true,
+                                    details: undefined,
+                                };
+                            }
+                        }
+                        const result = await callUpstream(browser, originalName, closeArgs, signal);
+                        return { ...toToolContent(result, originalName), details: undefined };
+                    }
+                    let result = await callUpstream(browser, originalName, effectiveParams, signal);
                     if (result.isError &&
                         OVERLAY_RECOVERABLE.has(originalName) &&
                         looksOverlayBlocked(extractTextContent(result.content))) {
@@ -182,11 +382,11 @@ export default function browserUseExtension(pi) {
                         // original call. Any failure here falls through to the
                         // original error, which already carries a hint.
                         try {
-                            const escapeArgs = typeof params.pageId === 'number'
-                                ? { pageId: params.pageId, key: 'Escape' }
+                            const escapeArgs = typeof effectiveParams.pageId === 'number'
+                                ? { pageId: effectiveParams.pageId, key: 'Escape' }
                                 : { key: 'Escape' };
                             await callUpstream(browser, 'press_key', escapeArgs, signal);
-                            result = await callUpstream(browser, originalName, params, signal);
+                            result = await callUpstream(browser, originalName, effectiveParams, signal);
                         }
                         catch {
                             // Fall through to the original result below.
@@ -195,10 +395,14 @@ export default function browserUseExtension(pi) {
                     const toolContent = toToolContent(result, originalName);
                     if (!toolContent.isError &&
                         (originalName === 'navigate_page' || originalName === 'take_snapshot')) {
-                        const url = originalName === 'navigate_page' && typeof params.url === 'string'
-                            ? params.url
-                            : pageUrlFromSnapshot(extractTextContent(result.content));
-                        const escalation = await escalateBlockedPage(url, extractTextContent(result.content), signal);
+                        // 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
+                            : undefined;
+                        const url = snapshotUrl ?? requestedUrl;
+                        const escalation = await escalateBlockedPage(url, extractTextContent(result.content), signal, { tool: originalName, requestedUrl });
                         const first = toolContent.content[0];
                         if (escalation && first && first.text !== undefined) {
                             first.text += escalation;
@@ -299,23 +503,257 @@ export default function browserUseExtension(pi) {
         pi.registerTool({
             name: `${TOOL_PREFIX}switch_mode`,
             label: `${TOOL_PREFIX}switch_mode`,
-            description: 'Switch the browser backend without restarting: "fresh" is an isolated clean room, "persistent" keeps the saved profile with your logins. Both default to headless; pass headed true to watch. Tabs do not transfer; call browser_list_pages after switching. Prefer fresh; escalate to persistent only on login walls.',
+            description: 'Switch the browser backend without restarting: "persistent" is Pi\'s own browser (saved profile with your logins, default), "fresh" is an isolated clean room for anonymous checks, "existing" attaches to your running Chrome (tabs go to the collapsed pi-browser-use group via browser_open_background_tab, consent popup each session). Fresh and persistent default to headless; pass headed true to watch. Tabs do not transfer; call browser_list_pages after switching. Prefer persistent; drop to fresh for clean-room checks.',
             parameters: Type.Object({
-                mode: Type.Union([Type.Literal('fresh'), Type.Literal('persistent')]),
+                mode: Type.Union([
+                    Type.Literal('fresh'),
+                    Type.Literal('persistent'),
+                    Type.Literal('existing'),
+                ]),
                 headed: Type.Optional(Type.Boolean({
                     description: 'Show the browser window. Default is headless — everything works with no popups.',
                 })),
+                rememberSite: Type.Optional(Type.Boolean({
+                    description: "Persistent only: remember the last-visited site's visibility (headless or headed-background) for next time.",
+                })),
             }),
             async execute(_toolCallId, params, signal) {
-                const mode = params.mode === 'persistent' ? 'persistent' : 'fresh';
-                const next = await switchBackend(mode, params.headed === true, signal);
+                const mode = params.mode === 'persistent'
+                    ? 'persistent'
+                    : params.mode === 'existing'
+                        ? 'existing'
+                        : 'fresh';
+                const { next, effectiveHeaded, backendNote } = await switchBackend(mode, params.headed === true, signal, { rememberSite: params.rememberSite === true });
+                const visibility = mode === 'existing' ? 'headed (your Chrome)' : effectiveHeaded ? 'headed' : 'headless';
+                const what = mode === 'fresh'
+                    ? 'a fresh isolated browser'
+                    : mode === 'persistent'
+                        ? 'the persistent Pi profile'
+                        : 'your running Chrome';
+                const extra = mode === 'existing'
+                    ? ' Open Pi tabs with browser_open_background_tab so they land in the collapsed pi-browser-use group.'
+                    : '';
+                void next;
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: mode === 'fresh'
-                                ? `Switched to a fresh isolated browser (${next.headless === false ? 'headed' : 'headless'}). Previous tabs are gone; call browser_list_pages to start.`
-                                : `Switched to the persistent profile (${next.headless === false ? 'headed' : 'headless'}). Previous tabs are gone; call browser_list_pages to start.`,
+                            text: `Switched to ${what} (${visibility})${backendNote}. Previous tabs are gone; call browser_list_pages to start.${extra}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            },
+        });
+    }
+    function registerSetupTool() {
+        pi.registerTool({
+            name: `${TOOL_PREFIX}setup`,
+            label: `${TOOL_PREFIX}setup`,
+            description: 'First-run setup for the persistent Pi browser profile: opens a plain headed Chrome window (no automation attached) for a human to sign into Google and any sites. Completes when the window is closed. Run once; afterwards Pi automates headless.',
+            parameters: Type.Object({}),
+            async execute() {
+                const profileDir = persistentProfileDir(config ?? {});
+                const meta = loadPersistentMetadata(profileDir);
+                if (meta.initialized) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Pi browser profile is already initialized (${profileDir}). If a login expired, use browser_reauth instead.`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                // No Chrome may hold the profile while the setup window runs.
+                await teardownBackend();
+                await runBootstrap({
+                    profileDir,
+                    executablePath: config?.executablePath,
+                    chromeArgs: config?.chromeArgs,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Pi browser profile initialized. Pi now works in the background — no Chrome window will appear during normal automation.',
+                        },
+                    ],
+                    details: undefined,
+                };
+            },
+        });
+    }
+    function registerStatusTool() {
+        pi.registerTool({
+            name: `${TOOL_PREFIX}status`,
+            label: `${TOOL_PREFIX}status`,
+            description: 'Plain-language Pi browser status: profile readiness, execution mode, and what to do next. No page is touched.',
+            parameters: Type.Object({}),
+            async execute() {
+                const mode = currentMode;
+                const profileDir = persistentProfileDir(config ?? {});
+                const meta = loadPersistentMetadata(profileDir);
+                const sitePins = loadSitePreferences(profileDir).length;
+                const lines = ['Pi Browser', '──────────'];
+                if (mode === 'fresh') {
+                    lines.push('Profile: Ephemeral (nothing persists)');
+                    lines.push('Execution: Headless');
+                }
+                else if (mode === 'persistent') {
+                    lines.push(`Profile: ${meta.initialized ? 'Ready' : 'Setup required'}`);
+                    if (!meta.initialized) {
+                        lines.push('Next step: run browser_setup and sign in, then close the window.');
+                    }
+                    else {
+                        const headed = config?.headless === false;
+                        lines.push(`Execution: ${headed ? 'Visible fallback (background)' : 'Headless'}${ownBackend?.running() ? '' : ' (backend stopped)'}`);
+                        if (meta.lastSuccessfulMode)
+                            lines.push(`Last working mode: ${meta.lastSuccessfulMode}`);
+                        if (sitePins > 0)
+                            lines.push(`Sites pinned to visible fallback: ${sitePins}`);
+                    }
+                }
+                else if (mode === 'existing') {
+                    lines.push('Profile: Your browser');
+                    lines.push('Execution: Background tabs in the collapsed pi-browser-use group');
+                    lines.push(`Tab bridge: ${bridge ? bridge.baseUrl() : 'not running'}`);
+                }
+                else {
+                    lines.push('Profile: Externally attached browser');
+                    lines.push('Execution: Visible (owned by its launcher)');
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }], details: undefined };
+            },
+        });
+    }
+    function registerReauthTool() {
+        pi.registerTool({
+            name: `${TOOL_PREFIX}reauth`,
+            label: `${TOOL_PREFIX}reauth`,
+            description: 'Reauthenticate the persistent Pi profile after a login/challenge wall: shuts the headless browser down cleanly, opens a headed window for the human to verify, then resumes headless. The plain variant (no automation attached) is for providers that reject instrumented browsers.',
+            parameters: Type.Object({
+                url: Type.Optional(Type.String({ description: 'Page that needs authentication. Defaults to last origin.' })),
+                variant: Type.Optional(Type.Union([Type.Literal('instrumented'), Type.Literal('plain')], {
+                    description: 'Headed variant: instrumented (Pi navigates first) or plain (maximum compatibility).',
+                })),
+            }),
+            async execute(_toolCallId, params, signal) {
+                if (currentMode !== 'persistent') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Reauth applies to the persistent Pi profile. Switch to it first with browser_switch_mode({"mode": "persistent"}).',
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                const url = typeof params.url === 'string' && params.url.length > 0
+                    ? params.url
+                    : (lastOrigin ?? 'this page');
+                const variant = params.variant === 'plain' ? 'plain' : 'instrumented';
+                if (!ownBackend) {
+                    // Legacy MCP-launched persistent: headed switch is the reauth path.
+                    await switchBackend('persistent', true, signal);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `A browser window just opened (legacy persistent backend). ${url}: please complete the login there, then tell the agent to continue.`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                // Spec §7: close headless Chrome cleanly before any headed reauth.
+                await teardownBackend();
+                const backend = new PersistentBackend({
+                    config: config ?? {},
+                    headed: variant === 'instrumented',
+                });
+                ownBackend = backend;
+                const message = await runReauth({
+                    backend,
+                    url,
+                    variant,
+                    restartBackend: (headed) => backend.restart(headed),
+                });
+                if (variant === 'plain') {
+                    // Plain window closed by the human: resume headless automation.
+                    const attach = await backend.restart(false);
+                    client = new DevToolsClient(attach);
+                    await client.ensureReady(signal);
+                    return {
+                        content: [
+                            { type: 'text', text: `${message}\n\nVerification recorded — Pi resumed headless.` },
+                        ],
+                        details: undefined,
+                    };
+                }
+                client = new DevToolsClient(backend.attachConfig());
+                await client.ensureReady(signal);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${message}\n\nAfter verifying, tell the agent to continue; it resumes with browser_switch_mode({"mode": "persistent"}) back to headless.`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            },
+        });
+    }
+    function registerOpenBackgroundTabTool() {
+        pi.registerTool({
+            name: `${TOOL_PREFIX}open_background_tab`,
+            label: `${TOOL_PREFIX}open_background_tab`,
+            description: 'Existing mode only: open a URL as an inactive tab in the collapsed pi-browser-use group via the Pi extension — never a foreground tab. Fails clearly when the extension bridge is unavailable.',
+            parameters: Type.Object({
+                url: Type.String({ description: 'URL to open in a background Pi tab.' }),
+                timeoutMs: Type.Optional(Type.Number({
+                    description: 'How long to wait for the extension (default 90000: a suspended worker wakes on the ~1min alarm cadence).',
+                })),
+            }),
+            async execute(_toolCallId, params, signal) {
+                if (currentMode !== 'existing') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Background Pi tabs need Existing mode (your Chrome). Switch first with browser_switch_mode({"mode": "existing"}).',
+                                isError: true,
+                            },
+                        ],
+                        details: undefined,
+                        isError: true,
+                    };
+                }
+                if (typeof params.url !== 'string' || params.url.length === 0) {
+                    throw new Error('A URL is required.');
+                }
+                const activeBridge = await ensureBridge();
+                const timeoutMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0 ? params.timeoutMs : 90_000;
+                const result = await openExistingPage(params.url, {
+                    bridge: activeBridge,
+                    listPages: async () => {
+                        await ensureConnected(signal);
+                        const pages = await client.callTool('list_pages', {}, signal);
+                        return mcpPageEntries(pages);
+                    },
+                }, { timeoutMs, signal });
+                trackPiUrl(params.url);
+                const selectHint = result.pageId !== undefined
+                    ? ` Select it with browser_select_page (it stays in the background).`
+                    : ' Call browser_list_pages to find it (it stays in the background).';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Opened ${params.url} as an inactive tab in the collapsed pi-browser-use group.${selectHint}`,
                         },
                     ],
                     details: undefined,
@@ -331,7 +769,10 @@ export default function browserUseExtension(pi) {
             parameters: Type.Object({}),
             async execute() {
                 await ensureConnected();
-                const report = await diagnose(config ?? {}, async () => (await client.listAllTools()).map((tool) => tool.name));
+                const report = await diagnose(config ?? {}, async () => (await client.listAllTools()).map((tool) => tool.name), {
+                    backend: ownBackend ? 'pi-owned' : undefined,
+                    bridgeUrl: bridge?.baseUrl() ?? null,
+                });
                 return { content: [{ type: 'text', text: formatDoctorReport(report) }], details: undefined };
             },
         });
@@ -368,20 +809,37 @@ export default function browserUseExtension(pi) {
     pi.on('session_start', async (_event, ctx) => {
         config = resolveConfig(loadConfig({ cwd: ctx.cwd, projectTrusted: isProjectTrusted(ctx) }));
         currentMode = describeMode();
-        prepareBrowserProfile(config);
-        client = new DevToolsClient(config);
+        if (currentMode === 'persistent' && shouldSelfLaunch(config)) {
+            // Phase 2: Pi owns the persistent Chrome process; MCP attaches.
+            ownBackend = new PersistentBackend({ config, headed: config.headless === false });
+            client = new DevToolsClient(await ownBackend.start());
+        }
+        else {
+            prepareBrowserProfile(config);
+            client = new DevToolsClient(config);
+        }
         await registerUpstreamTools();
         registerSaveArtifactTool();
         registerDoctorTool();
         registerSwitchModeTool();
+        registerSetupTool();
+        registerStatusTool();
+        registerReauthTool();
+        registerOpenBackgroundTabTool();
         if (config.visionModel) {
             await registerVisionTool(config.visionModel);
         }
     });
     pi.on('session_shutdown', async () => {
-        if (client) {
-            await client.close();
-            client = undefined;
+        await teardownBackend();
+        if (bridge) {
+            try {
+                await bridge.stop();
+            }
+            catch {
+                // Session teardown is best-effort.
+            }
+            bridge = undefined;
         }
     });
 }