@browserless.io/mcp 1.6.2 → 1.7.0

package/build/src/skills/system-prompt.js

@@ -50,7 +50,10 @@ Load manually via **browserless_skill** if suspected but not injected:
 ## Selectors
 - Use **ref=** (CSS) or **deep-ref=** (starts \`< \`) exactly as shown in snapshot
 - Example: \`[3] button "Sign In" ref=button#submit\` → \`"button#submit"\`
-- deep-ref for shadow DOM — see \`shadow-dom\` skill
+- deep-ref for shadow DOM / iframes — see \`shadow-dom\` skill
+
+## Iframes
+Snapshots include a \`Frames\` list (cross-origin iframes) when present. Elements inside a frame are tagged \`[frame#N]\` and carry a \`deep-ref=< *url* css\` selector that already pierces the frame — pass it as-is to \`click\`/\`type\`/\`hover\`/\`checkbox\`. No frame switching needed. captcha/payment widgets (reCAPTCHA, hCaptcha, Stripe, Turnstile) show up here. \`shadow-dom\` skill auto-loads when frames present.
 
 ## Tabs
 Snapshots include \`tabs\` + \`activeTargetId\` — no getTabs needed. Multi-tab / \`snapshot { targetId }\` in \`tabs\` skill (auto-loads when >1 tab).
@@ -66,6 +69,17 @@ Only click when href is \`javascript:\` / \`#\` / missing.
 3. **evaluate** { content } — JS (IIFE): \`(() => { return ... })()\`
 4. **html** { selector } — raw HTML
 
+## Files (upload / download)
+**To download a file, DRIVE THE BROWSER — do not \`curl\`/\`wget\`/\`fetch\` the file yourself as a first move.** Many real downloads (login/cookie-gated, generated server-side on demand, or triggered by a click whose response headers force the download) have NO fetchable URL — a direct fetch silently gets the wrong bytes, an HTML error page, or 403. Click/goto in the agent and collect from the auto-surfaced ledger. The ONLY time a direct fetch is correct: the ledger hands you a URL to use — the single-use \`/download/<id>\` URL, or an over-cap \`sourceUrl\`. Reaching for \`curl\` first is a bug, not a shortcut.
+**NEVER read a file's bytes or base64 into this conversation, and NEVER split/reassemble/inline base64 by hand.** That is the wrong tool and will stall.
+- **Upload a local file (stdio)**: \`uploadFile { selector, files: [{ path }] }\` — the server reads + encodes it.
+- **Upload a local file (HTTP)**: the server can't read your disk. Stage it once over HTTP, then use the handle:
+  \`curl -s -F file=@"/path/to/file" "<MCP_BASE_URL>/upload?token=<TOKEN>"\` → returns \`{ "handle": "browserless-download://…" }\` → \`uploadFile { files: [{ handle }] }\`. (The path-rejection error gives you the exact command with your token + URL filled in.)
+- **Re-upload something from \`getDownloads\`**: pass its \`handle\` (works in both modes).
+- **Download**: just trigger it in the agent (click a download link, or goto the file URL). The captured file **auto-surfaces** as a notification on the agent response (filename/size/handle), never the bytes — the server waits for it to finish (bounded by size), so it usually lands on that same call. stdio: file already saved, you get its path. HTTP: a **single-use** \`curl … /download/<id>?token=\` URL — fetch only if you need it. Files over the cap aren't transferred — you get the source URL to fetch directly. Path/handle reuses in \`uploadFile\`. (No separate download tool — use the agent.)
+- base64 \`content\` is a LAST RESORT — tiny inline data only.
+- Full recipe: \`file-transfers\` skill.
+
 ## Batching — Maximize Per Call
 Plan ALL actions from snapshot before next snapshot.
 
@@ -112,6 +126,21 @@ Never retry same failed action without re-snapshot.
 - See schema for: screenshot, solve, back, forward, reload, click, type, select, checkbox, hover, scroll, text, html, waitForNavigation, waitForTimeout, waitForRequest, liveURL, getTabs, switchTab, closeTab
 
 `;
+// Transport-specific file-transfer guidance, appended to the agent tool
+// description so the model knows its mode UP FRONT — instead of guessing (and
+// base64-ing files it should pass by path). The server knows the transport; the
+// model can't introspect it.
+export const fileTransferModeNote = (transport, mcpBaseUrl) => transport === 'stdio'
+    ? `\n\n## Runtime: LOCAL (stdio)\n` +
+        `Before any file transfer, know your mode: this server runs over **stdio**, on the same machine as your files. ` +
+        `To UPLOAD a local file, pass its **\`path\`** straight to \`uploadFile\` (\`files: [{ path: "/abs/file" }]\`) — the server reads it. ` +
+        `**Do NOT base64 the file or read its bytes into the conversation.** ` +
+        `DOWNLOADS are saved to local disk; the agent response gives you the path.`
+    : `\n\n## Runtime: REMOTE (HTTP)\n` +
+        `Before any file transfer, know your mode: this server runs over **HTTP** and **cannot read your filesystem**. ` +
+        `To UPLOAD a local file, stage it once over HTTP, then use the handle:\n` +
+        `  \`curl -s -F file=@"/abs/file" "${mcpBaseUrl}/upload?token=<YOUR_TOKEN>"\` -> { "handle": "browserless-download://..." } -> \`uploadFile { files: [{ handle }] }\`.\n` +
+        `**Never base64 a file through the conversation.** DOWNLOADS come back with a single-use \`${mcpBaseUrl}/download/<id>\` URL.`;
 export const SKILL_TOOL_DESCRIPTION = `Load a Browserless agent skill on demand.
 
 Use this when you suspect the page exhibits a non-trivial mechanic but no SKILL block was auto-injected into a previous response. The auto-injection heuristics are conservative; calling this tool is the explicit fallback.
@@ -125,4 +154,5 @@ Available skills:
 - **screenshots** — when to screenshot vs. snapshot, scope and format choices
 - **tabs** — multi-tab workflows, peek-without-switching
 - **autonomous-login** — load before authenticating: when the user asked you to log in, when a wall blocks the task, or as soon as a password input appears. Covers the don't-login-by-default posture, contextual credential matching, MFA/captcha branches, and the required final JSON response shape.
-- **captchas** — the \`solve\` command, response semantics, escalation path (Cloud-only)`;
+- **captchas** — the \`solve\` command, response semantics, escalation path (Cloud-only)
+- **file-transfers** — \`uploadFile\` / \`getDownloads\`, stdio-path vs. base64 content, size caps`;

package/build/src/tools/agent.d.ts

@@ -12,4 +12,27 @@ export { buildCrossOriginNotice, formatConnectError, formatErrorMessage, formatS
 export declare const formatScreenshotContent: (result: unknown, cmd: {
     params?: Record<string, unknown>;
 }, caption: string, skills: string) => Content[] | null;
+type DownloadEntry = {
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    data?: string;
+    error?: string;
+    maxBytes?: number;
+    sourceUrl?: string;
+    inProgress?: boolean;
+    receivedBytes?: number;
+    totalBytes?: number;
+};
+export declare const normalizeUploadCommand: (cmd: {
+    method: string;
+    params: Record<string, unknown>;
+}, transport: McpConfig["transport"], mcpBaseUrl?: string) => Promise<void>;
+type FormatOpts = {
+    transport: McpConfig['transport'];
+    sessionId?: string;
+    mcpBaseUrl?: string;
+    token?: string;
+};
+export declare const formatDownloads: (downloads: DownloadEntry[], prefix: string, skills: string, opts: FormatOpts) => Promise<Content[]>;
 export declare function registerAgentTools(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/agent.js

@@ -1,11 +1,14 @@
 import { UserError } from 'fastmcp';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { z } from 'zod';
+import { downloadUri, getDownload, storeDownload, FILE_TRANSFER_MAX_BYTES, } from '../lib/download-store.js';
 import { getOrCreateSession, send, closeSession, destroySession, isRetryableUpgradeError, } from '../lib/agent-client.js';
 import { classifyAgentError } from '../lib/error-classifier.js';
 import { defineTool } from '../lib/define-tool.js';
 import { detectSkills, markFired, renderSkill, renderSkills, skillsRegistry, } from '../skills/index.js';
 import { AgentParamsSchema } from './schemas.js';
-import { AGENT_SYSTEM_PROMPT, SKILL_TOOL_DESCRIPTION, } from '../skills/system-prompt.js';
+import { AGENT_SYSTEM_PROMPT, SKILL_TOOL_DESCRIPTION, fileTransferModeNote, } from '../skills/system-prompt.js';
 import { buildCrossOriginNotice, formatConnectError, formatErrorMessage, formatSnapshot, } from '../lib/agent-format.js';
 // export schemas, system prompt, and formatters
 export { AgentParamsSchema } from './schemas.js';
@@ -53,10 +56,127 @@ export const formatScreenshotContent = (result, cmd, caption, skills) => {
         content.push({ type: 'text', text: skills });
     return content;
 };
-// Zod parses params at the tool boundary, so this only needs to supply the {}
-// default when the field was omitted — the schema never delivers a string,
-// array, or null here.
-const coerceParams = (params) => params ?? {};
+const fmtBytes = (n) => typeof n !== 'number'
+    ? '?'
+    : n >= 1_048_576
+        ? `${(n / 1_048_576).toFixed(1)}MB`
+        : `${Math.round(n / 1024)}KB`;
+// Still-downloading entry: report progress so the caller knows to touch the
+// browser again to collect it (no bytes, nothing to save yet).
+const describeInProgressDownload = (d) => {
+    const got = fmtBytes(d.receivedBytes);
+    const total = d.totalBytes && d.totalBytes > 0 ? ` / ${fmtBytes(d.totalBytes)}` : '';
+    return `${d.filename ?? 'file'} — downloading (${got}${total}); touch the browser again to collect it`;
+};
+// Resolve each uploadFile entry to base64 `content` (from `content`, a prior
+// `handle`, or a local `path` in stdio) so the model never emits base64 itself.
+export const normalizeUploadCommand = async (cmd, transport, mcpBaseUrl) => {
+    if (cmd.method !== 'uploadFile')
+        return;
+    const files = cmd.params.files;
+    if (!Array.isArray(files))
+        return;
+    for (const file of files) {
+        if (!file || typeof file !== 'object')
+            continue;
+        const f = file;
+        if (typeof f.content === 'string' && f.content)
+            continue;
+        let buf;
+        let defaultName;
+        if (typeof f.handle === 'string' && f.handle) {
+            const record = getDownload(f.handle);
+            if (!record) {
+                throw new UserError(`Unknown upload handle "${f.handle}". Pass a handle returned by ` +
+                    `getDownloads, or supply base64 "content".`);
+            }
+            buf = await readFile(record.path);
+            defaultName = record.filename;
+            delete f.handle;
+        }
+        else if (typeof f.path === 'string' && f.path) {
+            if (transport !== 'stdio') {
+                const base = mcpBaseUrl ?? '<MCP_BASE_URL>';
+                const tokenQ = '?token=<YOUR_BROWSERLESS_TOKEN>';
+                throw new UserError('uploadFile "path" is not available in HTTP mode (the server can\'t ' +
+                    'read your filesystem). Stage the file once over HTTP, then pass the ' +
+                    'returned handle — do NOT base64 it through the conversation:\n' +
+                    `  curl -s -F file=@"${f.path}" "${base}/upload${tokenQ}"\n` +
+                    'then: uploadFile { files: [{ handle: "<handle from the response>" }] }');
+            }
+            const path = f.path;
+            buf = await readFile(path).catch((e) => {
+                throw new UserError(`Failed to read upload file "${path}": ` +
+                    (e instanceof Error ? e.message : String(e)));
+            });
+            defaultName = basename(path);
+            delete f.path;
+        }
+        else {
+            continue;
+        }
+        if (buf.byteLength > FILE_TRANSFER_MAX_BYTES) {
+            throw new UserError(`Upload file "${defaultName}" is ${buf.byteLength} bytes, over the ` +
+                `50MB limit.`);
+        }
+        f.content = buf.toString('base64');
+        if (!f.name)
+            f.name = defaultName;
+    }
+};
+const describeFailedDownload = (d) => {
+    let s = `${d.filename ?? 'unknown'}: ${d.error ?? 'no data'}` +
+        (d.maxBytes ? ` (max ${d.maxBytes} bytes)` : '');
+    // Over-cap files can't go through the transfer flow — point at the source so
+    // the caller can fetch it directly (e.g. curl) if it has network access.
+    if (d.error === 'FileTooLarge' && d.sourceUrl) {
+        s += ` — too large to transfer; fetch directly: ${d.sourceUrl}`;
+    }
+    return s;
+};
+// Persist a download to the server's filesystem (out of the model's context),
+// tagged to the MCP session for cleanup. Returns null for failed/empty entries.
+const persistDownload = async (d, sessionId) => {
+    if (d.error || !d.data || !d.filename)
+        return null;
+    return storeDownload(d.filename, d.mimeType ?? 'application/octet-stream', Buffer.from(d.data, 'base64'), sessionId);
+};
+// stdio: file is already on the local disk → return its path (reuse as
+// uploadFile { path }). http: return a single-use GET URL + handle; base64
+// never enters context, and fetching consumes the file.
+const describeReadyDownload = (record, opts) => {
+    if (opts.transport === 'stdio') {
+        return (`${record.path} (${record.mimeType}, ${record.size} bytes) — ` +
+            `reuse as uploadFile { path: "${record.path}" }`);
+    }
+    const base = opts.mcpBaseUrl ?? '<MCP_BASE_URL>';
+    const tokenQ = `?token=${opts.token ?? '<YOUR_BROWSERLESS_TOKEN>'}`;
+    return (`${record.filename} (${record.mimeType}, ${record.size} bytes)\n` +
+        `    save it:  curl -s "${base}/download/${record.id}${tokenQ}" -o "${record.filename}"   (single use)\n` +
+        `    or reuse: uploadFile { files: [{ handle: "${downloadUri(record.id)}" }] }`);
+};
+// Surface captured downloads as metadata + how to retrieve them (never bytes).
+export const formatDownloads = async (downloads, prefix, skills, opts) => {
+    const lines = [];
+    for (const d of downloads) {
+        if (d.inProgress) {
+            lines.push(`- ${describeInProgressDownload(d)}`);
+            continue;
+        }
+        const record = await persistDownload(d, opts.sessionId);
+        lines.push(`- ${record ? describeReadyDownload(record, opts) : describeFailedDownload(d)}`);
+    }
+    const header = opts.transport === 'stdio'
+        ? 'Downloads:'
+        : 'Downloads (save the ones you need — each GET works once):';
+    const text = downloads.length
+        ? `${prefix}${header}\n${lines.join('\n')}`
+        : `${prefix}No new downloads.`;
+    const content = [{ type: 'text', text }];
+    if (skills)
+        content.push({ type: 'text', text: skills });
+    return content;
+};
 const SkillIdSchema = z.enum(skillsRegistry.map((s) => s.id));
 const SkillToolParamsSchema = z.object({
     id: SkillIdSchema.describe('The skill to load (see tool description for the full list).'),
@@ -85,7 +205,8 @@ export function registerAgentTools(server, config, analytics) {
     });
     defineTool(server, config, analytics, {
         name: 'browserless_agent',
-        description: AGENT_SYSTEM_PROMPT,
+        description: AGENT_SYSTEM_PROMPT +
+            fileTransferModeNote(config.transport, config.mcpBaseUrl),
         parameters: AgentParamsSchema,
         annotations: {
             title: 'Browserless Agent',
@@ -93,15 +214,16 @@ export function registerAgentTools(server, config, analytics) {
             destructiveHint: true,
             openWorldHint: true,
         },
-        run: async ({ params, log, analytics, token, apiUrl, sessionId: mcpSessionId, }) => {
+        run: async ({ params, log, analytics, token, apiUrl, sessionId: mcpSessionId, attachSessionId, }) => {
             const commands = params.commands && params.commands.length > 0
                 ? params.commands.map((c) => ({
                     method: c.method,
-                    params: coerceParams(c.params),
+                    params: c.params ?? {},
                 }))
-                : [{ method: params.method, params: coerceParams(params.params) }];
+                : [{ method: params.method, params: params.params ?? {} }];
             const proxy = params.proxy;
             const profile = params.profile;
+            const createProfile = params.createProfile;
             const sendAnalytics = (success) => {
                 analytics?.fireToolRequest(token, 'browserless_agent', {
                     methods: commands.map((c) => c.method).join(','),
@@ -113,6 +235,7 @@ export function registerAgentTools(server, config, analytics) {
                     proxy_sticky: !!proxy?.proxySticky,
                     proxy_external: !!proxy?.externalProxyServer,
                     profile_used: !!profile,
+                    create_profile: !!createProfile,
                 });
             };
             const proxyCmd = commands.find((c) => c.method === 'proxy');
@@ -122,14 +245,32 @@ export function registerAgentTools(server, config, analytics) {
                     'Recovery: call `close` to end the current session, then call browserless_agent again with the proxy options set at the top level (alongside `method`/`commands`), e.g. { "proxy": "residential", "proxyCountry": "us", "commands": [ ... ] }.');
             }
             if (commands.length === 1 && commands[0].method === 'close') {
-                closeSession(mcpSessionId, token, proxy, profile);
+                closeSession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
                 sendAnalytics(true);
                 return [{ type: 'text', text: 'Browser session closed.' }];
             }
+            // Open-only call: no real command (e.g. `createProfile`/`profile`/`proxy`
+            // set with no method/commands). Dispatching the empty-method default would
+            // make the agent route reject it as `Missing required id/method`, so just
+            // open (or reuse) the session and report it's ready for follow-up commands.
+            if (commands.length === 1 && !commands[0].method) {
+                try {
+                    await getOrCreateSession(mcpSessionId, apiUrl, token, proxy, profile, createProfile, attachSessionId);
+                }
+                catch (connErr) {
+                    sendAnalytics(false);
+                    throw new UserError(formatConnectError(connErr));
+                }
+                sendAnalytics(true);
+                const text = createProfile
+                    ? `Profile-creation session "${createProfile.name}" is open (non-headless). Send commands to drive the login, then call saveProfile.`
+                    : 'Browser session is open. Send commands to drive it.';
+                return [{ type: 'text', text }];
+            }
             const runCommands = async (isRetry) => {
                 let agentSession;
                 try {
-                    agentSession = await getOrCreateSession(mcpSessionId, apiUrl, token, proxy, profile);
+                    agentSession = await getOrCreateSession(mcpSessionId, apiUrl, token, proxy, profile, createProfile, attachSessionId);
                 }
                 catch (connErr) {
                     // No retry when the server gave a definitive 4xx — re-attempting
@@ -138,7 +279,7 @@ export function registerAgentTools(server, config, analytics) {
                     if (isRetry || !isRetryableUpgradeError(connErr)) {
                         throw new UserError(formatConnectError(connErr));
                     }
-                    destroySession(mcpSessionId, token, proxy, profile);
+                    destroySession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
                     return runCommands(true);
                 }
                 // Execute all commands sequentially
@@ -150,7 +291,7 @@ export function registerAgentTools(server, config, analytics) {
                 let crossOriginBaseline = agentSession.lastUrl;
                 for (const cmd of commands) {
                     if (cmd.method === 'close') {
-                        closeSession(mcpSessionId, token, proxy, profile);
+                        closeSession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
                         results.push({ method: 'close', result: { closed: true } });
                         closedDuringBatch = true;
                         break;
@@ -162,7 +303,7 @@ export function registerAgentTools(server, config, analytics) {
                         resp = await send(agentSession, cmd.method, cmd.params);
                     }
                     catch (sendErr) {
-                        destroySession(mcpSessionId, token, proxy, profile);
+                        destroySession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
                         const errMessage = sendErr instanceof Error ? sendErr.message : String(sendErr);
                         if (!isRetry) {
                             log.warn(`agent: ${cmd.method} failed (first attempt, retrying once): ${errMessage}`);
@@ -182,7 +323,7 @@ export function registerAgentTools(server, config, analytics) {
                     if (resp.error) {
                         const err = resp.error;
                         if (err.code && FATAL_CODES.has(err.code)) {
-                            destroySession(mcpSessionId, token, proxy, profile);
+                            destroySession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
                             if (!isRetry) {
                                 return runCommands(true);
                             }
@@ -253,13 +394,29 @@ export function registerAgentTools(server, config, analytics) {
                 if (!last) {
                     return [{ type: 'text', text: 'Browser session closed.' }];
                 }
-                // Snapshot: format as compact ref-based text
+                // Auto-surface files Chrome captured this batch so the model needn't call
+                // getDownloads. Skipped on explicit drain/close; a failed poll is ignored.
+                let autoDownloads = [];
+                if (!closedDuringBatch && last.method !== 'getDownloads') {
+                    try {
+                        const dl = await send(agentSession, 'getDownloads', {});
+                        autoDownloads =
+                            dl.result
+                                ?.downloads ?? [];
+                    }
+                    catch {
+                        // ignore — downloads will surface on a later call
+                    }
+                }
+                const skillsText = triggered.length > 0 ? renderSkills(triggered) : '';
+                let baseContent;
                 if (lastSnapshot) {
+                    // Snapshot: compact ref-based text.
                     const notice = buildCrossOriginNotice(crossOriginBaseline, lastSnapshot.url);
                     const noticeBlock = notice ? `${notice}\n\n` : '';
                     if (lastSnapshot.url)
                         agentSession.lastUrl = lastSnapshot.url;
-                    return [
+                    baseContent = [
                         {
                             type: 'text',
                             text: appendSkills(batchPrefix +
@@ -269,22 +426,47 @@ export function registerAgentTools(server, config, analytics) {
                         },
                     ];
                 }
-                // Screenshot: return as image content block (vision input ≈ 1.5K tokens
-                // vs. ~67K tokens if we dumped the base64 inline as text).
-                if (last.method === 'screenshot') {
-                    const content = formatScreenshotContent(lastResult, lastCmd, batchPrefix, triggered.length > 0 ? renderSkills(triggered) : '');
-                    if (content)
-                        return content;
+                else if (last.method === 'getDownloads') {
+                    // Explicit drain.
+                    const downloads = lastResult?.downloads ?? [];
+                    const prefix = batchPrefix + (closedSuffix ? `${closedSuffix}\n\n` : '');
+                    return await formatDownloads(downloads, prefix, skillsText, {
+                        transport: config.transport,
+                        sessionId: mcpSessionId,
+                        mcpBaseUrl: config.mcpBaseUrl,
+                        token,
+                    });
                 }
-                // Everything else: return as JSON text
-                return [
-                    {
-                        type: 'text',
-                        text: appendSkills(batchPrefix + JSON.stringify(lastResult, null, 2), triggered),
-                    },
-                ];
+                else {
+                    // Screenshot → image content block; otherwise JSON text.
+                    const shot = last.method === 'screenshot'
+                        ? formatScreenshotContent(lastResult, lastCmd, batchPrefix, skillsText)
+                        : null;
+                    baseContent = shot ?? [
+                        {
+                            type: 'text',
+                            text: appendSkills(batchPrefix + JSON.stringify(lastResult, null, 2), triggered),
+                        },
+                    ];
+                }
+                // Append the captured-download notification (metadata only, no bytes).
+                if (autoDownloads.length > 0) {
+                    const notice = await formatDownloads(autoDownloads, '', '', {
+                        transport: config.transport,
+                        sessionId: mcpSessionId,
+                        mcpBaseUrl: config.mcpBaseUrl,
+                        token,
+                    });
+                    baseContent = [...baseContent, ...notice];
+                }
+                return baseContent;
             };
             try {
+                // Resolve any local upload paths to base64 once, before the (possibly
+                // retried) send loop runs.
+                for (const cmd of commands) {
+                    await normalizeUploadCommand(cmd, config.transport, config.mcpBaseUrl);
+                }
                 const result = await runCommands(false);
                 sendAnalytics(true);
                 return result;

package/build/src/tools/schemas.d.ts

@@ -84,6 +84,12 @@ export declare const AgentCommandSchema: z.ZodUnion<readonly [z.ZodDiscriminated
         selector: z.ZodString;
         text: z.ZodString;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    method: z.ZodLiteral<"loadSecret">;
+    params: z.ZodObject<{
+        ref: z.ZodString;
+        selector: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     method: z.ZodLiteral<"select">;
     params: z.ZodObject<{
@@ -214,6 +220,21 @@ export declare const AgentCommandSchema: z.ZodUnion<readonly [z.ZodDiscriminated
         waitForImages: z.ZodOptional<z.ZodBoolean>;
         timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    method: z.ZodLiteral<"uploadFile">;
+    params: z.ZodObject<{
+        selector: z.ZodString;
+        files: z.ZodArray<z.ZodObject<{
+            content: z.ZodOptional<z.ZodString>;
+            handle: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            mimeType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    method: z.ZodLiteral<"getDownloads">;
+    params: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, z.core.$strip>>>;
 }, z.core.$strip>, z.ZodObject<{
     method: z.ZodLiteral<"close">;
     params: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, z.core.$strip>>>;
@@ -221,6 +242,23 @@ export declare const AgentCommandSchema: z.ZodUnion<readonly [z.ZodDiscriminated
     method: z.ZodString;
     params: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$strip>]>;
+declare const CreateProfileSchema: z.ZodObject<{
+    name: z.ZodString;
+    proxy: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"residential">>;
+        sticky: z.ZodOptional<z.ZodBoolean>;
+        country: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chrome: "chrome";
+        chromium: "chromium";
+        stealth: "stealth";
+    }>>;
+    stealth: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 export declare const AgentParamsSchema: z.ZodObject<{
     method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     params: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -308,6 +346,12 @@ export declare const AgentParamsSchema: z.ZodObject<{
             selector: z.ZodString;
             text: z.ZodString;
         }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        method: z.ZodLiteral<"loadSecret">;
+        params: z.ZodObject<{
+            ref: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         method: z.ZodLiteral<"select">;
         params: z.ZodObject<{
@@ -438,6 +482,21 @@ export declare const AgentParamsSchema: z.ZodObject<{
             waitForImages: z.ZodOptional<z.ZodBoolean>;
             timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        method: z.ZodLiteral<"uploadFile">;
+        params: z.ZodObject<{
+            selector: z.ZodString;
+            files: z.ZodArray<z.ZodObject<{
+                content: z.ZodOptional<z.ZodString>;
+                handle: z.ZodOptional<z.ZodString>;
+                path: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+                mimeType: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        method: z.ZodLiteral<"getDownloads">;
+        params: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, z.core.$strip>>>;
     }, z.core.$strip>, z.ZodObject<{
         method: z.ZodLiteral<"close">;
         params: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, z.core.$strip>>>;
@@ -458,9 +517,29 @@ export declare const AgentParamsSchema: z.ZodObject<{
         externalProxyServer: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     profile: z.ZodOptional<z.ZodString>;
+    createProfile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        proxy: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodLiteral<"residential">>;
+            sticky: z.ZodOptional<z.ZodBoolean>;
+            country: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodString>;
+            preset: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chrome: "chrome";
+            chromium: "chromium";
+            stealth: "stealth";
+        }>>;
+        stealth: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     rationale: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** A single validated agent command. */
 export type AgentCommand = z.infer<typeof AgentCommandSchema>;
 /** The full `browserless_agent` tool params (single command, batch, proxy, profile). */
 export type AgentParams = z.infer<typeof AgentParamsSchema>;
+/** Params for opening a profile-creation session (POST /profile passthrough). */
+export type CreateProfileParams = z.infer<typeof CreateProfileSchema>;
+export {};