chrome-bridge-mcp 1.23.0 → 1.23.3

package/README.md

@@ -2,20 +2,22 @@
 
 > By [frsorrentino](https://github.com/frsorrentino) · npm `chrome-bridge-mcp` · not affiliated with other projects named "chrome-bridge".
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-375%20unit%20%2B%2032%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-388%20unit%20%2B%2041%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **Claude Code borrows a tab from the Chrome you are already using — signed in,
 with your extensions and your cookies — works in it, and hands it back. What
 only a person can do (a login, a 2FA code, a CAPTCHA, a choice) comes back to
 you through `handoff`: a banner in the page, you act, the agent continues.**
 
-Measured on a form-filling task: 2.75× fewer turns and 2.28× lower cost than
-the official browser extension, with ~3× the toolset and no paid plan. 60
+Measured against the official browser extension (paired runs, 27/09/2026, n=5
+per task, same model): filling a form, 2.5× fewer turns and 1.9× lower cost;
+finding one row in a 1,500-row table, 2.3× lower cost in about the same number
+of turns. ~3× the toolset and no paid plan. 60
 web-development tools (navigation, DOM inspection, visual regression, audits,
 network mocking) over a local WebSocket bridge, plus a headless instance for
 CI. Self-hosted, local-only. Works on ChromeOS.
 
-![The same form filled in 6 turns instead of 16.5 — 2.75× fewer turns, 2.28× lower cost](assets/readme/card1-race.png)
+![The same form filled in 6 turns instead of 15 — 2.5× fewer turns on the form, about half the cost on the form and on a 1,500-row table (paired runs, 27/09/2026, n=5)](assets/readme/card1-race.png)
 
 ## Quickstart
 
@@ -40,6 +42,16 @@ element refs, `click(ref="n1")` follows with no discovery turn in between.
 > instead: an unpacked extension is dropped on every reboot, because the
 > container isn't mounted when Chrome starts.
 
+> **On Windows** `install.sh` does not run from PowerShell or cmd. Use the
+> plugin path below (`claude plugin marketplace add frsorrentino/chrome-bridge`,
+> then `claude plugin install chrome-bridge@chrome-bridge`) with the extension
+> from the Web Store, or run `install.sh` from Git Bash. The plugin's error
+> log hooks run in Git Bash, as Claude Code runs every hook, and need Python
+> 3.8+ as `python3`, `python` or `py` (the Microsoft Store `python3` alias is
+> skipped); without Python they stay silent and the tools work the same. For
+> launch mode see `CHROME_BRIDGE_BROWSER` below: Google Chrome cannot load the
+> extension there, Microsoft Edge can.
+
 `install.sh` registers the MCP server with `--scope user`. To do it by hand:
 `claude mcp add --scope user chrome-bridge node /path/to/server/index.js`.
 For `execute_js`, enable **Allow user scripts** in `chrome://extensions` →
@@ -94,9 +106,10 @@ the ChatGPT app required. Claude in Chrome documents Linux desktop since
 September 2026; ChromeOS and WSL stay out. Competitor figures measured on
 2026-09-01 and 2026-09-11 (`docs/analisi-2026-09-11-concorrenti.md`).
 
-It wins on **round trips, not payload size**: short element refs instead of the
-screenshot-and-click loop, `fill_form` filling N fields in one call, table
-filtering done server-side. Per single turn it actually costs slightly *more*.
+It wins on **round trips** — short element refs instead of the
+screenshot-and-click loop, `fill_form` filling N fields in one call — and, on
+big pages, on **payload**: table filtering is done server-side. On the form, per single turn it actually costs
+slightly *more*.
 
 The full benchmark — method, every raw run including the unfavourable ones, and
 what the harness can't measure — is in
@@ -135,6 +148,12 @@ isolated sessions or CI:
 node server/index.js --launch --headless
 ```
 
+It looks for Chromium, Microsoft Edge, Brave and last Google Chrome in their
+standard paths on Linux, macOS and Windows; `CHROME_BRIDGE_BROWSER` picks
+another binary. Google Chrome 137+ ignores `--load-extension`, so the
+extension never connects in it: use Chromium, Edge, Brave or Chrome for
+Testing.
+
 Pair it with `session_record` + `replay` for smoke tests with no model in the
 loop. In launch mode `execute_js` falls back to `new Function` when the
 user-script toggle isn't available.
@@ -183,6 +202,7 @@ Environment variables, each with a matching CLI flag:
 | `CHROME_BRIDGE_CAPS` / `--caps` | `core` | `core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, `all`. `install.sh` uses `all` |
 | `CHROME_BRIDGE_NO_JS` / `--no-js` | unset | No arbitrary JavaScript in the page: `execute_js` and `modify_dom` leave the schema, `wait_for(condition=function)` and `javascript:`/`data:` URLs are refused. `get_status` reports `js_evaluation` |
 | `CHROME_BRIDGE_READ_ROOT` / `--read-root` | unset | Where `upload_file` may read from. Unset: any file except keys and credentials (`~/.ssh`, `~/.aws`, `~/.gnupg`, `.env*`, `id_*`, `*.pem`, `*.key`, …), symlinks resolved first. Set: only files under this directory, whatever their name — the way to upload a certificate key on purpose |
+| `CHROME_BRIDGE_BROWSER` | unset | Launch mode only: the browser binary, e.g. `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`. Unset: the first of Chromium, Edge, Brave, Google Chrome found in the standard paths (on Linux Chromium, then Google Chrome). Google Chrome 137+ cannot load the extension |
 | `CHROME_BRIDGE_OBSERVE` | unset | `off` stops the local error log below. The plugin sets `hook`: its hooks keep the log and the server stays out of it |
 | `CHROME_BRIDGE_WRITE_ROOT` / `--write-root` | unset | Every path the model chooses (`save_to`, `output_path`, exports) must be under this directory, checked before the browser does any work; the server's own state under `~/.config/chrome-bridge` stays writable. The CLI is your shell and is not restricted |
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.23.0",
+  "version": "1.23.3",
   "type": "module",
-  "description": "Chrome Bridge by frsorrentino: MCP server that lets Claude Code borrow a tab from your own logged-in Chrome and hand it back — logins, 2FA and CAPTCHAs stay with you (handoff). 60 tools, 2.75× fewer turns measured, ChromeOS included.",
+  "description": "Chrome Bridge by frsorrentino: MCP server that lets Claude Code borrow a tab from your own logged-in Chrome and hand it back — logins, 2FA and CAPTCHAs stay with you (handoff). 60 tools; about half the cost of Claude in Chrome, measured; ChromeOS included.",
   "main": "server/index.js",
   "bin": {
     "chrome-bridge-mcp": "server/index.js",

package/server/index.js

@@ -13,7 +13,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { WSManager } from './ws-manager.js';
 import { registerTools } from './tools.js';
 import { createObserver } from './observe.js';
-import { launchBrowser } from './launcher.js';
+import { BRANDED_CHROME_HINT, launchBrowser } from './launcher.js';
 import { DEFAULT_PORT, VERSION } from './protocol.js';
 
 // Launch mode: browser dedicato (profilo effimero + estensione unpacked).
@@ -59,7 +59,7 @@ async function main() {
     instructions: [
       'Selectors on DOM tools pierce shadow DOM with ">>>" ("my-app >>> button.save").',
       'tab_id omitted = the tab last navigated/created in this session, else the active tab. frame_id omitted = main frame (list frames with get_frames).',
-      'To find targets use get_interactives, not read_page(html); its refs (n1, n2…) are the ref param of click/type_text/hover, and navigate already returns them.',
+      'To find targets use get_interactives, not read_page(html); its refs (n1, n2…) are the ref param of click/type_text/hover and of fill_form fields, and navigate already returns them.',
       // Il costo dominante sono i TURNI, non i byte: un turno vale ~15-30 volte
       // un KB di output risparmiato. Queste due clausole si pagano una volta
       // qui e valgono più di qualunque ottimizzazione di schema.
@@ -74,7 +74,9 @@ async function main() {
   });
 
   // 2. Avvia il WebSocket server
-  const wsManager = new WSManager(PORT, { host: HOST });
+  // Con --launch l'estensione arriva solo dopo l'avvio a freddo di Chrome: su
+  // una macchina carica servono decine di secondi, non i 10 s del default.
+  const wsManager = new WSManager(PORT, { host: HOST, ...(LAUNCH && !process.env.CHROME_BRIDGE_CONNECT_WAIT_MS && { connectWait: 30000 }) });
   await wsManager.start();
 
   // 2b. Launch mode: browser dedicato che si connette alla nostra porta.
@@ -106,6 +108,8 @@ async function main() {
       throw new Error(`--launch requires a dedicated port, but ${wsManager.port} is owned by another chrome-bridge. Unset CHROME_BRIDGE_PORT (ephemeral) or pick a free one.`);
     }
     browser = await launchBrowser({ port: wsManager.port, headless: HEADLESS });
+    // Il Chrome brandizzato parte ma resta muto: l'errore di connessione dice perche'
+    if (browser.branded) wsManager.notConnectedHint = BRANDED_CHROME_HINT;
   }
 
   // 3. Registra i tool MCP (filtrati per capability)

package/server/launcher.js

@@ -11,17 +11,50 @@ import { spawn } from 'node:child_process';
 import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const EXTENSION_SRC = join(dirname(fileURLToPath(import.meta.url)), '..', 'extension');
 
-const BROWSER_CANDIDATES = [
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-];
+/**
+ * Percorsi standard per piattaforma. Chromium, Edge e Brave prima di Google
+ * Chrome: il Chrome brandizzato dalla 137 ignora --load-extension, parte ma
+ * l'estensione non si connette mai (test Windows del 27/09: Chrome 155 muto,
+ * Edge 154 connesso in meno di 6 s).
+ */
+export function browserCandidates(platform = process.platform, env = process.env) {
+  if (platform === 'win32') {
+    const bases = [env.LOCALAPPDATA, env.PROGRAMFILES, env['PROGRAMFILES(X86)']].filter(Boolean);
+    return [
+      ['Chromium', 'Application', 'chrome.exe'],
+      ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
+      ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'],
+      ['Google', 'Chrome', 'Application', 'chrome.exe'],
+    ].flatMap((parts) => bases.map((b) => win32.join(b, ...parts)));
+  }
+  if (platform === 'darwin') {
+    return [
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    ];
+  }
+  return [
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+  ];
+}
+
+/** Google Chrome brandizzato (non Chromium, non Chrome for Testing). */
+export function isBrandedChrome(path) {
+  return /google[\\/ _-]?chrome/i.test(path) && !/for[ _-]?testing/i.test(path);
+}
+
+export const BRANDED_CHROME_HINT = 'Google Chrome 137+ ignores --load-extension, so launch mode cannot load the extension into it:'
+  + ' set CHROME_BRIDGE_BROWSER to Chromium, Microsoft Edge, Brave or Chrome for Testing';
 
 export function findBrowser() {
   if (process.env.CHROME_BRIDGE_BROWSER) {
@@ -30,9 +63,10 @@ export function findBrowser() {
     }
     return process.env.CHROME_BRIDGE_BROWSER;
   }
-  const found = BROWSER_CANDIDATES.find((p) => existsSync(p));
+  const candidates = browserCandidates();
+  const found = candidates.find((p) => existsSync(p));
   if (!found) {
-    throw new Error(`No Chromium/Chrome binary found (tried: ${BROWSER_CANDIDATES.join(', ')}). Set CHROME_BRIDGE_BROWSER.`);
+    throw new Error(`No Chromium-based browser found (tried: ${candidates.join(', ')}). Set CHROME_BRIDGE_BROWSER to Chromium, Edge, Brave or Chrome for Testing.`);
   }
   return found;
 }
@@ -93,5 +127,7 @@ export async function launchBrowser({ port, headless = false }) {
   };
 
   console.error(`[chrome-bridge] launched ${browser}${headless ? ' (headless)' : ''} pid=${proc.pid}, ws port ${port}`);
-  return { pid: proc.pid, stop };
+  const branded = isBrandedChrome(browser);
+  if (branded) console.error(`[chrome-bridge] warning: ${BRANDED_CHROME_HINT}`);
+  return { pid: proc.pid, stop, branded };
 }

package/server/observe.js

@@ -40,12 +40,51 @@ const DEFAULTS = { enabled: true, dir: '', max_records: 2000, max_days: 90 };
 // \w di Python è Unicode: qui lo stesso insieme, esplicito.
 const W = '[\\p{L}\\p{N}_]';
 
+// Una home in qualunque forma, come observe.py (claude-observe d3fa492, invio
+// anonimo da Windows): C:\Users\x, C:/Users/x, /c/Users/x, /mnt/c/Users/x,
+// /cygdrive/c/Users/x, \\?\C:\Users\x, i \\ dentro JSON, /home/x, /Users/x.
+const SEP = '[\\\\/]+';
+const DRIVE = '(?:(?:[\\\\/]{2}\\?[\\\\/]+)?\\b[a-z]:|/mnt/[a-z]|/cygdrive/[a-z]|/[a-z](?=[\\\\/]))';
+const SEG = '[^\\\\/\\s"\'`<>|:*?,;()\\[\\]]';
+// il nome della cartella puo' avere spazi: con gli spazi solo se dopo viene un separatore
+const HOME_ANY_RE = new RegExp(`${DRIVE}?${SEP}(?:users|home|documents and settings)${SEP}(?:${SEG}+(?: ${SEG}+)+(?=[\\\\/])|${SEG}+)`, 'giu');
+const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\/]/gu, '\\$&');
+
+// Le home di questa macchina senza distinzione di separatore, unita' e
+// maiuscole (anche una USERPROFILE fuori da Users), e il nome utente come
+// segmento di percorso.
+function homeRes(env = process.env) {
+  const homes = [...new Set([homedir(), env.USERPROFILE || '', env.HOME || ''])];
+  const pats = [];
+  for (const h of homes.sort((a, b) => b.length - a.length)) {
+    let parts = h.split(/[\\/]+/u).filter((x) => x && x !== '?');
+    if (!parts.length) continue;
+    const drive = parts.length > 1 ? /^([A-Za-z]):?$/u.exec(parts[0]) : null;
+    let head = '';
+    if (drive && (parts[0].endsWith(':') || parts[0].length === 1)) {
+      const d = drive[1];
+      head = `(?:(?:[\\\\/]{2}\\?[\\\\/]+)?\\b${d}:|/mnt/${d}|/cygdrive/${d}|/${d}(?=[\\\\/]))`;
+      parts = parts.slice(1);
+    }
+    pats.push(head + parts.map((x) => SEP + reEscape(x)).join(''));
+  }
+  const names = new Set(homes.filter(Boolean).map((h) => basename(h.replace(/\\/gu, '/').replace(/\/+$/u, ''))));
+  for (const k of ['USERNAME', 'USER', 'LOGNAME']) names.add(env[k] || '');
+  const list = [...names].filter((n) => n.length >= 2 && !['users', 'home'].includes(n.toLowerCase())).sort((a, b) => b.length - a.length);
+  return [
+    pats.map((p) => new RegExp(`${p}(?![^\\\\/\\s"'\`<>|:*?,;()\\[\\]])`, 'giu')),
+    list.length ? new RegExp(`(?<=[\\\\/])(?:${list.map(reEscape).join('|')})(?=[\\\\/\\s"'\`<>|:*?,;()\\[\\]]|$)`, 'giu') : null,
+  ];
+}
+const [HOME_RES, USER_SEG_RE] = homeRes();
+
 export function scrub(text, limit = 300) {
   let t = String(text ?? '');
-  const home = homedir();
-  if (home && home !== '/') t = t.split(home).join('~');
   t = t.replace(new RegExp(`(?:${W}|[.+-])+@(?:${W}|-)+\\.(?:${W}|[.-])+`, 'gu'), '<EMAIL>');
   t = t.replace(/(https?:\/\/[^/\s?#"'»]+)[^\s"'»]*/gu, '$1/…');
+  for (const r of HOME_RES) t = t.replace(r, '~');
+  t = t.replace(HOME_ANY_RE, '~');
+  if (USER_SEG_RE) t = t.replace(USER_SEG_RE, '<USER>');
   t = t.replace(/\b(token|password|passwd|secret|api[_-]?key|authorization|bearer)("?\s*[:=]\s*|\s+)\S+/giu, '$1$2<SECRET>');
   t = t.replace(/\b(value_after|value|text)("?\s*[:=]?\s*)("[^"]*"|'[^']*'|«[^»]*»)/giu, '$1$2<STR>');
   t = t.replace(/\b(?=[A-Za-z0-9_\-+/]*\d)(?=[A-Za-z0-9_\-+/]*[A-Za-z])[A-Za-z0-9_\-+/=]{24,}\b/gu, '<SECRET>');

package/server/protocol.js

@@ -93,7 +93,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.23.0';
+export const VERSION               = '1.23.3';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;

package/server/tools.js

@@ -149,13 +149,25 @@ export function jsResultText(data, max) {
   return fitString('result_json_prefix', JSON.stringify(value));
 }
 
+// Nome di colonna del where → chiave della riga. Il nome esatto vince; poi
+// senza maiuscole e spazi ai bordi: con {"sku": …} contro l'intestazione
+// "SKU" il filtro non trovava nulla e il modello ritentava (3 run su 5 del
+// benchmark del 27/09/2026).
+const normCol = (c) => String(c).trim().toLowerCase();
+function tableCell(row, col) {
+  if (Object.hasOwn(row, col)) return row[col];
+  const k = normCol(col);
+  const hit = Object.keys(row).find((h) => normCol(h) === k);
+  return hit === undefined ? undefined : row[hit];
+}
+
 /** Una riga (oggetto colonna→valore o array di celle) soddisfa il filtro where. */
 function tableRowMatches(row, where) {
   return Object.entries(where).every(([col, needle]) => {
     const n = String(needle).toLowerCase();
     if (Array.isArray(row)) return row.some((cell) => String(cell).toLowerCase().includes(n));
-    if (col === 'any') return Object.values(row).some((cell) => String(cell).toLowerCase().includes(n));
-    const cell = row[col];
+    if (normCol(col) === 'any') return Object.values(row).some((cell) => String(cell).toLowerCase().includes(n));
+    const cell = tableCell(row, col);
     return cell != null && String(cell).toLowerCase().includes(n);
   });
 }
@@ -254,6 +266,12 @@ async function savedSummary(path, bytes, extra = {}) {
 
 const selectorField = (extra = '') => z.string()
   .describe(('CSS selector; ">>>" pierces shadow DOM. ' + extra).trim());
+// fill_form con invio: quanto aspettare che il testo della pagina cambi, ogni
+// quanto rileggerlo, quanto testo nuovo restituire al modello.
+const SUBMIT_SETTLE_MS = 2000;
+const SUBMIT_POLL_MS = 250;
+const SUBMIT_TEXT_MAX = 800;
+
 const waitAfter = z.enum(['none', 'navigation', 'networkidle']).optional().default('none')
   .describe('Settle before returning: navigation waits for a page load, networkidle for quiet traffic');
 
@@ -605,6 +623,44 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     } catch { return null; }
   }
 
+  // Testo della pagina (o del frame) per il confronto prima/dopo un invio.
+  // Resta nel server: al modello arriva solo la differenza.
+  async function pageText(tab_id, frame_id) {
+    try {
+      const t = await send(MessageType.READ_PAGE, { mode: 'text', tab_id, frame_id });
+      return typeof t === 'string' ? t : null;
+    } catch { return null; }
+  }
+
+  // Esito di un invio: url, titolo e le righe di testo che la pagina ha
+  // guadagnato. Il testo può arrivare dopo (fetch, redirect): si rilegge per
+  // al più SUBMIT_SETTLE_MS e, al primo cambiamento, una volta ancora dopo una
+  // pausa breve, perché un «Invio in corso…» non venga preso per l'esito.
+  const cutText = (t, max) => (t.length <= max ? t : `${t.slice(0, max)}…[+${t.length - max} chars: read_page for the rest]`);
+
+  async function submitOutcome(tab_id, frame_id, textBefore, snap) {
+    const deadline = Date.now() + SUBMIT_SETTLE_MS;
+    let text = await pageText(tab_id, frame_id);
+    while ((text == null || text === textBefore) && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, SUBMIT_POLL_MS));
+      text = await pageText(tab_id, frame_id);
+    }
+    if (text != null && text !== textBefore) {
+      await new Promise((r) => setTimeout(r, SUBMIT_POLL_MS));
+      text = (await pageText(tab_id, frame_id)) ?? text;
+    }
+    const seen = new Set(textBefore.split('\n').map((l) => l.trim()));
+    const gained = text == null ? [] : text.split('\n').map((l) => l.trim()).filter((l) => l && !seen.has(l));
+    const snapNow = await tabSnapshot(tab_id) ?? snap;
+    return {
+      url: snapNow?.url ?? null,
+      title: snapNow?.title ?? null,
+      // truncateText suggerirebbe parametri che fill_form non ha: taglio secco.
+      new_text: gained.length ? cutText(gained.join('\n'), SUBMIT_TEXT_MAX) : null,
+      ...(!gained.length && { note: text === textBefore ? 'page text unchanged after submit' : 'page text unavailable' }),
+    };
+  }
+
   // Delta compatto dopo un'azione: solo ciò che è cambiato (url, title, conteggi
   // DOM con segno, fuoco). Costa pochi token quando scatta, zero quando la
   // pagina è stabile, e risparmia al client lo screenshot per capire "cosa è
@@ -1268,24 +1324,55 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
   server.tool(
     'fill_form',
     'Batch fill form fields with React-compatible events. Handles input, select, checkbox, radio, and textarea. '
-    + 'With submit_selector it also submits, so a repeated call submits twice — not safe to retry blindly. '
+    + 'Fields and submit take a CSS selector or a ref (n1, n2…) from navigate/get_interactives. '
+    + 'With submit_selector it also submits, so a repeated call submits twice — not safe to retry blindly; '
+    + 'after a submit, after_submit carries url, title and the text the page gained (the confirmation or the errors). '
     + 'Each field reports value_after and mismatch; page_changed carries the DOM delta.',
     {
       fields: z.array(z.object({
-        selector: z.string(),
-        value: z.string(),
-      })).describe('{selector, value} pairs'),
+        selector: z.string().optional().describe('CSS selector; ignored when ref is given'),
+        ref: z.string().optional().describe('From navigate or get_interactives, e.g. "n3"'),
+        value: z.string().optional().describe('Text, option value or label; for checkbox/radio "true"/"false"'),
+        checked: z.boolean().optional().describe('Checkbox/radio instead of value: true checks, false unchecks'),
+      })).describe('{selector or ref, value or checked} per field'),
       submit_selector: z.string().optional().describe('Submit button to click after filling'),
+      submit_ref: z.string().optional().describe('Submit button as a ref, instead of submit_selector'),
       wait_after: waitAfter,
       tab_id: tabId,
       frame_id: frameId,
     },
-    async ({ fields, submit_selector, wait_after, tab_id, frame_id }) => {
+    async ({ fields, submit_selector, submit_ref, wait_after, tab_id, frame_id }) => {
+      // I ref che navigate e get_interactives danno valevano per click,
+      // type_text e hover ma non qui: il modello li passava comunque e
+      // perdeva un turno sull'errore di validazione. Il ref vince sul
+      // selettore, come negli altri tool.
+      // checked: il modello lo scriveva per le checkbox e lo schema, che
+      // voleva solo value, lo rifiutava (un turno, benchmark del 27/09/2026).
+      // L'estensione capisce "true"/"false": la traduzione resta qui.
+      const resolved = fields.map((f) => {
+        const selector = resolveTarget(f.ref ? undefined : f.selector, f.ref, tab_id);
+        const value = f.value ?? (typeof f.checked === 'boolean' ? String(f.checked) : undefined);
+        if (value === undefined) throw new Error(`fill_form: field ${f.ref ?? f.selector} needs value or checked`);
+        return { selector, value };
+      });
+      const submitSel = submit_ref ? resolveTarget(undefined, submit_ref, tab_id) : submit_selector;
       const before = await tabSnapshot(tab_id);
-      const data = await send(MessageType.FILL_FORM, { fields, submit_selector, tab_id, frame_id });
+      const textBefore = submitSel ? await pageText(tab_id, frame_id) : null;
+      const data = await send(MessageType.FILL_FORM, { fields: resolved, submit_selector: submitSel, tab_id, frame_id });
       const waited = await applyWaitAfter(send, wait_after, tab_id);
-      const changed = pageDelta(before, await tabSnapshot(tab_id));
-      const out = { ...data, ...(waited && { wait_after: waited }), ...(changed && { page_changed: changed }) };
+      const after = await tabSnapshot(tab_id);
+      const changed = pageDelta(before, after);
+      // Dopo un invio il modello vuole sapere com'è andata: prima spendeva 1-3
+      // turni fra find_text, extract e read_page per leggere la conferma.
+      const afterSubmit = submitSel && textBefore != null
+        ? await submitOutcome(tab_id, frame_id, textBefore, after)
+        : null;
+      const out = {
+        ...data,
+        ...(waited && { wait_after: waited }),
+        ...(changed && { page_changed: changed }),
+        ...(afterSubmit && { after_submit: afterSubmit }),
+      };
       // I campi che non hanno tenuto il valore in testa, in chiaro: sono la
       // riga che il modello deve leggere prima del JSON.
       const mism = (data?.fields ?? []).filter((f) => f && f.mismatch);
@@ -2014,7 +2101,7 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
       selector: z.string().optional().default('table').describe('The table to read; ">>>" pierces shadow DOM'),
       index: z.number().optional().default(0).describe('Which table to take when the selector matches several, 0-based'),
       max_rows: z.number().optional().default(100).describe('Max rows returned to you (output cap).'),
-      where: z.record(z.string(), z.string()).optional().describe('{column: substring} rows must match, case-insensitive contains. Key "any" matches any cell.'),
+      where: z.record(z.string(), z.string()).optional().describe('{column: substring} rows must match, case-insensitive (names too). Key "any" matches any cell.'),
       columns: z.array(z.string()).optional().describe('Return only these columns per row.'),
       offset: z.number().optional().default(0).describe('Skip N rows of the (filtered) set before applying max_rows.'),
       scan_rows: z.number().optional().default(2000).describe('Max rows materialized in-page to scan/filter; raise for very large tables.'),

package/server/ws-manager.js

@@ -37,6 +37,13 @@ export class WSManager {
     this.pingIntervalMs = opts.pingInterval ?? PING_INTERVAL_MS;
     this.pongGraceMs = opts.pongGrace ?? 10000;
     this.lastPong = 0;
+    // Quanto un comando aspetta un'estensione non ancora collegata prima di
+    // fallire. Rifiutare subito costava turni: con --launch il primo navigate
+    // arrivava prima che il Chrome appena avviato si collegasse (4 run su 10
+    // del benchmark del 27/09/2026), e il modello si arrendeva o indagava.
+    this.connectWaitMs = opts.connectWait ?? (Number(process.env.CHROME_BRIDGE_CONNECT_WAIT_MS) || 10000);
+    // Launch mode con un browser che non puo' caricare l'estensione: sostituisce il consiglio generico
+    this.notConnectedHint = null;
     this.stopped = false;
     this.mode = null;            // 'primary' | 'relay'
     this.relayExtConnected = undefined;  // relay mode: stato estensione riportato dal primary
@@ -101,18 +108,39 @@ export class WSManager {
    * Funziona identicamente in primary e relay mode.
    */
   sendCommand(type, params = {}) {
-    return new Promise((resolve, reject) => {
-      if (!this.isConnected()) {
+    if (this.isConnected()) return this._send(type, params);
+    return this._waitConnected(this.connectWaitMs).then((ok) => {
+      if (!ok) {
         // Un errore vago qui costa un turno intero al modello: dice cosa
         // osservare e qual è la prossima azione.
-        reject(new Error(
+        throw new Error(
           `Chrome extension not connected (server ${this.mode} on ${this.host}:${this.port}`
-          + `${this.mode === 'relay' ? ', reached through another chrome-bridge instance' : ''})`
-          + ' — open Chrome, check the chrome-bridge extension is enabled and its port matches',
-        ));
-        return;
+          + `${this.mode === 'relay' ? ', reached through another chrome-bridge instance' : ''}`
+          + `, waited ${Math.round(this.connectWaitMs / 1000)}s)`
+          + ` — ${this.notConnectedHint || 'open Chrome, check the chrome-bridge extension is enabled and its port matches'}`,
+        );
       }
+      return this._send(type, params);
+    });
+  }
 
+  /** Attende che isConnected() diventi vero, al più `ms`; false allo scadere o allo stop. */
+  async _waitConnected(ms) {
+    // Un tool fa spesso più invii di fila (snapshot, comando, snapshot): dopo
+    // un'attesa appena scaduta si fallisce subito, invece di sommare N attese.
+    if (this._waitFailedAt && Date.now() - this._waitFailedAt < 5000) return false;
+    const deadline = Date.now() + ms;
+    while (!this.stopped && Date.now() < deadline) {
+      if (this.isConnected()) return true;
+      await new Promise((r) => setTimeout(r, Math.min(100, Math.max(1, deadline - Date.now()))));
+    }
+    const ok = !this.stopped && this.isConnected();
+    this._waitFailedAt = ok ? 0 : Date.now();
+    return ok;
+  }
+
+  _send(type, params) {
+    return new Promise((resolve, reject) => {
       const command = createCommand(type, params);
       // Il timeout di trasporto non può essere più basso di quello chiesto dal
       // chiamante: `wait_for --timeout 90000` moriva a 60 s con un messaggio