iframer-toolkit 0.10.5 → 0.10.8

package/dist/mcp-server.cjs

@@ -659,18 +659,18 @@ var import_zod3 = require("zod");
 var import_zod2 = require("zod");
 var stepSchema = import_zod2.z.discriminatedUnion("type", [
   import_zod2.z.object({ type: import_zod2.z.literal("navigate"), url: import_zod2.z.string(), waitUntil: import_zod2.z.string().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("click"), selector: import_zod2.z.string() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Sets an input/textarea's value. Framework-aware: fires the React-safe native setter + input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) register the value AND mark the field touched. This is the fix for 'I filled the field but submit says it's still empty' \u2014 always use fill for form fields, not evaluate.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("click"), selector: import_zod2.z.string().describe("An @e ref from snapshot/find, an @a: anchor, or plain CSS. Text selectors (text=, :has-text(), :text-is()) are rejected: use a find step for text, then click its @e ref.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Sets an input/textarea's value. Framework-aware: fires the React-safe native setter + input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) register the value AND mark the field touched. This is the fix for 'I filled the field but submit says it's still empty' \u2014 always use fill for form fields, not evaluate."), force: import_zod2.z.boolean().optional().describe("Bypass the honeypot guard. fill refuses fields no human can reach (offscreen/clipped/transparent) \u2014 only set this when you are certain the field is real.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("human-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("right-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("human-type"), selector: import_zod2.z.string(), value: import_zod2.z.string(), skipClick: import_zod2.z.boolean().optional().describe("Skip the click-to-focus and type into the already-focused element. Use for editors that blur on a synthetic click (e.g. Draft.js). Either way, typing aborts safely if the target isn't actually focused."), speed: import_zod2.z.enum(["slow", "normal", "fast"]).optional().describe("Typing speed. 'normal' (~130ms/char, realistic, default), 'fast' (~45ms/char) for long non-sensitive text, 'slow' for extra realism.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("human-type"), selector: import_zod2.z.string(), value: import_zod2.z.string(), skipClick: import_zod2.z.boolean().optional().describe("Skip the click-to-focus and type into the already-focused element. Use for editors that blur on a synthetic click (e.g. Draft.js). Either way, typing aborts safely if the target isn't actually focused."), speed: import_zod2.z.enum(["slow", "normal", "fast"]).optional().describe("Typing speed. 'normal' (~130ms/char, realistic, default), 'fast' (~45ms/char) for long non-sensitive text, 'slow' for extra realism."), clear: import_zod2.z.boolean().optional().describe("Replace the field's existing text instead of appending to it.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("evaluate"), expression: import_zod2.z.string() }),
   import_zod2.z.object({ type: import_zod2.z.literal("extract"), expression: import_zod2.z.string() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait"), ms: import_zod2.z.number() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait-for"), selector: import_zod2.z.string(), timeout: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("scroll"), deltaY: import_zod2.z.number().optional(), selector: import_zod2.z.string().optional().describe("Scroll within this element instead of the window"), human: import_zod2.z.boolean().optional().describe("Real eased wheel events instead of an instant jump (slower, less bot-obvious)") }),
   import_zod2.z.object({ type: import_zod2.z.literal("select"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Option value to pick in a <select> \u2014 native selection, real change events (never set .value via evaluate)") }),
-  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string(), meta: import_zod2.z.boolean().optional(), ctrl: import_zod2.z.boolean().optional(), shift: import_zod2.z.boolean().optional(), alt: import_zod2.z.boolean().optional() }),
+  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string(), meta: import_zod2.z.boolean().optional().describe("Cmd/Ctrl+A selects all in every mode. Other Cmd/Ctrl shortcuts are rejected in extension mode (the relay drops them)."), ctrl: import_zod2.z.boolean().optional(), shift: import_zod2.z.boolean().optional(), alt: import_zod2.z.boolean().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("read"), selector: import_zod2.z.string().optional().describe("Element to read text from (CSS or @e ref); omit for the whole body"), maxChars: import_zod2.z.number().optional().describe("Cap returned text length (default 6000)") }),
   import_zod2.z.object({ type: import_zod2.z.literal("upload"), selector: import_zod2.z.string().describe("The <input type=file> (CSS, @e ref, or @a anchor)"), files: import_zod2.z.array(import_zod2.z.string()).describe("Absolute local file path(s) on this machine") }),
   import_zod2.z.object({ type: import_zod2.z.literal("paste"), selector: import_zod2.z.string().optional().describe("Field to paste the OS clipboard into; omit for the focused element. Reliable via CDP insertText where a \u2318V keyboard step isn't.") }),
@@ -783,6 +783,13 @@ ${api.domain} (${api.baseUrl})`);
       }
     }
   }
+  const serverErrors = (data.results || []).flatMap((r) => r.serverErrors || []);
+  if (serverErrors.length > 0) {
+    lines.push("\n--- Server errors (HTTP >= 400) ---");
+    for (const se of serverErrors) {
+      lines.push(`  [step ${se.stepIndex}] ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+    }
+  }
   if (data.error) {
     lines.push("\n--- Failure ---");
     if (typeof data.error === "string") {
@@ -793,6 +800,10 @@ ${api.domain} (${api.baseUrl})`);
       lines.push(`Message: ${data.error.message}`);
       lines.push(`Retryable: ${data.error.retryable}`);
       if (data.error.suggestion) lines.push(`Suggestion: ${data.error.suggestion}`);
+      const atFailure = serverErrors.filter((se) => se.stepIndex === data.error?.failedAtStep);
+      for (const se of atFailure) {
+        lines.push(`Server responded: ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+      }
       if (data.error.pageState?.url) lines.push(`URL at failure: ${data.error.pageState.url}`);
     }
   }
@@ -828,7 +839,7 @@ Returns: ok, completedSteps, output for snapshot/find/read/extract steps, obstac
         screenshotAfterEach: import_zod3.z.boolean().optional().describe("Take a screenshot after every step (expensive)"),
         continueOnObstacle: import_zod3.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
         continueOnError: import_zod3.z.boolean().optional().describe("Continue past failing steps (default: false)"),
-        captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes."),
+        captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes. Also surfaces every HTTP >= 400 response per step \u2014 turn it on when a form submit fails with only a vague on-page message, to read the server's real answer."),
         mode: import_zod3.z.enum(["headless", "binary-headful", "docker-headful", "extension"]).optional().describe("DO NOT SET unless the user explicitly requests a mode \u2014 iframer auto-selects and auto-escalates. 'extension' drives a real-Chrome tab (requires options.tabId from the `tabs` tool)."),
         autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)"),
         instanceId: import_zod3.z.string().optional().describe("Named parallel browser (default 'default') \u2014 distinct ids drive several browsers at once, each with its own session state."),
@@ -1203,6 +1214,23 @@ stop: save cookies/localStorage and close the browser \u2014 ALWAYS call when br
     },
     async ({ action, mode, urls, instanceId, outputDir }) => {
       try {
+        const SPAWNS_BROWSER = ["capture-start", "capture-stop", "get-cookies", "get-auth"];
+        let resolvedMode = mode;
+        if (SPAWNS_BROWSER.includes(action) && !mode) {
+          const live = await localApiGet("/instances").catch(() => ({ instances: [] }));
+          const match = (live.instances || []).find((i) => i.instanceId === (instanceId || "default"));
+          if (match) {
+            if (match.mode === "headless" || match.mode === "binary-headful") resolvedMode = match.mode;
+          } else {
+            const ext = await localApiGet("/extension/status").catch(() => ({ connected: false }));
+            if (ext.connected) {
+              return err(
+                `'${action}' would launch a new browser window, but the iframer extension is connected \u2014 you are probably driving a real Chrome tab. Read that tab instead: execute with options.mode="extension" and options.tabId (from the \`tabs\` tool). If you really want a separate browser, pass mode explicitly. Nothing was launched.`
+              );
+            }
+          }
+        }
+        mode = resolvedMode;
         if (action === "stop") {
           const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
           return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
@@ -2087,6 +2115,8 @@ CRITICAL RULES:
 7. If the browser crashes, call "session restart" and retry. Don't panic.
 8. ALWAYS call "session" action=stop when you are done with browser work. It saves session state and frees the browser. Idle browsers are auto-reclaimed, but don't rely on that.
 
+If headless detects Imperva or Akamai, immediately stop headless and pivot to headed in the same run; do not wait for a block, retry headless, or defer the switch to a future request. Use headed from the outset when the provider is already known in the current task. On detection, switch to headed and use respectful pacing (at least 3 seconds between top-level actions; no parallel bursts or repeated blocked retries). Do not announce the provider or explain the switch unless the user asks why. Only when asked, explain that the site is covered by Imperva or Akamai and iframer adjusts its browser mode and pacing to respect it.
+
 BROWSER MODES: Don't specify options.mode \u2014 iframer auto-selects and auto-escalates (headless \u2192 binary-headful). Only set a mode if the user explicitly asks.
 
 CAPTCHA: In binary-headful mode, ask the user to solve it in the visible window. In docker-headful mode, use the "solve-captcha" step.

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "iframer",
-  "version": "0.10.5",
+  "version": "0.10.8",
   "description": "Let iframer drive a Chrome tab you choose, on your real logged-in session.",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp2wbce98k+xDnEgtuzLyNXYBLEDY0nqChuvolb94B3VV1HsHFUulUyNe92eN6MjQuadDohQ2j5mj7zWs4yQoixgTQPe7Gm/+GHWdgxwM2s9t5opnLHwF90LPiJm6q1NGWLM4aK6JT+2I6FnUGmj2bzB4WIlf55C3aMEBoXTqIzG2U8s2cxkXGebWWqbPlMK/Phsmsvo4POWnidbGHPhBOq0iyPTu7RdSDlNdJdJ+dtdNXkMmltKUS881MQI9T6GcCCKhIKcZrJGGnk0xphlWyl+ublTAO0tbQSVB/K7D3JmCxMv690TPtYUPPhGi+C6VCv3IeutLmNo60mvux3wbGQIDAQAB",
   "permissions": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iframer-toolkit",
-  "version": "0.10.5",
+  "version": "0.10.8",
   "description": "Browser access toolkit for AI agents — CLI and MCP server for headless/headful browsing, login flows, and pipeline execution.",
   "keywords": [
     "iframer",

package/skills/iframer.md

@@ -13,6 +13,7 @@ You are an expert at using the iframer browser automation toolkit. The user want
 - `iframer.session` — stop (save state) or clear session data
 - `iframer.status` — system health, modes, stored credentials
 - `iframer.reverse-engineer` — capture API calls a site makes
+- `iframer.tabs` — list/open tabs in the user's REAL Chrome (needs the extension)
 
 ## Core rules
 
@@ -20,7 +21,10 @@ You are an expert at using the iframer browser automation toolkit. The user want
 2. **NEVER guess CSS selectors.** Use `snapshot` to see what's on the page, then use `@e` refs from the snapshot for click/fill/etc.
 3. **NEVER re-store credentials when login fails.** If credentials exist in `credentials list`, they are valid. Login failures are browser-mode or bot-detection problems, not credential problems. Retry with a stronger mode.
 4. **NEVER pass explicit selectors to the login step** unless the auto-detect failed AND you took a snapshot to find the right ones. The login step auto-detects email, password, submit, and OTP fields.
-5. **Let iframer handle mode escalation.** Don't hardcode modes. If you must pick one, prefer no mode (auto-select) or `binary-headful` for sites known to block headless.
+5. If headless detects Imperva or Akamai, immediately stop headless and pivot to headed in the same run; do not wait for a block, retry headless, or defer the switch to a future request. Use headed from the outset when the provider is already known in the current task. On detection, switch to headed and use respectful pacing (at least 3 seconds between top-level actions; no parallel bursts or repeated blocked retries). Do not announce the provider or explain the switch unless the user asks why. Only when asked, explain that the site is covered by Imperva or Akamai and iframer adjusts its browser mode and pacing to respect it.
+6. **Let iframer handle mode escalation.** Don't hardcode modes. If you must pick one, prefer no mode (auto-select) or `binary-headful` for sites known to block headless.
+7. **"My browser" / "my tabs" / "I'm already logged in there" means extension mode, never a launched browser.** See the section below. A launched browser has none of the user's logins and opening one is a visible, unwanted window on their desktop.
+8. **Every browser you open is yours to close.** Call `session stop` when the work is done, and if a call opened a browser by mistake, close it immediately instead of leaving it. `status` lists live windows.
 
 ## How to build pipelines
 
@@ -32,19 +36,19 @@ The `execute` tool takes a `steps` array. Each step is an object with a `type` f
 |------|--------|-------------|
 | `navigate` | `url`, `waitUntil?` | Go to URL |
 | `login` | `domain` | Auto-detect form, fill stored credentials, handle 2FA. Handles email-first flows (Slack, Microsoft, Google) and standard email+password flows. |
-| `snapshot` | — | Get interactive elements as structured list with @e refs. **Do this BEFORE interacting.** |
+| `snapshot` | — | Get interactive elements as structured list with @e refs. **Do this BEFORE interacting.** Fields no human can reach (honeypots pushed offscreen/clipped/transparent by an ancestor) are omitted; bait-looking ones (`website`, `fax`, tabindex=-1) are marked `[honeypot?]` — leave those empty unless the task clearly needs them. |
 | `find` | `role?`, `name?`, `text?`, `placeholder?`, `label?` | Find a specific element, returns a ref |
 | `screenshot` | `annotate?` | Take a screenshot. `annotate: true` overlays numbered badges. |
-| `click` | `selector` | Click element (use @e refs from snapshot) |
-| `fill` | `selector`, `value` | Fill input (use @e refs) |
+| `click` | `selector` | Click element (use @e refs from snapshot/find). Text selectors (`text=`, `:has-text()`, `:text-is()`) are rejected: `find` by text, then click the ref. |
+| `fill` | `selector`, `value`, `force?` | Fill input (use @e refs). Refuses honeypot fields (unreachable by a human) with an explanatory error — skip the field. `force: true` bypasses, only when you are certain it is real. |
 | `human-click` | `selector` or `x`, `y` | Human-like click with random offset |
-| `human-type` | `selector`, `value` | Human-like typing with variable delays |
+| `human-type` | `selector`, `value`, `clear?` | Human-like typing with variable delays. Appends by default; `clear: true` replaces the existing text. |
 | `scroll` | `deltaY?` | Scroll the page |
 | `wait` | `ms` | Wait N milliseconds |
 | `wait-for` | `selector`, `timeout?` | Wait for element to appear |
 | `evaluate` | `expression` | Run JS, return result |
 | `extract` | `expression` | Run JS, include result in response |
-| `keyboard` | `key` | Press a key (Enter, Escape, Tab, etc.) |
+| `keyboard` | `key`, `meta?`, `ctrl?` | Press a key (Enter, Escape, Tab, etc.). Cmd/Ctrl+A selects all everywhere; other Cmd/Ctrl shortcuts are refused in extension mode. |
 | `solve-captcha` | — | Auto-detect and solve reCAPTCHA or hCaptcha |
 
 ### Pipeline options
@@ -52,7 +56,7 @@ The `execute` tool takes a `steps` array. Each step is an object with a `type` f
 | Option | Default | Description |
 |--------|---------|-------------|
 | `mode` | auto | `headless`, `binary-headful`, `docker-headful`. Omit for auto-select + auto-escalation. |
-| `captureApi` | false | Record all XHR/fetch requests. Use for reverse-engineering. |
+| `captureApi` | false | Record all XHR/fetch requests. Use for reverse-engineering, and when a form submit fails with only a vague on-page message: every HTTP >= 400 response is reported per step, so you read the server's real answer (e.g. `POST /api/apply → 422: {"error":"..."}`) instead of guessing. |
 | `staleTimeoutMs` | 20000 | Per-step stale-state timeout |
 | `continueOnError` | false | Don't abort pipeline on step failure |
 | `screenshotAfterEach` | false | Screenshot after every step (expensive) |
@@ -199,7 +203,7 @@ session: { action: "restart" }
 ```
 This kills ALL running browser instances (local + Docker) and resets state. Credentials and knowledge cache are NOT affected. The next `execute` call launches a fresh browser automatically.
 
-**The execute tool also auto-recovers:** if it detects a crash (connection closed, timeout, ECONNREFUSED), it automatically restarts the browser and retries once before reporting failure. If auto-recovery also fails, the agent should call `session restart` manually and try again.
+**The execute tool also auto-recovers:** if it detects a *connection-level* crash (connection closed, ECONNREFUSED/ECONNRESET/EPIPE, socket hang up), it restarts the browser server and retries once before reporting failure. Timeouts are deliberately NOT auto-retried — a slow-but-healthy pipeline that hit the client timeout must not be re-run, or non-idempotent steps (form submits, purchases) would double-execute. If auto-recovery fails, or a step timed out, call `session restart` manually and continue from where you left off (don't blindly re-run the whole pipeline).
 
 ### Manage credentials
 
@@ -232,7 +236,7 @@ If an `execute` call takes a very long time (30s+), it's probably stuck on one o
 
 2. **Waiting for a page transition that never happens** — the site didn't redirect after form submission. Take a screenshot to see the current state, then decide what to do (wrong button clicked, error message on page, etc.).
 
-3. **Stale-state timeout** — iframer's stale monitor will abort after `staleTimeoutMs` (default 20s). The error will say "stale-state" and include a screenshot. Read the screenshot to understand what the page looks like.
+3. **Stale-state timeout** — iframer's stale monitor will abort after `staleTimeoutMs` (default 20s). The error will say "stale-state" and include a screenshot. Read the screenshot to understand what the page looks like. If the step targeted a selector that no longer exists, the error is reported as `element-not-found` instead ("No element matches …"): the page re-rendered it away. Re-snapshot right before acting and retry — do not change styles or theorise about visibility.
 
 **Recovery pattern for all stalls:**
 ```
@@ -274,7 +278,7 @@ Many modern sites don't have email+password on one page. The login step handles
 
 ## Recovering from MCP disconnect
 
-The iframer MCP server runs Chrome in-process. If Chrome crashes hard enough (native segfault, out of memory), the entire MCP server process dies and Claude Code shows "MCP disconnected."
+The iframer MCP server does NOT run Chrome — Chrome lives in a separate, shared local background server (the daemon on 127.0.0.1). The MCP process is just a thin HTTP/stdio client. So a browser crash can't take the MCP down with it: if Chrome dies, the daemon's own recovery handles it and the MCP keeps running. A real "MCP disconnected" in Claude Code means the MCP client process itself dropped (session killed, pipe closed), not a browser crash — the daemon and its warm browsers survive that too.
 
 **Recovery is simple — Claude Code auto-reconnects MCP servers.** Just wait 2-3 seconds and retry the tool call. Don't:
 - Try to run `claude mcp` commands
@@ -313,6 +317,56 @@ If the MCP disconnects repeatedly on the same operation, the site is probably to
 | Not passing `mode` consistently across execute calls in the same flow | Always pass the same `options.mode` for all steps in a multi-call flow |
 | Panicking when MCP disconnects (running `claude mcp`, inspecting source, giving up) | Just wait 2-3 seconds, call `status` to verify reconnect, then `session restart` and retry |
 
+## Driving the user's real Chrome (extension mode)
+
+Use this whenever the user says "my browser", "my tabs", "the page I have open", or the task
+needs accounts they are already signed into. A launched browser has a fresh, logged-out profile.
+
+1. `tabs` with `action: "list"` — returns open tabs as `[id <n>] title / url`. If it reports the
+   extension is not connected, tell the user to open Chrome / check the extension; do NOT fall
+   back to launching a browser.
+2. `execute` with `options.mode: "extension"` AND `options.tabId: <n>` from that list. Both are
+   required: `mode` alone is refused and launches nothing.
+3. Need a different page? `tabs` with `action: "open"` returns the new tab id. Do NOT use a
+   navigate-only pipeline in a launched browser to "get there".
+
+Rules while in extension mode:
+
+- **Do not call `session get-cookies` / `get-auth` / `capture-start` without a mode.** They default
+  to launching a separate window. The tab you are driving already has the auth; read it there.
+- **Do not call `session stop`.** There is nothing to stop, and it is the user's own browser.
+- `execute` never escalates in extension mode. If it fails, report why (extension disconnected,
+  tab closed) instead of retrying in a launched mode, which would silently use a logged-out profile.
+
+Driving a live single-page app (most dashboards) in extension mode:
+
+- **Act only on `@e` refs** from a `find`/`snapshot` in the same execute call. Never CSS you
+  guessed, never text selectors.
+- **Give steps that can wedge the tab their own execute call:** `navigate`, anything that opens or
+  closes a modal, and `evaluate`. If one hangs, the steps around it are not lost.
+- **If a step reports the tab stopped responding,** run a lone `read` or `snapshot` to confirm it
+  recovered, then continue. Don't resend the same step unchanged.
+- **Route changes:** `navigate` first. If the page never leaves, use `evaluate` with
+  `location.assign("<url>")`, or click the site's own link.
+- **Custom dropdowns (MUI, react-select, comboboxes):** click the field or its arrow button, `find`
+  the option (`role: "option", name: "Texas"`), click that `@e` ref. To filter first, `fill` the
+  field (it stays focused so the list stays open), then `find` and click the option. Don't type
+  with Cmd+A/Backspace tricks.
+- **Don't scroll with `evaluate` (`scrollIntoView`).** `click` scrolls its target into view itself.
+
+## Cleaning up after yourself
+
+A browser opened by mistake is a real, visible window sitting on the user's desktop. It is your
+job to close it, not theirs.
+
+- Any pipeline that opens a browser must end with `session stop` once the task is done.
+- If you opened a browser you did not need (wrong mode, wrong call, task turned out not to need
+  one), call `session stop` right away, in the same turn you noticed.
+- `status` lists live windows with their `instanceId`. If you see one you do not recognise from
+  your own work in this conversation, say so rather than silently leaving it.
+- A pipeline with no `navigate` step is refused unless a live browser already holds that
+  `instanceId`. If you get that error, you probably meant extension mode — go get a `tabId`.
+
 ## Mode selection guide
 
 | Scenario | Recommended mode |
@@ -325,6 +379,7 @@ If the MCP disconnects repeatedly on the same operation, the site is probably to
 | Need automated captcha solving | `docker-headful` (uses vision AI to solve) |
 | Need to watch the browser remotely / headless server | `docker-headful` |
 | Reverse-engineering after login | Same mode that login succeeded in |
+| "Use my browser" / user's own logins / their open tab | `extension` + `tabId` from the `tabs` tool |
 
 **Prefer `binary-headful` over `docker-headful` for most tasks.** Binary-headful runs Chrome directly on the user's machine — it's faster, more stable for long sessions, and the user can solve captchas manually. Docker-headful adds overhead (Xvfb, VNC, container networking) and heavy SPAs frequently stall or timeout inside the container.