chromeflow 0.12.2 → 0.12.3

package/bin/chromeflow.mjs

@@ -2988,7 +2988,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3015,7 +3015,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3590,55 +3590,55 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative2, options, skipNormalization) {
+    function resolveComponent(base, relative3, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative2 = parse3(serialize(relative2, options), options);
+        relative3 = parse3(serialize(relative3, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative2.scheme) {
-        target.scheme = relative2.scheme;
-        target.userinfo = relative2.userinfo;
-        target.host = relative2.host;
-        target.port = relative2.port;
-        target.path = removeDotSegments(relative2.path || "");
-        target.query = relative2.query;
+      if (!options.tolerant && relative3.scheme) {
+        target.scheme = relative3.scheme;
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
-          target.userinfo = relative2.userinfo;
-          target.host = relative2.host;
-          target.port = relative2.port;
-          target.path = removeDotSegments(relative2.path || "");
-          target.query = relative2.query;
+        if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+          target.userinfo = relative3.userinfo;
+          target.host = relative3.host;
+          target.port = relative3.port;
+          target.path = removeDotSegments(relative3.path || "");
+          target.query = relative3.query;
         } else {
-          if (!relative2.path) {
+          if (!relative3.path) {
             target.path = base.path;
-            if (relative2.query !== void 0) {
-              target.query = relative2.query;
+            if (relative3.query !== void 0) {
+              target.query = relative3.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative2.path[0] === "/") {
-              target.path = removeDotSegments(relative2.path);
+            if (relative3.path[0] === "/") {
+              target.path = removeDotSegments(relative3.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative2.path;
+                target.path = "/" + relative3.path;
               } else if (!base.path) {
-                target.path = relative2.path;
+                target.path = relative3.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative3.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative2.query;
+            target.query = relative3.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3646,7 +3646,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative2.fragment;
+      target.fragment = relative3.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -3817,7 +3817,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -22495,7 +22495,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -22512,7 +22512,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -22590,7 +22590,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -22851,12 +22851,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -23956,7 +23956,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -24599,12 +24599,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json = serializeMessage(message);
       if (this._stdout.write(json)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
@@ -24725,7 +24725,7 @@ var WsBridge = class {
       }
     }
     const requestId = crypto.randomUUID();
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       let lastProgressAt = Date.now();
       const fire = () => {
         this.pending.delete(requestId);
@@ -24738,7 +24738,7 @@ var WsBridge = class {
         timer = setTimeout(fire, timeoutMs);
       };
       this.pending.set(requestId, {
-        resolve: resolve2,
+        resolve: resolve3,
         reject,
         timer,
         refresh
@@ -24761,9 +24761,10 @@ import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 var PROMOTE_AT_SUCCESS = 2;
+var DEMOTE_AT_FAILS = 1;
 var PRUNE_AT_FAILS = 2;
 var PROVISIONAL_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
-var ATOM_KEYS = ["tool", "target", "selector", "recovered_via", "signal", "fragile", "reason"];
+var ATOM_KEYS = ["tool", "target", "selector", "recovered_via", "signal", "verification", "clear_first", "fragile", "reason"];
 function originKey(url) {
   if (!url) return void 0;
   try {
@@ -24779,6 +24780,9 @@ var FRAGILE_RE = /:nth-(of-type|child)\(|>\s*\w+:nth/;
 function signatureOf(steps) {
   return JSON.stringify(steps.map((a) => [a.tool, a.target, a.selector ?? ""]));
 }
+function flowCost(f) {
+  return f.steps.reduce((c, s) => c + 1 + (s.fragile ? 1 : 0) + (s.recovered_via ? 0.5 : 0), 0);
+}
 function sanitizeAtom(a) {
   const out = {};
   for (const k of ATOM_KEYS) {
@@ -24795,6 +24799,27 @@ function autoLabel(k, steps) {
   }
   return `auto: ${tools} @ ${path2}`;
 }
+function actionableVia(recovered_via) {
+  if (recovered_via && recovered_via.includes("fiber")) return "fiber";
+  return null;
+}
+function renderStep(s, i) {
+  const fragNote = s.fragile ? "  \u26A0fragile \u2014 if it misses on the first try, do NOT retry it; rediscover" : "";
+  if (s.tool === "type_text") {
+    const sel = s.selector ?? s.target;
+    const cf = s.clear_first ? ", clear_first=true" : "";
+    return `   ${i + 1}. type_text(into_selector=${JSON.stringify(sel)}${cf})${fragNote}`;
+  }
+  if (s.tool === "click_element") {
+    const isSel = s.target.startsWith("selector=");
+    const targ = isSel ? `selector=${JSON.stringify(s.selector ?? s.target.replace(/^selector=/, ""))}` : `textHint=${JSON.stringify(s.target)}`;
+    const via = actionableVia(s.recovered_via);
+    const viaStr = via ? `, via=${JSON.stringify(via)}` : "";
+    const ver = s.verification ? `, ${s.verification}` : s.signal === "navigated" || s.signal === "until_url_change" ? ", until_url_changes=true" : "";
+    return `   ${i + 1}. click_element(${targ}${viaStr}${ver})${fragNote}`;
+  }
+  return `   ${i + 1}. ${s.tool} ${s.target}${s.fragile ? "  \u26A0fragile" : ""}`;
+}
 var FlowStore = class {
   path;
   data;
@@ -24807,6 +24832,10 @@ var FlowStore = class {
   // origins whose recall hint already fired this session
   recalled = /* @__PURE__ */ new Set();
   // origins whose trusted flow was actually shown this session
+  recalledFlows = /* @__PURE__ */ new Map();
+  // the flows we showed, for mismatch/confirm attribution
+  dinged = /* @__PURE__ */ new Set();
+  // flow ids already failed this session (no double-count)
   lastOrigin;
   lastAutosaved = null;
   // most recent autosave, for save_flow to vouch for
@@ -24861,6 +24890,21 @@ var FlowStore = class {
     }
     if (changed) this.persist();
   }
+  /**
+   * Record a failed/mismatched replay against a flow: demote on first, prune on
+   * second (via pruneExpired's PRUNE_AT_FAILS check). `dedupeKey` collapses the
+   * repeated mismatch check (which runs on every observe) to one ding per flow
+   * per session; explicit tool failures pass no key so each real failure counts.
+   */
+  failFlow(f, dedupeKey) {
+    if (dedupeKey) {
+      if (this.dinged.has(dedupeKey)) return;
+      this.dinged.add(dedupeKey);
+    }
+    f.fail_count += 1;
+    f.last_replay_ok = false;
+    if (f.tier === "trusted" && f.fail_count >= DEMOTE_AT_FAILS) f.tier = "provisional";
+  }
   /**
    * Update the "current origin". Crossing to a DIFFERENT origin first autosaves
    * the origin we are leaving — that boundary is our best server-side proxy for
@@ -24879,18 +24923,54 @@ var FlowStore = class {
     if (!atom) return;
     const k = originKey(url) ?? this.lastOrigin;
     if (!k) return;
+    this.reconcileAgainstRecalled(k, atom);
     const list = this.buffer.get(k) ?? [];
     const sig = `${atom.tool}|${atom.target}|${atom.selector ?? ""}`;
     if (list.some((a) => `${a.tool}|${a.target}|${a.selector ?? ""}` === sig)) return;
     list.push(sanitizeAtom(atom));
     this.buffer.set(k, list);
   }
+  /**
+   * When the agent performs a notable step on an origin we recalled a flow for,
+   * compare it to the recalled steps of the same tool:
+   *   - same locator  -> the recalled step worked: mark the flow's replay OK.
+   *   - different locator (and the recalled one was never used) -> the stored
+   *     selector was wrong; the agent silently rediscovered -> fail the flow.
+   * This catches the "wrong element but technically succeeded" case that the
+   * explicit failure signal misses, and is what neutralises a drifted Reddit-style
+   * shadow-DOM selector before it costs another session.
+   */
+  reconcileAgainstRecalled(k, atom) {
+    const shown = this.recalledFlows.get(k);
+    if (!shown) return;
+    const atomLoc = atom.selector ?? atom.target;
+    let changed = false;
+    for (const f of shown) {
+      const sameTool = f.steps.filter((s) => s.tool === atom.tool);
+      if (sameTool.length === 0) continue;
+      const usedRecalled = sameTool.some((s) => (s.selector ?? s.target) === atomLoc || s.target === atom.target);
+      if (usedRecalled) {
+        if (f.last_replay_ok !== true) {
+          f.last_replay_ok = true;
+          changed = true;
+        }
+      } else {
+        const before = f.fail_count;
+        this.failFlow(f, `mismatch:${f.id}`);
+        if (f.fail_count !== before) changed = true;
+      }
+    }
+    if (changed) this.persist();
+  }
   /** Autosave a single origin's buffer as a provisional flow (or promote a match). */
   autoCommit(k) {
     const buf = this.buffer.get(k);
     if (!buf || buf.length === 0) return;
     this.buffer.delete(k);
     this.upsert(k, buf, null);
+    if (buf.length > 1) {
+      for (const atom of buf) this.upsert(k, [atom], null);
+    }
     this.lastAutosaved = { key: k, sig: signatureOf(buf) };
     this.pruneExpired();
     this.persist();
@@ -24912,11 +24992,12 @@ var FlowStore = class {
     if (existing) {
       existing.success_count += 1;
       existing.last_verified = now;
+      existing.last_replay_ok = true;
       existing.chromeflow_version = this.version;
       if (label !== null) {
         existing.tier = "trusted";
         existing.task_label = label;
-      } else if (existing.success_count >= PROMOTE_AT_SUCCESS) {
+      } else if (existing.success_count - existing.fail_count >= PROMOTE_AT_SUCCESS) {
         existing.tier = "trusted";
       }
     } else {
@@ -24929,41 +25010,45 @@ var FlowStore = class {
         last_verified: now,
         success_count: 1,
         fail_count: 0,
+        last_replay_ok: true,
         chromeflow_version: this.version
       });
     }
     this.data.origins[k] = flows;
     return { saved: steps.length };
   }
-  /** Compact recall hint for an origin (TRUSTED flows only), at most once per origin per session. */
+  /** Compact recall hint for an origin (RELIABLE trusted flows only), once per origin per session. */
   recallHint(url) {
     const k = originKey(url);
     if (!k || this.surfaced.has(k)) return "";
-    const flows = (this.data.origins[k] ?? []).filter((f) => f.tier === "trusted");
+    const flows = (this.data.origins[k] ?? []).filter(
+      (f) => f.tier === "trusted" && f.success_count > f.fail_count && f.last_replay_ok !== false
+    );
     if (flows.length === 0) return "";
     this.surfaced.add(k);
     this.recalled.add(k);
-    const best = [...flows].sort((a, b) => b.success_count - a.success_count).slice(0, 3);
+    const best = [...flows].sort((a, b) => {
+      const ca = flowCost(a), cb = flowCost(b);
+      if (ca !== cb) return ca - cb;
+      return b.success_count - a.success_count;
+    }).slice(0, 3);
+    this.recalledFlows.set(k, best);
     const lines = best.map((f) => {
-      const steps = f.steps.map((s, i) => {
-        const via = s.recovered_via ? ` [via ${s.recovered_via}]` : "";
-        const sig = s.signal ? ` (${s.signal})` : "";
-        const frag = s.fragile ? " \u26A0fragile-selector" : "";
-        return `   ${i + 1}. ${s.tool} ${s.target}${sig}${via}${frag}`;
-      }).join("\n");
+      const steps = f.steps.map((s, i) => renderStep(s, i)).join("\n");
       const stale = f.chromeflow_version !== this.version ? ` recorded on v${f.chromeflow_version}, re-verify` : "";
       return `  "${f.task_label}" (${f.steps.length} steps, ${f.success_count}x ok${stale}):
 ${steps}`;
     });
     return `
 
-\u2139 known_flow for ${k} \u2014 prefer these proven steps over rediscovery (verify each as usual):
+\u2139 known_flow for ${k} \u2014 these calls worked before; prefer them over rediscovery, but VERIFY each. If a recalled step fails or its element isn't found on the first attempt, do NOT retry it \u2014 discard the hint and rediscover from scratch.
 ${lines.join("\n")}`;
   }
   /**
-   * A recalled trusted step failed on replay. Raise its fail_count; drop the flow
-   * once it crosses PRUNE_AT_FAILS. Gated on the flow having actually been recalled
-   * this session, so an unrelated failure can't ding a flow the agent never used.
+   * A recalled step failed on replay (a click that returned success:false, or a
+   * type_text that did not land). Demote the matching flow on the first miss,
+   * prune on the second. Gated on the flow having actually been recalled this
+   * session, so an unrelated failure can't ding a flow the agent never used.
    */
   observeFailure(url, selectorOrText) {
     const k = originKey(url) ?? this.lastOrigin;
@@ -24972,10 +25057,11 @@ ${lines.join("\n")}`;
     if (!flows) return;
     let changed = false;
     for (const f of flows) {
-      if (f.tier !== "trusted") continue;
-      const hit = f.steps.some((s) => s.selector === selectorOrText || s.target === selectorOrText || s.target === `selector=${selectorOrText}`);
+      const hit = f.steps.some(
+        (s) => s.selector === selectorOrText || s.target === selectorOrText || s.target === `selector=${selectorOrText}`
+      );
       if (hit) {
-        f.fail_count += 1;
+        this.failFlow(f);
         changed = true;
       }
     }
@@ -25029,15 +25115,10 @@ ${lines.join("\n")}`;
   }
 };
 function isFragileSelector(selector) {
-  return !!selector && FRAGILE_RE.test(selector);
+  if (!selector) return false;
+  return FRAGILE_RE.test(selector) || selector.includes(",");
 }
 
-// packages/mcp-server/src/tools/browser.ts
-import { writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync2 } from "fs";
-import { tmpdir, homedir as homedir2 } from "os";
-import { join as join2 } from "path";
-import { execSync } from "child_process";
-
 // packages/mcp-server/src/policy.ts
 function isBlockedUrl(rawUrl) {
   let parsed;
@@ -25063,8 +25144,8 @@ function isBlockedUrl(rawUrl) {
   return { blocked: false };
 }
 
-// packages/mcp-server/src/tools/browser.ts
-function registerBrowserTools(server, bridge, flowStore) {
+// packages/mcp-server/src/tools/browser/navigation.ts
+function registerNavigationTools(server, bridge, flowStore) {
   server.tool(
     "open_page",
     `Navigate to a URL. By default reuses the active tab. Set new_tab=true to open alongside the current tab without losing it. After navigating, call get_page_text to read the page \u2014 do NOT take a screenshot.
@@ -25118,6 +25199,38 @@ After tabs.onUpdated fires status=complete, chromeflow also runs a 6s settle che
       return { content: [{ type: "text", text }] };
     }
   );
+  server.tool(
+    "inspect_request_headers",
+    `Capture the request headers Chrome sends to a URL \u2014 useful for diagnosing server-side bot detection. Returns method, URL, and all headers. Cookie values are redacted by default to avoid leaking session tokens into the agent context; pass redact_cookies: false to see them. By default opens a background tab for the inspection so your active tab keeps its scroll position and form state \u2014 set new_tab: false to use the active tab instead.`,
+    {
+      url: external_exports.string().url().describe("URL to navigate to and capture headers for"),
+      redact_cookies: external_exports.boolean().optional().describe("Replace each cookie's value with [REDACTED]. Default true. Set false only when you genuinely need the cookie content for debugging."),
+      new_tab: external_exports.boolean().optional().describe("Open the inspection in a background tab and close it when done. Default true (preserves the active tab's state). Set false to use the active tab \u2014 the active tab WILL navigate.")
+    },
+    async ({ url, redact_cookies = true, new_tab = true }) => {
+      const block = isBlockedUrl(url);
+      if (block.blocked) {
+        return { content: [{ type: "text", text: `inspect_request_headers refused: ${block.reason}` }] };
+      }
+      const response = await bridge.request({ type: "inspect_request_headers", url, new_tab }, 3e4);
+      const r = response;
+      let text = r.message ?? "(no headers captured)";
+      if (redact_cookies) {
+        text = text.replace(/^(cookie:\s*)(.+)$/gim, (_m, prefix, body) => {
+          const pairs = String(body).split(";").map((s) => s.trim()).filter(Boolean);
+          const names = pairs.map((p) => p.split("=")[0]);
+          return `${prefix}[REDACTED \u2014 ${pairs.length} cookies: ${names.join(", ")}]`;
+        });
+      }
+      return {
+        content: [{ type: "text", text }]
+      };
+    }
+  );
+}
+
+// packages/mcp-server/src/tools/browser/tabs.ts
+function registerTabTools(server, bridge, flowStore) {
   server.tool(
     "switch_to_tab",
     `Switch the active tab to a different open tab. Use this after open_page(new_tab=true) to switch back to the original tab, or to jump between tabs.
@@ -25201,6 +25314,40 @@ ${keptList}` }]
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/browser/snapshot.ts
+function registerSnapshotTools(server, bridge) {
+  server.tool(
+    "interactive_snapshot",
+    `Compact, accessibility-style list of the page's ACTIONABLE elements \u2014 each as [role] name \u2014 selector. Use this INSTEAD of get_page_text or take_screenshot when your goal is to ACT (click / type / select), not to read prose: it is far cheaper in tokens than dumping page text, and every line gives a ready-to-use selector for click_element / type_text. Pierces open AND closed shadow roots (Reddit faceplate-*, Radix/Stencil/Lit), which a raw accessibility tree misses. Returns the top elements by document order; pass max to widen. For reading article/body text, still use get_page_text.`,
+    {
+      max: external_exports.number().int().min(1).optional().describe("Max elements to return (default 60).")
+    },
+    async ({ max }) => {
+      let response;
+      try {
+        response = await bridge.request({ type: "interactive_snapshot", max });
+      } catch {
+        return { content: [{ type: "text", text: "interactive_snapshot is unavailable (reload/update the chromeflow extension). Fall back to get_page_text + find_text for now." }] };
+      }
+      const items = response.items ?? [];
+      if (items.length === 0) {
+        return { content: [{ type: "text", text: "No actionable elements found (page may render inside a cross-origin iframe, or content is non-interactive)." }] };
+      }
+      const lines = items.map((it, i) => `${i + 1}. [${it.role}]${it.name ? " " + it.name : ""} \u2014 ${it.selector}`);
+      return { content: [{ type: "text", text: `Actionable elements (${items.length}):
+${lines.join("\n")}` }] };
+    }
+  );
+}
+
+// packages/mcp-server/src/tools/browser/screenshot.ts
+import { writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync2 } from "fs";
+import { tmpdir, homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { execSync } from "child_process";
+function registerScreenshotTools(server, bridge) {
   server.tool(
     "take_screenshot",
     `Capture a screenshot of the active tab. By default the image is returned to the agent inline UNLESS it exceeds ~500KB base64, in which case it's saved to a temp file and the path is returned instead (preserves the agent's context window). Set inline="always" to force inline regardless of size, or inline="never" to always write to a file. Set save_to or copy_to_clipboard to also share the image with the user. Reserved for cases where DOM lookup has already failed \u2014 use get_page_text and find_text for reading content.
@@ -25334,6 +25481,10 @@ The saved file path can be passed directly to set_file_input(hint, file_path) to
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/browser/forms.ts
+function registerFormFieldTools(server, bridge) {
   server.tool(
     "get_form_fields",
     `Inventory form fields on the active page (inputs, textareas, selects, CodeMirror editors). Sorted top-to-bottom by y-position; includes fields below the fold.
@@ -25393,6 +25544,10 @@ To fill: fill_input("${r2.fields[0].label}", "<value>")` }] };
 ${lines.join("\n")}${r.warning ?? ""}${captchaLine}${oauthLine}` }] };
     }
   );
+}
+
+// packages/mcp-server/src/tools/browser/typing.ts
+function registerTypingTools(server, bridge, flowStore) {
   server.tool(
     "type_text",
     `Type text into the currently focused element via CDP keystrokes (produces isTrusted=true events). Use when fill_input fails because the page validates isTrusted (CodeMirror/Monaco/Ace editors, shadow DOM inputs, isTrusted-gated forms). Pass \`into_selector\` to focus the target before typing (shadow-piercing CSS) \u2014 combined with \`clear_first: true\`, this collapses the old "wait_for_click \u2192 execute_script selectAll \u2192 type_text" pattern into a single call. Pass \`frame: "iframe.selector"\` to type into a same-origin iframe's first editable element.
@@ -25417,23 +25572,32 @@ ${lines.join("\n")}${r.warning ?? ""}${captchaLine}${oauthLine}` }] };
         timeoutMs
       );
       const r = response;
+      const typeFailed = r.success === false || r.landed === false;
+      const locator = r.resolved_selector || into_selector;
       let capturable = "";
-      if (into_selector && r.success !== false) {
+      if (into_selector && !typeFailed) {
         flowStore.observe({
           tool: "type_text",
-          target: into_selector,
-          selector: into_selector,
+          target: locator,
+          selector: locator,
           signal: clear_first ? "type_text(clear_first)" : "type_text",
-          fragile: isFragileSelector(into_selector),
+          clear_first: clear_first || void 0,
+          fragile: isFragileSelector(locator),
           reason: "field needs real keystrokes (type_text, not fill_input)"
         });
         capturable = flowStore.capturableHint(void 0);
+      } else if (into_selector && typeFailed) {
+        flowStore.observeFailure(void 0, locator);
       }
       return {
         content: [{ type: "text", text: (r.message ?? (r.success ? "Text typed successfully" : "Failed to type text")) + capturable }]
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/browser/files.ts
+function registerFileInputTools(server, bridge) {
   server.tool(
     "set_file_input",
     `Upload a file to a file input \u2014 works even when the input is hidden behind a custom drag-and-drop zone. Returns success=true only after an observable commit (file count goes up, input gets reset, or verify_selector appears within wait_ms). See CLAUDE.md for batch-upload guidance.
@@ -25489,6 +25653,10 @@ Provide file_path OR file_content, not both.`,
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/browser/scripting.ts
+function registerScriptingTools(server, bridge) {
   server.tool(
     "execute_script",
     `Execute JavaScript in a tab's MAIN world (the page's own context, not the extension's isolated world). Use for reading framework state or DOM properties not visible in text \u2014 prefer get_page_text for visible content. Top-level \`return\` and \`await\` are supported.
@@ -25537,34 +25705,18 @@ PAGE ALERT: "${alert}" \u2014 the page showed a dialog with this message. Read i
       };
     }
   );
-  server.tool(
-    "inspect_request_headers",
-    `Capture the request headers Chrome sends to a URL \u2014 useful for diagnosing server-side bot detection. Returns method, URL, and all headers. Cookie values are redacted by default to avoid leaking session tokens into the agent context; pass redact_cookies: false to see them. By default opens a background tab for the inspection so your active tab keeps its scroll position and form state \u2014 set new_tab: false to use the active tab instead.`,
-    {
-      url: external_exports.string().url().describe("URL to navigate to and capture headers for"),
-      redact_cookies: external_exports.boolean().optional().describe("Replace each cookie's value with [REDACTED]. Default true. Set false only when you genuinely need the cookie content for debugging."),
-      new_tab: external_exports.boolean().optional().describe("Open the inspection in a background tab and close it when done. Default true (preserves the active tab's state). Set false to use the active tab \u2014 the active tab WILL navigate.")
-    },
-    async ({ url, redact_cookies = true, new_tab = true }) => {
-      const block = isBlockedUrl(url);
-      if (block.blocked) {
-        return { content: [{ type: "text", text: `inspect_request_headers refused: ${block.reason}` }] };
-      }
-      const response = await bridge.request({ type: "inspect_request_headers", url, new_tab }, 3e4);
-      const r = response;
-      let text = r.message ?? "(no headers captured)";
-      if (redact_cookies) {
-        text = text.replace(/^(cookie:\s*)(.+)$/gim, (_m, prefix, body) => {
-          const pairs = String(body).split(";").map((s) => s.trim()).filter(Boolean);
-          const names = pairs.map((p) => p.split("=")[0]);
-          return `${prefix}[REDACTED \u2014 ${pairs.length} cookies: ${names.join(", ")}]`;
-        });
-      }
-      return {
-        content: [{ type: "text", text }]
-      };
-    }
-  );
+}
+
+// packages/mcp-server/src/tools/browser.ts
+function registerBrowserTools(server, bridge, flowStore) {
+  registerNavigationTools(server, bridge, flowStore);
+  registerTabTools(server, bridge, flowStore);
+  registerSnapshotTools(server, bridge);
+  registerScreenshotTools(server, bridge);
+  registerFormFieldTools(server, bridge);
+  registerTypingTools(server, bridge, flowStore);
+  registerFileInputTools(server, bridge);
+  registerScriptingTools(server, bridge);
 }
 
 // packages/mcp-server/src/tools/highlight.ts
@@ -25609,10 +25761,8 @@ Returns whether the element was found. Set valueToType only when the user must p
   );
 }
 
-// packages/mcp-server/src/tools/capture.ts
-import { appendFileSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
-import { resolve, relative, isAbsolute, dirname as dirname2 } from "path";
-function registerCaptureTools(server, bridge) {
+// packages/mcp-server/src/tools/capture/input.ts
+function registerInputTools(server, bridge) {
   server.tool(
     "fill_input",
     `Fill a form input by visible label / placeholder / aria-label (\`textHint\`) OR by direct CSS selector (\`selector\`). Pass exactly one.
@@ -25668,6 +25818,10 @@ Or pass selector="<css>" instead of textHint to bypass fuzzy matching entirely.`
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/capture/extract.ts
+function registerExtractTools(server, bridge) {
   server.tool(
     "get_page_text",
     `Get the visible text content of the current page without taking a screenshot.
@@ -25770,6 +25924,12 @@ Pass level="error" to see only errors, or omit to see all levels.`,
 ${lines.join("\n")}` }] };
     }
   );
+}
+
+// packages/mcp-server/src/tools/capture/files.ts
+import { appendFileSync, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { resolve, relative, isAbsolute } from "path";
+function registerFileTools(server, bridge) {
   server.tool(
     "write_to_env",
     "Write a key=value pair to a .env file. Use this after capturing an API key or ID from the page.",
@@ -25884,6 +26044,12 @@ Size: ${r.size} bytes`
       };
     }
   );
+}
+
+// packages/mcp-server/src/tools/capture/fetch.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve2, relative as relative2, isAbsolute as isAbsolute2, dirname as dirname2 } from "path";
+function registerFetchTools(server, bridge) {
   server.tool(
     "fetch_url",
     `Make an HTTP request to a URL from the extension's privileged context, bypassing the page's Content-Security-Policy.
@@ -25934,16 +26100,16 @@ Set binary=true for non-text responses (PDFs, images, zips) \u2014 the body is r
 \u26A0 anti_bot_detected: "${r.anti_bot_detected}" \u2014 response body matches a known block / challenge page. Don't parse as the expected JSON/HTML; the user's IP may be challenged or the endpoint may require a real browser context.` : "";
       if (to_file) {
         const cwd = process.cwd();
-        const resolved = isAbsolute(to_file) ? to_file : resolve(cwd, to_file);
-        const rel = relative(cwd, resolved);
-        if (rel.startsWith("..") || isAbsolute(rel)) {
+        const resolved = isAbsolute2(to_file) ? to_file : resolve2(cwd, to_file);
+        const rel = relative2(cwd, resolved);
+        if (rel.startsWith("..") || isAbsolute2(rel)) {
           throw new Error(
             `Refusing to write fetch_url body outside the project directory. Target "${resolved}" is not under "${cwd}".`
           );
         }
         mkdirSync2(dirname2(resolved), { recursive: true });
         const buf = r.body_base64 ? Buffer.from(r.body_base64, "base64") : Buffer.from(r.body_text ?? "", "utf-8");
-        writeFileSync3(resolved, buf);
+        writeFileSync4(resolved, buf);
         const hdrLines = Object.keys(r.headers).sort().map((k) => `  ${k}: ${r.headers[k]}`).join("\n");
         return {
           content: [{
@@ -25971,8 +26137,16 @@ ${r.body_text}` : "";
   );
 }
 
-// packages/mcp-server/src/tools/flow.ts
-function registerFlowTools(server, bridge, flowStore) {
+// packages/mcp-server/src/tools/capture.ts
+function registerCaptureTools(server, bridge) {
+  registerInputTools(server, bridge);
+  registerExtractTools(server, bridge);
+  registerFileTools(server, bridge);
+  registerFetchTools(server, bridge);
+}
+
+// packages/mcp-server/src/tools/flow/click.ts
+function registerClickTools(server, bridge, flowStore) {
   server.tool(
     "click_element",
     `Click an interactive element by its visible text/aria-label (textHint) OR by direct CSS selector (selector). Pass exactly one.
@@ -26075,6 +26249,7 @@ Current URL: ${activeTab.url}`;
       const actionUrl = r.before_url ?? r.after_url;
       const nowUrl = r.after_url ?? r.before_url;
       const usedUntil = !!(until_selector || until_url_contains || until_text_contains || until_url_changes);
+      const verification = until_url_changes ? "until_url_changes=true" : until_selector ? `until_selector=${JSON.stringify(until_selector)}` : until_url_contains ? `until_url_contains=${JSON.stringify(until_url_contains)}` : until_text_contains ? `until_text_contains=${JSON.stringify(until_text_contains)}` : expect_submit ? "expect_submit=true" : void 0;
       if (r.success && (r.recovered_via || r.navigated || usedUntil)) {
         flowStore.observe({
           tool: "click_element",
@@ -26082,6 +26257,7 @@ Current URL: ${activeTab.url}`;
           selector,
           recovered_via: r.recovered_via,
           signal: r.navigated ? "navigated" : until_url_changes ? "until_url_change" : usedUntil ? "until_*" : r.recovered_via,
+          verification,
           fragile: isFragileSelector(selector),
           reason: r.recovered_via ? `click recovered via ${r.recovered_via}` : r.navigated ? "navigating submit/link" : "verified terminal click"
         }, actionUrl);
@@ -26105,6 +26281,33 @@ Current URL: ${activeTab.url}`;
       };
     }
   );
+  server.tool(
+    "click_at_coordinates",
+    `Dispatch a real CDP mouse click at viewport (x, y). The only way to interact with cross-origin iframes \u2014 \`click_element\` refuses cross-origin frames because \`find_text\` can't enter them, but a CDP-level mouse event resolves at the renderer process and reaches the iframe's content the way an OS-level click does.
+
+Coordinates are viewport CSS pixels, NOT screen coordinates. \`list_frames\` reports each iframe at \`(x, y, width, height)\` in this same space, so to click 50px in / 80px down inside an iframe: \`click_at_coordinates(frame.x + 50, frame.y + 80)\`.
+
+Runs the same humanlike sequence as \`click_element\` (bezier approach path, settle-hover micro-tremor, press, release, post-click micro-move) so behavioural fingerprinters can't distinguish the call from any other chromeflow click. Skips the activity probe \u2014 cross-origin iframe activity isn't observable from the parent.
+
+Refuses obviously-bad coordinates (negative, > 10000). Use this only when DOM matching has failed and you have a known target position from \`list_frames\` or a screenshot.`,
+    {
+      x: external_exports.number().describe("Viewport CSS X coordinate (left=0). Get from list_frames or a screenshot grid."),
+      y: external_exports.number().describe("Viewport CSS Y coordinate (top=0). Get from list_frames or a screenshot grid."),
+      button: external_exports.enum(["left", "right", "middle"]).optional().describe('Mouse button (default "left").'),
+      double: external_exports.boolean().optional().describe("Fire a double-click instead of a single click. Default false.")
+    },
+    async ({ x, y, button, double }) => {
+      const response = await bridge.request({ type: "click_at_coordinates", x, y, button, double });
+      const r = response;
+      const navLine = r.navigated && r.after_url ? `
+\u2192 Navigated: ${r.after_url}` : "";
+      return { content: [{ type: "text", text: `${r.message}${navLine}` }] };
+    }
+  );
+}
+
+// packages/mcp-server/src/tools/flow/save.ts
+function registerSaveFlowTools(server, flowStore) {
   server.tool(
     "save_flow",
     `Trust the hard-won interaction steps chromeflow buffered for the current site, immediately, as a named flow. chromeflow auto-buffers only NOTABLE resolutions (a click that needed a fallback, a verified submit, a field that needed real keystrokes), and AUTOSAVES them as a provisional flow when you leave the site \u2014 so memory works even if you never call this. Provisional flows are not recalled until they have been independently re-observed, or until you vouch for them here. Calling save_flow promotes the buffered steps to TRUSTED right away (an explicit "I confirm this worked"), so they are recalled next session instead of waiting to earn it.
@@ -26118,6 +26321,10 @@ Call this when a response shows \`flow_capturable\` and you are confident the ta
       return { content: [{ type: "text", text: res.message }] };
     }
   );
+}
+
+// packages/mcp-server/src/tools/flow/wait.ts
+function registerWaitTools(server, bridge) {
   server.tool(
     "wait_for_click",
     `Wait for the user to click (or interact with) the currently highlighted element, then return.
@@ -26160,29 +26367,6 @@ CDP re-dispatched: isTrusted=true click at (${r.target?.x ?? 0}, ${r.target?.y ?
       };
     }
   );
-  server.tool(
-    "click_at_coordinates",
-    `Dispatch a real CDP mouse click at viewport (x, y). The only way to interact with cross-origin iframes \u2014 \`click_element\` refuses cross-origin frames because \`find_text\` can't enter them, but a CDP-level mouse event resolves at the renderer process and reaches the iframe's content the way an OS-level click does.
-
-Coordinates are viewport CSS pixels, NOT screen coordinates. \`list_frames\` reports each iframe at \`(x, y, width, height)\` in this same space, so to click 50px in / 80px down inside an iframe: \`click_at_coordinates(frame.x + 50, frame.y + 80)\`.
-
-Runs the same humanlike sequence as \`click_element\` (bezier approach path, settle-hover micro-tremor, press, release, post-click micro-move) so behavioural fingerprinters can't distinguish the call from any other chromeflow click. Skips the activity probe \u2014 cross-origin iframe activity isn't observable from the parent.
-
-Refuses obviously-bad coordinates (negative, > 10000). Use this only when DOM matching has failed and you have a known target position from \`list_frames\` or a screenshot.`,
-    {
-      x: external_exports.number().describe("Viewport CSS X coordinate (left=0). Get from list_frames or a screenshot grid."),
-      y: external_exports.number().describe("Viewport CSS Y coordinate (top=0). Get from list_frames or a screenshot grid."),
-      button: external_exports.enum(["left", "right", "middle"]).optional().describe('Mouse button (default "left").'),
-      double: external_exports.boolean().optional().describe("Fire a double-click instead of a single click. Default false.")
-    },
-    async ({ x, y, button, double }) => {
-      const response = await bridge.request({ type: "click_at_coordinates", x, y, button, double });
-      const r = response;
-      const navLine = r.navigated && r.after_url ? `
-\u2192 Navigated: ${r.after_url}` : "";
-      return { content: [{ type: "text", text: `${r.message}${navLine}` }] };
-    }
-  );
   server.tool(
     "wait_for",
     `Wait for one of: a CSS selector to appear, a text substring (or any of an array of substrings) to appear, or an existing element's subtree to mutate. Pass exactly one of \`selector\`, \`text\`, or \`change_in\`. Pierces open AND closed shadow roots (text \`scope_selector\` pierces too). Pass \`shadow_root: true\` when waiting for the host's shadowRoot to attach (post-SPA-navigation hydration). \`scope_selector\` limits text-mode search; \`regex: true\` interprets text as a case-insensitive regex; \`frame: "iframe.selector"\` waits inside a same-origin iframe (text mode).
@@ -26272,6 +26456,10 @@ Examples: scroll_to_element("#submit-btn"), scroll_to_element("Billing address")
       return { content: [{ type: "text", text: msg }] };
     }
   );
+}
+
+// packages/mcp-server/src/tools/flow/find.ts
+function registerFindTools(server, bridge) {
   server.tool(
     "find_text",
     `Search the active page for text and return actionable matches (text, surrounding context, best-effort CSS selector, clickable flag). Use this instead of get_page_text when checking "is X on the page?" or locating a clickable target. Pierces open AND closed shadow roots. Pass \`frame: "iframe.selector"\` for same-origin iframe search.
@@ -26340,38 +26528,6 @@ ${lines.join("\n")}` }]
       };
     }
   );
-  server.tool(
-    "fill_form",
-    `Fill multiple form fields in a single call by targeting each field by its label text.
-Use this instead of calling fill_input repeatedly \u2014 it fills all fields in one round trip and returns a per-field success report.
-Ideal for forms with many textareas or inputs where each fill would otherwise require a separate tool call.
-fields is an array of {label, value} pairs. label should match the field's visible label, placeholder, or aria-label.
-
-Each per-field result includes the matched element description (e.g. \`<input name="title" id="..." placeholder="...">\`) so Claude can spot when fill_form picked the wrong field.
-
-Pass \`exact: true\` for forms with short generic labels (like "Rate" or "Amount") that may collide with similarly-labeled neighbours \u2014 fields without an exact aria-label/placeholder/name/id/label-text match will return success=false instead of silently filling the wrong field.`,
-    {
-      fields: external_exports.array(
-        external_exports.object({
-          label: external_exports.string().describe("Visible label, placeholder, or aria-label of the field"),
-          value: external_exports.string().describe("Value to fill in")
-        })
-      ).describe("List of fields to fill"),
-      exact: external_exports.boolean().optional().describe("If true, refuse fuzzy text-walk matches for every field. Default false.")
-    },
-    async ({ fields, exact }) => {
-      const response = await bridge.request({ type: "fill_form", fields, exact });
-      const r = response;
-      const lines = r.results.map((f) => `${f.success ? "\u2713" : "\u2717"} "${f.label}": ${f.message}`);
-      return {
-        content: [{
-          type: "text",
-          text: `Filled ${r.succeeded}/${r.total} fields:
-${lines.join("\n")}`
-        }]
-      };
-    }
-  );
   server.tool(
     "list_frames",
     `List every top-level iframe/frame on the active page, with its origin, whether its contentDocument is accessible (same-origin), and its on-screen position. Also reports shadow-host inventory so you can spot pages whose visible content is rendered inside closed shadow roots (Radix portals, Stencil/Lit, custom web components).
@@ -26430,8 +26586,53 @@ ${lines.join("\n")}${shadowSection}` }] };
   );
 }
 
+// packages/mcp-server/src/tools/flow/forms.ts
+function registerFillFormTools(server, bridge) {
+  server.tool(
+    "fill_form",
+    `Fill multiple form fields in a single call by targeting each field by its label text.
+Use this instead of calling fill_input repeatedly \u2014 it fills all fields in one round trip and returns a per-field success report.
+Ideal for forms with many textareas or inputs where each fill would otherwise require a separate tool call.
+fields is an array of {label, value} pairs. label should match the field's visible label, placeholder, or aria-label.
+
+Each per-field result includes the matched element description (e.g. \`<input name="title" id="..." placeholder="...">\`) so Claude can spot when fill_form picked the wrong field.
+
+Pass \`exact: true\` for forms with short generic labels (like "Rate" or "Amount") that may collide with similarly-labeled neighbours \u2014 fields without an exact aria-label/placeholder/name/id/label-text match will return success=false instead of silently filling the wrong field.`,
+    {
+      fields: external_exports.array(
+        external_exports.object({
+          label: external_exports.string().describe("Visible label, placeholder, or aria-label of the field"),
+          value: external_exports.string().describe("Value to fill in")
+        })
+      ).describe("List of fields to fill"),
+      exact: external_exports.boolean().optional().describe("If true, refuse fuzzy text-walk matches for every field. Default false.")
+    },
+    async ({ fields, exact }) => {
+      const response = await bridge.request({ type: "fill_form", fields, exact });
+      const r = response;
+      const lines = r.results.map((f) => `${f.success ? "\u2713" : "\u2717"} "${f.label}": ${f.message}`);
+      return {
+        content: [{
+          type: "text",
+          text: `Filled ${r.succeeded}/${r.total} fields:
+${lines.join("\n")}`
+        }]
+      };
+    }
+  );
+}
+
+// packages/mcp-server/src/tools/flow.ts
+function registerFlowTools(server, bridge, flowStore) {
+  registerClickTools(server, bridge, flowStore);
+  registerSaveFlowTools(server, flowStore);
+  registerWaitTools(server, bridge);
+  registerFindTools(server, bridge);
+  registerFillFormTools(server, bridge);
+}
+
 // packages/mcp-server/src/index.ts
-var PACKAGE_VERSION = true ? "0.12.2" : "dev";
+var PACKAGE_VERSION = true ? "0.12.3" : "dev";
 main().catch((err) => {
   console.error("[chromeflow] Fatal error:", err);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "MCP server for chromeflow \u2014 lets Claude Code or Codex CLI drive your real Chrome browser with sessions intact. Plugin install recommended; npx chromeflow for manual MCP wiring.",
   "type": "module",
   "main": "./bin/chromeflow.mjs",