@vibebrowser/mcp 0.2.6 → 0.2.7

package/dist/browser-cli.js

@@ -1,13 +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'));
@@ -24,6 +42,7 @@ 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)
@@ -36,8 +55,19 @@ 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')
@@ -128,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')
@@ -192,7 +222,12 @@ function registerBrowserSubcommands(browser) {
                 : undefined,
         }));
     });
-    // NOTE: resize command removed — no resize_page tool in the extension.
+    browser
+        .command('resize <width> <height>')
+        .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>')));
+    });
     browser
         .command('click <ref>')
         .description('Click an element by ref/index')
@@ -219,7 +254,13 @@ function registerBrowserSubcommands(browser) {
         .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('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')
@@ -239,7 +280,19 @@ function registerBrowserSubcommands(browser) {
         .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('dialog')
+        .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),
+            promptText: options.prompt ? String(options.prompt) : undefined,
+        }));
+    });
     browser
         .command('wait')
         .description('Wait for text or a short delay')
@@ -275,6 +328,7 @@ 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,
@@ -305,6 +359,7 @@ class BrowserCliContext {
     profile;
     json;
     timeoutMs;
+    devtoolsOnly;
     remoteUuid;
     requestedSessionId;
     target;
@@ -314,7 +369,10 @@ class BrowserCliContext {
     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.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;
@@ -329,25 +387,37 @@ class BrowserCliContext {
     }
     async connect() {
         await this.connection.start();
-        await delay(100);
-        this.sessions = await this.connection.listSessions(1_500).catch(() => this.connection.getSessions());
-        await this.connection.waitForToolsUpdate(500);
+        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;
         }
-        this.sessions = await this.connection.listSessions(1_500).catch(() => this.connection.getSessions());
+        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(this.connection.getConnectionErrorMessage());
+        if (!this.isBackendConnected() && this.tools.length === 0) {
+            throw new Error(this.getConnectionErrorMessage());
         }
     }
     async listSessions() {
-        this.sessions = await this.connection.listSessions(this.timeoutMs);
+        if (this.connection instanceof ExtensionConnection) {
+            this.sessions = await this.connection.listSessions(this.timeoutMs);
+        }
+        else {
+            this.sessions = [];
+        }
         return {
             ok: true,
             command: 'sessions',
@@ -359,29 +429,62 @@ class BrowserCliContext {
             sessions: this.sessions,
         };
     }
-    async status() {
-        this.sessions = await this.connection.listSessions(STATUS_TOOLS_TIMEOUT_MS).catch(() => this.connection.getSessions());
-        if (this.connection.isExtensionConnected()) {
+    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() {
@@ -473,7 +576,7 @@ class BrowserCliContext {
         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'],
+                names: ['take_snapshot'],
                 buildArgs: (tool) => withSnapshotArgs(tool, options),
             },
         ], {});
@@ -669,6 +772,37 @@ class BrowserCliContext {
         ], {});
         return this.outputFromInvocation('evaluate', invocation);
     }
+    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 upload(ref, path) {
+        const invocation = await this.callTool('upload', [
+            {
+                names: ['upload_file', 'file_upload'],
+                buildArgs: (tool) => withUploadArgs(tool, ref, path),
+            },
+        ], {});
+        return this.outputFromInvocation('upload', invocation);
+    }
+    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: ['handle_dialog'],
+                buildArgs: (tool) => withDialogArgs(tool, accept, options.promptText),
+            },
+        ], {});
+        return this.outputFromInvocation('dialog', invocation);
+    }
     async callGenericCommand(commandName, candidates, canonicalArgs) {
         const invocation = await this.callTool(commandName, candidates, canonicalArgs);
         return this.outputFromInvocation(commandName, invocation);
@@ -676,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));
@@ -700,34 +835,43 @@ class BrowserCliContext {
                         args[pageStateKey] = 'markdown';
                     }
                 }
-                const result = await this.connection.callTool(tool.name, args, this.timeoutMs);
-                return { tool: tool.name, args, result: result };
+                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(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) {
+        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) {
+                if (this.connection instanceof ExtensionConnection) {
                     this.tools = await this.connection.waitForToolsUpdate(1_000);
                 }
             }
         }
-        else {
-            this.tools = this.connection.getTools();
-        }
         this.toolsLoaded = true;
     }
     outputFromInvocation(commandName, invocation) {
@@ -749,6 +893,9 @@ class BrowserCliContext {
         if (!output.ok) {
             return output;
         }
+        if (!hasExplicitPageContext(invocation.args)) {
+            return output;
+        }
         const currentText = firstText(invocation.result);
         if (looksLikePageContentText(currentText) && !isLikelyIncompletePageContent(currentText, targetUrl)) {
             return output;
@@ -764,7 +911,7 @@ class BrowserCliContext {
         return {
             ...output,
             pageContent: fallback.content,
-            pageContentSource: 'take_md_snapshot',
+            pageContentSource: 'take_snapshot',
             ...(fallback.pageId !== targetPageId ? { pageId: fallback.pageId } : {}),
         };
     }
@@ -772,19 +919,11 @@ class BrowserCliContext {
         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) {
-            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;
         }
@@ -800,7 +939,7 @@ class BrowserCliContext {
             sessionId: this.currentSessionId(),
             requestedSessionId: this.requestedSessionId,
             ignoredCompatibilityOptions: this.ignoredCompatibilityOptions,
-            tool: 'take_md_snapshot',
+            tool: 'take_snapshot',
             recoveredFromTimeout: true,
             pageId: fallback.pageId,
             url,
@@ -852,7 +991,7 @@ class BrowserCliContext {
     }
     async takeMarkdownSnapshotForPage(pageId, timeoutMs = this.timeoutMs) {
         await this.ensureToolsLoaded();
-        const snapshotTool = this.tools.find((tool) => normalizeName(tool.name) === 'take_md_snapshot');
+        const snapshotTool = this.tools.find((tool) => normalizeName(tool.name) === 'take_snapshot');
         if (!snapshotTool) {
             return undefined;
         }
@@ -861,9 +1000,9 @@ class BrowserCliContext {
         if (pageKey) {
             args[pageKey] = pageId;
         }
-        const pageStateKey = hasProperty(snapshotTool, 'pageStateFormat', 'page_state_format');
-        if (pageStateKey) {
-            args[pageStateKey] = 'markdown';
+        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);
@@ -882,9 +1021,15 @@ class BrowserCliContext {
         }
     }
     mode() {
+        if (this.devtoolsOnly) {
+            return 'devtools';
+        }
         return this.remoteUuid ? 'remote' : 'local';
     }
     currentSessionId() {
+        if (this.devtoolsOnly) {
+            return undefined;
+        }
         if (this.remoteUuid) {
             return this.remoteUuid;
         }
@@ -896,6 +1041,30 @@ class BrowserCliContext {
         }
         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([
@@ -920,6 +1089,38 @@ function looksLikePageContentText(text) {
     }
     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) {
@@ -978,6 +1179,16 @@ 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;
@@ -1048,11 +1259,11 @@ function emitError(asJson, commandName, ctx, error) {
         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;
@@ -1458,6 +1669,12 @@ function withRequestDetailsArgs(tool, requestId) {
     maybeAssign(args, tool, 'reqid', requestId);
     return args;
 }
+function withResizeArgs(tool, width, height) {
+    const args = {};
+    maybeAssign(args, tool, 'width', width);
+    maybeAssign(args, tool, 'height', height);
+    return args;
+}
 function withRefArgs(tool, ref, extra = {}) {
     const args = { ...extra };
     const parsedRef = parseRef(ref);
@@ -1529,6 +1746,56 @@ function withFillFormArgs(tool, fields) {
     maybeAssign(args, tool, 'elements', fields);
     return args;
 }
+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 = {};
+    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) {
     const args = {};
     maybeAssign(args, tool, 'text', text);
@@ -1567,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 {