@browserless.io/mcp 1.6.2 → 1.7.1

package/build/src/lib/http-auth.d.ts

@@ -0,0 +1,22 @@
+import type { McpConfig } from '../@types/types.js';
+export interface ResolvedBrowserlessAuth {
+    token: string;
+    apiUrl: string;
+    attachSessionId?: string;
+}
+export interface AuthInput {
+    authHeader?: string;
+    tokenQuery?: string;
+    apiUrlHeader?: string;
+    browserlessUrlQuery?: string;
+    sessionIdHeader?: string;
+    sessionIdQuery?: string;
+}
+/**
+ * Resolve a Browserless API token from an inbound HTTP request, in order:
+ * (1) Authorization header with a plain API key, (2) `?token=` query param,
+ * (3) Authorization header with a Supabase JWT → resolved via PostgREST.
+ * Throws when none is present/valid. Shared by the FastMCP `authenticate`
+ * callback and the custom `/upload` route so both gate on the same rules.
+ */
+export declare const resolveBrowserlessAuth: (input: AuthInput, config: Pick<McpConfig, "browserlessApiUrl" | "supabaseUrl" | "supabaseServiceRoleKey">) => Promise<ResolvedBrowserlessAuth>;

package/build/src/lib/http-auth.js

@@ -0,0 +1,33 @@
+import { resolveApiKey } from './account-resolver.js';
+/**
+ * Resolve a Browserless API token from an inbound HTTP request, in order:
+ * (1) Authorization header with a plain API key, (2) `?token=` query param,
+ * (3) Authorization header with a Supabase JWT → resolved via PostgREST.
+ * Throws when none is present/valid. Shared by the FastMCP `authenticate`
+ * callback and the custom `/upload` route so both gate on the same rules.
+ */
+export const resolveBrowserlessAuth = async (input, config) => {
+    const headerToken = input.authHeader?.startsWith('Bearer ')
+        ? input.authHeader.slice(7)
+        : input.authHeader;
+    const apiUrl = input.apiUrlHeader ?? input.browserlessUrlQuery ?? config.browserlessApiUrl;
+    // A pre-created session id to attach to, threaded by the autologin runner.
+    // The agent tool opens /chromium/agent?sessionId=<this> instead of doing its
+    // own POST /profile.
+    const attachSessionId = input.sessionIdHeader ?? input.sessionIdQuery ?? undefined;
+    // JWTs have 3 dot-separated base64url segments; plain API keys do not.
+    const isJwt = headerToken ? headerToken.split('.').length === 3 : false;
+    if (headerToken && !isJwt) {
+        return { token: headerToken, apiUrl, attachSessionId };
+    }
+    if (input.tokenQuery) {
+        return { token: input.tokenQuery, apiUrl, attachSessionId };
+    }
+    if (isJwt && headerToken) {
+        const { apiKey } = await resolveApiKey(config.supabaseUrl, config.supabaseServiceRoleKey, headerToken);
+        return { token: apiKey, apiUrl, attachSessionId };
+    }
+    throw new Error('No Browserless API token provided. ' +
+        'Pass it as Authorization: Bearer <token> header, ' +
+        '?token= query parameter, or authenticate via OAuth.');
+};

package/build/src/resources/download-route.d.ts

@@ -0,0 +1,16 @@
+import type { FastMCP } from 'fastmcp';
+import type { McpConfig } from '../@types/types.js';
+/**
+ * Registers `GET /download/:id` on the HTTP-stream server. getDownloads surfaces
+ * a download as a notification (metadata only) plus this URL; the client fetches
+ * the bytes out-of-band when it decides to save them — over plain HTTP, NOT
+ * through the conversation:
+ *
+ *   curl -s "<mcpBaseUrl>/download/<id>?token=<token>" -o ./file
+ *
+ * Single use: the file is removed from the store and disk once served (or after
+ * the 15-min TTL / session end, whichever comes first). Same token rules as the
+ * MCP surface. Only meaningful for httpStream; in stdio the file is already on
+ * the local disk at the path getDownloads reported.
+ */
+export declare function registerDownloadRoute(server: FastMCP, config: McpConfig): void;

package/build/src/resources/download-route.js

@@ -0,0 +1,53 @@
+import { readFile, rm } from 'node:fs/promises';
+import { consumeDownload } from '../lib/download-store.js';
+import { resolveBrowserlessAuth } from '../lib/http-auth.js';
+/**
+ * Registers `GET /download/:id` on the HTTP-stream server. getDownloads surfaces
+ * a download as a notification (metadata only) plus this URL; the client fetches
+ * the bytes out-of-band when it decides to save them — over plain HTTP, NOT
+ * through the conversation:
+ *
+ *   curl -s "<mcpBaseUrl>/download/<id>?token=<token>" -o ./file
+ *
+ * Single use: the file is removed from the store and disk once served (or after
+ * the 15-min TTL / session end, whichever comes first). Same token rules as the
+ * MCP surface. Only meaningful for httpStream; in stdio the file is already on
+ * the local disk at the path getDownloads reported.
+ */
+export function registerDownloadRoute(server, config) {
+    const app = server.getApp();
+    app.get('/download/:id', async (c) => {
+        try {
+            await resolveBrowserlessAuth({
+                authHeader: c.req.header('authorization'),
+                tokenQuery: c.req.query('token'),
+                apiUrlHeader: c.req.header('x-browserless-api-url'),
+                browserlessUrlQuery: c.req.query('browserlessUrl'),
+            }, config);
+        }
+        catch {
+            return c.json({ ok: false, error: 'Unauthorized' }, 401);
+        }
+        // Single-use: consume removes it from the registry so a second GET 404s.
+        const record = consumeDownload(c.req.param('id'));
+        if (!record) {
+            return c.json({
+                ok: false,
+                error: 'Not found (already fetched, expired, or unknown)',
+            }, 404);
+        }
+        try {
+            const data = await readFile(record.path);
+            c.header('Content-Type', record.mimeType);
+            c.header('Content-Disposition', `attachment; filename="${record.filename.replace(/"/g, '')}"`);
+            return c.body(data);
+        }
+        catch {
+            return c.json({ ok: false, error: 'File no longer available' }, 410);
+        }
+        finally {
+            // Drop the bytes once served (or on read failure) — single use.
+            void rm(record.path, { force: true }).catch(() => { });
+        }
+    });
+}

package/build/src/resources/upload-route.d.ts

@@ -0,0 +1,3 @@
+import type { FastMCP } from 'fastmcp';
+import type { McpConfig } from '../@types/types.js';
+export declare function registerUploadRoute(server: FastMCP, config: McpConfig): void;

package/build/src/resources/upload-route.js

@@ -0,0 +1,53 @@
+import { downloadUri, storeDownload, FILE_TRANSFER_MAX_BYTES, } from '../lib/download-store.js';
+import { resolveBrowserlessAuth } from '../lib/http-auth.js';
+// Registers `POST /upload` (httpStream only): clients push a file's bytes over
+// plain HTTP and get back a handle to pass to the agent's `uploadFile`.
+//   curl -s -F file=@/path/to/file "<mcpBaseUrl>/upload?token=<token>"
+// Same token as the MCP surface; the base64 never enters the model's context.
+export function registerUploadRoute(server, config) {
+    const app = server.getApp();
+    app.post('/upload', async (c) => {
+        // Raw Hono routes bypass FastMCP's authenticate, so gate the route on the
+        // same Browserless token rules as the MCP surface — no anonymous drops.
+        try {
+            await resolveBrowserlessAuth({
+                authHeader: c.req.header('authorization'),
+                tokenQuery: c.req.query('token'),
+                apiUrlHeader: c.req.header('x-browserless-api-url'),
+                browserlessUrlQuery: c.req.query('browserlessUrl'),
+            }, config);
+        }
+        catch {
+            return c.json({ ok: false, error: 'Unauthorized' }, 401);
+        }
+        let file;
+        try {
+            const body = await c.req.parseBody();
+            file = body.file;
+        }
+        catch {
+            return c.json({
+                ok: false,
+                error: 'Expected multipart/form-data with a "file" field',
+            }, 400);
+        }
+        if (!(file instanceof File)) {
+            return c.json({
+                ok: false,
+                error: 'Missing multipart "file" field (use -F file=@path)',
+            }, 400);
+        }
+        const buf = Buffer.from(await file.arrayBuffer());
+        if (buf.byteLength > FILE_TRANSFER_MAX_BYTES) {
+            return c.json({ ok: false, error: 'FileTooLarge', maxBytes: FILE_TRANSFER_MAX_BYTES }, 413);
+        }
+        const record = await storeDownload(file.name || 'upload', file.type || 'application/octet-stream', buf);
+        return c.json({
+            ok: true,
+            handle: downloadUri(record.id),
+            filename: record.filename,
+            mimeType: record.mimeType,
+            size: record.size,
+        });
+    });
+}

package/build/src/skills/auth-profile.md

@@ -0,0 +1,66 @@
+# Authenticated Profiles
+
+A **profile** is a server-side bundle of cookies, localStorage, and IndexedDB
+captured from a live agent session and replayed on future sessions that connect
+with `profile=<name>`. Use it whenever a task needs the browser to start
+already signed in.
+
+## Recipe — creating a profile
+
+1. **Open a creation session.** Call `browserless_agent` with a top-level
+   `createProfile` object — do NOT pass `profile` (the two are mutually
+   exclusive). The MCP tool calls `POST /profile` for you, attaches the WS
+   to the creation session, and gives you a non-headless browser with a
+   10-minute keepalive:
+   ```json
+   {
+     "createProfile": { "name": "github" },
+     "commands": [
+       { "method": "goto", "params": { "url": "https://github.com/login" } }
+     ]
+   }
+   ```
+2. **Drive the auth flow like a normal task.** Type credentials (use values
+   the user supplied — never invent them), submit, and handle any
+   MFA/CAPTCHA step. If a CAPTCHA appears, load the `captchas` skill and
+   run `solve`.
+3. **Verify you are actually signed in before saving.** Re-snapshot and
+   confirm at least one of:
+   - an authenticated-only element (account menu, "Sign out" link, avatar)
+   - the URL is the post-login destination (not `/login`, `/signin`, or an
+     error path)
+   - a known auth cookie name appears in `document.cookie`
+     If none of these hold, do NOT save — a logged-out profile is worse than
+     no profile.
+4. **Call `saveProfile`** as the next command (JSON-RPC, no `Browserless.`
+   prefix):
+   ```json
+   { "method": "saveProfile", "params": { "name": "github" } }
+   ```
+   Pass the same `name` you opened the session with. If a profile with that
+   name already exists for this token, the call returns `ok: false` with an
+   `error` saying the profile already exists. Don't retry `saveProfile` with the
+   same name — choose a different name, or tell the user a profile by that name
+   already exists.
+5. **Inspect the result.** A successful save returns:
+
+   ```json
+   {
+     "ok": true,
+     "profileId": "...",
+     "name": "github",
+     "cookieCount": 12,
+     "originCount": 3,
+     "skippedOriginsCount": 0,
+     "skippedIdbDatabasesCount": 0,
+     "skippedIdbStoresCount": 0
+   }
+   ```
+
+   - `cookieCount === 0` is a red flag — the site likely uses session-only
+     cookies or storage you can't capture. Tell the user.
+   - Any non-zero `skipped*` count means partial capture — surface it.
+
+6. **Close** the session. Tell the user the profile name and how to use it
+   ("future calls can pass `profile: \"github\"`"). Do not echo cookie
+   values or any captured state.

package/build/src/skills/autonomous-login.md

@@ -1,95 +1,96 @@
 # Autonomous Login
 
-Page wants auth. **Default: don't.** Logins are intrusive and can damage account state. Proceed only when both gates pass.
+Page wants auth. **Default: don't.** Logins are intrusive and can damage account state. Proceed only when the gates below pass.
 
-## Gate 1 — Login required for continuing _this_ task?
+## Gate 0 — Did you drop your session binding?
 
-If the user's task is literally "log in / post / DM", or needs login to continue, gate passed. For extract/read/observe tasks, check whether the wall actually blocks the goal:
+`profile` (and `proxy`) bind **each** call to its hydrated session. If an earlier call this flow was logged in but this one looks logged out, the cause is almost certainly a missing `profile`/`proxy` param on **this** call — not stale cookies. Re-issue the call **with** the binding before treating the wall as real. Never re-authenticate to repair a parameter you forgot to pass.
 
-- Target content already in DOM beneath the wall? Read it directly.
-- Dismiss available (`Maybe later`, `Skip`, modal `×`)? Click it.
-- Alternative path — public mirror, archive.org, RSS, JSON endpoint, deep link?
+## Gate 1 — Login required to continue _this_ task?
 
-If the rest of the task completes without auth → `LOGIN_NOT_NEEDED`. Wikipedia, public docs/news, public read-only profiles.
+Task is literally "log in / post / DM" or needs login to proceed → pass. For read/extract tasks, check the wall actually blocks the goal:
 
-## Gate 2 — Credentials unambiguously for _this_ site?
+- Content already in DOM beneath the wall → read it.
+- Dismiss available (`Maybe later`, `Skip`, `×`) → click it.
+- Alt path (public mirror, archive.org, RSS, JSON endpoint, deep link) → use it.
+
+Task completes without auth → `LOGIN_NOT_NEEDED` (Wikipedia, public docs/news, public read-only profiles).
 
-**Password is not required to pass Gate 2.** Many sites use magic-link / email-only / passkey auth — an email alone (or any contextually-matched identifier) can be sufficient. Don't preemptively fail Gate 2 because no password is in context; let the form tell you at runtime. Only fail Gate 2 if the form actually demands a credential type you don't have.
+## Gate 2 — Credentials unambiguously for _this_ site?
 
-Identified **contextually** by name-to-domain correspondence — fixed names not required. Bar is **extraordinary evidence**, not plausibility.
+**Password not required** — magic-link / email-only / passkey sites accept an email (or any contextually-matched identifier) alone. Don't fail early for a missing password; let the form demand it at runtime. Fail only if the form requires a credential type you lack.
 
-- ✅ `instagram.com` + `instagramHandle` / `instagramPassword`
-- ✅ `LOGIN_USERNAME` / `LOGIN_PASSWORD` paired with `LOGIN_TARGET_URL` whose host matches
-- ❌ `wikipedia.org` + `instagramHandle` (names belong to a different service)
-- ❌ Bare `username` / `password` with no domain qualifier (ambiguous)
+Match **contextually** by name-to-domain correspondence (fixed names not required). Bar is **extraordinary evidence**, not plausibility.
 
-Absent / ambiguous / multiple plausible pairs → `MISSING_CONTEXT`. TOTP follows the same rule.
+- ✅ `instagram.com` + `instagramHandle`/`instagramPassword`
+- ✅ `LOGIN_USERNAME`/`LOGIN_PASSWORD` + `LOGIN_TARGET_URL` host matches
+- ❌ `wikipedia.org` + `instagramHandle` (different service)
+- ❌ bare `username`/`password`, no domain qualifier (ambiguous)
 
----
+Absent / ambiguous / multiple plausible pairs → `MISSING_CONTEXT`. TOTP same rule.
 
-If either gate fails, stop and emit the matching `reason_code`. Rest runs only when both pass.
+Gate 1 or 2 fails → stop, emit the matching `reason_code`. (Gate 0 isn't a stop — it means fix the call and retry.) Continue only when both pass.
 
 ## Reach the form
 
 - Password input in snapshot → continue.
-- Sign-in link/button visible → click, wait, re-snapshot.
-- Email-first (username only): type username, click `Continue` / `Next`, `waitForSelector` on `input[type="password"]` (10000ms), re-snapshot.
-- After two transitions with no password input → `FORM_NOT_FOUND`.
+- Sign-in link/button → click, wait, re-snapshot.
+- Email-first → type username, click `Continue`/`Next`, `waitForSelector` on `input[type="password"]` (10000ms), re-snapshot.
+- Two transitions, still no password → `FORM_NOT_FOUND`.
 
 ## Sanity check
 
-Confirm login (not signup/reset): submit name is `Sign in` / `Log in` / `Continue` (not `Sign up` / `Register` / `Reset`), and exactly **one** password field present. Else `FORM_NOT_FOUND`.
+Login, not signup/reset: submit reads `Sign in`/`Log in`/`Continue` (not `Sign up`/`Register`/`Reset`) and exactly **one** password field. Else `FORM_NOT_FOUND`.
 
 ## Field selection (anchor off password)
 
-- **Password**: `input[type="password"]`. With multiples: matches `/password/i` and **not** `confirm|new password`.
-- **Username** (first match): same-form `input[type="email"]` → input matching `/email|username|user|login|account/i` → visible text/email/tel input immediately preceding the password in `ref` order.
-- **Submit** (first match): same-form button matching `/^(sign in|log in|login|continue|submit)$/i` → `button[type="submit"]` in form → the only non-SSO visible button (skip `Continue with Google` etc. unless context names that provider).
+- **Password**: `input[type="password"]`; with multiples, matches `/password/i` and not `confirm|new password`.
+- **Username** (first hit): same-form `input[type="email"]` → `/email|username|user|login|account/i` → visible text/email/tel input immediately preceding the password in `ref` order.
+- **Submit** (first hit): same-form button `/^(sign in|log in|login|continue|submit)$/i` → `button[type="submit"]` in form → the only non-SSO visible button (skip `Continue with Google` etc. unless context names that provider).
 
-Any missing → `FORM_NOT_FOUND` with what's missing.
+Anything missing → `FORM_NOT_FOUND` (say what's missing).
 
 ## Submit
 
-Single batched call (type username, type password, click submit) with Gate-2 values. Then `waitForNavigation` (10000ms) or `waitForResponse` on `*`. If both time out, verify anyway — page may have updated in place. Re-snapshot.
+One batched call (type username, type password, click submit) with Gate-2 values → `waitForNavigation` (10000ms) or `waitForResponse` on `*`. Both time out → verify anyway (page may update in place). Re-snapshot. **Never retype the same credentials to retry** — caller's call.
 
 ## Verify success (any one, priority order)
 
 1. URL no longer matches `/login|signin|sign-in|log-in|auth|sso|account\/sign/i`.
 2. Password input absent from new snapshot.
-3. Authed-state element matching `/log out|sign out|my account|profile|dashboard|avatar/i`.
+3. Authed element matching `/log out|sign out|my account|profile|dashboard|avatar/i`.
 
-If none holds:
+The visible account/display name will usually NOT equal the email or username you typed (it's the profile's display name, often a real name) — that's expected, NOT a mismatch. Never mark a login failed because the shown identity differs from the credential; judge only by the three signals above.
 
-- Form error matching `/invalid|incorrect|wrong|doesn'?t match|not recognized|please try again/i` → `INVALID_CREDENTIALS`.
-- Captcha indicator → invoke `captchas` skill, re-verify. Unsolvable → `CAPTCHA_BLOCKED`.
+None holds:
+
+- Error matching `/invalid|incorrect|wrong|doesn'?t match|not recognized|please try again/i` → `INVALID_CREDENTIALS`.
+- Captcha → invoke `captchas` skill, re-verify; unsolvable → `CAPTCHA_BLOCKED`.
 - MFA prompt → MFA branch.
 - No change, no error → `SUBMIT_NO_FEEDBACK`.
 
-**Never retype the same credentials to retry.** Caller's call.
-
 ## MFA branch
 
-Required when snapshot has `autocomplete="one-time-code"`, numeric input with `maxlength` ∈ {4, 6, 8}, or label/`name`/`placeholder` matching `/code|verification|otp|2fa|two[- ]?factor|authenticator/i`.
+Triggered by `autocomplete="one-time-code"`, numeric input with `maxlength` ∈ {4,6,8}, or label/`name`/`placeholder` matching `/code|verification|otp|2fa|two[- ]?factor|authenticator/i`.
 
-- Contextually-matched TOTP available (same Gate-2 rule) → type, click submit, re-verify.
-- **No matching TOTP in context → ask the user for the code in plain text and STOP this turn. Do not call `close`. Do not emit the final JSON block. Leave the agent session open so the next turn can resume — the OTP input is still on the page and the cookies/state are intact.** When the user replies with a code, treat it as the TOTP value, type + click submit + re-verify. If the user declines or says they don't have one → `MFA_INPUT_MISSING`. Never attempt SMS/email/WebAuthn flows.
-- TOTP rejected (`/invalid|expired|incorrect/i`) → ask user for a fresh code (same don't-close rule); after one fresh-code rejection → `MFA_FAILED`.
-- Second MFA prompt after first cleared → `UNEXPECTED_STATE`.
+- Contextually-matched TOTP (Gate-2 rule) → type, submit, re-verify.
+- **No matching TOTP → ask the user for the code in plain text and STOP this turn. Do NOT `close`, do NOT emit the final JSON. Leave the session open so the OTP input and cookies/state survive to next turn.** User replies → treat as the TOTP, type + submit + re-verify. User declines / has none → `MFA_INPUT_MISSING`. Never attempt SMS/email/WebAuthn.
+- TOTP rejected (`/invalid|expired|incorrect/i`) → ask for a fresh code (same don't-close rule); one fresh-code rejection → `MFA_FAILED`.
+- Second MFA prompt after the first cleared → `UNEXPECTED_STATE`.
 
 ## Final response
 
-Call `close`, then emit **exactly one** fenced JSON block — nothing before or after, no prose. Fields: `success`, `reason_code`, `final_url`, `evidence`, `steps_taken` (JSON-RPC call count; batched call = 1). On failure, `success: false` and `final_url` = current URL.
+`close`, then emit **exactly one** fenced JSON block — nothing before or after, no prose. Fields: `success`, `reason_code`, `final_url`, `evidence`, `steps_taken` (JSON-RPC call count; batched call = 1). On failure: `success: false`, `final_url` = current URL.
 
 `reason_code` ∈ `SUCCESS` | `LOGIN_NOT_NEEDED` | `MISSING_CONTEXT` | `INVALID_CREDENTIALS` | `MFA_INPUT_MISSING` | `MFA_FAILED` | `CAPTCHA_BLOCKED` | `FORM_NOT_FOUND` | `SUBMIT_NO_FEEDBACK` | `FIELD_TYPE_MISMATCH` | `UNEXPECTED_STATE`.
 
 ## Don't
 
 - Log in just because a form is visible — gates first.
-- Use credentials whose names don't unambiguously belong to this site.
-- Guess among multiple plausible pairs — `MISSING_CONTEXT`.
-- Retry with the same credentials after failure.
+- Re-authenticate to fix an apparent logout before confirming you passed `profile`/`proxy` (Gate 0).
+- Use credentials whose names don't unambiguously belong to this site; guess among plausible pairs (→ `MISSING_CONTEXT`); or retry the same credentials after failure.
 - Try SSO buttons unless the task names that provider.
 - `evaluate` to set input `value` — use `type` so real keystrokes fire.
 - Leak credentials into narration, errors, or non-`type.params.text` fields.
-- Emit anything other than the final JSON block in your last _terminal_ message (ask-the-user turns are not terminal — emit plain prose and stop without `close`).
-- Close the session while waiting for a user-supplied OTP — leave it open so cookies, page state, and the OTP input survive the round-trip.
+- Emit anything but the final JSON in your last _terminal_ message (ask-the-user turns aren't terminal — plain prose, stop, no `close`).
+- `close` while awaiting a user-supplied OTP — leave the session open so cookies, page state, and the OTP input survive the round-trip.

package/build/src/skills/file-transfers.md

@@ -0,0 +1,88 @@
+# File Uploads & Downloads
+
+Transferring files to/from the browser. Two methods: `uploadFile` (attach files to an `<input type="file">`) and `getDownloads` (retrieve files Chrome downloaded).
+
+**Do not `curl`/`wget`/`fetch` a file yourself to download it.** That only works for a public, static, directly-addressable URL — the easy case. The general case (files behind login/cookies, generated server-side on demand, or served by a click via `Content-Disposition` headers) has **no URL you can fetch**, and a direct fetch silently returns the wrong bytes, an HTML page, or a 403. **Drive the browser** (click/goto), and the file is captured for you. A direct fetch is only correct when this flow _hands you_ a URL (the single-use `/download/<id>` URL, or an over-cap `sourceUrl`).
+
+**Key idea — never move bytes through this conversation.** Large files as base64 blow up the context. So downloads come back as a _handle_ (a path or a `browserless-download://` URI), and uploads take that handle (or a local path) instead of base64. The MCP server reads/writes the actual bytes on disk; you only pass small references. Only fall back to base64 `content` when you genuinely have raw bytes and no handle.
+
+## Downloading
+
+Just trigger the download in the agent — navigate to the file URL, or click a download link/button:
+
+```json
+{
+  "commands": [
+    { "method": "goto", "params": { "url": "https://example.com/report.csv" } }
+  ]
+}
+```
+
+- Captured downloads **auto-surface**: every agent response carries the current download ledger — **never the bytes**. You don't need to call anything to see it.
+- A short, size-scaled grace wait lets quick downloads land on the **same** call. A slower one shows up as **in-progress with a byte count** ("downloading 2.0MB / 10MB") — just keep using the browser; it'll appear completed on a later response. As long as you keep touching the browser, the download state stays fresh.
+- Files **larger than the cap** aren't transferred: you get a `FileTooLarge` note with the **source URL** — fetch it directly (e.g. `curl`) if you have network access.
+- You decide whether to save each file. (`getDownloads` still exists for an explicit poll, but it's rarely needed.)
+
+**Local (stdio) mode:** the file is already on the local disk (`BROWSERLESS_DOWNLOAD_DIR`, default a temp dir). The response lists the saved **path** — use/move it, or hand it straight back to `uploadFile { path }`. Nothing more to fetch.
+
+**Remote (HTTP) mode:** the server can't write to your disk, so each file comes with a **single-use** GET URL. Fetch it with `curl` to save locally — works **once**:
+
+```bash
+curl -s "<MCP_BASE_URL>/download/<id>?token=<YOUR_BROWSERLESS_TOKEN>" -o "report.csv"
+```
+
+The exact command (with id + token + URL) is in the `getDownloads` response. Alternatively, reuse the handle as `uploadFile { files: [{ handle: "browserless-download://<id>" }] }` to re-upload it elsewhere without ever fetching the bytes. A file is dropped after one GET, after 15 minutes, or when the session ends — whichever comes first.
+
+## Uploading
+
+```json
+{
+  "method": "uploadFile",
+  "params": {
+    "selector": "input[type=file]",
+    "files": [
+      { "handle": "browserless-download://abc-1", "name": "report.pdf" }
+    ]
+  }
+}
+```
+
+Each file is resolved in this order — pick the first you have:
+
+- **`handle`** — a handle from a previous `getDownloads`, or from staging a local file (below). The server reads the stored file. Works in **both** transports. This is how you re-upload a file you just downloaded — zero bytes through the conversation.
+- **`path`** — a local filesystem path. **stdio only** (HTTP can't read your filesystem). The server reads and encodes it.
+- **`content`** — base64 bytes. Last resort; avoid for large files.
+
+### Uploading a NEW local file in HTTP mode
+
+The server can't read your filesystem, so stage the file once over HTTP (bytes go via `curl`, never through the conversation), then use the returned handle:
+
+```bash
+curl -s -F file=@"/path/to/file.png" "<MCP_BASE_URL>/upload?token=<YOUR_BROWSERLESS_TOKEN>"
+# → { "ok": true, "handle": "browserless-download://abc-1", "filename": "file.png", ... }
+```
+
+The `/upload` route requires your Browserless token (`?token=` or `Authorization: Bearer`). The `uploadFile` path-rejection error gives you the exact command with the token filled in.
+
+```json
+{
+  "method": "uploadFile",
+  "params": {
+    "selector": "input[type=file]",
+    "files": [{ "handle": "browserless-download://abc-1" }]
+  }
+}
+```
+
+Staged files share the download store (15-minute TTL). **Never** base64 a file into `content` by hand — that's what staging avoids.
+
+Other params:
+
+- `selector` — the file input. If hidden behind a styled button, the input still exists in the DOM; target it directly (use a deep selector — prefix `<` followed by a space — for shadow DOM).
+- `name` / `mimeType` — optional; default from the handle/path, mimeType inferred from the extension.
+- Triggers native `input`/`change` events, so frameworks (React, etc.) see the file.
+- Returns `{ "ok": true }`, or `{ "ok": false, "error": "SelectorNotFound" | "InvalidTarget" | "FileTooLarge" }`.
+
+## Size limits
+
+Uploads and downloads are capped (server default 10MB, hard max 50MB). Oversized downloads report `error: "FileTooLarge"` (metadata, no data); oversized uploads return `ok: false, error: "FileTooLarge"`.

package/build/src/skills/index.js

@@ -11,6 +11,7 @@ const LOGIN_URL_RE = /\/(login|signin|sign-?in|log-?in|auth|sso|oauth)\b|\/accou
 const LOGIN_NUDGE_RE = /sign in to (view|see|continue|access|read|comment|post|reply|save|order|buy|checkout|your account)|please sign in|signed out\b.*sign in|create (an )?account to/i;
 const TAB_ERROR_CODES = ['TAB_NOT_FOUND', 'TAB_CLOSED', 'TAB_LIMIT_EXCEEDED'];
 const TAB_COMMAND_METHODS = ['getTabs', 'switchTab', 'createTab', 'closeTab'];
+const FILE_TRANSFER_METHODS = ['uploadFile', 'getDownloads'];
 const evalPredicate = (p, ctx) => {
     switch (p.kind) {
         case 'snapshot.has-element': {
@@ -145,6 +146,24 @@ const SKILL_SPECS = [
             ],
         ],
     },
+    {
+        // No auto-fire triggers: there is no snapshot/error/command signal for
+        // "about to create a profile". The model loads it by id via
+        // browserless_skill, prompted by the createProfile field description.
+        id: 'auth-profile',
+        path: 'src/skills/auth-profile.md',
+        triggers: [],
+    },
+    {
+        id: 'file-transfers',
+        path: 'src/skills/file-transfers.md',
+        triggers: [
+            // A file input on the page — uploads are likely next.
+            [{ kind: 'snapshot.has-input-type', type: 'file' }],
+            // The model issued an upload/download command.
+            [{ kind: 'command.method', methods: FILE_TRANSFER_METHODS }],
+        ],
+    },
     {
         id: 'captchas',
         path: 'src/skills/captchas.md',

package/build/src/skills/shadow-dom.md

@@ -2,6 +2,15 @@
 
 Snapshot contains `deep-ref=` selectors, or you hit `SELECTOR_NOT_FOUND` on regular selector. Page using shadow DOM or iframes — read before next action.
 
+## Iframes in the snapshot
+
+Iframes (same-origin and cross-origin) are now snapshotted too. When present:
+
+- Snapshot shows a `Frames (N iframes):` block listing each frame's label, URL, and origin.
+- Elements inside a frame are tagged `[frame#N]` and carry a ready `deep-ref=` selector — cross-origin uses `< *url* css`, same-origin uses `< css`. Pass it as-is to `click`/`type`/`hover`/`checkbox` — no frame switching, no hand-construction.
+
+Only build a deep selector by hand (below) when a frame element wasn't surfaced (a11y-empty widget, capped snapshot).
+
 ## Deep selectors: `< ` prefix
 
 Browserless deep selectors start with `< ` (less-than, space). Space mandatory. Format:
@@ -20,7 +29,7 @@ When snapshot lists `deep-ref=< button#deny`, pass to `click` / `type` / `hover`
 
 ## Constructing deep selectors for iframes snapshot didn't surface
 
-Snapshots only include accessible content. Iframes (captcha/payment widgets) often have nothing meaningful in accessibility tree. Build selector by hand:
+Fallback only — most cross-origin iframes are now in the snapshot (see above). Some widgets still have nothing meaningful in the accessibility tree. Build selector by hand:
 
 - `< *google.com/recaptcha* #recaptcha-anchor` — reCAPTCHA checkbox
 - `< *hcaptcha.com* #checkbox` — hCaptcha checkbox

package/build/src/skills/system-prompt.d.ts

@@ -1,2 +1,3 @@
-export declare const AGENT_SYSTEM_PROMPT = "Execute browser commands in persistent agent session.\n\n## Proxy (optional)\nProxy config is a **top-level tool argument** (`proxy`, `proxyCountry`, etc. on the tool call itself) \u2014 it is applied when the session is opened. **NEVER call `proxy` as a method inside `commands`** \u2014 a `{ method: \"proxy\", ... }` JSON-RPC mutation does NOT change the upstream proxy on an already-open session and will silently no-op.\n\n**If there is credible evidence the task needs a proxy, you MUST pass proxy options on the very FIRST call** (before any `goto`/`snapshot`), because the config is read once at session creation. Credible signals include: the user asks for a specific country/region/locale; the target site is known to geo-restrict or block datacenter IPs (streaming, ticketing, retail, banking, real-estate, news paywalls); a prior attempt returned 403/451/captcha/\"unusual traffic\"/\"access denied\"; the user explicitly mentions residential / sticky IP / proxy.\n\nIf you already opened a session without a proxy and now realize one is needed, you must `close` and start a new session with the proxy options set \u2014 there is no in-session switch.\n\n- `proxy: \"residential\"` \u2014 enable routing; `proxyCountry: \"us\"` \u2014 geo (ISO-2); `proxyState` / `proxyCity` (paid plans, 401 otherwise); `proxySticky: true` \u2014 stable IP; `proxyLocaleMatch: true` \u2014 match locale; `proxyPreset` \u2014 named config; `externalProxyServer: \"http://u:p@host:port\"` \u2014 bring your own (http(s) only)\n- Geo/preset/sticky require `proxy: \"residential\"` or `externalProxyServer` set\n\n## Auth\nNever log in by default. Never invent or assume credentials exist (no \"test credentials\", no \"your account\"). If the snapshot contains a sign-in link OR you're about to mention \"sign in\" / \"log in\" / \"auth required\" \u2014 even as a suggested option to the user \u2014 call `browserless_skill { id: \"autonomous-login\" }` **first**, then follow its gates. The skill decides whether login is appropriate and whether credentials are in scope; do not skip it just because no password field is on the page yet.\n\n## Terminal-Goal Check\nBefore declaring done, restate the user's terminal deliverable in one line and verify your evidence *directly* supports it \u2014 not a sibling question.\n**Empty-state substitution.** An empty/zero/null result from a resource that normally requires auth, scope, or filter context is evidence the *precondition* wasn't met \u2014 not evidence the question is answered. Empty cart while logged out, zero results while geo-restricted, empty inbox while unauthenticated: precondition failure \u2192 fix the precondition (often: load `autonomous-login`), don't return the empty result as the answer.\n**Multi-step preconditions.** When the task names multiple steps (\"go to X, then Y, report Z\"), evaluate preconditions for the *full chain* before treating any step as optional. A blocker on step N blocks the whole task even if step 1 returned data.\n\n## Skills (auto-injected)\nSKILL blocks auto-inject between `--- SKILL: <id> ---` markers when page/error needs special handling. Read carefully.\nLoad manually via **browserless_skill** if suspected but not injected:\n- `autonomous-login` \u2014 gates, credential rules, MFA/captcha, final JSON shape (see `## Auth` above for when to load)\n- `shadow-dom` \u2014 deep selectors, iframe targeting\n- `cookie-consent` \u2014 vendor-specific dismiss recipes\n- `modals` \u2014 closing dialogs and alertdialogs\n- `captchas` \u2014 the `solve` command (Cloud only)\n- `snapshot-misses` \u2014 truncated/empty snapshots, image-rendered content\n- `dynamic-content` \u2014 choosing the right `wait*` method\n- `screenshots` \u2014 when to screenshot vs. snapshot, scope and format choices\n- `tabs` \u2014 multi-tab workflows, peek-without-switching\n\n## Core Loop (ReAct: Reason \u2192 Act \u2192 Observe)\n1. **goto** \u2014 waits \"domcontentloaded\"\n2. **snapshot** \u2014 returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors\n3. **Plan** all actions from snapshot\n4. **Batch** execute\n5. **Re-snapshot** only if page changed\n6. Repeat \u2192 **close** when done\n\n## Snapshot Rules\n- Until you snapshot a page, you CANNOT click/type/interact \u2014 snapshot first, no exceptions\n- NEVER guess, assume, or infer selectors \u2014 CSS selectors from your training data are wrong. ONLY use ref= / deep-ref= from latest snapshot\n- Snapshot STALE after: click, goto, select, navigation\n- Snapshot VALID after: type, hover, scroll, evaluate\n- Expect new content? \u2192 re-snapshot\n- Element roles in snapshot (link, button, textbox, combobox, checkbox, heading) tell you what each does\n\n## Selectors\n- Use **ref=** (CSS) or **deep-ref=** (starts `< `) exactly as shown in snapshot\n- Example: `[3] button \"Sign In\" ref=button#submit` \u2192 `\"button#submit\"`\n- deep-ref for shadow DOM \u2014 see `shadow-dom` skill\n\n## Tabs\nSnapshots include `tabs` + `activeTargetId` \u2014 no getTabs needed. Multi-tab / `snapshot { targetId }` in `tabs` skill (auto-loads when >1 tab).\n\n## Links\n**Prefer goto over click** for links with href \u2014 immune to layout shifts, overlays, misclicks.\nExample: `[5] a \"About\" ref=a[href='/about']` \u2192 `goto { url: \"https://ex.com/about\" }`\nOnly click when href is `javascript:` / `#` / missing.\n\n## Content Extraction\n1. Check in-memory snapshot (text/values already there)\n2. **text** { selector } \u2014 from specific element\n3. **evaluate** { content } \u2014 JS (IIFE): `(() => { return ... })()`\n4. **html** { selector } \u2014 raw HTML\n\n## Batching \u2014 Maximize Per Call\nPlan ALL actions from snapshot before next snapshot.\n\n**Process:**\n1. Classify actions: **safe** (type, hover, scroll, evaluate, select, checkbox) vs. **page-changing** (click, goto)\n2. Batch: safe FIRST \u2192 page-changing LAST\n3. For forms: if submit button is in snapshot, batch type + click in one call\n4. Don't batch across navigations\n\n**Example form:**\n```json\n{ \"commands\": [\n  { \"method\": \"type\", \"params\": { \"selector\": \"input#email\", \"text\": \"j@d.com\" } },\n  { \"method\": \"click\", \"params\": { \"selector\": \"button#submit\" } }\n] }\n```\n\n## Async\nAfter async triggers (search, submit), use `wait*` before snapshot \u2014 `waitForResponse` best when API URL known. `dynamic-content` skill auto-loads on timeout. Never `evaluate` with setTimeout.\n\n## Error Recovery\nErrors tagged `Category: <NAME>`:\n- **SELECTOR_MISS** \u2014 re-snapshot; retry `< selector` if not already deep-ref\n- **SESSION_LOST** \u2014 a fresh session was opened automatically; re-goto + snapshot (prior state gone)\n- **UNAUTHORIZED** / **FORBIDDEN** \u2014 pick different path\n- **NOT_FOUND** \u2014 different URL\n- **SERVER_ERROR** \u2014 backoff, retry once\n- **NAVIGATION_FAILED** \u2014 verify URL\n- **TIMEOUT** \u2014 longer wait or different signal\n- **INVALID_PARAMS** \u2014 fix params (schema authoritative)\n- **UNKNOWN** \u2014 re-snapshot + re-plan\n\n`! NOTICE: URL changed cross-origin` = prior plan/refs invalid, re-plan.\nNever retry same failed action without re-snapshot.\n\n## Methods (non-obvious)\n- **goto** { url, waitUntil? } \u2014 default \"domcontentloaded\"; prefer over click for links\n- **snapshot** { maxElements?, targetId? } \u2014 cap 500; targetId peeks non-active tab\n- **evaluate** { content } \u2014 IIFE only\n- **waitForSelector** { selector, timeout? } \u2014 set 5000-10000ms\n- **waitForResponse** { url?, statuses?, timeout? } \u2014 url is glob `\"*api/results*\"`\n- **createTab** { url?, activate?, waitUntil? } \u2014 default activate: true; false = background\n- **close** \u2014 own call, NOT batched; only when task complete (premature close discards page state)\n- See schema for: screenshot, solve, back, forward, reload, click, type, select, checkbox, hover, scroll, text, html, waitForNavigation, waitForTimeout, waitForRequest, liveURL, getTabs, switchTab, closeTab\n\n";
-export declare const SKILL_TOOL_DESCRIPTION = "Load a Browserless agent skill on demand.\n\nUse 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.\n\nAvailable skills:\n- **shadow-dom** \u2014 deep selectors, iframe URL-pattern syntax, what works through deep-ref\n- **cookie-consent** \u2014 vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, etc.)\n- **modals** \u2014 close-button heuristics, ESC handling, alertdialog vs. dialog\n- **snapshot-misses** \u2014 truncated/empty snapshots, image-rendered content\n- **dynamic-content** \u2014 choosing the right `wait*` method after async triggers\n- **screenshots** \u2014 when to screenshot vs. snapshot, scope and format choices\n- **tabs** \u2014 multi-tab workflows, peek-without-switching\n- **autonomous-login** \u2014 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.\n- **captchas** \u2014 the `solve` command, response semantics, escalation path (Cloud-only)";
+export declare const AGENT_SYSTEM_PROMPT = "Execute browser commands in persistent agent session.\n\n## Proxy (optional)\nProxy config is a **top-level tool argument** (`proxy`, `proxyCountry`, etc. on the tool call itself) \u2014 it is applied when the session is opened. **NEVER call `proxy` as a method inside `commands`** \u2014 a `{ method: \"proxy\", ... }` JSON-RPC mutation does NOT change the upstream proxy on an already-open session and will silently no-op.\n\n**If there is credible evidence the task needs a proxy, you MUST pass proxy options on the very FIRST call** (before any `goto`/`snapshot`), because the config is read once at session creation. Credible signals include: the user asks for a specific country/region/locale; the target site is known to geo-restrict or block datacenter IPs (streaming, ticketing, retail, banking, real-estate, news paywalls); a prior attempt returned 403/451/captcha/\"unusual traffic\"/\"access denied\"; the user explicitly mentions residential / sticky IP / proxy.\n\nIf you already opened a session without a proxy and now realize one is needed, you must `close` and start a new session with the proxy options set \u2014 there is no in-session switch.\n\n- `proxy: \"residential\"` \u2014 enable routing; `proxyCountry: \"us\"` \u2014 geo (ISO-2); `proxyState` / `proxyCity` (paid plans, 401 otherwise); `proxySticky: true` \u2014 stable IP; `proxyLocaleMatch: true` \u2014 match locale; `proxyPreset` \u2014 named config; `externalProxyServer: \"http://u:p@host:port\"` \u2014 bring your own (http(s) only)\n- Geo/preset/sticky require `proxy: \"residential\"` or `externalProxyServer` set\n\n## Auth\nNever log in by default. Never invent or assume credentials exist (no \"test credentials\", no \"your account\"). If the snapshot contains a sign-in link OR you're about to mention \"sign in\" / \"log in\" / \"auth required\" \u2014 even as a suggested option to the user \u2014 call `browserless_skill { id: \"autonomous-login\" }` **first**, then follow its gates. The skill decides whether login is appropriate and whether credentials are in scope; do not skip it just because no password field is on the page yet.\n\n## Terminal-Goal Check\nBefore declaring done, restate the user's terminal deliverable in one line and verify your evidence *directly* supports it \u2014 not a sibling question.\n**Empty-state substitution.** An empty/zero/null result from a resource that normally requires auth, scope, or filter context is evidence the *precondition* wasn't met \u2014 not evidence the question is answered. Empty cart while logged out, zero results while geo-restricted, empty inbox while unauthenticated: precondition failure \u2192 fix the precondition (often: load `autonomous-login`), don't return the empty result as the answer.\n**Multi-step preconditions.** When the task names multiple steps (\"go to X, then Y, report Z\"), evaluate preconditions for the *full chain* before treating any step as optional. A blocker on step N blocks the whole task even if step 1 returned data.\n\n## Skills (auto-injected)\nSKILL blocks auto-inject between `--- SKILL: <id> ---` markers when page/error needs special handling. Read carefully.\nLoad manually via **browserless_skill** if suspected but not injected:\n- `autonomous-login` \u2014 gates, credential rules, MFA/captcha, final JSON shape (see `## Auth` above for when to load)\n- `shadow-dom` \u2014 deep selectors, iframe targeting\n- `cookie-consent` \u2014 vendor-specific dismiss recipes\n- `modals` \u2014 closing dialogs and alertdialogs\n- `captchas` \u2014 the `solve` command (Cloud only)\n- `snapshot-misses` \u2014 truncated/empty snapshots, image-rendered content\n- `dynamic-content` \u2014 choosing the right `wait*` method\n- `screenshots` \u2014 when to screenshot vs. snapshot, scope and format choices\n- `tabs` \u2014 multi-tab workflows, peek-without-switching\n\n## Core Loop (ReAct: Reason \u2192 Act \u2192 Observe)\n1. **goto** \u2014 waits \"domcontentloaded\"\n2. **snapshot** \u2014 returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors\n3. **Plan** all actions from snapshot\n4. **Batch** execute\n5. **Re-snapshot** only if page changed\n6. Repeat \u2192 **close** when done\n\n## Snapshot Rules\n- Until you snapshot a page, you CANNOT click/type/interact \u2014 snapshot first, no exceptions\n- NEVER guess, assume, or infer selectors \u2014 CSS selectors from your training data are wrong. ONLY use ref= / deep-ref= from latest snapshot\n- Snapshot STALE after: click, goto, select, navigation\n- Snapshot VALID after: type, hover, scroll, evaluate\n- Expect new content? \u2192 re-snapshot\n- Element roles in snapshot (link, button, textbox, combobox, checkbox, heading) tell you what each does\n\n## Selectors\n- Use **ref=** (CSS) or **deep-ref=** (starts `< `) exactly as shown in snapshot\n- Example: `[3] button \"Sign In\" ref=button#submit` \u2192 `\"button#submit\"`\n- deep-ref for shadow DOM / iframes \u2014 see `shadow-dom` skill\n\n## Iframes\nSnapshots 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 \u2014 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.\n\n## Tabs\nSnapshots include `tabs` + `activeTargetId` \u2014 no getTabs needed. Multi-tab / `snapshot { targetId }` in `tabs` skill (auto-loads when >1 tab).\n\n## Links\n**Prefer goto over click** for links with href \u2014 immune to layout shifts, overlays, misclicks.\nExample: `[5] a \"About\" ref=a[href='/about']` \u2192 `goto { url: \"https://ex.com/about\" }`\nOnly click when href is `javascript:` / `#` / missing.\n\n## Content Extraction\n1. Check in-memory snapshot (text/values already there)\n2. **text** { selector } \u2014 from specific element\n3. **evaluate** { content } \u2014 JS (IIFE): `(() => { return ... })()`\n4. **html** { selector } \u2014 raw HTML\n\n## Files (upload / download)\n**To download a file, DRIVE THE BROWSER \u2014 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 \u2014 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 \u2014 the single-use `/download/<id>` URL, or an over-cap `sourceUrl`. Reaching for `curl` first is a bug, not a shortcut.\n**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.\n- **Upload a local file (stdio)**: `uploadFile { selector, files: [{ path }] }` \u2014 the server reads + encodes it.\n- **Upload a local file (HTTP)**: the server can't read your disk. Stage it once over HTTP, then use the handle:\n  `curl -s -F file=@\"/path/to/file\" \"<MCP_BASE_URL>/upload?token=<TOKEN>\"` \u2192 returns `{ \"handle\": \"browserless-download://\u2026\" }` \u2192 `uploadFile { files: [{ handle }] }`. (The path-rejection error gives you the exact command with your token + URL filled in.)\n- **Re-upload something from `getDownloads`**: pass its `handle` (works in both modes).\n- **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 \u2014 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 \u2026 /download/<id>?token=` URL \u2014 fetch only if you need it. Files over the cap aren't transferred \u2014 you get the source URL to fetch directly. Path/handle reuses in `uploadFile`. (No separate download tool \u2014 use the agent.)\n- base64 `content` is a LAST RESORT \u2014 tiny inline data only.\n- Full recipe: `file-transfers` skill.\n\n## Batching \u2014 Maximize Per Call\nPlan ALL actions from snapshot before next snapshot.\n\n**Process:**\n1. Classify actions: **safe** (type, hover, scroll, evaluate, select, checkbox) vs. **page-changing** (click, goto)\n2. Batch: safe FIRST \u2192 page-changing LAST\n3. For forms: if submit button is in snapshot, batch type + click in one call\n4. Don't batch across navigations\n\n**Example form:**\n```json\n{ \"commands\": [\n  { \"method\": \"type\", \"params\": { \"selector\": \"input#email\", \"text\": \"j@d.com\" } },\n  { \"method\": \"click\", \"params\": { \"selector\": \"button#submit\" } }\n] }\n```\n\n## Async\nAfter async triggers (search, submit), use `wait*` before snapshot \u2014 `waitForResponse` best when API URL known. `dynamic-content` skill auto-loads on timeout. Never `evaluate` with setTimeout.\n\n## Error Recovery\nErrors tagged `Category: <NAME>`:\n- **SELECTOR_MISS** \u2014 re-snapshot; retry `< selector` if not already deep-ref\n- **SESSION_LOST** \u2014 a fresh session was opened automatically; re-goto + snapshot (prior state gone)\n- **UNAUTHORIZED** / **FORBIDDEN** \u2014 pick different path\n- **NOT_FOUND** \u2014 different URL\n- **SERVER_ERROR** \u2014 backoff, retry once\n- **NAVIGATION_FAILED** \u2014 verify URL\n- **TIMEOUT** \u2014 longer wait or different signal\n- **INVALID_PARAMS** \u2014 fix params (schema authoritative)\n- **UNKNOWN** \u2014 re-snapshot + re-plan\n\n`! NOTICE: URL changed cross-origin` = prior plan/refs invalid, re-plan.\nNever retry same failed action without re-snapshot.\n\n## Methods (non-obvious)\n- **goto** { url, waitUntil? } \u2014 default \"domcontentloaded\"; prefer over click for links\n- **snapshot** { maxElements?, targetId? } \u2014 cap 500; targetId peeks non-active tab\n- **evaluate** { content } \u2014 IIFE only\n- **waitForSelector** { selector, timeout? } \u2014 set 5000-10000ms\n- **waitForResponse** { url?, statuses?, timeout? } \u2014 url is glob `\"*api/results*\"`\n- **createTab** { url?, activate?, waitUntil? } \u2014 default activate: true; false = background\n- **close** \u2014 own call, NOT batched; only when task complete (premature close discards page state)\n- See schema for: screenshot, solve, back, forward, reload, click, type, select, checkbox, hover, scroll, text, html, waitForNavigation, waitForTimeout, waitForRequest, liveURL, getTabs, switchTab, closeTab\n\n";
+export declare const fileTransferModeNote: (transport: "stdio" | "httpStream", mcpBaseUrl: string) => string;
+export declare const SKILL_TOOL_DESCRIPTION = "Load a Browserless agent skill on demand.\n\nUse 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.\n\nAvailable skills:\n- **shadow-dom** \u2014 deep selectors, iframe URL-pattern syntax, what works through deep-ref\n- **cookie-consent** \u2014 vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, etc.)\n- **modals** \u2014 close-button heuristics, ESC handling, alertdialog vs. dialog\n- **snapshot-misses** \u2014 truncated/empty snapshots, image-rendered content\n- **dynamic-content** \u2014 choosing the right `wait*` method after async triggers\n- **screenshots** \u2014 when to screenshot vs. snapshot, scope and format choices\n- **tabs** \u2014 multi-tab workflows, peek-without-switching\n- **autonomous-login** \u2014 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.\n- **captchas** \u2014 the `solve` command, response semantics, escalation path (Cloud-only)\n- **file-transfers** \u2014 `uploadFile` / `getDownloads`, stdio-path vs. base64 content, size caps";