@agent360/browser-mcp 1.23.0 → 1.24.0

package/README.md

@@ -1,4 +1,4 @@
-# Browser MCP by Agent360
+# Browser MCP by [Agent360](https://agent360.dk)
 
 [![npm version](https://img.shields.io/npm/v/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)
 [![npm downloads](https://img.shields.io/npm/dw/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)
@@ -7,11 +7,17 @@
 [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
 [![Chrome Web Store](https://img.shields.io/badge/Chrome_Web_Store-live-green)](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)
 
-**Control your real Chrome from Claude Code — with your logins, cookies, and 2FA.**
+**Your AI agent drives your real, logged-in Chrome — and works where headless tools die.**
 
-![Browser MCP Demo](assets/demo.gif)
+[![Browser MCP Demo](assets/demo.gif)](https://browsermcp.dev)
 
-The only browser MCP with **multi-session support** (10 concurrent AI sessions), **human-in-the-loop** (2FA, CAPTCHA, credentials), and **built-in provider integrations** (Stripe, HubSpot, Slack, and 6 more). 34 tools total.
+▶ **[Watch the 37-second demo with sound →](https://browsermcp.dev)**
+
+Browser MCP gives Claude Code (and any MCP client — Cursor, VS Code agent mode) control of your actual Chrome: your cookies, your sessions, your 2FA. So it works on CAPTCHA, 2FA and anti-bot sites where Playwright and Puppeteer get blocked — because it's *you* browsing.
+
+The killer move: it hits a login wall, reads the verification code from your own Gmail tab, and continues the sign-in. No API can do that. Operate platforms with no API, QA your own web app end-to-end, or work dashboards, LinkedIn and Reddit at human pace — with you approving the sensitive steps.
+
+34 tools. Auto-clicks the reCAPTCHA v2 checkbox, with a human fallback for the rest. Multi-session color-coded tab groups. **MIT, free, and 100% local — nothing leaves your machine.**
 
 ## Install — 2 steps (~60 seconds)
 
@@ -125,7 +131,7 @@ No Developer mode needed. Then run `npx @agent360/browser-mcp install --skip-ext
 ### CAPTCHA Solving
 | Tool | Description |
 |------|-------------|
-| `browser_solve_captcha` | Detect and solve CAPTCHAs. Auto-detects reCAPTCHA v2/v3, hCaptcha, Turnstile, FunCaptcha. Actions: `detect`, `click_checkbox` (auto-click, ~80% pass with Google login), `click_grid` (AI vision guided), `ask_human` (fallback) |
+| `browser_solve_captcha` | Detect and solve CAPTCHAs. Auto-detects reCAPTCHA v2/v3, hCaptcha, Turnstile, FunCaptcha. Actions: `detect`, `click_checkbox` (auto-click, often passes when signed into Google), `click_grid` (AI vision guided), `ask_human` (fallback) |
 
 ### Human-in-the-Loop
 | Tool | Description |

package/extension/background.js

@@ -9,34 +9,44 @@
 // ── Session Tab Management ─────────────────────────────────────────────────
 
 const SESSION_COLORS = ['blue', 'green', 'yellow', 'red', 'pink', 'purple', 'cyan', 'orange'];
+// Select-all modifier is platform-dependent: Cmd (meta=4) on macOS, Ctrl (2) elsewhere.
+// Get this wrong and the field isn't selected — Backspace no-ops and new text concatenates onto the old.
+const SELECT_ALL_MODS = /Mac/i.test(navigator.userAgent) ? 4 : 2;
 const sessions = new Map(); // port → { tabIds: Set, groupId: number|null, color: string, label: string }
-let sessionsLoaded = false;
+// FIX-2: promise-cache latch (not a boolean). The old `if(sessionsLoaded) return`
+// flipped the flag BEFORE awaiting storage, so a second concurrent caller on a freshly
+// woken service worker proceeded against an EMPTY sessions Map. Caching the promise makes
+// every concurrent caller await the SAME populated completion. Resets to null on SW
+// eviction (module re-init) and on error, so the next wake retries.
+let restorePromise = null;
 
 // Restore sessions from storage (service workers lose in-memory state on suspend)
-async function restoreSessions() {
-  if (sessionsLoaded) return;
-  sessionsLoaded = true;
-  const { sessions: saved } = await chrome.storage.local.get({ sessions: {} });
-  for (const [port, data] of Object.entries(saved)) {
-    // Verify tabs still exist
-    const validTabIds = new Set();
-    for (const tabId of (data.tabIds || [])) {
-      try {
-        await chrome.tabs.get(tabId);
-        validTabIds.add(tabId);
-      } catch {} // tab no longer exists
-    }
-    if (validTabIds.size > 0) {
-      const activeTabId = data.activeTabId && validTabIds.has(data.activeTabId) ? data.activeTabId : null;
-      sessions.set(Number(port), {
-        tabIds: validTabIds,
-        activeTabId,
-        groupId: data.groupId || null,
-        color: data.color || SESSION_COLORS[sessions.size % SESSION_COLORS.length],
-        label: data.label || `Claude ${sessions.size + 1}`,
-      });
+function restoreSessions() {
+  if (restorePromise) return restorePromise;
+  restorePromise = (async () => {
+    const { sessions: saved } = await chrome.storage.local.get({ sessions: {} });
+    for (const [port, data] of Object.entries(saved)) {
+      // Verify tabs still exist
+      const validTabIds = new Set();
+      for (const tabId of (data.tabIds || [])) {
+        try {
+          await chrome.tabs.get(tabId);
+          validTabIds.add(tabId);
+        } catch {} // tab no longer exists
+      }
+      if (validTabIds.size > 0) {
+        const activeTabId = data.activeTabId && validTabIds.has(data.activeTabId) ? data.activeTabId : null;
+        sessions.set(Number(port), {
+          tabIds: validTabIds,
+          activeTabId,
+          groupId: data.groupId || null,
+          color: data.color || SESSION_COLORS[sessions.size % SESSION_COLORS.length],
+          label: data.label || `Claude ${sessions.size + 1}`,
+        });
+      }
     }
-  }
+  })().catch(err => { restorePromise = null; throw err; });
+  return restorePromise;
 }
 
 function getSession(port) {
@@ -103,10 +113,7 @@ async function addTabToSession(port, tabId) {
     }
 
     if (session.groupId === null) {
-      const validTabIds = [...session.tabIds].filter(id => {
-        try { return id; } catch { return false; }
-      });
-      const groupId = await chrome.tabs.group({ tabIds: validTabIds });
+      const groupId = await chrome.tabs.group({ tabIds: [...session.tabIds] });
       session.groupId = groupId;
       await chrome.tabGroups.update(groupId, {
         title: session.label,
@@ -158,17 +165,25 @@ function persistSessions() {
 async function getSessionTab(port, activate = false) {
   const session = getSession(port);
   let target = null;
+  // Remember our OWN about:blank placeholder so we reuse it instead of spawning another
+  // on every read-only call before the first navigate (FIX-4: about:blank proliferation).
+  let blankFallback = null;
+  const consider = (tab) => {
+    if (!tab) return false;
+    if (tab.url.startsWith('chrome://')) return false;
+    if (tab.url.startsWith('about:')) { if (!blankFallback) blankFallback = tab; return false; }
+    return true;
+  };
 
   // Prefer the active (last navigated) tab
   if (session.activeTabId) {
     try {
       const tab = await chrome.tabs.get(session.activeTabId);
-      if (tab && !tab.url.startsWith('chrome://') && !tab.url.startsWith('about:')) {
-        target = tab;
-      }
+      if (consider(tab)) target = tab;
     } catch {
+      const dead = session.activeTabId;   // FIX-17: capture id BEFORE nulling (was deleting null)
       session.activeTabId = null;
-      session.tabIds.delete(session.activeTabId);
+      session.tabIds.delete(dead);
     }
   }
 
@@ -177,30 +192,48 @@ async function getSessionTab(port, activate = false) {
     for (const tabId of session.tabIds) {
       try {
         const tab = await chrome.tabs.get(tabId);
-        if (tab && !tab.url.startsWith('chrome://') && !tab.url.startsWith('about:')) {
-          session.activeTabId = tabId;
-          target = tab;
-          break;
-        }
+        if (consider(tab)) { session.activeTabId = tabId; target = tab; break; }
       } catch {
         session.tabIds.delete(tabId);
       }
     }
   }
 
-  // No usable tab — create one
+  // Reuse our own blank placeholder rather than spawning yet another one (FIX-4).
+  if (!target && blankFallback) {
+    target = blankFallback;
+    session.activeTabId = target.id;
+    persistSessions();
+  }
+
+  // No usable tab at all — create ONE placeholder and pin it as the active tab so the
+  // NEXT call reuses it (FIX-4) instead of creating a fresh about:blank every time.
   if (!target) {
     target = await chrome.tabs.create({ url: 'about:blank', active: false });
     await addTabToSession(port, target.id);
-    return target;
+    session.activeTabId = target.id;
+    persistSessions();
+    // fall through to the activate branch (SC-3: previously returned early, skipping it)
   }
 
-  // Activate the tab so Chrome APIs target it (not whatever user is viewing)
-  if (activate && !target.active) {
-    await chrome.tabs.update(target.id, { active: true });
-    // Brief wait for Chrome to render the tab
-    await new Promise(r => setTimeout(r, 150));
-    target = await chrome.tabs.get(target.id);
+  // Activate the tab WITHOUT stealing the user's focus (FIX-1). This is a BACKGROUND tool:
+  // screenshot/press_key run constantly, so we must NOT chrome.windows.update({focused:true})
+  // here — that yanked Chrome to the foreground on every action. We only (a) un-minimize a
+  // minimized window (needed so it can composite) and (b) make the tab active within its
+  // window. The truly-occluded (covered) case is handled as a bounded last-resort
+  // raise-and-restore inside the screenshot handler only.
+  if (activate) {
+    try {
+      if (target.windowId != null) {
+        const win = await chrome.windows.get(target.windowId).catch(() => null);
+        if (win && win.state === 'minimized') {
+          await chrome.windows.update(target.windowId, { state: 'normal' }); // no focused:true
+        }
+      }
+      if (!target.active) await chrome.tabs.update(target.id, { active: true });
+      await new Promise(r => setTimeout(r, 150));
+      target = await chrome.tabs.get(target.id);
+    } catch { /* best-effort; capture path surfaces the real error */ }
   }
 
   return target;
@@ -233,34 +266,39 @@ async function debuggerAttach(tabId) {
     debuggerAttached.delete(tabId);
   }
 
-  try {
-    await chrome.debugger.attach({ tabId }, '1.3');
-    // Verify attach actually took effect (Chrome can silently no-op after user-cancel)
-    if (await verifyAttachedWithChrome(tabId)) {
-      debuggerAttached.add(tabId);
-      return;
-    }
-    throw new Error(
-      `Debugger detached (GHOST_ATTACH): chrome.debugger.attach returned success but Chrome state shows tab ${tabId} not attached. ` +
-      `This typically means the user clicked "Cancel" on Chrome's debugger banner. ` +
-      `Fix: reload Browser MCP extension (chrome://extensions/ → ↻) or restart Chrome.`
-    );
-  } catch (e) {
-    if (e.message?.includes('Already attached')) {
-      // Chrome side has session — sync local cache
-      debuggerAttached.add(tabId);
-      return;
-    }
-    if (e.message?.includes('Cannot attach') || e.message?.includes('canceled') || e.message?.includes('GHOST_ATTACH') || e.message?.includes('Debugger detached')) {
-      throw new Error(
-        `Debugger detached (BLOCKED_BY_USER): Cannot attach debugger to tab ${tabId}. ` +
-        `Chrome blocks debugger attach — user likely clicked "Cancel" on debugger banner earlier this session. ` +
-        `Fix: chrome://extensions/ → Browser MCP → reload (↻) icon. Or restart Chrome. ` +
-        `Original error: ${e.message}`
-      );
+  // Up to 3 attempts. A "ghost attach" (attach resolves but getTargets shows the tab
+  // NOT attached) is usually TRANSIENT: the page is mid-navigation/reload — e.g. the
+  // Metro dev-server rebuilding localhost:8081 auto-detaches the debugger. Retrying
+  // after a short delay lets the reload settle. Only a ghost that survives all retries
+  // is a real user-canceled banner. (Previously we threw on the first ghost, which made
+  // dev-server URLs unusable during their initial bundle.)
+  let lastMsg = '';
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await chrome.debugger.attach({ tabId }, '1.3');
+      if (await verifyAttachedWithChrome(tabId)) {
+        debuggerAttached.add(tabId);
+        return;
+      }
+      // Ghost — detach cleanly so the next attempt starts fresh, then retry.
+      lastMsg = 'attach resolved but Chrome shows tab not attached (ghost — page likely mid-reload)';
+      try { await chrome.debugger.detach({ tabId }); } catch {}
+    } catch (e) {
+      if (e.message?.includes('Already attached')) {
+        // Chrome side has session — sync local cache
+        debuggerAttached.add(tabId);
+        return;
+      }
+      // "Cannot attach"/"canceled" can also be transient during navigation — retry too.
+      lastMsg = e.message || String(e);
     }
-    throw e;
+    if (attempt < 2) await new Promise(r => setTimeout(r, 250 + attempt * 250));
   }
+  throw new Error(
+    `Debugger attach failed after 3 attempts (tab ${tabId}). Last: ${lastMsg}. ` +
+    `If persistent: the page may be continuously reloading (dev-server mid-build — wait, then retry), ` +
+    `or the user canceled Chrome's debugger banner — reload Browser MCP (chrome://extensions/ → ↻) or restart Chrome.`
+  );
 }
 
 async function debuggerDetach(tabId) {
@@ -409,6 +447,20 @@ async function debuggerClick(tabId, x, y) {
           el = inner; host = inner;
         }
         window.__bmcpClickTarget = el || null;
+        // FIX-13: watch whether the trusted click (step 2) actually lands on the target,
+        // so step 3's framework-fallback does NOT double-fire on elements that stay
+        // connected (toggles, checkboxes, add-to-cart, form fields).
+        window.__bmcpClicked = false;
+        try { window.__bmcpClickListener && document.removeEventListener('click', window.__bmcpClickListener, true); } catch (e) {}
+        window.__bmcpClickListener = (ev) => {
+          try {
+            const t = ev.target;
+            if (el && (t === el || el.contains(t) || (ev.composedPath && ev.composedPath().includes(el)))) {
+              window.__bmcpClicked = true;
+            }
+          } catch (e) {}
+        };
+        document.addEventListener('click', window.__bmcpClickListener, true);
       })()`,
     });
     // 1. mouseMoved first (triggers hover state, required by some frameworks)
@@ -435,7 +487,10 @@ async function debuggerClick(tabId, x, y) {
     await cdpSend(tabId, 'Runtime.evaluate', {
       expression: `(() => {
         const el = window.__bmcpClickTarget;
-        try { delete window.__bmcpClickTarget; } catch (e) {}
+        const landed = window.__bmcpClicked === true;
+        try { window.__bmcpClickListener && document.removeEventListener('click', window.__bmcpClickListener, true); } catch (e) {}
+        try { delete window.__bmcpClickTarget; delete window.__bmcpClicked; delete window.__bmcpClickListener; } catch (e) {}
+        if (landed) return;                   // FIX-13: trusted click already landed — do NOT double-fire
         if (!el || !el.isConnected) return;   // already navigated/handled — don't double-fire
         const opts = { bubbles: true, cancelable: true, composed: true, view: window, clientX: ${x}, clientY: ${y} };
         try { el.dispatchEvent(new PointerEvent('pointerdown', opts)); } catch (e) {}
@@ -515,9 +570,9 @@ async function debuggerFill(tabId, selector, value) {
   await debuggerFocus(tabId, selector);
   await debuggerAttach(tabId);
   try {
-    // Ctrl+A to select all, then Backspace to clear
+    // Select-all (Cmd+A on macOS, Ctrl+A elsewhere), then Backspace to clear
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: 2,
+      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: SELECT_ALL_MODS,
     });
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
       type: 'keyUp', key: 'a', code: 'KeyA',
@@ -617,10 +672,20 @@ async function safeExecuteScript(tabId, func, args = [], world = 'MAIN') {
 
 function buildTextFinderJS(textPattern, tagFilter) {
   const escaped = JSON.stringify(textPattern);
-  const tagCheck = tagFilter ? `&& el.tagName === ${JSON.stringify(tagFilter.toUpperCase())}` : '';
+  const wantTag = tagFilter ? JSON.stringify(tagFilter.toUpperCase()) : 'null';
   return `(function() {
     const text = ${escaped};
-    // Collect all elements including inside shadow DOM
+    const wantTag = ${wantTag};
+    // Interactive controls we prefer to actually click. Fixes the class of bug where a
+    // text match lands on a large CONTAINER (e.g. Angular Material <mat-nav-list>,
+    // toolbar, list-item) whose center is NOT over the real <button> — so the trusted
+    // click misses and menus/dropdowns never open.
+    const CLICKABLE = 'a,button,summary,label,[role="button"],[role="menuitem"],' +
+      '[role="menuitemcheckbox"],[role="menuitemradio"],[role="option"],[role="tab"],' +
+      '[role="link"],[role="checkbox"],[role="radio"],[role="switch"],[onclick],' +
+      '[mat-button],[mat-raised-button],[mat-stroked-button],[mat-flat-button],' +
+      '[mat-icon-button],[mat-fab],[mat-mini-fab],[mat-menu-item],[mat-list-item],' +
+      'mat-checkbox,mat-slide-toggle,mat-radio-button';
     function collectAll(root, results) {
       for (const el of root.querySelectorAll('*')) {
         results.push(el);
@@ -629,23 +694,34 @@ function buildTextFinderJS(textPattern, tagFilter) {
       return results;
     }
     const all = collectAll(document, []);
-    // Exact match first (prefer leaf nodes)
-    for (const el of all) {
-      if (el.children.length > 3) continue;
-      const t = el.textContent?.trim();
-      if (t === text ${tagCheck}) {
-        return el;
-      }
-    }
-    // Partial match fallback
-    for (const el of all) {
-      if (el.children.length > 3) continue;
-      const t = el.textContent?.trim();
-      if (t && t.includes(text) ${tagCheck}) {
-        return el;
+    const tagOk = (el) => !wantTag || el.tagName === wantTag;
+    // Map a matched element to the ACTIONABLE control: itself if clickable, else the
+    // nearest clickable ancestor (only if its own text isn't much larger than the match,
+    // so we don't grab a whole toolbar), else a clickable descendant.
+    function toClickable(el) {
+      if (el.matches && el.matches(CLICKABLE)) return el;
+      const anc = el.closest && el.closest(CLICKABLE);
+      if (anc && (anc.textContent || '').trim().length <= text.length + 40) return anc;
+      const desc = el.querySelector && el.querySelector(CLICKABLE);
+      if (desc) return desc;
+      return el;
+    }
+    function pick(test) {
+      const matches = all.filter(el => tagOk(el) && test((el.textContent || '').trim()));
+      if (!matches.length) return null;
+      // Prefer the INNERMOST matches (an element that is not an ancestor of another
+      // match) — this is what "prefer leaf nodes" was supposed to do.
+      const inner = matches.filter(el => !matches.some(o => o !== el && el.contains && el.contains(o)));
+      const pool = inner.length ? inner : matches;
+      // Prefer a match that resolves to a real interactive control.
+      for (const el of pool) {
+        const c = toClickable(el);
+        if (c && c.matches && c.matches(CLICKABLE)) return c;
       }
+      return toClickable(pool[0]);
     }
-    return null;
+    // Exact match first, then partial fallback.
+    return pick(t => t === text) || pick(t => t && t.includes(text));
   })()`;
 }
 
@@ -771,7 +847,7 @@ chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
       dispatch(port, msg.method, msg.params)
         .then(result => sendResponse(result))
         .catch(err => sendResponse({ __error: err.message || String(err) }));
-    });
+    }).catch(err => sendResponse({ __error: err.message || String(err) })); // else a storage-restore reject hangs the caller
     return true; // async response
   }
 
@@ -829,22 +905,6 @@ chrome.tabs.onCreated.addListener(async (tab) => {
   }
 });
 
-// ── CAPTCHA Detection ────────────────────────────────────────────────────────
-
-async function detectCaptcha(tabId) {
-  try {
-    return await debuggerEval(tabId, `
-      (function() {
-        if (document.querySelector('iframe[src*="hcaptcha.com"]') || document.querySelector('.h-captcha')) return 'hcaptcha';
-        if (document.querySelector('iframe[src*="recaptcha"]') || document.querySelector('.g-recaptcha')) return 'recaptcha';
-        if (document.querySelector('iframe[src*="challenges.cloudflare.com"]') || document.querySelector('.cf-turnstile')) return 'turnstile';
-        if (document.documentElement.innerHTML.includes('challenge-platform')) return 'challenge';
-        return null;
-      })()
-    `);
-  } catch { return null; }
-}
-
 // ── Deep Shadow DOM Query ────────────────────────────────────────────────────
 // querySelectorDeep: finds elements inside shadow DOMs (Shopify, Salesforce, etc.)
 
@@ -995,7 +1055,7 @@ async function setDateMaskedTyping(tabId, selector, iso, format) {
   await debuggerAttach(tabId);
   try {
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: 2,
+      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: SELECT_ALL_MODS,
     });
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
       type: 'keyUp', key: 'a', code: 'KeyA',
@@ -1039,23 +1099,6 @@ async function isPickerOpen(tabId) {
   })()`);
 }
 
-async function getPickerRoot(tabId) {
-  return await debuggerEval(tabId, `(() => {
-    const sels = ${JSON.stringify(PICKER_OPEN_SELECTORS)};
-    for (const s of sels) {
-      try {
-        const el = document.querySelector(s);
-        if (el) {
-          const root = el.closest('[role="dialog"], .react-datepicker, .MuiPickersPopper-root, .ant-picker-dropdown') || el;
-          // Return a stable selector path — for runtime use we re-query each time
-          return true;
-        }
-      } catch {}
-    }
-    return false;
-  })()`);
-}
-
 async function setDatePicker(tabId, selector, iso) {
   const [yStr, mStr, dStr] = iso.split('-');
   const targetYear = parseInt(yStr, 10);
@@ -1712,26 +1755,61 @@ async function dispatch(port, method, params) {
     }
 
     case 'screenshot': {
-      const tab = await getSessionTab(port);
-      if (tab.url.startsWith('chrome://')) throw new Error('Cannot screenshot chrome:// pages');
-      // Use debugger Page.captureScreenshot as PRIMARY method.
-      // captureVisibleTab requires active tab in active window — fails when
-      // user is in terminal. Debugger works regardless of tab focus.
-      try {
-        await debuggerAttach(tab.id);
-        const { data } = await cdpSend(tab.id, 'Page.captureScreenshot', {
-          format: 'png',
-        });
-        return { image: 'data:image/png;base64,' + data };
-      } catch {
-        // Debugger failed — fall back to captureVisibleTab (needs active tab)
+      // getSessionTab(…, true) is focus-NEUTRAL now: it un-minimizes + activates the tab
+      // but does NOT steal window focus (FIX-1). Screenshots run constantly, so the common
+      // path must never yank Chrome to the foreground.
+      const tab = await getSessionTab(port, true);
+      if (tab.url.startsWith('chrome://') || tab.url.startsWith('about:')) {
+        throw new Error(`Cannot screenshot ${tab.url.split(':')[0]}: pages — navigate to a real page first`);
+      }
+      // Capture without stealing focus: CDP Page.captureScreenshot (default → fromSurface:false
+      // retry) works for background/visible tabs; captureVisibleTab is the secondary.
+      const tryCapture = async () => {
         try {
-          await chrome.tabs.update(tab.id, { active: true });
-          await new Promise(r => setTimeout(r, 150));
-          const dataUrl = await chrome.tabs.captureVisibleTab(null, { format: 'png' });
+          await debuggerAttach(tab.id);
+          try {
+            const shot = await cdpSend(tab.id, 'Page.captureScreenshot', { format: 'png' });
+            return { image: 'data:image/png;base64,' + shot.data };
+          } catch {
+            const shot = await cdpSend(tab.id, 'Page.captureScreenshot', {
+              format: 'png', fromSurface: false, captureBeyondViewport: false,
+            });
+            return { image: 'data:image/png;base64,' + shot.data };
+          }
+        } catch {
+          // CDP failed entirely — native tabs API (needs the tab visible in its window).
+          const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' });
           return { image: dataUrl };
-        } catch (e) {
-          throw new Error('Screenshot failed: ' + e.message);
+        }
+      };
+
+      // Attempt 1 — focus-neutral. Handles the vast majority (background-but-visible window).
+      try {
+        return await tryCapture();
+      } catch (firstErr) {
+        // Both methods failed → the window is genuinely OCCLUDED (covered by other windows),
+        // so Chrome's compositor produced no frames. LAST RESORT ONLY: raise the window to
+        // de-occlude it, capture, then RESTORE the user's previously-focused window. This
+        // focus-steal happens ONLY in the rare covered case — never on a normal screenshot.
+        const prev = await chrome.windows.getLastFocused().catch(() => null);
+        try {
+          await chrome.windows.update(tab.windowId, { focused: true, state: 'normal' });
+          await chrome.tabs.update(tab.id, { active: true }).catch(() => {});
+          await new Promise(r => setTimeout(r, 250)); // let it composite
+          return await tryCapture();
+        } catch (secondErr) {
+          throw new Error(
+            `Screenshot failed after focus-neutral AND raised attempts. ` +
+            `First: ${firstErr?.message || firstErr}. Raised: ${secondErr?.message || secondErr}. ` +
+            `If both say "image readback failed" the GPU compositor is not producing frames — ` +
+            `disable Chrome hardware acceleration (chrome://settings/system) as a last resort.`
+          );
+        } finally {
+          // Give focus back to the user's previous Chrome window (best-effort; getLastFocused
+          // only sees Chrome windows, so a non-Chrome IDE can't be re-focused programmatically).
+          if (prev && prev.id != null && prev.id !== tab.windowId) {
+            await chrome.windows.update(prev.id, { focused: true }).catch(() => {});
+          }
         }
       }
     }
@@ -1797,13 +1875,50 @@ async function dispatch(port, method, params) {
         diag.main_throw = String(e?.message || e);
       }
 
-      // Step 3: DIAG MODE — don't fallback to debugger, return scripting-state info instead
-      return {
-        result: '__SCRIPTING_FAILED__',
-        method: 'scripting-failed',
-        diag,
-        note: 'Both ISOLATED + MAIN scripting paths returned null/error. See diag for details.',
-      };
+      // Step 3: debugger fallback — the ONLY universal path for arbitrary STRING code
+      // (both scripting worlds block `new Function`: ISOLATED via MV3 extension-CSP,
+      // MAIN via the page's own unsafe-eval CSP). CDP Runtime.evaluate bypasses CSP.
+      // FIX (2026-07-16): retry on an EMPTY/undefined CDP response. On some pages the
+      // debugger auto-detaches mid-command and `chrome.debugger.sendCommand` RESOLVES
+      // with `undefined` instead of rejecting, so cdpSend's throw-based retry never
+      // fires and debuggerEval silently returned undefined → the caller saw a bare
+      // `{method:"debugger"}` with no result. Also surface script exceptions + raw
+      // diagnostics so a genuine failure is never mistaken for an empty success.
+      let rawDbg, dbgErr = '';
+      for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+          await debuggerAttach(tab.id);
+          rawDbg = await cdpSend(tab.id, 'Runtime.evaluate', {
+            expression: '(' + params.code + '\n)',
+            returnByValue: true,
+            awaitPromise: true,
+          });
+          if (rawDbg && rawDbg.exceptionDetails) {
+            const ex = rawDbg.exceptionDetails;
+            await debuggerDetach(tab.id).catch(() => {});
+            throw new Error('__SCRIPT_EX__' + (ex.exception?.description || ex.text || 'Script exception'));
+          }
+          if (rawDbg && rawDbg.result && rawDbg.result.type !== 'undefined') {
+            await debuggerDetach(tab.id).catch(() => {});
+            return { result: rawDbg.result.value, method: 'debugger' };
+          }
+          dbgErr = 'empty/undefined CDP response: ' + JSON.stringify(rawDbg);
+        } catch (e) {
+          const m = String(e?.message || e);
+          if (m.startsWith('__SCRIPT_EX__')) {
+            throw new Error(m.slice('__SCRIPT_EX__'.length) + ' | scripting-diag: ' + JSON.stringify(diag));
+          }
+          dbgErr = m;
+          if (!/detach|attach|empty|gone|given id|not attached/i.test(m)) break;
+        }
+        await debuggerDetach(tab.id).catch(() => {});
+        await new Promise(r => setTimeout(r, 200 + attempt * 200));
+      }
+      throw new Error(
+        'execute_script failed on all paths. debugger: ' + dbgErr +
+        ' | raw: ' + JSON.stringify(rawDbg) +
+        ' | scripting-diag: ' + JSON.stringify(diag)
+      );
     }
 
     case 'click': {

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Agent360 Browser MCP",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Control your real Chrome from Claude Code — navigate, click, fill, screenshot, solve CAPTCHAs. 34 tools, multi-session.",
   "permissions": [
     "tabs",

package/index.js

@@ -209,7 +209,7 @@ const INSTRUCTIONS = `You control the user's real Chrome browser via this MCP se
 ## CAPTCHA handling
 Use browser_solve_captcha to detect and solve CAPTCHAs automatically:
 1. Call browser_solve_captcha() — detects CAPTCHA type on page
-2. If reCAPTCHA v2 checkbox found → call browser_solve_captcha(action="click_checkbox") — auto-clicks, passes ~80% with logged-in Google
+2. If reCAPTCHA v2 checkbox found → call browser_solve_captcha(action="click_checkbox") — auto-clicks; often passes when signed into Google
 3. If image challenge appears → call browser_screenshot, analyze the grid visually, then call browser_solve_captcha(action="click_grid", cells=[2,5,7]) with the correct cell indices
 4. If all else fails → call browser_solve_captcha(action="ask_human") to show overlay to user
 5. After solving, retry the action that was blocked
@@ -397,7 +397,7 @@ function handleAbout(args) {
 }
 
 async function handleExtractToken(args) {
-  const { provider, store_in_vault } = args;
+  const { provider } = args;
   const info = PROVIDER_PAGES[provider];
 
   if (!info) {
@@ -410,18 +410,11 @@ async function handleExtractToken(args) {
   }
 
   const nav = await sendToExtension('navigate', { url: info.url });
-  const content = [
-    { type: 'text', text: `Navigated to ${info.url} (${nav.title})\n\nInstructions: ${info.instructions}\n\nUse browser_get_page_content or browser_screenshot to find the token, then use browser_execute_script to extract it.` },
-  ];
-
-  if (store_in_vault) {
-    content.push({
-      type: 'text',
-      text: `\nWhen you have the token, POST it to the vault:\ncurl -X POST http://localhost:8000/v1/vault/connect -H "Authorization: Bearer {jwt}" -d '{"provider":"${provider}","token":"{extracted_token}"}'`,
-    });
-  }
-
-  return { content };
+  return {
+    content: [
+      { type: 'text', text: `Navigated to ${info.url} (${nav.title})\n\nInstructions: ${info.instructions}\n\nUse browser_get_page_content or browser_screenshot to find the token, then use browser_execute_script to extract it.` },
+    ],
+  };
 }
 
 // ── Graceful shutdown ──────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent360/browser-mcp",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Browser MCP — control your real Chrome from Claude Code. 34 tools, CAPTCHA solving, date pickers, autocomplete combobox, overlay dismissal, file upload, multi-session, human-in-the-loop.",
   "mcpName": "io.github.Agent360dk/browser-mcp",
   "type": "module",
@@ -42,7 +42,11 @@
   "engines": {
     "node": ">=18"
   },
-  "author": "Agent360 <hello@agent360.dk>",
+  "author": {
+    "name": "Agent360",
+    "email": "hello@agent360.dk",
+    "url": "https://agent360.dk"
+  },
   "license": "MIT",
   "homepage": "https://browsermcp.dev",
   "repository": {

package/tools.js

@@ -378,19 +378,18 @@ export const TOOLS = [
   },
   {
     name: 'browser_extract_token',
-    description: 'Navigate to a provider\'s API settings page and extract the API token. Optionally store it in Agent360 vault.',
+    description: 'Navigate to a provider\'s API settings page so you can read its API token from the page.',
     inputSchema: {
       type: 'object',
       properties: {
         provider: { type: 'string', description: 'Provider slug (stripe, hubspot, slack, etc.)' },
-        store_in_vault: { type: 'boolean', description: 'If true, POST token to Agent360 vault API' },
       },
       required: ['provider'],
     },
   },
   {
     name: 'browser_solve_captcha',
-    description: 'Detect and solve CAPTCHAs on the current page. Auto-detects reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and FunCaptcha. Tries auto-click first (works ~80% with logged-in Google), then returns a screenshot for AI vision analysis, then falls back to asking the user. Returns detection info and solving status.',
+    description: 'Detect and solve CAPTCHAs on the current page. Auto-detects reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and FunCaptcha. Tries auto-click first (often clears reCAPTCHA v2 when signed into Google), then returns a screenshot for AI vision analysis, then falls back to asking the user. Returns detection info and solving status.',
     inputSchema: {
       type: 'object',
       properties: {