@vibebrowser/mcp 0.2.4 → 0.2.6

package/dist/browser-cli.js

@@ -0,0 +1,1597 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+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;
+export function registerBrowserCommand(program) {
+    const browser = buildBrowserCommand(program.command('browser'));
+    registerBrowserSubcommands(browser);
+}
+export function registerStandaloneBrowserCli(program) {
+    const browser = buildBrowserCommand(program);
+    registerBrowserSubcommands(browser);
+}
+function buildBrowserCommand(command) {
+    return command
+        .description('OpenClaw-compatible browser CLI for the connected Vibe browser session')
+        .option('--browser-profile <name>', 'Compatibility profile name', DEFAULT_BROWSER_PROFILE)
+        .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('-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('--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')
+        .action(async function () {
+        await runBrowserCommand(this, 'status', false, async (ctx) => ctx.status());
+    });
+    browser
+        .command('start')
+        .description('Connect to the browser bridge and verify the session is reachable')
+        .action(async function () {
+        await runBrowserCommand(this, 'start', false, async (ctx) => {
+            const status = await ctx.status();
+            return {
+                ...status,
+                started: status.extensionConnected,
+                managedLifecycle: false,
+                note: status.extensionConnected
+                    ? 'Connected to Vibe browser session'
+                    : 'Vibe uses an attach-only browser session; no managed browser process was started',
+            };
+        });
+    });
+    browser
+        .command('stop')
+        .description('Compatibility no-op: the Vibe browser bridge does not manage browser process lifecycle')
+        .action(async function () {
+        await runBrowserCommand(this, 'stop', false, async (ctx) => ({
+            ...await ctx.status(),
+            stopped: false,
+            managedLifecycle: false,
+            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')
+        .action(async function () {
+        await runBrowserCommand(this, 'tabs', true, async (ctx) => ctx.listPages());
+    });
+    const tab = browser.command('tab').description('Tab helpers');
+    tab
+        .action(async function () {
+        await runBrowserCommand(this, 'tab', true, async (ctx) => ctx.listPages());
+    });
+    tab
+        .command('new [url]')
+        .description('Open a new tab')
+        .action(async function (url) {
+        await runBrowserCommand(this, 'tab new', true, async (ctx) => ctx.open(url));
+    });
+    tab
+        .command('select <id>')
+        .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));
+    });
+    tab
+        .command('close <id>')
+        .description('Close a tab/page')
+        .action(async function (id) {
+        await runBrowserCommand(this, 'tab close', true, async (ctx) => ctx.close(id));
+    });
+    browser
+        .command('open <url>')
+        .description('Open a URL in a new page or navigate using the best available tool')
+        .action(async function (url) {
+        await runBrowserCommand(this, 'open', true, async (ctx) => ctx.open(url));
+    });
+    browser
+        .command('navigate <url>')
+        .description('Navigate the active page to a URL')
+        .action(async function (url) {
+        await runBrowserCommand(this, 'navigate', true, async (ctx) => ctx.navigate(url));
+    });
+    browser
+        .command('focus <id>')
+        .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));
+    });
+    browser
+        .command('close <id>')
+        .description('Close a tab/page')
+        .action(async function (id) {
+        await runBrowserCommand(this, 'close', true, async (ctx) => ctx.close(id));
+    });
+    browser
+        .command('snapshot')
+        .description('Capture a textual browser snapshot')
+        .option('--format <format>', 'Snapshot format (ai or aria)', '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')
+        .option('--frame <selector>', 'Frame selector for the snapshot')
+        .option('--compact', 'Compatibility flag', false)
+        .option('--depth <depth>', 'Compatibility flag')
+        .option('--efficient', 'Compatibility flag', false)
+        .option('--labels', 'Include labels when supported by backend', false)
+        .action(async function () {
+        await runBrowserCommand(this, 'snapshot', true, async (ctx, options) => ctx.snapshot({
+            format: String(options.format || 'ai'),
+            limit: options.limit ? parsePositiveInteger(String(options.limit), '--limit') : undefined,
+            interactive: Boolean(options.interactive),
+            selector: options.selector ? String(options.selector) : undefined,
+            frame: options.frame ? String(options.frame) : undefined,
+            compact: Boolean(options.compact),
+            depth: options.depth ? parsePositiveInteger(String(options.depth), '--depth') : undefined,
+            efficient: Boolean(options.efficient),
+            labels: Boolean(options.labels),
+        }));
+    });
+    browser
+        .command('screenshot')
+        .description('Capture a browser screenshot')
+        .option('--full-page', 'Request a full page screenshot when supported', false)
+        .option('--ref <ref>', 'Element ref/index')
+        .option('--output <path>', 'Write screenshot bytes to a file')
+        .option('--detail <level>', 'Screenshot detail level')
+        .option('--grayscale', 'Use grayscale when supported', false)
+        .action(async function () {
+        await runBrowserCommand(this, 'screenshot', true, async (ctx, options) => ctx.screenshot({
+            fullPage: Boolean(options.fullPage),
+            ref: options.ref ? String(options.ref) : undefined,
+            outputPath: options.output ? String(options.output) : undefined,
+            detail: options.detail ? String(options.detail) : undefined,
+            grayscale: Boolean(options.grayscale),
+        }));
+    });
+    // NOTE: pdf, console, errors commands removed — no matching browser tools.
+    browser
+        .command('requests')
+        .description('List network requests')
+        .option('--filter <pattern>', 'Substring filter')
+        .option('--limit <count>', 'Maximum requests to print')
+        .option('--clear', 'Compatibility flag', false)
+        .action(async function () {
+        await runBrowserCommand(this, 'requests', true, async (ctx, options) => ctx.requests({
+            filter: options.filter ? String(options.filter) : undefined,
+            limit: options.limit ? parsePositiveInteger(String(options.limit), '--limit') : undefined,
+        }));
+    });
+    browser
+        .command('responsebody [pattern]')
+        .description('Show a matching response body when network inspection is available')
+        .option('--max-chars <count>', 'Truncate response body output')
+        .action(async function (pattern) {
+        await runBrowserCommand(this, 'responsebody', true, async (ctx, options) => ctx.responseBody({
+            pattern,
+            maxChars: options.maxChars
+                ? parsePositiveInteger(String(options.maxChars), '--max-chars')
+                : undefined,
+        }));
+    });
+    // NOTE: resize command removed — no resize_page tool in the extension.
+    browser
+        .command('click <ref>')
+        .description('Click an element by ref/index')
+        .option('--double', 'Double click when supported', false)
+        .action(async function (ref) {
+        await runBrowserCommand(this, 'click', true, async (ctx, options) => ctx.click(ref, { double: Boolean(options.double) }));
+    });
+    browser
+        .command('type <ref> <text>')
+        .description('Type/fill text into an element')
+        .option('--submit', 'Submit after typing', false)
+        .action(async function (ref, text) {
+        await runBrowserCommand(this, 'type', true, async (ctx, options) => ctx.type(ref, text, { submit: Boolean(options.submit) }));
+    });
+    browser
+        .command('press <keys>')
+        .description('Press a key or key chord')
+        .action(async function (keys) {
+        await runBrowserCommand(this, 'press', true, async (ctx) => ctx.press(keys));
+    });
+    browser
+        .command('hover <ref>')
+        .description('Hover an element by ref/index')
+        .action(async function (ref) {
+        await runBrowserCommand(this, 'hover', true, async (ctx) => ctx.hover(ref));
+    });
+    // NOTE: scrollintoview, download, waitfordownload, upload commands removed — no matching tools.
+    browser
+        .command('drag <source> <target>')
+        .description('Drag one element to another')
+        .action(async function (source, target) {
+        await runBrowserCommand(this, 'drag', true, async (ctx) => ctx.drag(source, target));
+    });
+    browser
+        .command('select <ref> <values...>')
+        .description('Select one or more values in a field')
+        .action(async function (ref, values) {
+        await runBrowserCommand(this, 'select', true, async (ctx) => ctx.select(ref, values));
+    });
+    browser
+        .command('fill')
+        .description('Fill a form using JSON field descriptors')
+        .requiredOption('--fields <json>', 'JSON array of field descriptors')
+        .action(async function () {
+        await runBrowserCommand(this, 'fill', true, async (ctx, options) => ctx.fillForm(String(options.fields)));
+    });
+    // NOTE: dialog command removed — no handle_dialog tool in the extension.
+    browser
+        .command('wait')
+        .description('Wait for text or a short delay')
+        .option('--text <value...>', 'Texts to wait for')
+        .option('--seconds <seconds>', 'Wait for a fixed number of seconds')
+        .option('--timeout <ms>', 'Override command timeout')
+        .action(async function () {
+        await runBrowserCommand(this, 'wait', true, async (ctx, options, baseOptions) => ctx.wait({
+            text: Array.isArray(options.text) ? options.text.map(String) : undefined,
+            seconds: options.seconds ? Number(options.seconds) : undefined,
+            timeoutMs: options.timeout ? parsePositiveInteger(String(options.timeout), '--timeout') : parsePositiveInteger(baseOptions.timeout, '--timeout'),
+        }));
+    });
+    browser
+        .command('evaluate')
+        .description('Evaluate JavaScript through the browser tool backend')
+        .requiredOption('--fn <function>', 'Function to evaluate')
+        .option('--ref <ref>', 'Element ref/index argument')
+        .option('--args <json>', 'JSON array of additional arguments')
+        .action(async function () {
+        await runBrowserCommand(this, 'evaluate', true, async (ctx, options) => ctx.evaluate({
+            fn: String(options.fn),
+            ref: options.ref ? String(options.ref) : undefined,
+            argsJson: options.args ? String(options.args) : 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();
+    const localOptions = command.opts();
+    const ctx = new BrowserCliContext({
+        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();
+        if (requireExtension) {
+            await ctx.ensureExtensionConnected();
+        }
+        const output = await handler(ctx, localOptions, globalOptions);
+        emitOutput(Boolean(globalOptions.json), output, formatHumanOutput(commandName, output));
+    }
+    catch (error) {
+        emitError(Boolean(globalOptions.json), commandName, ctx, error);
+        process.exitCode = 1;
+    }
+    finally {
+        await ctx.shutdown();
+    }
+}
+class BrowserCliContext {
+    connection;
+    profile;
+    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, 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}`);
+        }
+    }
+    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() {
+        await this.connection.stop();
+    }
+    async ensureExtensionConnected() {
+        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(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()) {
+            // 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(),
+            managedLifecycle: false,
+            transport: 'vibebrowser-mcp',
+            toolCount: this.tools.length,
+            tools: this.tools.map((tool) => tool.name),
+        };
+    }
+    async listPages() {
+        const invocation = await this.callTool('tabs', [
+            { names: ['list_pages', 'get_tabs'] },
+        ], {});
+        const pages = extractPages(invocation.result);
+        return {
+            ok: true,
+            command: 'tabs',
+            profile: this.profile,
+            mode: this.mode(),
+            sessionId: this.currentSessionId(),
+            requestedSessionId: this.requestedSessionId,
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            tool: invocation.tool,
+            pages,
+            raw: normalizeToolResult(invocation.result),
+        };
+    }
+    async open(url) {
+        if (!url) {
+            return this.callGenericCommand('open', [{ names: ['new_page', 'create_new_tab'] }], {});
+        }
+        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) {
+        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: ['close_page', 'close_tab'],
+                buildArgs: (tool) => withPageArgs(tool, id),
+            },
+        ], {});
+        return this.outputFromInvocation('close', invocation);
+    }
+    async focus(id) {
+        const invocation = await this.callTool('focus', [
+            {
+                names: ['switch_to_page', 'switch_to_tab', 'select_page', 'focus_tab'],
+                buildArgs: (tool) => withPageArgs(tool, id),
+            },
+        ], {});
+        return this.outputFromInvocation('focus', invocation);
+    }
+    async snapshot(options) {
+        const wantsAria = options.format === 'aria' || options.interactive || Boolean(options.selector) || Boolean(options.frame);
+        const invocation = await this.callTool('snapshot', [
+            {
+                names: [wantsAria ? 'take_a11y_snapshot' : 'take_md_snapshot'],
+                buildArgs: (tool) => withSnapshotArgs(tool, options),
+            },
+        ], {});
+        const text = firstText(invocation.result);
+        return {
+            ok: true,
+            command: 'snapshot',
+            profile: this.profile,
+            mode: this.mode(),
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            tool: invocation.tool,
+            format: wantsAria ? 'aria' : options.format,
+            snapshot: limitText(text, options.limit),
+            raw: normalizeToolResult(invocation.result),
+        };
+    }
+    async screenshot(options) {
+        const invocation = await this.callTool('screenshot', [
+            {
+                names: ['take_screenshot', 'screenshot'],
+                buildArgs: (tool) => withScreenshotArgs(tool, options),
+            },
+        ], {});
+        const savedPath = maybeWriteBinaryOutput(invocation.result, options.outputPath);
+        return {
+            ok: true,
+            command: 'screenshot',
+            profile: this.profile,
+            mode: this.mode(),
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            tool: invocation.tool,
+            outputPath: savedPath || options.outputPath,
+            raw: normalizeToolResult(invocation.result),
+        };
+    }
+    async requests(options) {
+        const invocation = await this.callTool('requests', [
+            {
+                names: ['list_network_requests'],
+                buildArgs: (tool) => withRequestListArgs(tool, options),
+            },
+        ], {});
+        let requests = extractRequests(invocation.result);
+        if (options.filter) {
+            const needle = options.filter.toLowerCase();
+            requests = requests.filter((request) => JSON.stringify(request).toLowerCase().includes(needle));
+        }
+        if (options.limit) {
+            requests = requests.slice(0, options.limit);
+        }
+        return {
+            ok: true,
+            command: 'requests',
+            profile: this.profile,
+            mode: this.mode(),
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            tool: invocation.tool,
+            requests,
+            raw: normalizeToolResult(invocation.result),
+        };
+    }
+    async responseBody(options) {
+        const requests = await this.requests({ filter: options.pattern, limit: 1 });
+        const list = Array.isArray(requests.requests) ? requests.requests : [];
+        const first = list[0];
+        const requestId = first?.requestId ?? guessRequestId(requests.raw);
+        if (!requestId) {
+            throw new Error('No matching network request found');
+        }
+        const invocation = await this.callTool('responsebody', [
+            {
+                names: ['get_network_request'],
+                buildArgs: (tool) => withRequestDetailsArgs(tool, requestId),
+            },
+        ], {});
+        const body = limitText(extractResponseBody(invocation.result), options.maxChars);
+        return {
+            ok: true,
+            command: 'responsebody',
+            profile: this.profile,
+            mode: this.mode(),
+            ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+            requestId,
+            tool: invocation.tool,
+            responseBody: body,
+            raw: normalizeToolResult(invocation.result),
+        };
+    }
+    async click(ref, options) {
+        const invocation = await this.callTool('click', [
+            {
+                names: ['click'],
+                buildArgs: (tool) => withRefArgs(tool, ref, { dblClick: options.double }),
+            },
+        ], {});
+        return this.outputFromInvocation('click', invocation);
+    }
+    async type(ref, text, options) {
+        const invocation = await this.callTool('type', [
+            {
+                names: ['fill'],
+                buildArgs: (tool) => withFillArgs(tool, ref, text),
+            },
+            {
+                names: ['type_text', 'type'],
+                buildArgs: (tool) => withTypeArgs(tool, text, options.submit ? 'Enter' : undefined),
+            },
+        ], {});
+        return this.outputFromInvocation('type', invocation);
+    }
+    async press(keys) {
+        const invocation = await this.callTool('press', [
+            {
+                names: ['press_key', 'keyboard_shortcut'],
+                buildArgs: (tool) => withKeysArgs(tool, keys),
+            },
+        ], {});
+        return this.outputFromInvocation('press', invocation);
+    }
+    async hover(ref) {
+        const invocation = await this.callTool('hover', [
+            {
+                names: ['hover'],
+                buildArgs: (tool) => withRefArgs(tool, ref),
+            },
+        ], {});
+        return this.outputFromInvocation('hover', invocation);
+    }
+    async drag(source, target) {
+        const invocation = await this.callTool('drag', [
+            {
+                names: ['drag'],
+                buildArgs: (tool) => withDragArgs(tool, source, target),
+            },
+        ], {});
+        return this.outputFromInvocation('drag', invocation);
+    }
+    async select(ref, values) {
+        const invocation = await this.callTool('select', [
+            {
+                names: ['fill'],
+                buildArgs: (tool) => withFillArgs(tool, ref, values.length === 1 ? values[0] : values),
+            },
+            {
+                names: ['select_option', 'select'],
+                buildArgs: (tool) => withSelectArgs(tool, ref, values),
+            },
+        ], {});
+        return this.outputFromInvocation('select', invocation);
+    }
+    async fillForm(fieldsJson) {
+        const fields = parseJsonValue(fieldsJson, '--fields');
+        if (!Array.isArray(fields)) {
+            throw new Error('--fields must be a JSON array');
+        }
+        const invocation = await this.callTool('fill', [
+            {
+                names: ['fill_form'],
+                buildArgs: (tool) => withFillFormArgs(tool, fields),
+            },
+        ], {});
+        return this.outputFromInvocation('fill', invocation);
+    }
+    async wait(options) {
+        if (options.text && options.text.length > 0) {
+            const invocation = await this.callTool('wait', [
+                {
+                    names: ['wait_for'],
+                    buildArgs: (tool) => withWaitArgs(tool, options.text, options.timeoutMs),
+                },
+            ], {});
+            return this.outputFromInvocation('wait', invocation);
+        }
+        if (typeof options.seconds === 'number' && Number.isFinite(options.seconds) && options.seconds >= 0) {
+            await delay(Math.round(options.seconds * 1000));
+            return {
+                ok: true,
+                command: 'wait',
+                profile: this.profile,
+                mode: this.mode(),
+                ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
+                waitedSeconds: options.seconds,
+            };
+        }
+        throw new Error('wait requires either --text or --seconds');
+    }
+    async evaluate(options) {
+        const invocation = await this.callTool('evaluate', [
+            {
+                names: ['evaluate_script'],
+                buildArgs: (tool) => withEvaluateArgs(tool, options.fn, options.ref, options.argsJson),
+            },
+        ], {});
+        return this.outputFromInvocation('evaluate', invocation);
+    }
+    async callGenericCommand(commandName, candidates, canonicalArgs) {
+        const invocation = await this.callTool(commandName, candidates, canonicalArgs);
+        return this.outputFromInvocation(commandName, invocation);
+    }
+    async callTool(commandName, candidates, canonicalArgs) {
+        await this.ensureToolsLoaded();
+        const available = new Map(this.tools.map((tool) => [normalizeName(tool.name), tool]));
+        for (const candidate of candidates) {
+            for (const candidateName of candidate.names) {
+                const tool = available.get(normalizeName(candidateName));
+                if (!tool) {
+                    continue;
+                }
+                const args = candidate.buildArgs
+                    ? candidate.buildArgs(tool)
+                    : withCanonicalArgs(tool, canonicalArgs);
+                // 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(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(effectiveTimeout);
+            }
+            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) {
+                    this.tools = await this.connection.waitForToolsUpdate(1_000);
+                }
+            }
+        }
+        else {
+            this.tools = this.connection.getTools();
+        }
+        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) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(humanOutput);
+}
+function emitError(asJson, commandName, ctx, 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,
+            command: commandName,
+            profile: DEFAULT_BROWSER_PROFILE,
+            mode: 'local',
+            error: message,
+        }, null, 2));
+        return;
+    }
+    console.error(`Error: ${message}`);
+}
+function formatHumanOutput(commandName, output) {
+    switch (commandName) {
+        case 'status':
+        case 'start':
+        case 'stop':
+            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 [
+                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 [
+                output.title ? `Title: ${String(output.title)}` : null,
+                output.url ? `URL: ${String(output.url)}` : null,
+                output.snapshot ? String(output.snapshot) : firstDefinedText(output.raw, ''),
+            ].filter(Boolean).join('\n');
+        case 'requests': {
+            const requests = Array.isArray(output.requests) ? output.requests : [];
+            if (requests.length === 0) {
+                return firstDefinedText(output.raw, 'No requests reported by browser');
+            }
+            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 'responsebody':
+            return String(output.responseBody ?? firstDefinedText(output.raw, ''));
+        default:
+            if (output.outputPath) {
+                return `Saved to ${String(output.outputPath)}`;
+            }
+            return firstDefinedText(output.raw, JSON.stringify(output, null, 2));
+    }
+}
+function boolText(value) {
+    return value ? 'yes' : 'no';
+}
+function firstDefinedText(value, fallback) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    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;
+}
+function normalizeToolResult(result) {
+    return sanitizeUnknown(result) ?? null;
+}
+function sanitizeUnknown(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeUnknown(item) ?? null);
+    if (value && typeof value === 'object') {
+        const output = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const sanitized = sanitizeUnknown(entry);
+            if (sanitized !== undefined) {
+                output[key] = sanitized;
+            }
+        }
+        return output;
+    }
+    return undefined;
+}
+function maybeWriteBinaryOutput(result, outputPath) {
+    if (!outputPath) {
+        return undefined;
+    }
+    const image = result.content?.find((item) => item.type === 'image');
+    if (!image || !('data' in image) || typeof image.data !== 'string') {
+        return undefined;
+    }
+    const target = resolve(outputPath);
+    writeFileSync(target, Buffer.from(image.data, 'base64'));
+    return target;
+}
+function extractPages(result) {
+    const direct = extractStructured(result, ['pages', 'tabs', 'targets']);
+    if (Array.isArray(direct)) {
+        return direct.map((entry) => normalizePage(entry));
+    }
+    const parsed = parseResultText(result);
+    if (Array.isArray(parsed)) {
+        return parsed.map((entry) => normalizePage(entry));
+    }
+    if (parsed && typeof parsed === 'object') {
+        for (const key of ['pages', 'tabs', 'targets']) {
+            const candidate = parsed[key];
+            if (Array.isArray(candidate)) {
+                return candidate.map((entry) => normalizePage(entry));
+            }
+        }
+    }
+    // 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 {};
+    }
+    const record = value;
+    return {
+        ...sanitizeUnknown(record),
+        id: firstDefined(record, ['pageId', 'tabId', 'id', 'targetId']),
+        title: firstString(record, ['title', 'name']),
+        url: firstString(record, ['url']),
+        active: firstBoolean(record, ['active', 'selected', 'focused']),
+    };
+}
+function extractRequests(result) {
+    const direct = extractStructured(result, ['requests']);
+    if (Array.isArray(direct)) {
+        return direct.map((entry) => normalizeRequest(entry));
+    }
+    const parsed = parseResultText(result);
+    if (Array.isArray(parsed)) {
+        return parsed.map((entry) => normalizeRequest(entry));
+    }
+    if (parsed && typeof parsed === 'object') {
+        const requests = parsed.requests;
+        if (Array.isArray(requests)) {
+            return requests.map((entry) => normalizeRequest(entry));
+        }
+    }
+    return [];
+}
+function normalizeRequest(value) {
+    if (!value || typeof value !== 'object') {
+        return {};
+    }
+    const record = value;
+    return {
+        ...sanitizeUnknown(record),
+        requestId: firstString(record, ['requestId', 'reqid', 'id']),
+        url: firstString(record, ['url']),
+        method: firstString(record, ['method']),
+        status: firstNumber(record, ['status']),
+    };
+}
+function extractResponseBody(result) {
+    const direct = extractStructured(result, ['responseBody', 'body']);
+    if (typeof direct === 'string') {
+        return direct;
+    }
+    const parsed = parseResultText(result);
+    if (parsed && typeof parsed === 'object') {
+        for (const key of ['responseBody', 'body']) {
+            const candidate = parsed[key];
+            if (typeof candidate === 'string') {
+                return candidate;
+            }
+        }
+    }
+    return firstText(result);
+}
+function guessRequestId(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.requestId === 'string') {
+        return record.requestId;
+    }
+    return undefined;
+}
+function extractStructured(result, keys) {
+    for (const key of keys) {
+        if (key in result) {
+            return result[key];
+        }
+    }
+    return undefined;
+}
+function parseResultText(result) {
+    const text = firstText(result);
+    if (!text) {
+        return undefined;
+    }
+    return parseJsonText(text);
+}
+function firstText(result) {
+    const item = result.content?.find((entry) => entry.type === 'text');
+    return item && 'text' in item && typeof item.text === 'string' ? item.text : '';
+}
+function parseJsonText(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const candidates = [trimmed];
+    if (trimmed.startsWith('```')) {
+        const fenced = trimmed
+            .replace(/^```[a-zA-Z0-9_-]*\n/, '')
+            .replace(/\n```$/, '')
+            .trim();
+        candidates.push(fenced);
+    }
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return undefined;
+}
+function parseJsonValue(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label} must be valid JSON: ${message}`);
+    }
+}
+function stringifyJson(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+}
+function limitText(text, limit) {
+    if (!limit || limit <= 0) {
+        return text;
+    }
+    const lines = text.split('\n');
+    return lines.length <= limit ? text : `${lines.slice(0, limit).join('\n')}\n...`;
+}
+function parsePositiveInteger(value, label) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+    return parsed;
+}
+function normalizeName(value) {
+    return value.replace(/[-\s]/g, '_').toLowerCase();
+}
+function toolProperties(tool) {
+    return tool.inputSchema.properties ?? {};
+}
+function hasProperty(tool, ...names) {
+    const properties = toolProperties(tool);
+    return names.find((name) => Object.prototype.hasOwnProperty.call(properties, name));
+}
+function withCanonicalArgs(tool, canonicalArgs) {
+    const output = {};
+    for (const [key, value] of Object.entries(canonicalArgs)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(toolProperties(tool), key)) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+function withUrlArgs(tool, url) {
+    const args = {};
+    const urlKey = hasProperty(tool, 'url');
+    if (urlKey)
+        args[urlKey] = url;
+    const typeKey = hasProperty(tool, 'type');
+    if (typeKey && normalizeName(tool.name) === 'navigate_page') {
+        args[typeKey] = 'url';
+    }
+    return args;
+}
+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) {
+    const args = {};
+    const numeric = Number.parseInt(id, 10);
+    const key = hasProperty(tool, 'pageId', 'tabId', 'id');
+    if (key) {
+        args[key] = Number.isFinite(numeric) && String(numeric) === id ? numeric : id;
+    }
+    return args;
+}
+function withSnapshotArgs(tool, options) {
+    const args = {};
+    maybeAssign(args, tool, 'format', options.format);
+    maybeAssign(args, tool, 'selector', options.selector);
+    maybeAssign(args, tool, 'frame', options.frame);
+    maybeAssign(args, tool, 'compact', options.compact || undefined);
+    maybeAssign(args, tool, 'depth', options.depth);
+    maybeAssign(args, tool, 'efficient', options.efficient || undefined);
+    maybeAssign(args, tool, 'labels', options.labels || undefined);
+    maybeAssign(args, tool, 'a11y', true);
+    maybeAssign(args, tool, 'markdown', false);
+    return args;
+}
+function withScreenshotArgs(tool, options) {
+    const args = {};
+    if (options.ref) {
+        Object.assign(args, withRefArgs(tool, options.ref));
+    }
+    maybeAssign(args, tool, 'fullPage', options.fullPage || undefined);
+    maybeAssign(args, tool, 'detail', options.detail);
+    maybeAssign(args, tool, 'grayscale', options.grayscale || undefined);
+    return args;
+}
+function withRequestListArgs(tool, options) {
+    const args = {};
+    if (options.limit) {
+        maybeAssign(args, tool, 'limit', options.limit);
+        maybeAssign(args, tool, 'pageSize', options.limit);
+    }
+    return args;
+}
+function withRequestDetailsArgs(tool, requestId) {
+    const args = {};
+    maybeAssign(args, tool, 'requestId', requestId);
+    maybeAssign(args, tool, 'reqid', requestId);
+    return args;
+}
+function withRefArgs(tool, ref, extra = {}) {
+    const args = { ...extra };
+    const parsedRef = parseRef(ref);
+    if (hasProperty(tool, 'ref')) {
+        args.ref = parsedRef.raw;
+    }
+    if (parsedRef.numeric !== undefined && hasProperty(tool, 'index')) {
+        args.index = parsedRef.numeric;
+    }
+    if (hasProperty(tool, 'uid')) {
+        args.uid = parsedRef.raw;
+    }
+    if (hasProperty(tool, 'selector')) {
+        args.selector = parsedRef.raw;
+    }
+    return args;
+}
+function withFillArgs(tool, ref, value) {
+    const args = withRefArgs(tool, ref);
+    if (hasProperty(tool, 'value')) {
+        args.value = Array.isArray(value) ? value[0] : value;
+    }
+    if (hasProperty(tool, 'text')) {
+        args.text = Array.isArray(value) ? value.join(' ') : value;
+    }
+    return args;
+}
+function withTypeArgs(tool, text, submitKey) {
+    const args = {};
+    maybeAssign(args, tool, 'text', text);
+    maybeAssign(args, tool, 'value', text);
+    if (submitKey) {
+        maybeAssign(args, tool, 'submitKey', submitKey);
+    }
+    return args;
+}
+function withKeysArgs(tool, keys) {
+    const args = {};
+    maybeAssign(args, tool, 'keys', keys);
+    maybeAssign(args, tool, 'shortcut', keys);
+    maybeAssign(args, tool, 'key', keys);
+    return args;
+}
+function withDragArgs(tool, source, target) {
+    const args = {};
+    if (hasProperty(tool, 'source')) {
+        args.source = source;
+    }
+    if (hasProperty(tool, 'target')) {
+        args.target = target;
+    }
+    if (hasProperty(tool, 'from_uid')) {
+        args.from_uid = source;
+    }
+    if (hasProperty(tool, 'to_uid')) {
+        args.to_uid = target;
+    }
+    return args;
+}
+function withSelectArgs(tool, ref, values) {
+    const args = withRefArgs(tool, ref);
+    maybeAssign(args, tool, 'value', values.length === 1 ? values[0] : values);
+    maybeAssign(args, tool, 'values', values);
+    return args;
+}
+function withFillFormArgs(tool, fields) {
+    const args = {};
+    maybeAssign(args, tool, 'fields', fields);
+    maybeAssign(args, tool, 'elements', fields);
+    return args;
+}
+function withWaitArgs(tool, text, timeoutMs) {
+    const args = {};
+    maybeAssign(args, tool, 'text', text);
+    maybeAssign(args, tool, 'timeout', timeoutMs);
+    return args;
+}
+function withEvaluateArgs(tool, fn, ref, argsJson) {
+    const args = {};
+    maybeAssign(args, tool, 'function', fn);
+    const values = [];
+    if (ref) {
+        values.push(ref);
+    }
+    if (argsJson) {
+        const parsed = parseJsonValue(argsJson, '--args');
+        if (!Array.isArray(parsed)) {
+            throw new Error('--args must be a JSON array');
+        }
+        for (const entry of parsed) {
+            values.push(typeof entry === 'string' ? entry : JSON.stringify(entry));
+        }
+    }
+    if (values.length > 0) {
+        maybeAssign(args, tool, 'args', values);
+    }
+    return args;
+}
+function maybeAssign(target, tool, property, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (hasProperty(tool, property)) {
+        target[property] = value;
+    }
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function parseRef(ref) {
+    const numeric = Number.parseInt(ref, 10);
+    return {
+        raw: ref,
+        numeric: Number.isFinite(numeric) && String(numeric) === ref ? numeric : undefined,
+    };
+}
+function firstDefined(record, keys) {
+    for (const key of keys) {
+        if (record[key] !== undefined) {
+            return record[key];
+        }
+    }
+    return undefined;
+}
+function firstString(record, keys) {
+    const value = firstDefined(record, keys);
+    return typeof value === 'string' ? value : undefined;
+}
+function firstBoolean(record, keys) {
+    const value = firstDefined(record, keys);
+    return typeof value === 'boolean' ? value : undefined;
+}
+function firstNumber(record, keys) {
+    const value = firstDefined(record, keys);
+    return typeof value === 'number' ? value : undefined;
+}
+//# sourceMappingURL=browser-cli.js.map