@flowriki/agent 0.1.0-beta.64 → 0.1.0-beta.65

package/dist/cli.js

@@ -4,6 +4,7 @@ import {
   AGENT_VERSION,
   agentUpdateFor,
   authenticationResolver,
+  backupsFor,
   checkAssertion,
   closeRunSession,
   connect,
@@ -23,8 +24,9 @@ import {
   resolveService,
   runtimeValue,
   start,
-  status
-} from "./chunk-2MTLWAXK.js";
+  status,
+  withBackups
+} from "./chunk-FJVNOLHT.js";
 import {
   CLOUD_PROVIDERS,
   CLOUD_PROVIDER_NAME,
@@ -52,7 +54,7 @@ import {
   slugify,
   stepRefusedOn,
   targetFor
-} from "./chunk-RI63WNGU.js";
+} from "./chunk-PDUMGI6V.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -245,6 +247,13 @@ var ServiceClient = class {
       { method: "POST", body: JSON.stringify(input) }
     );
   }
+  /** A test case that cannot be automated, and why. */
+  reportBlocker(projectId, input) {
+    return this.call(
+      `/api/agent/cases/blocker?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
   /** A helper, its secrets sealed by the service. */
   createHelper(projectId, input) {
     return this.call(
@@ -253,6 +262,11 @@ var ServiceClient = class {
     );
   }
   /** What a new flow starts after: the flows, in run order, and their steps. */
+  /** A saved flow's steps, to fix it from rather than record it again. */
+  savedFlow(projectId, name, platform) {
+    const q = new URLSearchParams({ projectId, name, ...platform ? { platform } : {} });
+    return this.call(`/api/agent/flows/saved?${q}`);
+  }
   flowsAfter(projectId, after) {
     return this.call(
       `/api/agent/flows/after?projectId=${encodeURIComponent(projectId)}`,
@@ -417,6 +431,15 @@ import fs from "fs";
 import path from "path";
 var MAX_TREE = 14e3;
 var MAX_STEP_VIEW = 6e3;
+function quiet(tree) {
+  return tree.split("\n").filter((line) => {
+    const t = line.trim();
+    if (/^- \/url:/.test(t)) return false;
+    if (/^- img$/.test(t) || /^- img:$/.test(t)) return false;
+    if (/^- listitem$/.test(t)) return false;
+    return true;
+  }).join("\n");
+}
 function topLevelBlocks(tree) {
   const blocks = [];
   for (const line of tree.split("\n")) {
@@ -430,7 +453,7 @@ function topLevelBlocks(tree) {
   };
 }
 var STEP_TIMEOUT_MS = 1e4;
-var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b/i;
+var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b|token|api[-_\s]?key|access[-_\s]?key|card[-_\s]?number|credit[-_\s]?card/i;
 var TYPED = "typed_";
 var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
 var SIGN_UP = /\b(sign[\s-]?up|register|registration|create (an |your )?account|join)\b/i;
@@ -609,6 +632,8 @@ var AuthoringSession = class _AuthoringSession {
   values = /* @__PURE__ */ new Map();
   resolvers = null;
   lastTree = null;
+  /** The navigation as last shown, so a step repeats it only when it changed. */
+  lastNavigation = null;
   /** Values typed into secret fields, by their `typed:` reference. */
   typed = /* @__PURE__ */ new Map();
   draft = null;
@@ -670,6 +695,8 @@ var AuthoringSession = class _AuthoringSession {
    * it is kept, so a flow interrupted — the program stopped, the limit hit,
    * the agent restarted — is not lost: starting the same flow again replays
    * what was kept and carries on from there, unless `fresh` says start over. */
+  /** Steps of a saved flow still to put back, after one failed on the way. */
+  waiting = [];
   async start(input, catalog, opts = {}) {
     await this.close();
     this.catalog = catalog;
@@ -678,7 +705,8 @@ var AuthoringSession = class _AuthoringSession {
     this.typed = /* @__PURE__ */ new Map();
     this.lastTree = null;
     this.verified = null;
-    const left = opts.fresh ? null : this.readDraft(input.projectId, input.name);
+    this.waiting = [];
+    const left = opts.fresh ? null : this.readDraft(input.projectId, input.name) ?? (opts.saved?.length ? { steps: opts.saved } : null);
     if (opts.fresh) this.dropDraft(input.projectId, input.name);
     const opened = isMobile(input.platform) ? await this.startMobile(input.platform, catalog) : await this.startWeb(input, catalog);
     this.report();
@@ -691,7 +719,7 @@ var AuthoringSession = class _AuthoringSession {
   async resume(steps, opened) {
     const draft = this.draft;
     let failed = null;
-    for (const step of steps) {
+    for (const [at, step] of steps.entries()) {
       try {
         if (this.mobile) {
           const done = await runMobileSteps(this.mobile, [step], this.mobileResolvers());
@@ -713,17 +741,28 @@ var AuthoringSession = class _AuthoringSession {
         this.checkpoint();
       } catch (error) {
         failed = `${describe(step)} \u2014 ${error.message.split("\n")[0]}`;
+        this.waiting = steps.slice(at + 1);
         break;
       }
     }
     this.checkpoint();
     const kept = draft.steps.length;
-    const head = failed ? `Resumed "${draft.name}": ${kept} of ${steps.length} earlier steps are back; the next one did not work this time and was dropped (${failed}). Carry on from here.` : `Resumed "${draft.name}": its ${kept} earlier step${kept === 1 ? "" : "s"} ${kept === 1 ? "is" : "are"} back. Carry on from here.`;
+    const later = this.waiting.length ? ` ${this.waiting.length} later step${this.waiting.length === 1 ? " is" : "s are"} waiting: do the failed step again the way the page now needs, then continue_flow puts ${this.waiting.length === 1 ? "it" : "them"} back.` : "";
+    const head = failed ? `Resumed "${draft.name}": ${kept} of ${steps.length} earlier steps are back; the next one did not work this time and was dropped (${failed}).${later}` : `Resumed "${draft.name}": its ${kept} earlier step${kept === 1 ? "" : "s"} ${kept === 1 ? "is" : "are"} back. Carry on from here.`;
     const view = this.mobile ? await this.snapshot() : opened.includes("\n") ? await this.snapshot() : opened;
     return `${head}
 
 ${view}`;
   }
+  /** Put back the steps that were waiting after a failed one — replayed,
+   *  kept as they pass; the next that fails is where you take over again. */
+  async continueFlow() {
+    this.requireOpen();
+    const steps = this.waiting;
+    if (!steps.length) throw new Error("no steps are waiting \u2014 the flow is whole; add_check, replay_flow and save_flow");
+    this.waiting = [];
+    return this.resume(steps, "");
+  }
   // ── Drafts on disk ──────────────────────────────────────────────────────
   static draftFile(projectId, name) {
     return path.join(flowrikiHome(), "drafts", projectId.replace(/[^A-Za-z0-9_-]/g, "_"), `${slugify(name) || "flow"}.json`);
@@ -945,32 +984,36 @@ Record the flows it needs; on every act, add_check and use_helper pass line: the
     const before = this.lastTree;
     this.lastTree = tree;
     const cap = (t, max) => t.length > max ? `${t.slice(0, max)}
-\u2026 (cut \u2014 read_page shows the whole page)` : t;
-    if (full || before === null) return head + cap(tree, MAX_TREE);
-    const { dialogs, navigation } = topLevelBlocks(tree);
+\u2026 (cut)` : t;
+    if (full || before === null) {
+      this.lastNavigation = topLevelBlocks(tree).navigation ?? null;
+      return head + cap(tree, MAX_TREE);
+    }
+    const { dialogs, navigation: nav } = topLevelBlocks(tree);
+    const navigation = nav && nav !== this.lastNavigation ? nav : null;
+    this.lastNavigation = nav ?? null;
     if (dialogs.length) {
-      return head + cap([...navigation ? [navigation] : [], ...dialogs].join("\n"), MAX_STEP_VIEW) + "\n(only the open dialog and the navigation \u2014 read_page shows the whole page)";
+      return head + cap([...navigation ? [navigation] : [], ...dialogs].join("\n"), MAX_STEP_VIEW) + "\n(only the open dialog)";
     }
     const was = new Set(before.split("\n"));
     const now = new Set(tree.split("\n"));
     const added = tree.split("\n").filter((l) => !was.has(l));
     const removed = before.split("\n").filter((l) => !now.has(l));
-    if (added.length === 0 && removed.length === 0) return head + "(the page did not change \u2014 read_page shows it)";
+    if (added.length === 0 && removed.length === 0) return head + "(the page did not change)";
     if (added.length + removed.length > 120) return head + cap(tree, MAX_STEP_VIEW);
     return head + [
       ...navigation ? [navigation, ""] : [],
       added.length ? `Appeared:
 ${added.join("\n")}` : "",
       removed.length ? `Gone:
-${removed.join("\n")}` : "",
-      "(changes since the last step \u2014 read_page shows the whole page)"
+${removed.join("\n")}` : ""
     ].filter(Boolean).join("\n");
   }
   async webTree() {
     const { page, draft } = this.requireOpen();
     await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
     const tree = numberDuplicates(labelTree(
-      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
+      quiet(await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`)),
       await fieldNames(page)
     ));
     const title = await page.title().catch(() => "");
@@ -980,7 +1023,28 @@ Steps so far: ${draft.steps.length}
 ` };
   }
   /** Do one thing on the page, and keep it as a step if it worked. */
+  /** The step that failed last, and how many times in a row. */
+  failing = null;
+  /** DO ONE STEP — and notice when the same step keeps failing. Retrying it
+   *  turn after turn was where whole jobs went: each try re-reads the entire
+   *  conversation. On the third failure in a row, the answer says to stop. */
   async act(input) {
+    const key = [input.action, input.role ?? "", input.name ?? "", input.within ?? "", input.nth ?? ""].join("|");
+    try {
+      const done = await this.actOnce(input);
+      this.failing = null;
+      return done;
+    } catch (error) {
+      this.failing = this.failing?.key === key ? { key, times: this.failing.times + 1 } : { key, times: 1 };
+      if (this.failing.times >= 3) {
+        error.message = `${error.message}
+
+THIS STEP HAS FAILED ${this.failing.times} TIMES IN A ROW. Do not try it again: if another way to reach the same thing is not obvious from the page, call report_blocker for the test case (kind: stuck, with the line) and move on.`;
+      }
+      throw error;
+    }
+  }
+  async actOnce(input) {
     if (this.mobile) return this.mobileAct(input);
     const refused = stepRefusedOn(input.action === "tap" ? "click" : input.action, "web");
     if (refused) throw new Error(refused);
@@ -992,11 +1056,11 @@ Steps so far: ${draft.steps.length}
     if ((input.action === "fill" || input.action === "select" || input.action === "press" || input.action === "navigate") && input.value === void 0) {
       throw new Error(`${input.action} needs a value`);
     }
-    const target = navigating ? { role: "", name: "" } : asLabelled({ role: input.role ?? "", name: input.name ?? "" }, await fieldNames(page));
+    const target = navigating ? { role: "", name: "", scope: "" } : asLabelled({ role: input.role ?? "", name: input.name ?? "" }, await fieldNames(page));
     const secret = input.action === "fill" && (input.secret ?? (SECRET_WORDS.test(input.name ?? "") || SECRET_WORDS.test(target.name)));
     const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
     if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
-    const step = RecordedStepSchema.parse({
+    let step = RecordedStepSchema.parse({
       id,
       type: input.action,
       ...target,
@@ -1011,6 +1075,7 @@ Steps so far: ${draft.steps.length}
       // environment the run is pointed at rather than the one written on.
       ...input.action === "navigate" && input.value?.startsWith("/") ? { navigationBase: "application" } : {}
     });
+    if (!navigating && input.action !== "press") step = RecordedStepSchema.parse(withBackups(step, await backupsFor(page, step)));
     try {
       this.page = await executeStep(page, step, {
         pages: run.pages,
@@ -1133,9 +1198,7 @@ ${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
     if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
     const [gone] = draft.steps.splice(number - 1, 1);
     this.checkpoint();
-    return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
-
-${this.list()}`;
+    return `Removed step ${number} (${describe(gone)}); ${draft.steps.length} steps now. The browser was not undone.`;
   }
   /** Run the whole draft from the start, in a browser of its own, the way a
    *  run will — the proof the steps work together, not just one at a time. */
@@ -1347,7 +1410,7 @@ Steps so far: ${draft.steps.length}
       throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
     }
     if ((type === "fill" || type === "select" || type === "navigate") && input.value === void 0) throw new Error(`${input.action} needs a value`);
-    let target = { role: "", name: "" };
+    let target = { role: "", name: "", scope: "" };
     let password = false;
     if (input.role) {
       const asked = { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} };
@@ -1552,6 +1615,20 @@ THE MODEL \u2014 get this right before recording anything:
   account.
 - HELPERS (an inbox for email codes, an authenticator, SMS, an API call) are made
   with create_helper when the catalog has none that fits.
+- HEALING fixes a test's automation, never its business: change only how steps
+  find and reach things (an element renamed or moved, a new screen in the way,
+  a wait). Never change a case's Given / When / Then, what a check expects or
+  which checks are on, and never drop a row \u2014 in a heal the service refuses
+  such a save. If the app itself behaves differently now, report_blocker
+  (app-bug) and leave that case.
+- WHEN A CASE CANNOT BE AUTOMATED, say so with report_blocker and move on to
+  the next case \u2014 never loop. Report it when the app itself is broken at that
+  step (app-bug), when it needs something only a person has \u2014 a captcha, a
+  real card, a code sent to somebody's own phone (needs-person), when a
+  business step is unclear or does not match the app (unclear-step), when the
+  screen or feature cannot be reached (not-found), or after 3 failed tries at
+  the same step (stuck). Name the line it stopped at and what would unblock it.
+  A case marked manual by a person is not to be automated at all.
 - SEVERAL ELEMENTS WITH THE SAME NAME (two "Proceed to Checkout" buttons, twelve
   "Select & Customize") are told apart by POSITION, like an XPath index: read_page
   marks each one [nth N of M], and act / add_check take nth (0 = the first). Use it
@@ -1571,7 +1648,7 @@ THE MODEL \u2014 get this right before recording anything:
   "Ordering \u2013 Pizza builder", "Checkout \u2013 Payment". Flows (features) and the
   cases built from them use the same names. Keep one area per folder.
 
-KNOWLEDGE: project_brief is the project's memory \u2014 read it first. Search the
+KNOWLEDGE: project_brief is the project's memory \u2014 given with the request when there is one (then do not call it again). Search the
 knowledge pages with knowledge_search; read one with knowledge_read.
 product.md is "About the product": the person's own description of
 the product, in their words, as long as they like \u2014 read it first. Beside it,
@@ -1631,14 +1708,17 @@ mix rows on a phone with rows in a browser (a customer orders in the app, an
 admin approves on the website).
 
 HOW TO WORK:
-1. Call project_catalog. Reuse what exists \u2014 published, and on Claude's working
-   branch \u2014 rather than writing it again.
-2. Before recording, say the plan to the person: the folders, the building-block
-   flows (and what each starts after), and the test cases (rows + what each
-   checks). Then record the blocks, earliest first.
-3. Record with start_flow (pass "after" for the flows it continues from), read
-   the page with read_page, and act using the role and name EXACTLY as the page
-   shows them. If a name appears more than once, pass "within" with the name of
+1. Reuse what exists \u2014 published, and on Claude's working branch \u2014 rather than
+   writing it again: project_catalog lists it (once is enough; a repeat says
+   whether anything changed).
+2. Plan the folders, the building-block flows (and what each starts after) and
+   the test cases (rows + what each checks), then record the blocks, earliest
+   first. No need to wait for an answer: nobody is at the keyboard.
+3. Record with start_flow (pass "after" for the flows it continues from) \u2014 it
+   answers with the page \u2014 and act using the role and name EXACTLY as the page
+   shows them, several steps per act when they are all on the page already.
+   Each step answers with what changed; read_page only when you need the whole
+   page again. If a name appears more than once, pass "within" with the name of
    the region, dialog or form \u2014 or "dialog" / "navigation".
 4. For things outside the page \u2014 an emailed code or link, an authenticator
    code, a text message, an API call \u2014 use use_helper with a helper from the
@@ -1724,8 +1804,19 @@ var caseSpec = (args) => ({
 });
 var text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...isError ? { isError } : {} });
 var str = (value) => typeof value === "string" ? value : value === void 0 || value === null ? void 0 : String(value);
+var STEP_PROPERTIES = {
+  action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward", "tap", "longPress", "swipe", "scroll", "hideKeyboard", "permission", "launchApp", "terminateApp", "resetApp", "background", "rotate"] },
+  role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox." },
+  name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
+  within: { type: "string", description: "When the name is not unique: the region, dialog or form that holds it." },
+  nth: { type: "integer", minimum: 0, description: "Which one when several share role and name: 0 is the first ([nth N of M] in read_page)." },
+  value: { type: "string" },
+  secret: { type: "boolean", description: "fill only: a password, PIN or key \u2014 kept out of the flow, saved to the vault." },
+  line: { type: "integer", minimum: 1, description: "The test case line (from start_case) this step carries out." }
+};
 function authoringTools(service, session) {
-  let defaultProject = null;
+  let defaultProject = process.env["FLOWRIKI_PROJECT_ID"]?.trim() || null;
+  const catalogSaid = /* @__PURE__ */ new Map();
   const catalogs = /* @__PURE__ */ new Map();
   const projectFor = async (asked) => {
     const named = str(asked);
@@ -1819,13 +1910,20 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
     {
       name: "project_catalog",
       title: "What a test can be built from",
-      description: "The project's base URL, features (folders for flows), existing flows, sign-in profiles with their accounts, and helpers (email codes, 2FA, SMS, API calls). Read this before starting a flow.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      description: "What exists to build from: base URL, features with their flows, test-case folders (counts \u2014 name a folder to list its cases), sign-in profiles with accounts, and helpers. start_flow reads it by itself; call this to see what to reuse. platform: only that platform's flows. A second call in the same job says whether anything changed.",
+      inputSchema: { type: "object", properties: {
+        projectId: { type: "string", description: "Optional when you are on one project." },
+        platform: { type: "string", enum: ["web", "android", "ios"], description: "Only this platform's flows." },
+        folder: { type: "string", description: "List the test cases of this folder (by name)." }
+      }, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
         const c = await catalogOf(projectId, true);
-        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps${isMobile(f.platform) ? `, ${f.platform}` : ""})`).join("\n");
+        const onlyPlatform = str(args["platform"]);
+        const onPlatform = (f) => !onlyPlatform || (onlyPlatform === "web" ? !isMobile(f.platform) : f.platform === onlyPlatform);
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId && onPlatform(f)).map((f) => `    - ${f.name} (${f.steps} steps${isMobile(f.platform) ? `, ${f.platform}` : ""})`).join("\n");
+        const askedFolder = str(args["folder"])?.toLowerCase();
         const platforms = platformsOf(c);
         const phones = platforms.android || platforms.ios ? await devicesSummary() : [];
         const phoneLines = ["android", "ios"].filter((p) => platforms[p]).map((p) => {
@@ -1834,11 +1932,11 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
           const farms = (c.mobile?.cloud ?? []).map((f) => CLOUD_PROVIDER_NAME[f.provider]);
           const chosen = c.mobile?.devices[p];
           return `${p === "android" ? "Android" : "iOS"} app: ${app ?? "(not named \u2014 Settings \u2192 Environments)"}
-  Phones on this computer: ${here.length ? here.map((d) => `${d.name}${d.state === "ready" ? "" : ` (${d.state})`}`).join(", ") : "none"}` + (farms.length ? `
+  Phones on this computer: ${here.filter((d) => d.state === "ready").map((d) => d.name).join(", ") || "none running"}${here.some((d) => d.state !== "ready") ? ` (+${here.filter((d) => d.state !== "ready").length} switched off)` : ""}` + (farms.length ? `
   Cloud device farms: ${farms.join(", ")}` : "") + `
   Runs: ${c.runWhere?.[p] === "cloud" ? "in the cloud" : "on this computer"}` + (chosen ? ` \u2014 ${chosen.kind === "local" ? chosen.name || chosen.id : `${CLOUD_PROVIDER_NAME[chosen.provider]}: ${chosen.device}`}` : "");
         });
-        return text([
+        const out = [
           `Project ${projectId}. Tests: ${[platforms.web && "web", platforms.android && "Android app", platforms.ios && "iOS app"].filter(Boolean).join(", ")}.`,
           platforms.web ? `Base URL: ${c.baseUrl || "(not set)"}${c.runWhere?.web === "cloud" ? " \u2014 test runs use a cloud browser; recording is on this computer" : ""}` : "",
           ...phoneLines,
@@ -1857,15 +1955,27 @@ On Claude's working branch "${c.draft.title}" (${c.draft.changeId}), not yet pub
           ] : [],
           `
 Test cases:${(c.cases ?? []).length ? "" : " none published"}`,
-          ...(c.caseFolders ?? []).map((f) => `  - ${f.key ? `${f.key} ` : ""}${f.name} (id ${f.id})
-${(c.cases ?? []).filter((t) => t.folderId === f.id).map((t) => `    - ${t.key ? `${t.key} ` : ""}${t.name} \u2014 ${t.rows.length ? `rows: ${t.rows.join(" \u2192 ")}` : "not automated yet"}`).join("\n")}`),
+          // COUNTS, unless a folder is asked for: hundreds of cases written
+          // and not automated yet were most of this answer, re-read on every
+          // turn after. read_test_cases has any case's steps.
+          ...(c.caseFolders ?? []).map((f) => {
+            const inside = (c.cases ?? []).filter((t) => t.folderId === f.id);
+            const head = `  - ${f.key ? `${f.key} ` : ""}${f.name} (id ${f.id}) \u2014 ${inside.length} case${inside.length === 1 ? "" : "s"}, ${inside.filter((t) => t.rows.length).length} automated`;
+            if (askedFolder !== f.name.toLowerCase()) return head;
+            return `${head}
+${inside.map((t) => `    - ${t.key ? `${t.key} ` : ""}${t.name} \u2014 ${t.rows.length ? `rows: ${t.rows.join(" \u2192 ")}` : "not automated yet"}`).join("\n")}`;
+          }),
           `
 Sign-in profiles:${c.signIns.length ? "" : " none"}`,
           ...c.signIns.map((s) => `  - ${s.name} (profileId ${s.profileId})${s.fields?.length ? ` \u2014 fields ${s.fields.map((f) => `"${f}"`).join(", ")}` : ""}: ${s.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
           `
 Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
           ...c.helpers.map((h) => `  - ${h.name} (id ${h.id}) \u2014 ${h.what}${h.inputs.length ? `; needs ${h.inputs.map((n) => `{{${n}}}`).join(", ")}` : ""}${h.description ? ` \u2014 ${h.description}` : ""}`)
-        ].filter(Boolean).join("\n"));
+        ].filter(Boolean).join("\n");
+        const key = `${projectId}|${onlyPlatform ?? ""}|${askedFolder ?? ""}`;
+        if (catalogSaid.get(key) === out) return text("Nothing has changed since you last read the catalog in this job.");
+        catalogSaid.set(key, out);
+        return text(out);
       }
     },
     {
@@ -1957,9 +2067,13 @@ ${m.platform === "web" ? "Web pages" : "Android screens"} runs reached:`);
         if (signIn && !catalog.signIns.some((s) => s.profileId === signIn.profileId)) {
           throw new Error(`no sign-in profile ${signIn.profileId} \u2014 project_catalog lists them`);
         }
-        const asked = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
-        const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
         const platforms = platformsOf(catalog);
+        const named = str(args["name"]) ?? "";
+        const wantedPlatform = str(args["platform"]);
+        const saved = args["fresh"] === true ? null : await Promise.resolve().then(() => service.savedFlow(projectId, named, wantedPlatform)).then((r) => r.flow).catch(() => null);
+        const askedAfter = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
+        const asked = askedAfter.length ? askedAfter : saved?.after ?? [];
+        const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
         const enabled = ["web", "android", "ios"].filter((p) => platforms[p]);
         const platform = str(args["platform"]) ?? (enabled.length === 1 ? enabled[0] : enabled.includes("web") ? "web" : void 0);
         if (!platform) throw new Error(`this project tests ${enabled.join(" and ")} \u2014 say which with platform`);
@@ -1970,10 +2084,10 @@ ${m.platform === "web" ? "Web pages" : "Android screens"} runs reached:`);
           ...isMobile(platform) ? { platform, ...device ? { device } : {} } : {},
           ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
           name: str(args["name"]) ?? "Untitled flow",
-          ...feature ? { featureId: feature.id } : { featureName: featureAsked },
-          startPath: str(args["startPath"]) || (isMobile(platform) ? "" : "/"),
-          ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
-        }, catalog, { ...args["fresh"] === true ? { fresh: true } : {} });
+          ...feature ? { featureId: feature.id } : saved ? { featureId: saved.featureId } : { featureName: featureAsked },
+          startPath: str(args["startPath"]) || saved?.startPath || (isMobile(platform) ? "" : "/"),
+          ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : saved?.signIn ? { signIn: saved.signIn } : {}
+        }, catalog, { ...args["fresh"] === true ? { fresh: true } : {}, ...saved ? { saved: saved.steps } : {} });
         const after = plan?.prerequisites.length ? ` It starts after ${plan.prerequisites.map((p) => `"${p.name}"`).join(" \u2192 ")}, which ran first.` : "";
         return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} ${isMobile(platform) ? "The app is open on the phone." : "The browser is open."}
 
@@ -1990,37 +2104,60 @@ ${page}`);
     },
     {
       name: "act",
-      title: "Do one thing on the page",
-      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value (on a phone, a deep link). back/forward: nothing. PHONE ONLY: tap (role + name), longPress (role + name), swipe (value up/down/left/right, optionally on role + name), scroll (to role + name, or value up/down), hideKeyboard, permission (value allow/deny), launchApp, terminateApp, resetApp, background (value: seconds), rotate (value portrait/landscape).`,
+      title: "Do things on the page",
+      description: `Perform a step \u2014 or several, in order, as steps: [...] \u2014 and keep each one that works. Stops at the first that fails; returns one line per step and the page afterwards. Batch steps whose elements are already on the page (filling a form, then submitting). click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value (on a phone, a deep link). back/forward: nothing. PHONE ONLY: tap (role + name), longPress (role + name), swipe (value up/down/left/right, optionally on role + name), scroll (to role + name, or value up/down), hideKeyboard, permission (value allow/deny), launchApp, terminateApp, resetApp, background (value: seconds), rotate (value portrait/landscape).`,
       inputSchema: {
         type: "object",
         properties: {
-          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward", "tap", "longPress", "swipe", "scroll", "hideKeyboard", "permission", "launchApp", "terminateApp", "resetApp", "background", "rotate"] },
-          role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox, checkbox, combobox." },
-          name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
-          within: { type: "string", description: "When the name is not unique: the name of the region, dialog, form or navigation that holds it." },
-          nth: { type: "integer", minimum: 0, description: "Which one, when several elements share this role and name: 0 is the first in the order read_page lists them (each shared name is marked [nth N of M]). Leave it out when the name is unique." },
-          value: { type: "string" },
-          secret: { type: "boolean", description: "fill only: the value is a secret (a password, PIN, key) \u2014 kept out of the flow and saved to the vault. Fields named like a password are secret without this." },
-          line: { type: "integer", minimum: 1, description: "The number of the test case's line (from start_case) this step carries out." }
+          ...STEP_PROPERTIES,
+          steps: { type: "array", maxItems: 25, items: { type: "object", properties: STEP_PROPERTIES, required: ["action"], additionalProperties: false }, description: "Several steps in order, instead of one." }
         },
-        required: ["action"],
         additionalProperties: false
       },
       run: async (args) => {
-        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward \u2014 or on a phone tap, longPress, swipe, scroll, hideKeyboard, permission, launchApp, terminateApp, resetApp, background, rotate");
-        const action = args["action"];
-        return tagged(args, async () => session.act({
-          action,
-          ...str(args["role"]) ? { role: str(args["role"]) } : {},
-          ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
-          ...str(args["within"]) ? { within: str(args["within"]) } : {},
-          ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {},
-          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {},
-          ...typeof args["secret"] === "boolean" ? { secret: args["secret"] } : {}
-        }));
+        const stepOf = (raw) => {
+          if (!isAction(raw["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward \u2014 or on a phone tap, longPress, swipe, scroll, hideKeyboard, permission, launchApp, terminateApp, resetApp, background, rotate");
+          return {
+            action: raw["action"],
+            ...str(raw["role"]) ? { role: str(raw["role"]) } : {},
+            ...str(raw["name"]) !== void 0 ? { name: str(raw["name"]) } : {},
+            ...str(raw["within"]) ? { within: str(raw["within"]) } : {},
+            ...Number.isInteger(raw["nth"]) && raw["nth"] >= 0 ? { nth: raw["nth"] } : {},
+            ...str(raw["value"]) !== void 0 ? { value: str(raw["value"]) } : {},
+            ...typeof raw["secret"] === "boolean" ? { secret: raw["secret"] } : {}
+          };
+        };
+        const batch = Array.isArray(args["steps"]) ? args["steps"].slice(0, 25) : null;
+        if (!batch?.length) return tagged(args, async () => session.act(stepOf(args)));
+        const said = [];
+        let page = "";
+        for (let i = 0; i < batch.length; i++) {
+          const raw = batch[i];
+          const what = `${String(raw["action"])}${str(raw["name"]) ? ` "${str(raw["name"])}"` : str(raw["value"]) && raw["action"] !== "fill" ? ` ${str(raw["value"])}` : ""}`;
+          const before = session.keptCount();
+          try {
+            page = await session.act(stepOf(raw));
+            const line = Number(raw["line"]);
+            said.push(`${i + 1}. ${what} \u2014 kept${Number.isInteger(line) && line > 0 ? session.tagSince(before, line) : ""}`);
+          } catch (error) {
+            said.push(`${i + 1}. ${what} \u2014 FAILED: ${error.message}`);
+            if (i < batch.length - 1) said.push(`Steps ${i + 2}\u2013${batch.length} were not done.`);
+            break;
+          }
+        }
+        return text(`${said.join("\n")}${page ? `
+
+The page after the last kept step:
+${page}` : ""}`);
       }
     },
+    {
+      name: "continue_flow",
+      title: "Put back the waiting steps",
+      description: "After start_flow reopened a saved flow and one step no longer worked: once you have done that step again the way the page now needs, put back the saved steps that came after it \u2014 replayed and kept as they pass, up to the next that fails.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      run: async () => text(await session.continueFlow())
+    },
     {
       name: "add_check",
       title: "Add a check",
@@ -2336,8 +2473,10 @@ ${c.key ? `${c.key} ` : ""}${c.feature} \u203A ${c.name} (${c.id})`, ...c.busine
         const { cases, missing } = await service.readCases(projectId, refs);
         const parts = cases.map((c) => [
           `${c.key ? `${c.key} ` : ""}${c.folder} \u203A ${c.name} (${c.id}) \u2014 ${c.automated ? `automated, rows: ${c.rows.join(" \u2192 ")}` : "not automated yet"}`,
+          ...c.manual ? ["  MANUAL \u2014 a person runs this one by hand. Do not automate it."] : [],
+          ...c.blocked ? [`  BLOCKED last time (${c.blocked.kind}${c.blocked.line ? `, at line ${c.blocked.line}` : ""}): ${c.blocked.detail}${c.blocked.needs ? ` \u2014 needs: ${c.blocked.needs}` : ""}. Try again only if that has changed; otherwise report_blocker again.`] : [],
           ...c.description ? [`  ${c.description}`] : [],
-          ...c.businessSteps.length ? c.businessSteps.map((s) => `  ${s.keyword} ${s.text}`) : ["  (no business steps written)"]
+          ...c.businessSteps.length ? c.businessSteps.map((s, i) => `  ${i + 1}. ${s.keyword} ${s.text}`) : ["  (no business steps written)"]
         ].join("\n"));
         if (missing.length) parts.push(`Not found: ${missing.join(", ")} \u2014 project_catalog lists the test cases.`);
         return text(parts.join("\n\n") || "No test cases found.");
@@ -2463,6 +2602,39 @@ Next: create_account for each person who signs in this way.`);
 Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accountId}"}.`);
       }
     },
+    {
+      name: "report_blocker",
+      title: "Say a test case cannot be automated",
+      description: "Record that a test case could not be automated, and why \u2014 so it is marked Blocked on its page with the line it stopped at and what would unblock it, instead of looking untouched. kind: app-bug (the app itself is broken at that step), needs-person (a captcha, a real card, a code on somebody's own phone \u2014 something only a person has), unclear-step (a business step is unclear or does not match the app), not-found (the screen or feature cannot be reached), stuck (3 failed tries at the same step). Then move on to the next case. Saving the case automated later takes the mark off by itself.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          case: { type: "string", description: "The case's id, TC-\u2026 (read_test_cases gives it)." },
+          kind: { type: "string", enum: ["app-bug", "needs-person", "unclear-step", "not-found", "stuck"] },
+          line: { type: "number", description: "The business step it stopped at, counted from 1." },
+          detail: { type: "string", description: "What happened, in a sentence or two: what you did and what the app did." },
+          needs: { type: "string", description: 'What would unblock it, said for a person \u2014 e.g. "a helper for the SMS code", "the step should say which plan to pick".' },
+          platform: { type: "string", enum: ["web", "android", "ios"] },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches the case is on." }
+        },
+        required: ["case", "kind", "detail"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.reportBlocker(projectId, {
+          case: str(args["case"]) ?? "",
+          kind: str(args["kind"]) ?? "",
+          detail: str(args["detail"]) ?? "",
+          ...typeof args["line"] === "number" ? { line: args["line"] } : {},
+          ...str(args["needs"]) ? { needs: str(args["needs"]) } : {},
+          ...str(args["platform"]) ? { platform: str(args["platform"]) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        return text(`Marked ${made.key ?? made.caseId} Blocked \u2014 ${made.label}. A person sees it on the case with what it needs. Move on to the next case.`);
+      }
+    },
     {
       name: "create_helper",
       title: "Make a helper",
@@ -2496,7 +2668,7 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
     {
       name: "project_brief",
       title: "Read the project's memory",
-      description: "The project's own knowledge, in one call: About the product (product.md, and product/<web|android|ios>.md where a platform differs), memory/decisions.md, what each linked codebase folder was learned as and which platform's code it holds, what each platform looked like when explored (explore/<platform>.md), and the list of feature pages and session summaries. Call it first in every conversation. With platform and/or features, the brief is the slice for that job: that platform's part and exploration, those features' notes, the code tagged for the platform, and who can sign in.",
+      description: "The project's own knowledge, in one call: About the product (product.md, and product/<web|android|ios>.md where a platform differs), memory/decisions.md, what each linked codebase folder was learned as and which platform's code it holds, what each platform looked like when explored (explore/<platform>.md), and the list of feature pages and session summaries. Call it at the start when no brief was given with the request (a given brief IS this). With platform and/or features, the brief is the slice for that job: that platform's part and exploration, those features' notes, the code tagged for the platform, and who can sign in.",
       inputSchema: { type: "object", properties: { projectId: { type: "string" }, platform: { type: "string", enum: ["web", "android", "ios"], description: "The platform the job is about." }, features: { type: "array", items: { type: "string" }, description: "The features (or case folders) the job is about, by name." } }, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async (args) => {
@@ -2839,6 +3011,10 @@ async function runMcp(opts) {
   const connection = connectionFor(service);
   const session = connection ? new AuthoringSession(new ServiceClient(connection), opts.headless ? { headless: true } : {}) : null;
   let tools = connection && session ? authoringTools(new ServiceClient(connection), session) : authoringTools(null, null);
+  const only = (process.env["FLOWRIKI_TOOLS"] ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+  if (only.length) tools = tools.filter((tool) => only.includes(tool.name));
+  const except = (process.env["FLOWRIKI_TOOLS_EXCEPT"] ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+  if (except.length) tools = tools.filter((tool) => !except.includes(tool.name));
   if (!connection) {
     const why = `This computer is not connected to Flowriki at ${service}. Run \`flowriki-agent connect\` in a terminal, approve it in your browser, then restart Claude.`;
     tools = tools.map((tool) => ({ ...tool, run: async () => ({ content: [{ type: "text", text: why }], isError: true }) }));
@@ -2959,6 +3135,8 @@ Run \`flowriki-agent --help\`.`);
           console.log(`
   ${bold("Approve this computer in your browser")}`);
           console.log(`  ${url}
+`);
+          if (note.detail?.["code"]) console.log(`  ${bold("Your code:")} ${bold(String(note.detail["code"]))}  ${dim("\u2014 the page asks for it")}
 `);
           if (note.detail?.["canOpen"] === false) {
             console.log(dim("  Open the approval link in your browser.\n"));
@@ -3025,11 +3203,16 @@ Run \`flowriki-agent --help\`.`);
       setInterval(() => void tellIfBehind(), 6 * 60 * 6e4).unref();
       let stopping = false;
       const shutdown = async (signal) => {
-        if (stopping) return;
+        if (stopping) {
+          console.log(dim("  stopping now"));
+          process.exit(130);
+        }
         stopping = true;
         console.log(dim(`
-  ${signal} \u2014 stopping`));
-        await started.stop();
+  ${signal} \u2014 stopping (press Ctrl-C again to stop at once)`));
+        const force = setTimeout(() => process.exit(1), 1e4);
+        force.unref();
+        await started.stop().catch(() => void 0);
         process.exit(0);
       };
       process.on("SIGINT", () => void shutdown("SIGINT"));