@vibebrowser/mcp 0.2.5 → 0.2.7

package/dist/browser-cli.js

@@ -1,11 +1,31 @@
-import { writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { ExtensionConnection } from './connection.js';
+import { DevtoolsFallbackConnection } from './devtools-fallback.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 MIME_TYPE_BY_EXTENSION = {
+    '.css': 'text/css',
+    '.csv': 'text/csv',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp',
+    '.xml': 'application/xml',
+};
 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_UUID = process.env.VIBE_REMOTE_URL || 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;
 export function registerBrowserCommand(program) {
     const browser = buildBrowserCommand(program.command('browser'));
@@ -22,17 +42,32 @@ function buildBrowserCommand(command) {
         .option('--target <target>', 'OpenClaw compatibility target selector (accepted, not used by the Vibe browser CLI)')
         .option('-p, --port <number>', 'WebSocket port for local relay (agent) connection', String(DEFAULT_WS_PORT))
         .option('-d, --debug', 'Enable debug logging', false)
+        .option('--devtools', 'Use only chrome-devtools backend (bypasses extension relay)', 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
         .command('status')
         .description('Show browser bridge status')
+        .option('--wait-for-extension', 'Wait for extension connection before returning status', false)
+        .option('--wait-timeout <ms>', 'Maximum wait time when --wait-for-extension is enabled')
+        .option('--poll-interval <ms>', 'Polling interval while waiting for extension')
         .action(async function () {
-        await runBrowserCommand(this, 'status', false, async (ctx) => ctx.status());
+        await runBrowserCommand(this, 'status', false, async (ctx, options) => ctx.status({
+            waitForExtension: Boolean(options.waitForExtension),
+            waitTimeoutMs: options.waitTimeout
+                ? parsePositiveInteger(String(options.waitTimeout), '--wait-timeout')
+                : undefined,
+            pollIntervalMs: options.pollInterval
+                ? parsePositiveInteger(String(options.pollInterval), '--poll-interval')
+                : undefined,
+        }));
     });
     browser
         .command('start')
@@ -61,6 +96,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 +121,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 +145,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));
     });
@@ -117,7 +158,7 @@ function registerBrowserSubcommands(browser) {
     browser
         .command('snapshot')
         .description('Capture a textual browser snapshot')
-        .option('--format <format>', 'Snapshot format (ai or aria)', 'ai')
+        .option('--format <format>', 'Snapshot format: "ai" (default, content-script markdown — may fail on background tabs or complex SPAs) or "aria" (CDP accessibility tree — reliable for all tabs)', 'ai')
         .option('--limit <count>', 'Max visible lines/items to print in human mode')
         .option('--interactive', 'Prefer interactive/ARIA-flavored snapshot output', false)
         .option('--selector <selector>', 'Selector to scope the snapshot to')
@@ -156,31 +197,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')
@@ -207,9 +224,9 @@ function registerBrowserSubcommands(browser) {
     });
     browser
         .command('resize <width> <height>')
-        .description('Resize the browser viewport')
+        .description('Resize the current page viewport/window')
         .action(async function (width, height) {
-        await runBrowserCommand(this, 'resize', true, async (ctx) => ctx.resize(parsePositiveInteger(width, 'width'), parsePositiveInteger(height, 'height')));
+        await runBrowserCommand(this, 'resize', true, async (ctx) => ctx.resize(parsePositiveInteger(width, '<width>'), parsePositiveInteger(height, '<height>')));
     });
     browser
         .command('click <ref>')
@@ -238,11 +255,12 @@ function registerBrowserSubcommands(browser) {
         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));
+        .command('upload <ref> <path>')
+        .description('Upload a local file via an input element reference')
+        .action(async function (ref, path) {
+        await runBrowserCommand(this, 'upload', true, async (ctx) => ctx.upload(ref, path));
     });
+    // NOTE: scrollintoview, download, waitfordownload commands removed — no matching tools.
     browser
         .command('drag <source> <target>')
         .description('Drag one element to another')
@@ -255,25 +273,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')
@@ -283,15 +282,15 @@ function registerBrowserSubcommands(browser) {
     });
     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')
+        .description('Handle browser dialog (accept/dismiss prompt/confirm/alert)')
+        .option('--accept', 'Accept dialog', false)
+        .option('--dismiss', 'Dismiss dialog', false)
+        .option('--prompt <text>', 'Optional prompt text when accepting')
         .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,
+            promptText: options.prompt ? String(options.prompt) : undefined,
         }));
     });
     browser
@@ -320,31 +319,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();
@@ -352,12 +328,15 @@ async function runBrowserCommand(command, commandName, requireExtension, handler
     const ctx = new BrowserCliContext({
         port: parsePositiveInteger(globalOptions.port, '--port'),
         debug: Boolean(globalOptions.debug),
+        devtools: Boolean(globalOptions.devtools),
         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();
@@ -380,18 +359,27 @@ class BrowserCliContext {
     profile;
     json;
     timeoutMs;
+    devtoolsOnly;
     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.devtoolsOnly = init.devtools;
+        this.connection = init.devtools
+            ? new DevtoolsFallbackConnection(init.debug)
+            : 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}`);
@@ -399,37 +387,104 @@ class BrowserCliContext {
     }
     async connect() {
         await this.connection.start();
-        await delay(100);
-        await this.connection.waitForToolsUpdate(500);
+        if (this.connection instanceof ExtensionConnection) {
+            const extension = this.connection;
+            await delay(100);
+            this.sessions = await extension.listSessions(1_500).catch(() => extension.getSessions());
+            await extension.waitForToolsUpdate(500);
+        }
     }
     async shutdown() {
         await this.connection.stop();
     }
     async ensureExtensionConnected() {
-        if (this.connection.isExtensionConnected()) {
+        if (this.isBackendConnected()) {
             return;
         }
+        if (this.connection instanceof ExtensionConnection) {
+            const extension = this.connection;
+            this.sessions = await extension.listSessions(1_500).catch(() => extension.getSessions());
+        }
+        this.toolsLoaded = false;
         await this.ensureToolsLoaded();
-        if (!this.connection.isExtensionConnected()) {
-            throw new Error('No browser extension is connected to the Vibe relay');
+        if (!this.isBackendConnected() && this.tools.length === 0) {
+            throw new Error(this.getConnectionErrorMessage());
         }
     }
-    async status() {
-        if (this.connection.isExtensionConnected()) {
-            await this.ensureToolsLoaded();
+    async listSessions() {
+        if (this.connection instanceof ExtensionConnection) {
+            this.sessions = await this.connection.listSessions(this.timeoutMs);
+        }
+        else {
+            this.sessions = [];
+        }
+        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(options = {}) {
+        const waitForExtension = options.waitForExtension === true;
+        const waitTimeoutMs = options.waitTimeoutMs ?? this.timeoutMs;
+        const pollIntervalMs = options.pollIntervalMs ?? 250;
+        const waitStartedAt = Date.now();
+        if (this.connection instanceof ExtensionConnection) {
+            const extension = this.connection;
+            this.sessions = await extension.listSessions(STATUS_TOOLS_TIMEOUT_MS).catch(() => extension.getSessions());
+        }
+        else {
+            this.sessions = [];
         }
+        if (waitForExtension && !this.isBackendConnected()) {
+            const deadline = Date.now() + waitTimeoutMs;
+            while (!this.isBackendConnected() && Date.now() < deadline) {
+                const remainingMs = deadline - Date.now();
+                if (remainingMs <= 0) {
+                    break;
+                }
+                await delay(Math.min(pollIntervalMs, remainingMs));
+                if (this.connection instanceof ExtensionConnection) {
+                    const extension = this.connection;
+                    this.sessions = await extension.listSessions(STATUS_TOOLS_TIMEOUT_MS).catch(() => extension.getSessions());
+                }
+            }
+        }
+        if (this.isBackendConnected()) {
+            // 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);
+        }
+        await this.ensureToolsLoaded(STATUS_TOOLS_TIMEOUT_MS);
         return {
             ok: true,
             command: 'status',
             profile: this.profile,
-            mode: this.remoteUuid ? 'remote' : 'local',
+            mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            sessions: this.sessions,
             ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
-            relayConnected: this.connection.getStatus() === 'connected',
-            extensionConnected: this.connection.isExtensionConnected(),
+            relayConnected: this.connection instanceof ExtensionConnection
+                ? this.connection.getStatus() === 'connected'
+                : false,
+            extensionConnected: this.isBackendConnected(),
             managedLifecycle: false,
             transport: 'vibebrowser-mcp',
             toolCount: this.tools.length,
             tools: this.tools.map((tool) => tool.name),
+            ...(waitForExtension
+                ? {
+                    waitForExtension: true,
+                    waitedMs: Date.now() - waitStartedAt,
+                }
+                : {}),
         };
     }
     async listPages() {
@@ -442,6 +497,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 +509,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: ['take_snapshot'],
                 buildArgs: (tool) => withSnapshotArgs(tool, options),
             },
         ], {});
@@ -553,38 +612,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 +665,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 +705,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 +727,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 +740,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,36 +772,36 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('evaluate', invocation);
     }
-    async highlight(ref) {
-        const invocation = await this.callTool('highlight', [
-            {
-                names: ['highlight'],
-                buildArgs: (tool) => withRefArgs(tool, ref),
-            },
+    async resize(width, height) {
+        const invocation = await this.callTool('resize', [
             {
-                names: ['hover'],
-                buildArgs: (tool) => withRefArgs(tool, ref, { duration: 1500 }),
+                names: ['resize_page'],
+                buildArgs: (tool) => withResizeArgs(tool, width, height),
             },
         ], {});
-        return this.outputFromInvocation('highlight', invocation);
+        return this.outputFromInvocation('resize', invocation);
     }
-    async traceStart(options) {
-        const invocation = await this.callTool('trace start', [
+    async upload(ref, path) {
+        const invocation = await this.callTool('upload', [
             {
-                names: ['performance_start_trace'],
-                buildArgs: (tool) => withTraceStartArgs(tool, options),
+                names: ['upload_file', 'file_upload'],
+                buildArgs: (tool) => withUploadArgs(tool, ref, path),
             },
         ], {});
-        return this.outputFromInvocation('trace start', invocation);
+        return this.outputFromInvocation('upload', invocation);
     }
-    async traceStop(outputPath) {
-        const invocation = await this.callTool('trace stop', [
+    async dialog(options) {
+        if (options.accept && options.dismiss) {
+            throw new Error('dialog supports either --accept or --dismiss, not both');
+        }
+        const accept = options.dismiss ? false : true;
+        const invocation = await this.callTool('dialog', [
             {
-                names: ['performance_stop_trace'],
-                buildArgs: (tool) => withTraceStopArgs(tool, outputPath),
+                names: ['handle_dialog'],
+                buildArgs: (tool) => withDialogArgs(tool, accept, options.promptText),
             },
         ], {});
-        return this.outputFromInvocation('trace stop', invocation);
+        return this.outputFromInvocation('dialog', invocation);
     }
     async callGenericCommand(commandName, candidates, canonicalArgs) {
         const invocation = await this.callTool(commandName, candidates, canonicalArgs);
@@ -842,6 +810,7 @@ class BrowserCliContext {
     async callTool(commandName, candidates, canonicalArgs) {
         await this.ensureToolsLoaded();
         const available = new Map(this.tools.map((tool) => [normalizeName(tool.name), tool]));
+        const compatibilityErrors = [];
         for (const candidate of candidates) {
             for (const candidateName of candidate.names) {
                 const tool = available.get(normalizeName(candidateName));
@@ -851,44 +820,430 @@ class BrowserCliContext {
                 const args = candidate.buildArgs
                     ? candidate.buildArgs(tool)
                     : withCanonicalArgs(tool, canonicalArgs);
-                const result = await this.connection.callTool(tool.name, args);
-                return { tool: tool.name, args, result: result };
+                // 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';
+                    }
+                }
+                try {
+                    const result = await this.connection.callTool(tool.name, args, this.timeoutMs);
+                    return { tool: tool.name, args, result: result };
+                }
+                catch (error) {
+                    if (!isToolArgumentCompatibilityError(error)) {
+                        throw error;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    compatibilityErrors.push(`${tool.name}: ${message}`);
+                }
             }
         }
         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(', ')}`);
+        const compatibilityHint = compatibilityErrors.length > 0
+            ? ` Compatibility errors: ${compatibilityErrors.join(' | ')}`
+            : '';
+        throw new Error(`No compatible browser tool found for "${commandName}". Tried ${requested.join(', ')}. Available tools: ${this.tools.map((tool) => tool.name).join(', ')}.${compatibilityHint}`);
     }
-    async ensureToolsLoaded() {
+    async ensureToolsLoaded(timeoutMs) {
         if (this.toolsLoaded && this.tools.length > 0) {
             return;
         }
-        if (this.connection.isExtensionConnected()) {
-            try {
-                this.tools = await this.connection.refreshTools(this.timeoutMs);
-            }
-            catch {
-                this.tools = await this.connection.waitForToolsUpdate(1_000);
-            }
+        const effectiveTimeout = timeoutMs ?? this.timeoutMs;
+        try {
+            this.tools = await this.connection.refreshTools(effectiveTimeout);
         }
-        else {
+        catch {
+            // 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) {
+                if (this.connection instanceof ExtensionConnection) {
+                    this.tools = await this.connection.waitForToolsUpdate(1_000);
+                }
+            }
         }
         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;
+        }
+        if (!hasExplicitPageContext(invocation.args)) {
+            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_snapshot',
+            ...(fallback.pageId !== targetPageId ? { pageId: fallback.pageId } : {}),
+        };
+    }
+    async recoverPageContentAfterTimeout(commandName, url, error) {
+        if (!isTimeoutError(error)) {
+            return undefined;
+        }
+        if (this.pageId === undefined) {
+            return undefined;
+        }
+        const recoveryTimeoutMs = Math.max(this.timeoutMs, 10_000);
+        let targetPageId = this.pageId;
+        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_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_snapshot');
+        if (!snapshotTool) {
+            return undefined;
+        }
+        const args = {};
+        const pageKey = hasProperty(snapshotTool, 'pageId', 'tabId');
+        if (pageKey) {
+            args[pageKey] = pageId;
+        }
+        const formatKey = hasProperty(snapshotTool, 'format', 'pageStateFormat', 'page_state_format');
+        if (formatKey) {
+            args[formatKey] = '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() {
+        if (this.devtoolsOnly) {
+            return 'devtools';
+        }
         return this.remoteUuid ? 'remote' : 'local';
     }
+    currentSessionId() {
+        if (this.devtoolsOnly) {
+            return undefined;
+        }
+        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;
+    }
+    isBackendConnected() {
+        if (this.connection instanceof ExtensionConnection) {
+            return this.connection.isExtensionConnected();
+        }
+        return this.connection.isAvailable();
+    }
+    getConnectionErrorMessage() {
+        if (this.connection instanceof ExtensionConnection) {
+            return this.connection.getConnectionErrorMessage();
+        }
+        return this.connection.getUnavailableReason() || 'chrome-devtools backend unavailable';
+    }
+    outputMode() {
+        return this.mode();
+    }
+    outputContext() {
+        return {
+            profile: this.profile,
+            mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+        };
+    }
+}
+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 hasExplicitPageContext(args) {
+    const candidates = [args.pageId, args.tabId, args.page_id, args.tab_id];
+    return candidates.some((candidate) => {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return true;
+        }
+        if (typeof candidate === 'string') {
+            return /^\d+$/.test(candidate.trim());
+        }
+        return false;
+    });
+}
+function shouldAttachImplicitPageContent(commandName, args) {
+    if (!hasExplicitPageContext(args)) {
+        return false;
+    }
+    return commandName !== 'close';
+}
+function stripImplicitPageContent(result) {
+    const firstTextIndex = result.content.findIndex((entry) => entry.type === 'text');
+    if (firstTextIndex < 0) {
+        return result;
+    }
+    const firstTextEntry = result.content[firstTextIndex];
+    if (!('text' in firstTextEntry) || !looksLikePageContentText(firstTextEntry.text)) {
+        return result;
+    }
+    return {
+        ...result,
+        content: result.content.filter((_, index) => index !== firstTextIndex),
+    };
+}
+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 isToolArgumentCompatibilityError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (!message) {
+        return false;
+    }
+    if (/timed out|timeout|relay connection|connection lost|not connected|no connection|disconnected/.test(message)) {
+        return false;
+    }
+    return /missing required|required (field|property|argument)|invalid argument|invalid args|invalid input|unexpected argument|unexpected property|unknown argument|does not accept|unrecognized (field|property|argument)/.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,13 +1253,17 @@ 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) {
+        const context = ctx.outputContext();
         console.log(JSON.stringify({
             ok: false,
             command: commandName,
-            profile: DEFAULT_BROWSER_PROFILE,
-            mode: 'local',
+            ...context,
             error: message,
         }, null, 2));
         return;
@@ -919,19 +1278,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 +1322,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 +1338,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 +1405,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 +1476,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 +1603,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 +1655,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) {
@@ -1358,36 +1740,60 @@ 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) {
+function withUploadArgs(tool, ref, path) {
+    const args = withRefArgs(tool, ref);
+    maybeAssign(args, tool, 'filePath', path);
+    maybeAssign(args, tool, 'path', path);
+    if (hasProperty(tool, 'paths')) {
+        args.paths = [path];
+    }
+    const filenameKey = hasProperty(tool, 'filename');
+    const mimeTypeKey = hasProperty(tool, 'mimeType');
+    const contentBase64Key = hasProperty(tool, 'contentBase64');
+    const hasTopLevelPayload = Boolean(filenameKey && mimeTypeKey && contentBase64Key);
+    const fileKey = hasProperty(tool, 'file');
+    const fileSchema = fileKey ? toolProperties(tool)[fileKey] : undefined;
+    const fileProperties = isRecord(fileSchema) && isRecord(fileSchema.properties) ? fileSchema.properties : undefined;
+    const hasNestedPayload = Boolean(fileKey
+        && fileProperties
+        && Object.prototype.hasOwnProperty.call(fileProperties, 'filename')
+        && Object.prototype.hasOwnProperty.call(fileProperties, 'mimeType')
+        && Object.prototype.hasOwnProperty.call(fileProperties, 'contentBase64'));
+    if (!hasTopLevelPayload && !hasNestedPayload) {
+        return args;
+    }
+    const filePayload = buildUploadFilePayload(path);
+    if (hasTopLevelPayload && filenameKey && mimeTypeKey && contentBase64Key) {
+        args[filenameKey] = filePayload.filename;
+        args[mimeTypeKey] = filePayload.mimeType;
+        args[contentBase64Key] = filePayload.contentBase64;
+    }
+    if (hasNestedPayload && fileKey) {
+        args[fileKey] = filePayload;
+    }
+    return args;
+}
+function withDialogArgs(tool, accept, promptText) {
     const args = {};
-    maybeAssign(args, tool, 'action', action);
-    maybeAssign(args, tool, 'promptText', prompt);
+    if (hasProperty(tool, 'action')) {
+        args.action = accept ? 'accept' : 'dismiss';
+    }
+    if (hasProperty(tool, 'accept')) {
+        args.accept = accept;
+    }
+    if (promptText !== undefined) {
+        maybeAssign(args, tool, 'promptText', promptText);
+        maybeAssign(args, tool, 'prompt', promptText);
+        if (hasProperty(tool, 'prompt_text')) {
+            args.prompt_text = promptText;
+        }
+    }
     return args;
 }
 function withWaitArgs(tool, text, timeoutMs) {
@@ -1417,21 +1823,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;
@@ -1443,6 +1834,24 @@ function maybeAssign(target, tool, property, value) {
 function stripUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }
+function buildUploadFilePayload(path) {
+    let contentBase64;
+    try {
+        contentBase64 = readFileSync(path).toString('base64');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read upload file at "${path}": ${message}`);
+    }
+    return {
+        filename: basename(path),
+        mimeType: MIME_TYPE_BY_EXTENSION[extname(path).toLowerCase()] ?? 'application/octet-stream',
+        contentBase64,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
 function parseRef(ref) {
     const numeric = Number.parseInt(ref, 10);
     return {