@vibebrowser/mcp 0.2.5 → 0.2.6

package/dist/browser-cli.js

@@ -4,6 +4,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { ExtensionConnection } from './connection.js';
 import { DEFAULT_WS_PORT } from './types.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
+/** Short timeout for the `status` command — it should never block for 30 s. */
+const STATUS_TOOLS_TIMEOUT_MS = 2_000;
 const DEFAULT_BROWSER_PROFILE = process.env.VIBE_BROWSER_PROFILE || 'user';
 const DEFAULT_REMOTE_UUID = process.env.VIBE_EXTENSION_UUID || process.env.VIBE_RELAY_UUID;
 const DEFAULT_REMOTE_RELAY_URL = process.env.VIBE_REMOTE_RELAY_URL || process.env.VIBE_RELAY_URL;
@@ -23,9 +25,12 @@ function buildBrowserCommand(command) {
         .option('-p, --port <number>', 'WebSocket port for local relay (agent) connection', String(DEFAULT_WS_PORT))
         .option('-d, --debug', 'Enable debug logging', false)
         .option('-r, --remote <uuid>', 'Connect to a remote extension via public relay (provide the extension UUID)', DEFAULT_REMOTE_UUID)
+        .option('-s, --session <id>', 'Target a specific local browser session ID; defaults to the first connected session')
         .option('--relay-url <url>', 'Custom relay server URL', DEFAULT_REMOTE_RELAY_URL)
         .option('--json', 'Emit machine-readable JSON output', false)
-        .option('--timeout <ms>', 'Command timeout in milliseconds', String(DEFAULT_TIMEOUT_MS));
+        .option('--timeout <ms>', 'Command timeout in milliseconds', String(DEFAULT_TIMEOUT_MS))
+        .option('--page-id <id>', 'Target a specific page/tab by its numeric ID (avoids switching the user\'s active tab)')
+        .option('--pageId <id>', 'Alias for --page-id');
 }
 function registerBrowserSubcommands(browser) {
     browser
@@ -61,6 +66,12 @@ function registerBrowserSubcommands(browser) {
             note: 'The Vibe browser bridge does not own the browser process, so stop only disconnects this CLI session',
         }));
     });
+    browser
+        .command('sessions')
+        .description('List connected browser sessions')
+        .action(async function () {
+        await runBrowserCommand(this, 'sessions', false, async (ctx) => ctx.listSessions());
+    });
     browser
         .command('tabs')
         .description('List browser tabs/pages')
@@ -80,7 +91,7 @@ function registerBrowserSubcommands(browser) {
     });
     tab
         .command('select <id>')
-        .description('Focus a tab/page')
+        .description('Switch to a tab/page by its ID (rarely needed — most commands accept a tab id argument instead, prefer that to avoid disrupting the user\'s browser)')
         .action(async function (id) {
         await runBrowserCommand(this, 'tab select', true, async (ctx) => ctx.focus(id));
     });
@@ -104,7 +115,7 @@ function registerBrowserSubcommands(browser) {
     });
     browser
         .command('focus <id>')
-        .description('Focus a tab/page')
+        .description('Switch focus to a tab/page by its ID (rarely needed — most commands accept a tab id argument instead, prefer that to avoid disrupting the user\'s browser)')
         .action(async function (id) {
         await runBrowserCommand(this, 'focus', true, async (ctx) => ctx.focus(id));
     });
@@ -156,31 +167,7 @@ function registerBrowserSubcommands(browser) {
             grayscale: Boolean(options.grayscale),
         }));
     });
-    browser
-        .command('pdf')
-        .description('Render the current page as PDF when supported')
-        .option('--output <path>', 'Write PDF bytes to a file')
-        .action(async function () {
-        await runBrowserCommand(this, 'pdf', true, async (ctx, options) => ctx.pdf(options.output ? String(options.output) : undefined));
-    });
-    browser
-        .command('console')
-        .description('List console messages')
-        .option('--level <level>', 'Console level filter')
-        .option('--preserve', 'Include preserved messages when supported', false)
-        .action(async function () {
-        await runBrowserCommand(this, 'console', true, async (ctx, options) => ctx.consoleMessages({
-            level: options.level ? String(options.level) : undefined,
-            preserve: Boolean(options.preserve),
-        }));
-    });
-    browser
-        .command('errors')
-        .description('List console errors')
-        .option('--clear', 'Compatibility flag', false)
-        .action(async function () {
-        await runBrowserCommand(this, 'errors', true, async (ctx) => ctx.consoleMessages({ level: 'error' }));
-    });
+    // NOTE: pdf, console, errors commands removed — no matching browser tools.
     browser
         .command('requests')
         .description('List network requests')
@@ -205,12 +192,7 @@ function registerBrowserSubcommands(browser) {
                 : undefined,
         }));
     });
-    browser
-        .command('resize <width> <height>')
-        .description('Resize the browser viewport')
-        .action(async function (width, height) {
-        await runBrowserCommand(this, 'resize', true, async (ctx) => ctx.resize(parsePositiveInteger(width, 'width'), parsePositiveInteger(height, 'height')));
-    });
+    // NOTE: resize command removed — no resize_page tool in the extension.
     browser
         .command('click <ref>')
         .description('Click an element by ref/index')
@@ -237,12 +219,7 @@ function registerBrowserSubcommands(browser) {
         .action(async function (ref) {
         await runBrowserCommand(this, 'hover', true, async (ctx) => ctx.hover(ref));
     });
-    browser
-        .command('scrollintoview <ref>')
-        .description('Scroll an element into view when supported')
-        .action(async function (ref) {
-        await runBrowserCommand(this, 'scrollintoview', true, async (ctx) => ctx.scrollIntoView(ref));
-    });
+    // NOTE: scrollintoview, download, waitfordownload, upload commands removed — no matching tools.
     browser
         .command('drag <source> <target>')
         .description('Drag one element to another')
@@ -255,25 +232,6 @@ function registerBrowserSubcommands(browser) {
         .action(async function (ref, values) {
         await runBrowserCommand(this, 'select', true, async (ctx) => ctx.select(ref, values));
     });
-    browser
-        .command('download <ref> [filename]')
-        .description('Trigger/download an element when supported')
-        .action(async function (ref, filename) {
-        await runBrowserCommand(this, 'download', true, async (ctx) => ctx.download(ref, filename));
-    });
-    browser
-        .command('waitfordownload [filename]')
-        .description('Wait for a download when supported')
-        .action(async function (filename) {
-        await runBrowserCommand(this, 'waitfordownload', true, async (ctx) => ctx.waitForDownload(filename));
-    });
-    browser
-        .command('upload <path>')
-        .description('Upload a file when supported')
-        .option('--ref <ref>', 'Element ref/index')
-        .action(async function (path) {
-        await runBrowserCommand(this, 'upload', true, async (ctx, options) => ctx.upload(path, options.ref ? String(options.ref) : undefined));
-    });
     browser
         .command('fill')
         .description('Fill a form using JSON field descriptors')
@@ -281,19 +239,7 @@ function registerBrowserSubcommands(browser) {
         .action(async function () {
         await runBrowserCommand(this, 'fill', true, async (ctx, options) => ctx.fillForm(String(options.fields)));
     });
-    browser
-        .command('dialog')
-        .description('Accept or dismiss a browser dialog')
-        .option('--accept', 'Accept the dialog', false)
-        .option('--dismiss', 'Dismiss the dialog', false)
-        .option('--prompt <text>', 'Prompt text to enter')
-        .action(async function () {
-        await runBrowserCommand(this, 'dialog', true, async (ctx, options) => ctx.dialog({
-            accept: Boolean(options.accept),
-            dismiss: Boolean(options.dismiss),
-            prompt: options.prompt ? String(options.prompt) : undefined,
-        }));
-    });
+    // NOTE: dialog command removed — no handle_dialog tool in the extension.
     browser
         .command('wait')
         .description('Wait for text or a short delay')
@@ -320,31 +266,8 @@ function registerBrowserSubcommands(browser) {
             argsJson: options.args ? String(options.args) : undefined,
         }));
     });
-    browser
-        .command('highlight <ref>')
-        .description('Highlight an element when supported')
-        .action(async function (ref) {
-        await runBrowserCommand(this, 'highlight', true, async (ctx) => ctx.highlight(ref));
-    });
-    const trace = browser.command('trace').description('Start/stop browser tracing');
-    trace
-        .command('start')
-        .description('Start a trace')
-        .option('--reload', 'Reload the page during trace start when supported', false)
-        .option('--output <path>', 'Trace output path')
-        .action(async function () {
-        await runBrowserCommand(this, 'trace start', true, async (ctx, options) => ctx.traceStart({
-            reload: Boolean(options.reload),
-            outputPath: options.output ? String(options.output) : undefined,
-        }));
-    });
-    trace
-        .command('stop')
-        .description('Stop an active trace')
-        .option('--output <path>', 'Trace output path')
-        .action(async function () {
-        await runBrowserCommand(this, 'trace stop', true, async (ctx, options) => ctx.traceStop(options.output ? String(options.output) : undefined));
-    });
+    // NOTE: highlight command removed — no highlight tool; users can use 'hover' directly.
+    // NOTE: trace commands removed — no performance_start_trace/performance_stop_trace tools.
 }
 async function runBrowserCommand(command, commandName, requireExtension, handler) {
     const globalOptions = command.optsWithGlobals();
@@ -353,11 +276,13 @@ async function runBrowserCommand(command, commandName, requireExtension, handler
         port: parsePositiveInteger(globalOptions.port, '--port'),
         debug: Boolean(globalOptions.debug),
         remoteUuid: globalOptions.remote,
+        sessionId: globalOptions.session,
         relayUrl: globalOptions.relayUrl,
         profile: globalOptions.browserProfile || DEFAULT_BROWSER_PROFILE,
         json: Boolean(globalOptions.json),
         timeoutMs: parsePositiveInteger(globalOptions.timeout, '--timeout'),
         target: globalOptions.target,
+        pageId: globalOptions.pageId ? parsePositiveInteger(globalOptions.pageId, '--page-id') : undefined,
     });
     try {
         await ctx.connect();
@@ -381,17 +306,22 @@ class BrowserCliContext {
     json;
     timeoutMs;
     remoteUuid;
+    requestedSessionId;
     target;
+    pageId;
     toolsLoaded = false;
     tools = [];
+    sessions = [];
     ignoredCompatibilityOptions;
     constructor(init) {
-        this.connection = new ExtensionConnection(init.port, init.debug, init.remoteUuid ? { uuid: init.remoteUuid, relayUrl: init.relayUrl } : undefined);
+        this.connection = new ExtensionConnection(init.port, init.debug, init.remoteUuid ? { uuid: init.remoteUuid, relayUrl: init.relayUrl } : undefined, init.remoteUuid ? undefined : { sessionId: init.sessionId });
         this.profile = init.profile;
         this.json = init.json;
         this.timeoutMs = init.timeoutMs;
         this.remoteUuid = init.remoteUuid;
+        this.requestedSessionId = init.sessionId;
         this.target = init.target;
+        this.pageId = init.pageId;
         this.ignoredCompatibilityOptions = [];
         if (this.target) {
             this.ignoredCompatibilityOptions.push(`target=${this.target}`);
@@ -400,6 +330,7 @@ class BrowserCliContext {
     async connect() {
         await this.connection.start();
         await delay(100);
+        this.sessions = await this.connection.listSessions(1_500).catch(() => this.connection.getSessions());
         await this.connection.waitForToolsUpdate(500);
     }
     async shutdown() {
@@ -409,20 +340,41 @@ class BrowserCliContext {
         if (this.connection.isExtensionConnected()) {
             return;
         }
+        this.sessions = await this.connection.listSessions(1_500).catch(() => this.connection.getSessions());
         await this.ensureToolsLoaded();
         if (!this.connection.isExtensionConnected()) {
-            throw new Error('No browser extension is connected to the Vibe relay');
+            throw new Error(this.connection.getConnectionErrorMessage());
         }
     }
+    async listSessions() {
+        this.sessions = await this.connection.listSessions(this.timeoutMs);
+        return {
+            ok: true,
+            command: 'sessions',
+            profile: this.profile,
+            mode: this.mode(),
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            sessions: this.sessions,
+        };
+    }
     async status() {
+        this.sessions = await this.connection.listSessions(STATUS_TOOLS_TIMEOUT_MS).catch(() => this.connection.getSessions());
         if (this.connection.isExtensionConnected()) {
-            await this.ensureToolsLoaded();
+            // Use a short timeout for status — this is a diagnostic command that
+            // should return quickly.  Fall back to cached tools if the extension
+            // is slow to respond.
+            await this.ensureToolsLoaded(STATUS_TOOLS_TIMEOUT_MS);
         }
         return {
             ok: true,
             command: 'status',
             profile: this.profile,
             mode: this.remoteUuid ? 'remote' : 'local',
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            sessions: this.sessions,
             ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
             relayConnected: this.connection.getStatus() === 'connected',
             extensionConnected: this.connection.isExtensionConnected(),
@@ -442,6 +394,8 @@ class BrowserCliContext {
             command: 'tabs',
             profile: this.profile,
             mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
             ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
             tool: invocation.tool,
             pages,
@@ -452,72 +406,74 @@ class BrowserCliContext {
         if (!url) {
             return this.callGenericCommand('open', [{ names: ['new_page', 'create_new_tab'] }], {});
         }
-        const invocation = await this.callTool('open', [
-            {
-                names: ['new_page', 'create_new_tab'],
-                buildArgs: (tool) => withUrlArgs(tool, url),
-            },
-            {
-                names: ['navigate_page', 'navigate_to_url'],
-                buildArgs: (tool) => withNavigateArgs(tool, url),
-            },
-        ], {});
-        return this.outputFromInvocation('open', invocation);
+        try {
+            const invocation = await this.callTool('open', [
+                {
+                    names: ['new_page', 'create_new_tab'],
+                    buildArgs: (tool) => withOpenArgs(tool, url),
+                },
+                {
+                    names: ['navigate_page', 'navigate_to_url'],
+                    buildArgs: (tool) => withNavigateArgs(tool, url, this.timeoutMs),
+                },
+            ], {});
+            const output = this.outputFromInvocation('open', invocation);
+            return this.ensurePageContentInOutput('open', invocation, output, url);
+        }
+        catch (error) {
+            const recovered = await this.recoverPageContentAfterTimeout('open', url, error);
+            if (recovered) {
+                return recovered;
+            }
+            throw error;
+        }
     }
     async navigate(url) {
-        const invocation = await this.callTool('navigate', [
-            {
-                names: ['navigate_page', 'navigate_to_url'],
-                buildArgs: (tool) => withNavigateArgs(tool, url),
-            },
+        try {
+            const invocation = await this.callTool('navigate', [
+                {
+                    names: ['navigate_page', 'navigate_to_url'],
+                    buildArgs: (tool) => withNavigateArgs(tool, url, this.timeoutMs),
+                },
+                {
+                    names: ['new_page', 'create_new_tab'],
+                    buildArgs: (tool) => withOpenArgs(tool, url),
+                },
+            ], {});
+            const output = this.outputFromInvocation('navigate', invocation);
+            return this.ensurePageContentInOutput('navigate', invocation, output, url);
+        }
+        catch (error) {
+            const recovered = await this.recoverPageContentAfterTimeout('navigate', url, error);
+            if (recovered) {
+                return recovered;
+            }
+            throw error;
+        }
+    }
+    async close(id) {
+        const invocation = await this.callTool('close', [
             {
-                names: ['new_page', 'create_new_tab'],
-                buildArgs: (tool) => withUrlArgs(tool, url),
+                names: ['close_page', 'close_tab'],
+                buildArgs: (tool) => withPageArgs(tool, id),
             },
         ], {});
-        return this.outputFromInvocation('navigate', invocation);
+        return this.outputFromInvocation('close', invocation);
     }
     async focus(id) {
         const invocation = await this.callTool('focus', [
             {
-                names: ['select_page', 'switch_to_tab', 'focus_tab'],
+                names: ['switch_to_page', 'switch_to_tab', 'select_page', 'focus_tab'],
                 buildArgs: (tool) => withPageArgs(tool, id),
             },
         ], {});
         return this.outputFromInvocation('focus', invocation);
     }
-    async close(id) {
-        const invocation = await this.callTool('close', [
-            {
-                names: ['close_page', 'close_tab'],
-                buildArgs: (tool) => withPageArgs(tool, id),
-            },
-        ], {});
-        return this.outputFromInvocation('close', invocation);
-    }
     async snapshot(options) {
         const wantsAria = options.format === 'aria' || options.interactive || Boolean(options.selector) || Boolean(options.frame);
-        if (!wantsAria) {
-            const result = await this.connection.getSnapshot();
-            return {
-                ok: true,
-                command: 'snapshot',
-                profile: this.profile,
-                mode: this.mode(),
-                ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
-                format: options.format,
-                url: result.url,
-                title: result.title,
-                snapshot: limitText(result.snapshot, options.limit),
-            };
-        }
         const invocation = await this.callTool('snapshot', [
             {
-                names: ['take_a11y_snapshot'],
-                buildArgs: (tool) => withSnapshotArgs(tool, options),
-            },
-            {
-                names: ['take_snapshot', 'get_page_content'],
+                names: [wantsAria ? 'take_a11y_snapshot' : 'take_md_snapshot'],
                 buildArgs: (tool) => withSnapshotArgs(tool, options),
             },
         ], {});
@@ -553,38 +509,6 @@ class BrowserCliContext {
             raw: normalizeToolResult(invocation.result),
         };
     }
-    async pdf(outputPath) {
-        const invocation = await this.callTool('pdf', [{ names: ['pdf', 'generate_pdf'] }], {});
-        const savedPath = maybeWriteBinaryOutput(invocation.result, outputPath);
-        return {
-            ok: true,
-            command: 'pdf',
-            profile: this.profile,
-            mode: this.mode(),
-            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
-            tool: invocation.tool,
-            outputPath: savedPath || outputPath,
-            raw: normalizeToolResult(invocation.result),
-        };
-    }
-    async consoleMessages(options) {
-        const invocation = await this.callTool('console', [
-            {
-                names: ['list_console_messages'],
-                buildArgs: (tool) => withConsoleArgs(tool, options),
-            },
-        ], {});
-        return {
-            ok: true,
-            command: options.level === 'error' ? 'errors' : 'console',
-            profile: this.profile,
-            mode: this.mode(),
-            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
-            tool: invocation.tool,
-            messages: extractMessages(invocation.result),
-            raw: normalizeToolResult(invocation.result),
-        };
-    }
     async requests(options) {
         const invocation = await this.callTool('requests', [
             {
@@ -638,15 +562,6 @@ class BrowserCliContext {
             raw: normalizeToolResult(invocation.result),
         };
     }
-    async resize(width, height) {
-        const invocation = await this.callTool('resize', [
-            {
-                names: ['resize_page'],
-                buildArgs: (tool) => withResizeArgs(tool, width, height),
-            },
-        ], {});
-        return this.outputFromInvocation('resize', invocation);
-    }
     async click(ref, options) {
         const invocation = await this.callTool('click', [
             {
@@ -687,15 +602,6 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('hover', invocation);
     }
-    async scrollIntoView(ref) {
-        const invocation = await this.callTool('scrollintoview', [
-            {
-                names: ['scroll_into_view', 'scrollintoview'],
-                buildArgs: (tool) => withRefArgs(tool, ref),
-            },
-        ], {});
-        return this.outputFromInvocation('scrollintoview', invocation);
-    }
     async drag(source, target) {
         const invocation = await this.callTool('drag', [
             {
@@ -718,37 +624,6 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('select', invocation);
     }
-    async download(ref, filename) {
-        const invocation = await this.callTool('download', [
-            {
-                names: ['download'],
-                buildArgs: (tool) => withDownloadArgs(tool, ref, filename),
-            },
-            {
-                names: ['click'],
-                buildArgs: (tool) => withRefArgs(tool, ref),
-            },
-        ], {});
-        return this.outputFromInvocation('download', invocation);
-    }
-    async waitForDownload(filename) {
-        const invocation = await this.callTool('waitfordownload', [
-            {
-                names: ['wait_for_download', 'waitfordownload'],
-                buildArgs: (tool) => withFilenameArgs(tool, filename),
-            },
-        ], {});
-        return this.outputFromInvocation('waitfordownload', invocation);
-    }
-    async upload(path, ref) {
-        const invocation = await this.callTool('upload', [
-            {
-                names: ['upload_file'],
-                buildArgs: (tool) => withUploadArgs(tool, path, ref),
-            },
-        ], {});
-        return this.outputFromInvocation('upload', invocation);
-    }
     async fillForm(fieldsJson) {
         const fields = parseJsonValue(fieldsJson, '--fields');
         if (!Array.isArray(fields)) {
@@ -762,16 +637,6 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('fill', invocation);
     }
-    async dialog(options) {
-        const action = options.accept ? 'accept' : options.dismiss ? 'dismiss' : 'accept';
-        const invocation = await this.callTool('dialog', [
-            {
-                names: ['handle_dialog'],
-                buildArgs: (tool) => withDialogArgs(tool, action, options.prompt),
-            },
-        ], {});
-        return this.outputFromInvocation('dialog', invocation);
-    }
     async wait(options) {
         if (options.text && options.text.length > 0) {
             const invocation = await this.callTool('wait', [
@@ -804,37 +669,6 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('evaluate', invocation);
     }
-    async highlight(ref) {
-        const invocation = await this.callTool('highlight', [
-            {
-                names: ['highlight'],
-                buildArgs: (tool) => withRefArgs(tool, ref),
-            },
-            {
-                names: ['hover'],
-                buildArgs: (tool) => withRefArgs(tool, ref, { duration: 1500 }),
-            },
-        ], {});
-        return this.outputFromInvocation('highlight', invocation);
-    }
-    async traceStart(options) {
-        const invocation = await this.callTool('trace start', [
-            {
-                names: ['performance_start_trace'],
-                buildArgs: (tool) => withTraceStartArgs(tool, options),
-            },
-        ], {});
-        return this.outputFromInvocation('trace start', invocation);
-    }
-    async traceStop(outputPath) {
-        const invocation = await this.callTool('trace stop', [
-            {
-                names: ['performance_stop_trace'],
-                buildArgs: (tool) => withTraceStopArgs(tool, outputPath),
-            },
-        ], {});
-        return this.outputFromInvocation('trace stop', invocation);
-    }
     async callGenericCommand(commandName, candidates, canonicalArgs) {
         const invocation = await this.callTool(commandName, candidates, canonicalArgs);
         return this.outputFromInvocation(commandName, invocation);
@@ -851,23 +685,44 @@ class BrowserCliContext {
                 const args = candidate.buildArgs
                     ? candidate.buildArgs(tool)
                     : withCanonicalArgs(tool, canonicalArgs);
-                const result = await this.connection.callTool(tool.name, args);
+                // Inject --page-id into every tool call that accepts pageId/tabId,
+                // so the agent doesn't need to use focus/tab select (which disrupts
+                // the user's active browser tab).
+                if (this.pageId !== undefined) {
+                    const pageKey = hasProperty(tool, 'pageId', 'tabId');
+                    if (pageKey && !(pageKey in args)) {
+                        args[pageKey] = this.pageId;
+                    }
+                }
+                if (shouldRequestPageStateForCommand(commandName)) {
+                    const pageStateKey = hasProperty(tool, 'pageStateFormat', 'page_state_format');
+                    if (pageStateKey && !('pageStateFormat' in args) && !('page_state_format' in args)) {
+                        args[pageStateKey] = 'markdown';
+                    }
+                }
+                const result = await this.connection.callTool(tool.name, args, this.timeoutMs);
                 return { tool: tool.name, args, result: result };
             }
         }
         const requested = candidates.flatMap((candidate) => candidate.names);
         throw new Error(`No compatible browser tool found for "${commandName}". Tried ${requested.join(', ')}. Available tools: ${this.tools.map((tool) => tool.name).join(', ')}`);
     }
-    async ensureToolsLoaded() {
+    async ensureToolsLoaded(timeoutMs) {
         if (this.toolsLoaded && this.tools.length > 0) {
             return;
         }
+        const effectiveTimeout = timeoutMs ?? this.timeoutMs;
         if (this.connection.isExtensionConnected()) {
             try {
-                this.tools = await this.connection.refreshTools(this.timeoutMs);
+                this.tools = await this.connection.refreshTools(effectiveTimeout);
             }
             catch {
-                this.tools = await this.connection.waitForToolsUpdate(1_000);
+                // Refresh timed out or failed — fall back to cached tools or a short
+                // passive wait so the status command is not blocked.
+                this.tools = this.connection.getTools();
+                if (this.tools.length === 0) {
+                    this.tools = await this.connection.waitForToolsUpdate(1_000);
+                }
             }
         }
         else {
@@ -876,19 +731,308 @@ class BrowserCliContext {
         this.toolsLoaded = true;
     }
     outputFromInvocation(commandName, invocation) {
+        const pageContent = firstText(invocation.result);
         return {
             ok: !invocation.result.isError,
             command: commandName,
             profile: this.profile,
             mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
             ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
             tool: invocation.tool,
+            ...(looksLikePageContentText(pageContent) ? { pageContent } : {}),
             raw: normalizeToolResult(invocation.result),
         };
     }
+    async ensurePageContentInOutput(commandName, invocation, output, targetUrl) {
+        if (!output.ok) {
+            return output;
+        }
+        const currentText = firstText(invocation.result);
+        if (looksLikePageContentText(currentText) && !isLikelyIncompletePageContent(currentText, targetUrl)) {
+            return output;
+        }
+        const targetPageId = extractPageIdFromResult(invocation.result) ?? this.pageId;
+        if (targetPageId === undefined) {
+            return output;
+        }
+        const fallback = await this.takeMarkdownSnapshotForTarget(targetPageId, targetUrl);
+        if (!fallback.content) {
+            return output;
+        }
+        return {
+            ...output,
+            pageContent: fallback.content,
+            pageContentSource: 'take_md_snapshot',
+            ...(fallback.pageId !== targetPageId ? { pageId: fallback.pageId } : {}),
+        };
+    }
+    async recoverPageContentAfterTimeout(commandName, url, error) {
+        if (!isTimeoutError(error)) {
+            return undefined;
+        }
+        const recoveryTimeoutMs = Math.max(this.timeoutMs, 10_000);
+        let targetPageId = this.pageId;
+        if (targetPageId === undefined) {
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                const pages = await this.listPagesForRecovery(recoveryTimeoutMs);
+                const matched = findBestPageMatchByUrl(pages, url);
+                if (matched) {
+                    targetPageId = matched.id;
+                    break;
+                }
+                await delay(750);
+            }
+        }
+        if (targetPageId === undefined) {
+            return undefined;
+        }
+        const fallback = await this.takeMarkdownSnapshotForTarget(targetPageId, url, recoveryTimeoutMs);
+        if (!fallback.content) {
+            return undefined;
+        }
+        return {
+            ok: true,
+            command: commandName,
+            profile: this.profile,
+            mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            tool: 'take_md_snapshot',
+            recoveredFromTimeout: true,
+            pageId: fallback.pageId,
+            url,
+            pageContent: fallback.content,
+            raw: {
+                recovery: 'timeout_fallback',
+            },
+        };
+    }
+    async takeMarkdownSnapshotForTarget(initialPageId, targetUrl, timeoutMs = this.timeoutMs) {
+        let latest;
+        let pageId = initialPageId;
+        const recoveryTimeoutMs = Math.max(timeoutMs, 10_000);
+        const attempts = 8;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            latest = await this.takeMarkdownSnapshotForPage(pageId, recoveryTimeoutMs);
+            if (latest && !isLikelyIncompletePageContent(latest, targetUrl)) {
+                return { content: latest, pageId };
+            }
+            if (targetUrl) {
+                const pages = await this.listPagesForRecovery(recoveryTimeoutMs);
+                const matched = findBestPageMatchByUrl(pages, targetUrl);
+                if (matched) {
+                    pageId = matched.id;
+                }
+            }
+            if (attempt < attempts - 1) {
+                await delay(750);
+            }
+        }
+        return { content: latest, pageId };
+    }
+    async listPagesForRecovery(timeoutMs) {
+        try {
+            await this.ensureToolsLoaded(timeoutMs);
+            const listTool = this.tools.find((tool) => {
+                const normalized = normalizeName(tool.name);
+                return normalized === 'list_pages' || normalized === 'get_tabs';
+            });
+            if (!listTool) {
+                return [];
+            }
+            const result = await this.connection.callTool(listTool.name, {}, timeoutMs);
+            return extractPages(result);
+        }
+        catch {
+            return [];
+        }
+    }
+    async takeMarkdownSnapshotForPage(pageId, timeoutMs = this.timeoutMs) {
+        await this.ensureToolsLoaded();
+        const snapshotTool = this.tools.find((tool) => normalizeName(tool.name) === 'take_md_snapshot');
+        if (!snapshotTool) {
+            return undefined;
+        }
+        const args = {};
+        const pageKey = hasProperty(snapshotTool, 'pageId', 'tabId');
+        if (pageKey) {
+            args[pageKey] = pageId;
+        }
+        const pageStateKey = hasProperty(snapshotTool, 'pageStateFormat', 'page_state_format');
+        if (pageStateKey) {
+            args[pageStateKey] = 'markdown';
+        }
+        try {
+            const result = await this.connection.callTool(snapshotTool.name, args, timeoutMs);
+            const text = firstText(result);
+            if (!text) {
+                return undefined;
+            }
+            const trimmed = text.trim();
+            if (/^Error:/i.test(trimmed) || /Failed to get valid tab/i.test(trimmed)) {
+                return undefined;
+            }
+            return text;
+        }
+        catch {
+            return undefined;
+        }
+    }
     mode() {
         return this.remoteUuid ? 'remote' : 'local';
     }
+    currentSessionId() {
+        if (this.remoteUuid) {
+            return this.remoteUuid;
+        }
+        const connectedSessionIds = new Set(this.sessions
+            .filter((session) => session.connected)
+            .map((session) => session.sessionId));
+        if (this.requestedSessionId && connectedSessionIds.has(this.requestedSessionId)) {
+            return this.requestedSessionId;
+        }
+        return this.sessions.find((session) => session.connected)?.sessionId;
+    }
+}
+function shouldRequestPageStateForCommand(commandName) {
+    return new Set([
+        'open',
+        'navigate',
+        'click',
+        'type',
+        'press',
+        'hover',
+        'drag',
+        'select',
+        'fill',
+    ]).has(commandName);
+}
+function looksLikePageContentText(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (/Error retrieving page content/i.test(trimmed) || /page content extraction failed/i.test(trimmed)) {
+        return false;
+    }
+    return /```(?:markdown|text|html)/i.test(trimmed) || /Page State Format:/i.test(trimmed);
+}
+function isLikelyIncompletePageContent(text, targetUrl) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return true;
+    }
+    const interactiveRefCount = (trimmed.match(/\[M\d+:/g) || []).length;
+    // Common in early snapshots right after new_page(waitForReady=false):
+    // tab exists but title/url are still empty.
+    if (/Tab ID:[^\n]*\nTitle:\s*\nURL:\s*(?:\n|$)/i.test(trimmed)) {
+        return true;
+    }
+    if (/#\s*Markdown Snapshot:\s*Untitled/i.test(trimmed) && interactiveRefCount < 5) {
+        return true;
+    }
+    if (targetUrl) {
+        const normalizedTarget = normalizeUrlForMatch(targetUrl);
+        const hasAnyUrl = /\bURL:\s*\S+/i.test(trimmed);
+        const textNormalized = normalizeUrlForMatch(trimmed);
+        if (!hasAnyUrl) {
+            return true;
+        }
+        if (normalizedTarget && !textNormalized.includes(normalizedTarget)) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractPageIdFromResult(result) {
+    const direct = firstDefined(result, ['pageId', 'tabId', 'id']);
+    if (typeof direct === 'number' && Number.isFinite(direct)) {
+        return direct;
+    }
+    const parsed = parseResultText(result);
+    if (parsed && typeof parsed === 'object') {
+        const parsedId = firstDefined(parsed, ['pageId', 'tabId', 'id']);
+        if (typeof parsedId === 'number' && Number.isFinite(parsedId)) {
+            return parsedId;
+        }
+    }
+    const text = firstText(result);
+    const createdMatch = /new background page \(ID:\s*(\d+)\)/i.exec(text);
+    if (createdMatch) {
+        return Number.parseInt(createdMatch[1], 10);
+    }
+    const tabMatch = /\bTab ID:\s*(\d+)\b/i.exec(text);
+    if (tabMatch) {
+        return Number.parseInt(tabMatch[1], 10);
+    }
+    const pageMatch = /\bPage ID:\s*(\d+)\b/i.exec(text);
+    if (pageMatch) {
+        return Number.parseInt(pageMatch[1], 10);
+    }
+    return undefined;
+}
+function isTimeoutError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /timed out|timeout/i.test(message);
+}
+function findBestPageMatchByUrl(pages, targetUrl) {
+    const normalizedTarget = normalizeUrlForMatch(targetUrl);
+    let bestExact;
+    let bestPartial;
+    for (const page of pages) {
+        const id = toFinitePageId(page.id);
+        if (id === undefined || typeof page.url !== 'string') {
+            continue;
+        }
+        const normalizedPage = normalizeUrlForMatch(page.url);
+        if (normalizedPage === normalizedTarget) {
+            if (!bestExact || id > bestExact.id) {
+                bestExact = { id, url: page.url };
+            }
+        }
+        if (normalizedPage.includes(normalizedTarget) || normalizedTarget.includes(normalizedPage)) {
+            if (!bestPartial || id > bestPartial.id) {
+                bestPartial = { id, url: page.url };
+            }
+        }
+    }
+    return bestExact ?? bestPartial;
+}
+function toFinitePageId(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizeUrlForMatch(value) {
+    const trimmed = value.trim().replace(/\/$/, '');
+    if (!trimmed) {
+        return trimmed;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        return safeDecode(`${parsed.origin}${parsed.pathname}${parsed.search}`.replace(/\/$/, ''));
+    }
+    catch {
+        return safeDecode(trimmed);
+    }
+}
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
 }
 function emitOutput(asJson, data, humanOutput) {
     if (asJson) {
@@ -898,7 +1042,11 @@ function emitOutput(asJson, data, humanOutput) {
     console.log(humanOutput);
 }
 function emitError(asJson, commandName, ctx, error) {
-    const message = error instanceof Error ? error.message : String(error);
+    let message = error instanceof Error ? error.message : String(error);
+    // Improve guidance when the extension requires a pageId that wasn't provided
+    if (/\bpageId\b/i.test(message) && /\bmissing\b|\brequired\b/i.test(message)) {
+        message += '\nHint: use `tabs` to list pages, then pass --page-id <id> to target a specific tab.';
+    }
     if (asJson) {
         console.log(JSON.stringify({
             ok: false,
@@ -919,19 +1067,36 @@ function formatHumanOutput(commandName, output) {
             return [
                 `Profile: ${String(output.profile)}`,
                 `Mode: ${String(output.mode)}`,
+                output.sessionId ? `Session: ${String(output.sessionId)}` : null,
+                output.requestedSessionId && output.requestedSessionId !== output.sessionId ? `Requested session: ${String(output.requestedSessionId)}` : null,
                 `Relay connected: ${boolText(output.relayConnected)}`,
                 `Extension connected: ${boolText(output.extensionConnected)}`,
                 `Managed lifecycle: ${boolText(output.managedLifecycle)}`,
                 output.toolCount !== undefined ? `Tools: ${String(output.toolCount)}` : null,
                 output.note ? String(output.note) : null,
             ].filter(Boolean).join('\n');
+        case 'sessions': {
+            const sessions = Array.isArray(output.sessions) ? output.sessions : [];
+            if (sessions.length === 0) {
+                return 'No browser sessions connected';
+            }
+            return sessions.map((session, index) => {
+                const selected = output.sessionId === session.sessionId ? ' [selected]' : '';
+                const connected = session.connected ? 'connected' : 'disconnected';
+                const tools = session.toolCount !== undefined ? ` tools=${session.toolCount}` : '';
+                return `${index + 1}. ${session.sessionId}${selected} - ${connected}${tools}`;
+            }).join('\n');
+        }
         case 'tabs':
         case 'tab': {
             const pages = Array.isArray(output.pages) ? output.pages : [];
             if (pages.length === 0) {
                 return firstDefinedText(output.raw, 'No tabs reported by browser');
             }
-            return pages.map((page, index) => `${index + 1}. ${page.active ? '[active] ' : ''}${page.title || '(untitled)'}${page.url ? ` — ${page.url}` : ''}${page.id !== undefined ? ` [id=${page.id}]` : ''}`).join('\n');
+            return [
+                output.sessionId ? `Session: ${String(output.sessionId)}` : null,
+                ...pages.map((page, index) => `${index + 1}. ${page.active ? '[active] ' : ''}${page.title || '(untitled)'}${page.url ? ` — ${page.url}` : ''}${page.id !== undefined ? ` [id=${page.id}]` : ''}`),
+            ].filter(Boolean).join('\n');
         }
         case 'snapshot':
             return [
@@ -946,14 +1111,6 @@ function formatHumanOutput(commandName, output) {
             }
             return requests.map((request, index) => `${index + 1}. ${request.method || 'GET'} ${request.url || '(unknown)'}${request.status !== undefined ? ` [${request.status}]` : ''}${request.requestId ? ` [id=${request.requestId}]` : ''}`).join('\n');
         }
-        case 'console':
-        case 'errors': {
-            const messages = Array.isArray(output.messages) ? output.messages : [];
-            if (messages.length > 0) {
-                return messages.map((message) => stringifyJson(message)).join('\n');
-            }
-            return firstDefinedText(output.raw, 'No console messages reported by browser');
-        }
         case 'responsebody':
             return String(output.responseBody ?? firstDefinedText(output.raw, ''));
         default:
@@ -970,8 +1127,19 @@ function firstDefinedText(value, fallback) {
     if (typeof value === 'string' && value.length > 0) {
         return value;
     }
-    if (value && typeof value === 'object' && 'text' in value && typeof value.text === 'string') {
-        return value.text;
+    if (value && typeof value === 'object') {
+        // Direct { text: "..." } wrapper
+        if ('text' in value && typeof value.text === 'string') {
+            return value.text;
+        }
+        // MCP tool result: { content: [{ type: 'text', text: '...' }] }
+        const rec = value;
+        if (Array.isArray(rec.content)) {
+            const textItem = rec.content.find((entry) => entry && typeof entry === 'object' && entry.type === 'text');
+            if (textItem && typeof textItem.text === 'string' && textItem.text.length > 0) {
+                return textItem.text;
+            }
+        }
     }
     return fallback;
 }
@@ -1026,8 +1194,34 @@ function extractPages(result) {
             }
         }
     }
+    // Fallback: parse the plain-text format produced by ListPagesTool
+    // e.g. 'Page 123 [ACTIVE]: "Google" - https://www.google.com'
+    const text = firstText(result);
+    if (text) {
+        const textPages = parsePlainTextPages(text);
+        if (textPages.length > 0) {
+            return textPages;
+        }
+    }
     return [];
 }
+// Matches ListPagesTool output: 'Page <id>[ [ACTIVE]]: "title" - url'
+const PAGE_LINE_RE = /^Page\s+(\d+)\s*(\[ACTIVE\])?\s*:\s*"(.*)"\s*-\s*(.+)$/i;
+function parsePlainTextPages(text) {
+    const pages = [];
+    for (const line of text.split('\n')) {
+        const match = PAGE_LINE_RE.exec(line.trim());
+        if (match) {
+            pages.push({
+                id: Number(match[1]),
+                active: match[2] !== undefined,
+                title: match[3],
+                url: match[4].trim(),
+            });
+        }
+    }
+    return pages;
+}
 function normalizePage(value) {
     if (!value || typeof value !== 'object') {
         return {};
@@ -1071,26 +1265,6 @@ function normalizeRequest(value) {
         status: firstNumber(record, ['status']),
     };
 }
-function extractMessages(result) {
-    const direct = extractStructured(result, ['messages', 'consoleMessages']);
-    if (Array.isArray(direct)) {
-        return direct.map((entry) => sanitizeUnknown(entry) ?? null);
-    }
-    const parsed = parseResultText(result);
-    if (Array.isArray(parsed)) {
-        return parsed.map((entry) => sanitizeUnknown(entry) ?? null);
-    }
-    if (parsed && typeof parsed === 'object') {
-        for (const key of ['messages', 'consoleMessages']) {
-            const candidate = parsed[key];
-            if (Array.isArray(candidate)) {
-                return candidate.map((entry) => sanitizeUnknown(entry) ?? null);
-            }
-        }
-    }
-    const text = firstText(result);
-    return text ? [text] : [];
-}
 function extractResponseBody(result) {
     const direct = extractStructured(result, ['responseBody', 'body']);
     if (typeof direct === 'string') {
@@ -1218,12 +1392,24 @@ function withUrlArgs(tool, url) {
     }
     return args;
 }
-function withNavigateArgs(tool, url) {
+function withOpenArgs(tool, url) {
+    const args = withUrlArgs(tool, url);
+    const waitForReadyKey = hasProperty(tool, 'waitForReady');
+    if (waitForReadyKey) {
+        args[waitForReadyKey] = false;
+    }
+    return stripUndefined(args);
+}
+function withNavigateArgs(tool, url, timeoutMs) {
     const args = withUrlArgs(tool, url);
     const pageIdKey = hasProperty(tool, 'pageId', 'tabId');
     if (pageIdKey && !(pageIdKey in args)) {
         args[pageIdKey] = undefined;
     }
+    const timeoutKey = hasProperty(tool, 'timeoutMs', 'timeout');
+    if (timeoutKey && typeof timeoutMs === 'number' && Number.isFinite(timeoutMs)) {
+        args[timeoutKey] = timeoutMs;
+    }
     return stripUndefined(args);
 }
 function withPageArgs(tool, id) {
@@ -1258,21 +1444,6 @@ function withScreenshotArgs(tool, options) {
     maybeAssign(args, tool, 'grayscale', options.grayscale || undefined);
     return args;
 }
-function withConsoleArgs(tool, options) {
-    const args = {};
-    if (options.level) {
-        if (hasProperty(tool, 'types')) {
-            args.types = [options.level];
-        }
-        else {
-            maybeAssign(args, tool, 'level', options.level);
-        }
-    }
-    if (options.preserve) {
-        maybeAssign(args, tool, 'includePreservedMessages', true);
-    }
-    return args;
-}
 function withRequestListArgs(tool, options) {
     const args = {};
     if (options.limit) {
@@ -1287,12 +1458,6 @@ function withRequestDetailsArgs(tool, requestId) {
     maybeAssign(args, tool, 'reqid', requestId);
     return args;
 }
-function withResizeArgs(tool, width, height) {
-    const args = {};
-    maybeAssign(args, tool, 'width', width);
-    maybeAssign(args, tool, 'height', height);
-    return args;
-}
 function withRefArgs(tool, ref, extra = {}) {
     const args = { ...extra };
     const parsedRef = parseRef(ref);
@@ -1358,38 +1523,12 @@ function withSelectArgs(tool, ref, values) {
     maybeAssign(args, tool, 'values', values);
     return args;
 }
-function withDownloadArgs(tool, ref, filename) {
-    const args = withRefArgs(tool, ref);
-    maybeAssign(args, tool, 'filename', filename);
-    maybeAssign(args, tool, 'path', filename);
-    return args;
-}
-function withFilenameArgs(tool, filename) {
-    const args = {};
-    maybeAssign(args, tool, 'filename', filename);
-    maybeAssign(args, tool, 'path', filename);
-    return args;
-}
-function withUploadArgs(tool, path, ref) {
-    const args = {};
-    maybeAssign(args, tool, 'filePath', resolve(path));
-    if (ref) {
-        Object.assign(args, withRefArgs(tool, ref));
-    }
-    return args;
-}
 function withFillFormArgs(tool, fields) {
     const args = {};
     maybeAssign(args, tool, 'fields', fields);
     maybeAssign(args, tool, 'elements', fields);
     return args;
 }
-function withDialogArgs(tool, action, prompt) {
-    const args = {};
-    maybeAssign(args, tool, 'action', action);
-    maybeAssign(args, tool, 'promptText', prompt);
-    return args;
-}
 function withWaitArgs(tool, text, timeoutMs) {
     const args = {};
     maybeAssign(args, tool, 'text', text);
@@ -1417,21 +1556,6 @@ function withEvaluateArgs(tool, fn, ref, argsJson) {
     }
     return args;
 }
-function withTraceStartArgs(tool, options) {
-    const args = {};
-    maybeAssign(args, tool, 'reload', options.reload || undefined);
-    if (options.outputPath) {
-        maybeAssign(args, tool, 'filePath', resolve(options.outputPath));
-    }
-    return args;
-}
-function withTraceStopArgs(tool, outputPath) {
-    const args = {};
-    if (outputPath) {
-        maybeAssign(args, tool, 'filePath', resolve(outputPath));
-    }
-    return args;
-}
 function maybeAssign(target, tool, property, value) {
     if (value === undefined) {
         return;