chromeflow 0.10.24 → 0.11.1

package/bin/chromeflow.mjs

@@ -24670,7 +24670,8 @@ var WsBridge = class {
           return;
         }
         if (msg.type === "ready") {
-          console.error("[chromeflow] Extension ready");
+          const token = typeof msg.token === "string" ? msg.token : void 0;
+          console.error(`[chromeflow] Extension ready${token ? " (token presented)" : ""}`);
           const cwd = process.cwd();
           const host = process.env.CHROMEFLOW_HOST ?? (process.env.CLAUDE_PLUGIN_ROOT ? "claude" : void 0);
           ws.send(JSON.stringify({
@@ -24755,10 +24756,153 @@ var WsBridge = class {
   }
 };
 
+// packages/mcp-server/src/flow-store.ts
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+function originKey(url) {
+  if (!url) return void 0;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return void 0;
+    const path2 = u.pathname && u.pathname !== "/" ? u.pathname.replace(/\/+$/, "") : "";
+    return u.origin + path2;
+  } catch {
+    return void 0;
+  }
+}
+var FRAGILE_RE = /:nth-(of-type|child)\(|>\s*\w+:nth/;
+var FlowStore = class {
+  path;
+  data;
+  version;
+  // In-memory, per-session state (never persisted):
+  buffer = /* @__PURE__ */ new Map();
+  // notable atoms not yet committed, by origin
+  surfaced = /* @__PURE__ */ new Set();
+  // origins whose recall hint already fired this session
+  lastOrigin;
+  constructor(version2, baseDir) {
+    this.version = version2;
+    this.path = join(baseDir ?? join(homedir(), ".chromeflow"), "flows.json");
+    this.data = this.load();
+  }
+  load() {
+    try {
+      if (existsSync(this.path)) {
+        const parsed = JSON.parse(readFileSync(this.path, "utf-8"));
+        if (parsed && parsed.version === 1 && parsed.origins) return parsed;
+      }
+    } catch {
+      try {
+        renameSync(this.path, this.path + ".corrupt");
+      } catch {
+      }
+    }
+    return { version: 1, origins: {} };
+  }
+  persist() {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const tmp = this.path + ".tmp";
+      writeFileSync(tmp, JSON.stringify(this.data, null, 2), "utf-8");
+      renameSync(tmp, this.path);
+    } catch {
+    }
+  }
+  /** Update the "current origin" from any URL chromeflow observed. */
+  noteUrl(url) {
+    const k = originKey(url);
+    if (k) this.lastOrigin = k;
+  }
+  /** Buffer a notable atom against an origin (defaults to last-seen origin). */
+  observe(atom, url) {
+    if (!atom) return;
+    const k = originKey(url) ?? this.lastOrigin;
+    if (!k) return;
+    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(atom);
+    this.buffer.set(k, list);
+  }
+  /** Compact recall hint for an origin, at most once per origin per session. */
+  recallHint(url) {
+    const k = originKey(url);
+    if (!k || this.surfaced.has(k)) return "";
+    const flows = this.data.origins[k];
+    if (!flows || flows.length === 0) return "";
+    this.surfaced.add(k);
+    const best = [...flows].sort((a, b) => b.success_count - a.success_count).slice(0, 3);
+    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 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):
+${lines.join("\n")}`;
+  }
+  /** Nudge to save buffered hard-won steps, when there are uncommitted ones. */
+  capturableHint(url) {
+    const k = originKey(url) ?? this.lastOrigin;
+    if (!k) return "";
+    const buf = this.buffer.get(k);
+    if (!buf || buf.length === 0) return "";
+    const reasons = [...new Set(buf.map((a) => a.reason))].slice(0, 2).join("; ");
+    return `
+
+\u2139 flow_capturable: ${buf.length} hard-won step(s) on ${k} not yet saved (${reasons}). Call save_flow("<task label>") to persist them so future runs skip the trial-and-error.`;
+  }
+  /** Commit the buffered atoms for an origin as a named flow. */
+  commit(taskLabel, url) {
+    const k = originKey(url) ?? this.lastOrigin;
+    if (!k) return { saved: 0, origin: null, message: "No origin known yet \u2014 navigate or interact with a page first." };
+    const buf = this.buffer.get(k) ?? [];
+    if (buf.length === 0) {
+      return { saved: 0, origin: k, message: `Nothing notable buffered for ${k}. Flows capture hard-won steps (a fallback fired, a verified submit, a field needing real keystrokes) \u2014 an ordinary first-try click isn't recorded.` };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const sig = JSON.stringify(buf.map((a) => [a.tool, a.target, a.selector ?? ""]));
+    const flows = this.data.origins[k] ?? [];
+    const existing = flows.find((f) => f.task_label === taskLabel && JSON.stringify(f.steps.map((a) => [a.tool, a.target, a.selector ?? ""])) === sig);
+    if (existing) {
+      existing.success_count += 1;
+      existing.last_verified = now;
+      existing.chromeflow_version = this.version;
+    } else {
+      flows.push({
+        id: `${k}#${flows.length + 1}`,
+        task_label: taskLabel,
+        steps: buf,
+        created_at: now,
+        last_verified: now,
+        success_count: 1,
+        fail_count: 0,
+        chromeflow_version: this.version
+      });
+    }
+    this.data.origins[k] = flows;
+    this.buffer.delete(k);
+    this.persist();
+    return { saved: buf.length, origin: k, message: `Saved flow "${taskLabel}" (${buf.length} steps) for ${k}.` };
+  }
+};
+function isFragileSelector(selector) {
+  return !!selector && FRAGILE_RE.test(selector);
+}
+
 // packages/mcp-server/src/tools/browser.ts
-import { writeFileSync, copyFileSync, readFileSync } from "fs";
-import { tmpdir, homedir } from "os";
-import { join } from "path";
+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
@@ -24787,7 +24931,7 @@ function isBlockedUrl(rawUrl) {
 }
 
 // packages/mcp-server/src/tools/browser.ts
-function registerBrowserTools(server, bridge) {
+function registerBrowserTools(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.
@@ -24836,6 +24980,8 @@ After tabs.onUpdated fires status=complete, chromeflow also runs a 6s settle che
 
 \u2139 dismissed_beforeunload: true \u2014 the previous page had unsaved content (typed text in a composer, form draft, etc.) and Chrome's "Are you sure you want to leave?" dialog was auto-dismissed so navigation could proceed. If that draft was load-bearing, navigate back and re-capture before continuing.`;
       }
+      flowStore.noteUrl(r.current_url ?? url);
+      text += flowStore.recallHint(r.current_url ?? url);
       return { content: [{ type: "text", text }] };
     }
   );
@@ -24942,13 +25088,13 @@ Refuses fast on pages that are in fullscreen mode (captureVisibleTab hangs there
       const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
       const filename = `chromeflow-${timestamp}.png`;
       const imageBuffer = Buffer.from(response.image, "base64");
-      const tmpPath = join(tmpdir(), filename);
+      const tmpPath = join2(tmpdir(), filename);
       const needTmp = !shouldInline || sharing;
-      if (needTmp) writeFileSync(tmpPath, imageBuffer);
+      if (needTmp) writeFileSync2(tmpPath, imageBuffer);
       const notes = [];
       let landedPath = tmpPath;
       if (save_to !== "none") {
-        const savePath = save_to === "cwd" ? join(process.cwd(), filename) : join(homedir(), "Downloads", filename);
+        const savePath = save_to === "cwd" ? join2(process.cwd(), filename) : join2(homedir2(), "Downloads", filename);
         copyFileSync(tmpPath, savePath);
         notes.push(`Saved to ${savePath}`);
         landedPath = savePath;
@@ -24990,7 +25136,7 @@ The saved file path can be passed directly to set_file_input(hint, file_path) to
     async ({ save_to = "downloads" }) => {
       const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
       const filename = `terminal-${timestamp}.png`;
-      const savePath = save_to === "cwd" ? join(process.cwd(), filename) : join(homedir(), "Downloads", filename);
+      const savePath = save_to === "cwd" ? join2(process.cwd(), filename) : join2(homedir2(), "Downloads", filename);
       let captured = false;
       try {
         const bounds = execSync(`osascript -e '
@@ -25025,7 +25171,7 @@ The saved file path can be passed directly to set_file_input(hint, file_path) to
           content: [{ type: "text", text: "Failed to capture terminal. Ensure Screen Recording permission is granted to your terminal app in System Settings > Privacy & Security > Screen Recording." }]
         };
       }
-      const imageBuffer = readFileSync(savePath);
+      const imageBuffer = readFileSync2(savePath);
       const base642 = imageBuffer.toString("base64");
       let clipboardNote = "";
       try {
@@ -25135,24 +25281,70 @@ ${lines.join("\n")}${r.warning ?? ""}${captchaLine}${oauthLine}` }] };
         timeoutMs
       );
       const r = response;
+      let capturable = "";
+      if (into_selector && r.success !== false) {
+        flowStore.observe({
+          tool: "type_text",
+          target: into_selector,
+          selector: into_selector,
+          signal: clear_first ? "type_text(clear_first)" : "type_text",
+          fragile: isFragileSelector(into_selector),
+          reason: "field needs real keystrokes (type_text, not fill_input)"
+        });
+        capturable = flowStore.capturableHint(void 0);
+      }
       return {
-        content: [{ type: "text", text: r.message ?? (r.success ? "Text typed successfully" : "Failed to type text") }]
+        content: [{ type: "text", text: (r.message ?? (r.success ? "Text typed successfully" : "Failed to type text")) + capturable }]
       };
     }
   );
   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.",
+    `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.
+
+Two ways to supply the file:
+- file_path (CDP mode): an absolute path on the machine running this server. Reaches both open AND closed shadow roots.
+- file_content + file_name (inline-content mode): base64 file bytes plus a filename, materialized into the input directly. Use this when the server has no local disk access (e.g. a remote endpoint that can't see your filesystem). Caveat: inline-content mode reaches OPEN shadow roots only \u2014 if the input lives in a closed shadow root, use file_path instead.
+
+Provide file_path OR file_content, not both.`,
     {
       hint: external_exports.string().describe("Label text, name, or surrounding text of the file input. Use empty string to target the first file input on the page."),
-      file_path: external_exports.string().describe("Absolute path to the file to upload (e.g. /Users/you/Downloads/task.zip)"),
+      file_path: external_exports.string().optional().describe("Absolute path to the file to upload (e.g. /Users/you/Downloads/task.zip). CDP mode \u2014 reaches closed shadow roots. Provide this OR file_content."),
+      file_content: external_exports.string().optional().describe("Base64-encoded file bytes (no data: prefix) for inline-content mode. Use when the server has no local disk access. Requires file_name. Reaches OPEN shadow roots only. Provide this OR file_path."),
+      file_name: external_exports.string().optional().describe('Filename to present to the page in inline-content mode (e.g. "report.pdf"). Required when file_content is set.'),
+      mime_type: external_exports.string().optional().describe('Optional MIME type for inline-content mode (e.g. "application/pdf"). Inferred from file_name when omitted.'),
       wait_ms: external_exports.number().int().min(0).optional().describe("How long to wait for an observable change after setting the file (default 3000). Increase for slow uploaders that take a moment to render thumbnails."),
       verify_selector: external_exports.string().optional().describe('Optional CSS selector that should appear after a successful upload (e.g. ".photo-thumbnail", "[data-uploaded=true]"). When matched, set_file_input returns success immediately.')
     },
-    async ({ hint, file_path, wait_ms, verify_selector }) => {
+    async ({ hint, file_path, file_content, file_name, mime_type, wait_ms, verify_selector }) => {
+      if (!file_path && !file_content) {
+        return {
+          content: [{ type: "text", text: "Failed to set file: provide either file_path or file_content." }]
+        };
+      }
+      if (file_path && file_content) {
+        return {
+          content: [{ type: "text", text: "Failed to set file: provide file_path OR file_content, not both." }]
+        };
+      }
+      if (file_content && !file_name) {
+        return {
+          content: [{ type: "text", text: "Failed to set file: file_content requires file_name." }]
+        };
+      }
       const wsTimeout = Math.max(3e4, (wait_ms ?? 3e3) + 1e4);
       const response = await bridge.request(
-        { type: "set_file_input", hint, filePath: file_path, waitMs: wait_ms, verifySelector: verify_selector },
+        {
+          type: "set_file_input",
+          hint,
+          // snake -> camel, mirroring the existing file_path -> filePath mapping.
+          filePath: file_path,
+          fileContent: file_content,
+          fileName: file_name,
+          mimeType: mime_type,
+          waitMs: wait_ms,
+          verifySelector: verify_selector
+        },
         wsTimeout
       );
       const r = response;
@@ -25170,7 +25362,7 @@ ${lines.join("\n")}${r.warning ?? ""}${captchaLine}${oauthLine}` }] };
 **Shadow-piercing helpers are pre-injected** into every script:
 - \`$deep(selector, root?)\` \u2014 querySelector that walks open shadow roots
 - \`$deepAll(selector, root?)\` \u2014 querySelectorAll equivalent, returns an array
-- \`shadowDocument\` \u2014 the open shadow root with the most interactive elements (buttons, inputs, links), or \`document\` if none. Useful when an SPA mounts ALL of its UI inside a single root shadow host (Outlier-style annotation dashboards): replace every \`document.querySelector*\` call with \`shadowDocument.querySelector*\` and the same code now reaches the SPA's content. On pages with multiple shadow roots (e.g. one for CSS theme vars, one for content), this picks the content root automatically.
+- \`shadowDocument\` \u2014 the open shadow root with the most interactive elements (buttons, inputs, links), or \`document\` if none. Useful when an SPA mounts ALL of its UI inside a single root shadow host (annotation-style dashboards that wrap the whole app in one web component): replace every \`document.querySelector*\` call with \`shadowDocument.querySelector*\` and the same code now reaches the SPA's content. On pages with multiple shadow roots (e.g. one for CSS theme vars, one for content), this picks the content root automatically.
 - \`shadowDocuments\` \u2014 array of ALL open shadow roots on the page (in DOM order). Use when you need to search across multiple shadow roots or when the automatic pick is wrong.
 
 The helpers pierce OPEN shadow roots only \u2014 MAIN world can't reach closed roots. For closed roots, use find_text / get_page_text / click_element / fill_input which pierce both kinds via chrome.dom.openOrClosedShadowRoot.
@@ -25282,8 +25474,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, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { resolve, relative, isAbsolute, dirname } from "path";
+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) {
   server.tool(
     "fill_input",
@@ -25471,7 +25663,7 @@ ${lines.join("\n")}` }] };
         envPath = resolved;
         let existing = "";
         try {
-          existing = readFileSync2(envPath, "utf-8");
+          existing = readFileSync3(envPath, "utf-8");
         } catch {
         }
         const lines = existing.split("\n");
@@ -25479,7 +25671,7 @@ ${lines.join("\n")}` }] };
         const existingIndex = lines.findIndex((l) => keyPattern.test(l));
         if (existingIndex !== -1) {
           lines[existingIndex] = `${key}=${value}`;
-          writeFileSync2(envPath, lines.join("\n"), "utf-8");
+          writeFileSync3(envPath, lines.join("\n"), "utf-8");
         } else {
           const toAppend = (existing && !existing.endsWith("\n") ? "\n" : "") + `${key}=${value}
 `;
@@ -25613,9 +25805,9 @@ Set binary=true for non-text responses (PDFs, images, zips) \u2014 the body is r
             `Refusing to write fetch_url body outside the project directory. Target "${resolved}" is not under "${cwd}".`
           );
         }
-        mkdirSync(dirname(resolved), { recursive: true });
+        mkdirSync2(dirname2(resolved), { recursive: true });
         const buf = r.body_base64 ? Buffer.from(r.body_base64, "base64") : Buffer.from(r.body_text ?? "", "utf-8");
-        writeFileSync2(resolved, buf);
+        writeFileSync3(resolved, buf);
         const hdrLines = Object.keys(r.headers).sort().map((k) => `  ${k}: ${r.headers[k]}`).join("\n");
         return {
           content: [{
@@ -25644,7 +25836,7 @@ ${r.body_text}` : "";
 }
 
 // packages/mcp-server/src/tools/flow.ts
-function registerFlowTools(server, bridge) {
+function registerFlowTools(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.
@@ -25686,7 +25878,7 @@ ANTI-BOT SUBMIT CEILING \u2014 synthetic clicks on social/auth platforms (Reddit
       try_fiber: external_exports.boolean().optional().describe(`Opt-in last-resort fallback when silently_rejected fires. After the activity probe reports zero activity, chromeflow walks the React fiber tree from the matched element (up to 12 levels), finds the nearest \`__reactProps$.onClick\` prop, and invokes it with a minimal synthetic event. Now shadow-DOM-aware: when the element is inside a shadow root, the fiber walk searches for React root containers inside that shadow root instead of walking the light DOM. Returns fiber_attempted=true in the response when the path was taken. Do NOT default to this; reserve for repeat silently_rejected on a known-safe React site.`),
       activity_timeout_ms: external_exports.number().int().min(500).optional().describe(`How long the activity probe watches for DOM mutations, focus changes, URL changes, or alert/toast/modal appearance after the click (default 1500ms). The probe returns early as soon as activity is detected, so the default adds only ~100ms on successful clicks. Increase to 2500-4000ms for buttons that trigger async API calls before producing visible DOM changes. The probe reports "silently_rejected" when zero activity is seen within this window; a higher value reduces false negatives but slows genuine rejection detection. For buttons where the click triggers a 3-5s API call with no immediate DOM change, use skip_activity_probe instead.`),
       skip_activity_probe: external_exports.boolean().optional().describe(`Skip the 1500ms activity probe AND all automatic fallbacks (tap gesture, pointer chain, DOM .click(), fiber walk) after the CDP click. The click is dispatched and success is returned immediately without verifying page activity. Use for buttons that trigger slow async API calls (3-5s+) before producing visible DOM changes, where the activity probe would falsely report "silently_rejected" and the fallback chain would double-fire. Verify state yourself via find_text or execute_script after an appropriate delay. NOTE: this is set IMPLICITLY when any until_* clause is passed, since the until-clause already provides verification. WARNING: no automatic silent-rejection detection when this is set without an until-clause.`),
-      via: external_exports.enum(["auto", "cdp", "fiber"]).optional().describe(`Click dispatch mode. "auto" (default): CDP click, then fiber fallback when try_fiber=true and the activity probe failed. "cdp": CDP click only, no fiber fallback ever. "fiber": skip the CDP bezier + activity probe entirely and invoke __reactProps$.onClick directly. Use "fiber" on React-heavy SPAs (Outlier-style dashboards) where you already know the site is fiber-only \u2014 cuts ~3 seconds of ceremony off the round trip. The fiber path is undocumented React internal access, prefer "auto" until you've confirmed the site needs it.`),
+      via: external_exports.enum(["auto", "cdp", "fiber"]).optional().describe(`Click dispatch mode. "auto" (default): CDP click, then fiber fallback when try_fiber=true and the activity probe failed. "cdp": CDP click only, no fiber fallback ever. "fiber": skip the CDP bezier + activity probe entirely and invoke __reactProps$.onClick directly. Use "fiber" on React-heavy SPAs (fiber-only annotation dashboards) where you already know the site is fiber-only \u2014 cuts ~3 seconds of ceremony off the round trip. The fiber path is undocumented React internal access, prefer "auto" until you've confirmed the site needs it.`),
       in_dialog: external_exports.boolean().optional().describe(`Scope candidate matches to the topmost open dialog (\`[role=dialog]\`, \`[role=alertdialog]\`, or \`<dialog open>\`), highest z-index wins. Use when Radix/Headless UI dialogs portal to document.body and a generic textHint like "Cancel" would otherwise match the wrong button. Returns scope_missed=true when no dialog is open.`),
       dialog_query: external_exports.string().optional().describe(`Scope candidate matches to a specific dialog by heading or aria-label substring. Use when multiple dialogs are open and in_dialog (topmost) would pick the wrong one \u2014 e.g. click_element("Confirm", dialog_query="Delete account"). Mutually exclusive with in_dialog; dialog_query wins when both are set.`),
       wait_until_enabled_ms: external_exports.number().int().min(0).optional().describe(`When the matched target is currently disabled (native disabled OR aria-disabled=true), poll for up to this many ms waiting for it to become enabled before clicking. Default 0 (do not wait \u2014 return target_disabled immediately). Use 2000-5000 for Submit-style buttons that briefly disable while an async copilot/validator/save is in flight. On timeout the response carries target_disabled=true plus a structured disabled_state snapshot (disabled, aria_disabled, pointer_events, opacity, visible) so the caller can decide between "wait more" or "field is genuinely missing \u2014 run get_form_fields(only_empty:true)".`)
@@ -25744,21 +25936,51 @@ Current URL: ${activeTab.url}`;
         focusLine = `
 \u2192 Focused: <${f.tag}${idBit}${nameBit}${aria}${valueBit}>`;
       }
+      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);
+      if (r.success && (r.recovered_via || r.navigated || usedUntil)) {
+        flowStore.observe({
+          tool: "click_element",
+          target: textHint ?? `selector=${selector}`,
+          selector,
+          recovered_via: r.recovered_via,
+          signal: r.navigated ? "navigated" : until_url_changes ? "until_url_change" : usedUntil ? "until_*" : r.recovered_via,
+          fragile: isFragileSelector(selector),
+          reason: r.recovered_via ? `click recovered via ${r.recovered_via}` : r.navigated ? "navigating submit/link" : "verified terminal click"
+        }, actionUrl);
+      }
+      flowStore.noteUrl(nowUrl);
+      const recall = flowStore.recallHint(nowUrl);
+      const capturable = flowStore.capturableHint(actionUrl);
       if (!r.success) {
         return {
           content: [
             {
               type: "text",
-              text: `Could not click "${targetLabel}": ${r.message}${navLine}${focusLine}`
+              text: `Could not click "${targetLabel}": ${r.message}${navLine}${focusLine}${recall}`
             }
           ]
         };
       }
       return {
-        content: [{ type: "text", text: `${r.message}${navLine}${focusLine}` }]
+        content: [{ type: "text", text: `${r.message}${navLine}${focusLine}${recall}${capturable}` }]
       };
     }
   );
+  server.tool(
+    "save_flow",
+    `Persist the hard-won interaction steps chromeflow buffered for the current site as a reusable, named flow. chromeflow auto-buffers only NOTABLE resolutions (a click that needed a fallback, a verified submit, a field that needed real keystrokes) \u2014 so you just give the task a label and it commits whatever is buffered for the current origin. Next session, those steps are surfaced back as a known_flow hint so you skip the trial-and-error.
+
+Call this when a response shows \`flow_capturable\`. Stored locally only (~/.chromeflow/flows.json), selectors/signals only \u2014 never typed text. Guidance, not autopilot: recalled steps are still verified on replay.`,
+    {
+      task_label: external_exports.string().describe('Short human label for what this flow accomplishes, e.g. "submit text post", "set flair and submit", "log report time".')
+    },
+    async ({ task_label }) => {
+      const res = flowStore.commit(task_label);
+      return { content: [{ type: "text", text: res.message }] };
+    }
+  );
   server.tool(
     "wait_for_click",
     `Wait for the user to click (or interact with) the currently highlighted element, then return.
@@ -26072,21 +26294,22 @@ ${lines.join("\n")}${shadowSection}` }] };
 }
 
 // packages/mcp-server/src/index.ts
-var PACKAGE_VERSION = true ? "0.10.24" : "dev";
+var PACKAGE_VERSION = true ? "0.11.1" : "dev";
 main().catch((err) => {
   console.error("[chromeflow] Fatal error:", err);
   process.exit(1);
 });
 async function main() {
   const bridge = new WsBridge();
+  const flowStore = new FlowStore(PACKAGE_VERSION);
   const server = new McpServer({
     name: "chromeflow",
     version: PACKAGE_VERSION
   });
-  registerBrowserTools(server, bridge);
+  registerBrowserTools(server, bridge, flowStore);
   registerHighlightTools(server, bridge);
   registerCaptureTools(server, bridge);
-  registerFlowTools(server, bridge);
+  registerFlowTools(server, bridge, flowStore);
   const registered = server._registeredTools ?? {};
   const toolNames = Object.keys(registered).sort();
   console.error(`[chromeflow] v${PACKAGE_VERSION} \u2014 registered ${toolNames.length} tools`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.10.24",
+  "version": "0.11.1",
   "description": "MCP server for chromeflow — 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",