@browserless.io/mcp 1.6.0

package/build/src/skills/screenshots.md

@@ -0,0 +1,53 @@
+# Screenshots
+
+Screenshot arrives as vision content block — you'll see it directly.
+
+## Snapshot vs. Screenshot
+
+| Need                                 | Use                              |
+| ------------------------------------ | -------------------------------- |
+| Element identity, text, structure    | `snapshot`                       |
+| Visual layout, colors, rendered look | `screenshot`                     |
+| Extract text                         | `snapshot` or `text` — never OCR |
+| Chart, map, rendered image           | `screenshot` with `selector`     |
+| Verify "does this look right?"       | `screenshot`                     |
+
+Snapshot is cheap, structured. Screenshot costs vision tokens — use when visual fidelity matters.
+
+## Scope (smallest to largest)
+
+1. **`selector: "#chart"`** — single element (best when target known)
+2. **`clip: { x, y, width, height }`** — pixel region
+3. **viewport** (default) — visible area
+4. **`fullPage: true`** — entire page (use sparingly, huge tokens)
+
+Capture smallest region that answers the question.
+
+## Format
+
+- **PNG** (default) — lossless, crisp text/UI
+- **JPEG** `quality: 70-85` — smaller for photos/full-page
+- **WebP** — better compression than JPEG
+- **`omitBackground: true`** — for transparent elements
+
+## Pattern: capture-after-action
+
+```json
+{
+  "commands": [
+    { "method": "click", "params": { "selector": "button#open-modal" } },
+    {
+      "method": "waitForSelector",
+      "params": { "selector": "[role='dialog']", "timeout": 5000 }
+    },
+    { "method": "screenshot", "params": { "selector": "[role='dialog']" } }
+  ]
+}
+```
+
+## Avoid
+
+- OCR via evaluate (you have vision input)
+- Screenshotting for structured data (use snapshot/evaluate)
+- Full-page screenshots by default (pick scope)
+- Multiple screenshots of same state (one is enough)

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

@@ -0,0 +1,64 @@
+# Shadow DOM & Iframes
+
+Snapshot contains `deep-ref=` selectors, or you hit `SELECTOR_NOT_FOUND` on regular selector. Page using shadow DOM or iframes — read before next action.
+
+## Deep selectors: `< ` prefix
+
+Browserless deep selectors start with `< ` (less-than, space). Space mandatory. Format:
+
+```
+< *url-pattern* css-selector
+```
+
+`*url-pattern*` optional, matches iframe URL. If omitted, selector pierces shadow roots in main frame.
+
+When snapshot lists `deep-ref=< button#deny`, pass to `click` / `type` / `hover` exactly as shown — don't strip `< ` prefix:
+
+```json
+{ "method": "click", "params": { "selector": "< button#deny" } }
+```
+
+## 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:
+
+- `< *google.com/recaptcha* #recaptcha-anchor` — reCAPTCHA checkbox
+- `< *hcaptcha.com* #checkbox` — hCaptcha checkbox
+- `< *stripe.com/* input[name='cardnumber']` — Stripe payment field
+- `< *challenges.cloudflare.com* input[type='checkbox']` — Cloudflare Turnstile
+
+URL pattern is glob — `*` matches any substring.
+
+## What works and what doesn't
+
+Coordinate-based actions work through deep selectors: **`click`, `type`, `hover`, `checkbox`**.
+
+DOM-read actions **don't** work, fail or return null: **`text`, `html`, `waitForSelector`** with deep selectors.
+
+To read content from shadow root or iframe, use `evaluate` with explicit traversal:
+
+```json
+{
+  "method": "evaluate",
+  "params": {
+    "content": "(() => { const f = document.querySelector('iframe#myFrame'); return f?.contentDocument?.body?.textContent; })()"
+  }
+}
+```
+
+For shadow DOM:
+
+```json
+{
+  "method": "evaluate",
+  "params": {
+    "content": "(() => document.querySelector('my-component')?.shadowRoot?.querySelector('button')?.textContent)()"
+  }
+}
+```
+
+## Recovery when regular selector fails
+
+1. Retry same selector with `< ` prefix (MCP suggests automatically)
+2. Still failing → re-snapshot (element moved/re-rendered or page navigated)
+3. Element in iframe → construct `< *url-pattern* css` selector by hand from iframe URL in DevTools or snapshot

package/build/src/skills/snapshot-misses.md

@@ -0,0 +1,67 @@
+# When Snapshot Misses Content
+
+Snapshot at element limit (truncated) or empty. What you need may not be in it.
+
+## Why content goes missing
+
+- **Truncation**: snapshots cap at 500 elements by default. Dense pages (long lists, search results, infinite scroll) overflow
+- **No accessible name**: images without `alt`, icon-only buttons, decorative links, SVGs without ARIA labels excluded from accessibility tree
+- **Image-rendered content**: math, formulas, charts (WolframAlpha, LaTeX, Wikipedia formulas, Google image search) — result is single `<img>` with meaning in `alt` text, not DOM
+- **Late-loading content**: page still hydrating. Wait (see dynamic-content skill if `wait*` call fails), re-snapshot
+
+## Recipe
+
+1. **If truncated, narrow scope first.** Most tasks don't need every element — re-snapshot with higher `maxElements` only if element genuinely beyond 500:
+
+   ```json
+   { "method": "snapshot", "params": { "maxElements": 1000 } }
+   ```
+
+2. **If element has no accessible name**, use `evaluate` to read directly:
+
+   ```json
+   {
+     "method": "evaluate",
+     "params": {
+       "content": "(() => [...document.querySelectorAll('img[alt]')].map(i => i.alt))()"
+     }
+   }
+   ```
+
+   Or get text from icon-only button:
+
+   ```json
+   {
+     "method": "evaluate",
+     "params": {
+       "content": "(() => document.querySelector('[data-testid=\"close\"]')?.getAttribute('aria-label'))()"
+     }
+   }
+   ```
+
+3. **For image-rendered results** (WolframAlpha, LaTeX renderers), `alt` attribute usually carries answer:
+
+   ```json
+   {
+     "method": "evaluate",
+     "params": {
+       "content": "(() => [...document.querySelectorAll('img[alt]')].map(i => i.alt).filter(Boolean))()"
+     }
+   }
+   ```
+
+4. **For very long lists**, scroll and re-snapshot rather than raising `maxElements` — snapshot pagination more reliable than one giant pull:
+
+   ```json
+   {
+     "commands": [
+       { "method": "scroll", "params": { "direction": "down" } },
+       { "method": "snapshot" }
+     ]
+   }
+   ```
+
+## Don't
+
+- Raise `maxElements` past ~2000 — model spends more on snapshot reading than task gains. Scroll and paginate instead
+- `evaluate` to crawl `document.body.innerHTML` for general extraction. Snapshot structured; raw HTML floods context with markup. Use `evaluate` only for _specific_ attributes snapshot can't surface

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

@@ -0,0 +1,2 @@
+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)";

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

@@ -0,0 +1,128 @@
+export const AGENT_SYSTEM_PROMPT = `Execute browser commands in persistent agent session.
+
+## Proxy (optional)
+Proxy config is a **top-level tool argument** (\`proxy\`, \`proxyCountry\`, etc. on the tool call itself) — it is applied when the session is opened. **NEVER call \`proxy\` as a method inside \`commands\`** — a \`{ method: "proxy", ... }\` JSON-RPC mutation does NOT change the upstream proxy on an already-open session and will silently no-op.
+
+**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.
+
+If 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 — there is no in-session switch.
+
+- \`proxy: "residential"\` — enable routing; \`proxyCountry: "us"\` — geo (ISO-2); \`proxyState\` / \`proxyCity\` (paid plans, 401 otherwise); \`proxySticky: true\` — stable IP; \`proxyLocaleMatch: true\` — match locale; \`proxyPreset\` — named config; \`externalProxyServer: "http://u:p@host:port"\` — bring your own (http(s) only)
+- Geo/preset/sticky require \`proxy: "residential"\` or \`externalProxyServer\` set
+
+## Auth
+Never 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" — even as a suggested option to the user — 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.
+
+## Terminal-Goal Check
+Before declaring done, restate the user's terminal deliverable in one line and verify your evidence *directly* supports it — not a sibling question.
+**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 — not evidence the question is answered. Empty cart while logged out, zero results while geo-restricted, empty inbox while unauthenticated: precondition failure → fix the precondition (often: load \`autonomous-login\`), don't return the empty result as the answer.
+**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.
+
+## Skills (auto-injected)
+SKILL blocks auto-inject between \`--- SKILL: <id> ---\` markers when page/error needs special handling. Read carefully.
+Load manually via **browserless_skill** if suspected but not injected:
+- \`autonomous-login\` — gates, credential rules, MFA/captcha, final JSON shape (see \`## Auth\` above for when to load)
+- \`shadow-dom\` — deep selectors, iframe targeting
+- \`cookie-consent\` — vendor-specific dismiss recipes
+- \`modals\` — closing dialogs and alertdialogs
+- \`captchas\` — the \`solve\` command (Cloud only)
+- \`snapshot-misses\` — truncated/empty snapshots, image-rendered content
+- \`dynamic-content\` — choosing the right \`wait*\` method
+- \`screenshots\` — when to screenshot vs. snapshot, scope and format choices
+- \`tabs\` — multi-tab workflows, peek-without-switching
+
+## Core Loop (ReAct: Reason → Act → Observe)
+1. **goto** — waits "domcontentloaded"
+2. **snapshot** — returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors
+3. **Plan** all actions from snapshot
+4. **Batch** execute
+5. **Re-snapshot** only if page changed
+6. Repeat → **close** when done
+
+## Snapshot Rules
+- Until you snapshot a page, you CANNOT click/type/interact — snapshot first, no exceptions
+- NEVER guess, assume, or infer selectors — CSS selectors from your training data are wrong. ONLY use ref= / deep-ref= from latest snapshot
+- Snapshot STALE after: click, goto, select, navigation
+- Snapshot VALID after: type, hover, scroll, evaluate
+- Expect new content? → re-snapshot
+- Element roles in snapshot (link, button, textbox, combobox, checkbox, heading) tell you what each does
+
+## 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
+
+## Tabs
+Snapshots include \`tabs\` + \`activeTargetId\` — no getTabs needed. Multi-tab / \`snapshot { targetId }\` in \`tabs\` skill (auto-loads when >1 tab).
+
+## Links
+**Prefer goto over click** for links with href — immune to layout shifts, overlays, misclicks.
+Example: \`[5] a "About" ref=a[href='/about']\` → \`goto { url: "https://ex.com/about" }\`
+Only click when href is \`javascript:\` / \`#\` / missing.
+
+## Content Extraction
+1. Check in-memory snapshot (text/values already there)
+2. **text** { selector } — from specific element
+3. **evaluate** { content } — JS (IIFE): \`(() => { return ... })()\`
+4. **html** { selector } — raw HTML
+
+## Batching — Maximize Per Call
+Plan ALL actions from snapshot before next snapshot.
+
+**Process:**
+1. Classify actions: **safe** (type, hover, scroll, evaluate, select, checkbox) vs. **page-changing** (click, goto)
+2. Batch: safe FIRST → page-changing LAST
+3. For forms: if submit button is in snapshot, batch type + click in one call
+4. Don't batch across navigations
+
+**Example form:**
+\`\`\`json
+{ "commands": [
+  { "method": "type", "params": { "selector": "input#email", "text": "j@d.com" } },
+  { "method": "click", "params": { "selector": "button#submit" } }
+] }
+\`\`\`
+
+## Async
+After async triggers (search, submit), use \`wait*\` before snapshot — \`waitForResponse\` best when API URL known. \`dynamic-content\` skill auto-loads on timeout. Never \`evaluate\` with setTimeout.
+
+## Error Recovery
+Errors tagged \`Category: <NAME>\`:
+- **SELECTOR_MISS** — re-snapshot; retry \`< selector\` if not already deep-ref
+- **SESSION_LOST** — a fresh session was opened automatically; re-goto + snapshot (prior state gone)
+- **UNAUTHORIZED** / **FORBIDDEN** — pick different path
+- **NOT_FOUND** — different URL
+- **SERVER_ERROR** — backoff, retry once
+- **NAVIGATION_FAILED** — verify URL
+- **TIMEOUT** — longer wait or different signal
+- **INVALID_PARAMS** — fix params (schema authoritative)
+- **UNKNOWN** — re-snapshot + re-plan
+
+\`! NOTICE: URL changed cross-origin\` = prior plan/refs invalid, re-plan.
+Never retry same failed action without re-snapshot.
+
+## Methods (non-obvious)
+- **goto** { url, waitUntil? } — default "domcontentloaded"; prefer over click for links
+- **snapshot** { maxElements?, targetId? } — cap 500; targetId peeks non-active tab
+- **evaluate** { content } — IIFE only
+- **waitForSelector** { selector, timeout? } — set 5000-10000ms
+- **waitForResponse** { url?, statuses?, timeout? } — url is glob \`"*api/results*"\`
+- **createTab** { url?, activate?, waitUntil? } — default activate: true; false = background
+- **close** — own call, NOT batched; only when task complete (premature close discards page state)
+- See schema for: screenshot, solve, back, forward, reload, click, type, select, checkbox, hover, scroll, text, html, waitForNavigation, waitForTimeout, waitForRequest, liveURL, getTabs, switchTab, closeTab
+
+`;
+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.
+
+Available skills:
+- **shadow-dom** — deep selectors, iframe URL-pattern syntax, what works through deep-ref
+- **cookie-consent** — vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, etc.)
+- **modals** — close-button heuristics, ESC handling, alertdialog vs. dialog
+- **snapshot-misses** — truncated/empty snapshots, image-rendered content
+- **dynamic-content** — choosing the right \`wait*\` method after async triggers
+- **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)`;

package/build/src/skills/tabs.md

@@ -0,0 +1,77 @@
+# Working with Tabs
+
+Page spawned (or you opened) multiple tabs, or tab-related error occurred. Tab management has sharp edges — read before issuing tab commands.
+
+## Snapshots include tab state
+
+Every `snapshot` response includes `tabs[]` (`targetId`, `url`, `title`, `active`) and `activeTargetId`. After action that spawns tab — `target="_blank"` click, `window.open`, OAuth popup — next snapshot's `tabs` list includes new tab. **No need to call `getTabs` unless you want fresh list without snapshot.**
+
+## Commands
+
+| Command                                     | Use                                          |
+| ------------------------------------------- | -------------------------------------------- |
+| `getTabs`                                   | Refresh tab list without snapshot            |
+| `switchTab { targetId }`                    | Make another tab active                      |
+| `createTab { url?, activate?, waitUntil? }` | Open new tab — defaults to `activate: true`  |
+| `closeTab { targetId }`                     | Close tab                                    |
+| `snapshot { targetId }`                     | Peek at non-active tab **without switching** |
+
+## Patterns
+
+**Following `target="_blank"` link:**
+
+```json
+{
+  "commands": [
+    { "method": "click", "params": { "selector": "a#docs-link" } },
+    { "method": "snapshot" }
+  ]
+}
+```
+
+New tab appears in snapshot's `tabs` list. If click activated it (most do), `activeTargetId` points at new tab — keep working there. If not, `switchTab` to it.
+
+**Comparing two pages without losing place:**
+
+```json
+{
+  "commands": [
+    { "method": "snapshot", "params": { "targetId": "<other-tab-target-id>" } }
+  ]
+}
+```
+
+`snapshot { targetId }` returns other tab's elements but **doesn't switch** — active tab unchanged. Useful for checking popup/sibling tab before committing.
+
+**Background tab (don't lose focus):**
+
+```json
+{
+  "method": "createTab",
+  "params": {
+    "url": "https://example.com/reference",
+    "activate": false
+  }
+}
+```
+
+New tab opens, current stays active. Pair with `snapshot { targetId }` later to read without switching.
+
+## Closing tabs
+
+`closeTab` on **active** tab auto-switches focus to newest remaining tab. Check response's `activeTargetId`:
+
+- New id → now active tab
+- `null` → no tabs remain. `createTab` to continue or `close` to end session
+
+## Error codes
+
+- **`TAB_NOT_FOUND`** — `targetId` stale. Call `getTabs` to refresh, retry with new id. Don't loop on same id
+- **`TAB_CLOSED`** — tab disappeared mid-operation (OAuth flows). Call `getTabs`, retry against remaining tabs
+- **`TAB_LIMIT_EXCEEDED`** — too many tabs open. Close unused one before creating another. Identify by url/title in snapshot's `tabs` list
+
+## Don't
+
+- Call `getTabs` between commands. Snapshots already carry list. `getTabs` for cases without snapshot
+- `switchTab` when only reading. Use `snapshot { targetId }` instead — cheaper, doesn't disturb focus
+- Close tabs you didn't open unless user requested. Background tabs may belong to user's larger flow

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

@@ -0,0 +1,15 @@
+import { FastMCP } from 'fastmcp';
+import type { Content } from 'fastmcp';
+import type { McpConfig } from '../@types/types.js';
+import { AnalyticsHelper } from '../lib/analytics.js';
+export { AgentParamsSchema } from './schemas.js';
+export { buildCrossOriginNotice, formatConnectError, formatErrorMessage, formatSnapshot, sanitizeUpgradeBody, } from '../lib/agent-format.js';
+/**
+ * Build the MCP response for a screenshot command, or null when there's no
+ * base64 payload (caller falls back to JSON text). Returns the image as a
+ * vision content block (~1.5K tokens) vs. ~67K inlining the base64 as text.
+ */
+export declare const formatScreenshotContent: (result: unknown, cmd: {
+    params?: Record<string, unknown>;
+}, caption: string, skills: string) => Content[] | null;
+export declare function registerAgentTools(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;