@flowriki/agent 0.1.0-beta.33 → 0.1.0-beta.36

package/dist/{chunk-3UUCI66O.js → chunk-N3P4O3OH.js}

@@ -6,7 +6,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.33";
+var AGENT_VERSION = "0.1.0-beta.36";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -11278,6 +11278,7 @@ export {
   closeRunSession,
   replayFlow,
   executeStep,
+  replayCase,
   fieldNames,
   helperRunner,
   resolveCheckouts,

package/dist/cli.js

@@ -15,13 +15,14 @@ import {
   mirrorCheckTargets,
   openRunSession,
   prepareBrowsers,
+  replayCase,
   replayFlow,
   resolveCheckouts,
   resolveService,
   runtimeValue,
   start,
   status
-} from "./chunk-3UUCI66O.js";
+} from "./chunk-N3P4O3OH.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -39,7 +40,7 @@ async function handle(message, tools, info) {
       const version = PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0];
       return reply({
         protocolVersion: version,
-        capabilities: { tools: { listChanged: false } },
+        capabilities: { tools: { listChanged: true } },
         serverInfo: { name: info.name, version: info.version },
         instructions: info.instructions
       });
@@ -95,6 +96,10 @@ function serve(tools, info, io = {}) {
     const task = handle(message, tools, info).then((answer) => {
       if (answer) output.write(`${JSON.stringify(answer)}
 `);
+      if (message.method === "notifications/initialized") {
+        output.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}
+`);
+      }
     });
     pending.add(task);
     void task.finally(() => pending.delete(task));
@@ -168,17 +173,73 @@ var ServiceClient = class {
       { method: "DELETE" }
     );
   }
-  saveFlow(projectId, title, flow) {
+  saveFlow(projectId, title, flow, where = {}, secretValues = {}) {
     return this.call(
       `/api/agent/flows?projectId=${encodeURIComponent(projectId)}`,
-      { method: "POST", body: JSON.stringify({ title, flow }) }
+      { method: "POST", body: JSON.stringify({ title, flow, ...where, secretValues }) }
+    );
+  }
+  /** A sign-in made from a recorded login flow. */
+  createSignIn(projectId, input) {
+    return this.call(
+      `/api/agent/sign-ins?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** An account for a sign-in; secret values are sealed by the service and
+   *  never come back. */
+  createAccount(projectId, input) {
+    return this.call(
+      `/api/agent/accounts?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** A helper, its secrets sealed by the service. */
+  createHelper(projectId, input) {
+    return this.call(
+      `/api/agent/helpers?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** What a new flow starts after: the flows, in run order, and their steps. */
+  flowsAfter(projectId, after) {
+    return this.call(
+      `/api/agent/flows/after?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ after }) }
+    );
+  }
+  /** Build a test case from flows — as a dry run, or saved. */
+  buildCase(projectId, spec, dryRun) {
+    return this.call(`/api/agent/cases?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify({ ...spec, dryRun }) });
+  }
+  /** Gather Claude's open branches here into one. */
+  gatherChanges(projectId, opts = {}) {
+    return this.call(
+      `/api/agent/changes/gather?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(opts) }
     );
   }
 };
 
 // src/mcp/session.ts
 var MAX_TREE = 14e3;
+var MAX_STEP_VIEW = 6e3;
+function topLevelBlocks(tree) {
+  const blocks = [];
+  for (const line of tree.split("\n")) {
+    if (line.startsWith("- ") || blocks.length === 0) blocks.push([line]);
+    else blocks[blocks.length - 1].push(line);
+  }
+  const named = (b, kinds) => kinds.some((k) => b[0].startsWith(`- ${k}`));
+  return {
+    dialogs: blocks.filter((b) => named(b, ["dialog", "alertdialog"])).map((b) => b.join("\n")),
+    navigation: blocks.find((b) => named(b, ["navigation", "banner"]))?.join("\n") ?? null
+  };
+}
 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 TYPED = "typed_";
+var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
 var ACTIONS = ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"];
 var isAction = (value) => ACTIONS.includes(String(value));
 var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
@@ -202,12 +263,18 @@ function labelTree(tree, fields) {
   for (const f of fields) out = out.split(`- ${f.role} ${JSON.stringify(f.hint)}`).join(`- ${f.role} ${JSON.stringify(f.label)}`);
   return out;
 }
+function describeRows(rows) {
+  return rows.map((r) => [
+    `Row ${r.row}: "${r.flow}" (${r.browser})`,
+    ...r.checks.length ? r.checks.map((c) => `  ${c.on ? "[on] " : "[off]"} ${c.n}. ${c.check}`) : ["  (no checks in this flow)"]
+  ].join("\n")).join("\n");
+}
 function describe(step) {
   const target = step.name ? `${step.role || "element"} "${step.name}"` : step.role || "";
   const where = step.scope ? ` in "${step.scope}"` : step.scopeRole ? ` in the ${step.scopeRole}` : "";
   switch (step.type) {
     case "fill":
-      return `type "${step.value}" into ${target}${where}`;
+      return step.secret ? `type a secret (\u2022\u2022\u2022\u2022\u2022\u2022) into ${target}${where}` : `type "${step.value}" into ${target}${where}`;
     case "select":
       return `choose "${step.value}" in ${target}${where}`;
     case "check":
@@ -238,8 +305,24 @@ var AuthoringSession = class {
   page = null;
   values = /* @__PURE__ */ new Map();
   resolvers = null;
+  lastTree = null;
+  /** Values typed into secret fields, by their `typed:` reference. */
+  typed = /* @__PURE__ */ new Map();
   draft = null;
   catalog = null;
+  /** Text going back to Claude, with every secret typed here masked — a
+   *  password box's value is in the page's tree, and a careless form puts it
+   *  in the address. */
+  redact(text2) {
+    let out = text2;
+    for (const value of this.typed.values()) {
+      if (value.length < 3) continue;
+      out = out.split(value).join("\u2022\u2022\u2022\u2022\u2022\u2022");
+      const encoded = encodeURIComponent(value);
+      if (encoded !== value) out = out.split(encoded).join("\u2022\u2022\u2022\u2022\u2022\u2022");
+    }
+    return out;
+  }
   get open() {
     return this.run !== null;
   }
@@ -252,11 +335,11 @@ var AuthoringSession = class {
    *  helper or sign-in appears, never kept beyond this process. */
   async prepare(extra = []) {
     const draft = this.draft;
-    const prepared = await this.service.prepare(draft.projectId, [...draft.steps, ...extra], draft.signIn ?? null);
+    const prepared = await this.service.prepare(draft.projectId, withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]), draft.signIn ?? null);
     const runHelper = helperRunner(prepared.helpers, prepared.secrets);
     this.resolvers = {
       resolveAuth: authenticationResolver(prepared.authentications),
-      resolveSecret: (ref) => prepared.secrets[ref],
+      resolveSecret: (ref) => this.typed.get(ref) ?? prepared.secrets[ref],
       ...runHelper ? { runHelper } : {}
     };
     return this.resolvers;
@@ -272,6 +355,8 @@ var AuthoringSession = class {
     this.catalog = catalog;
     this.draft = { ...input, steps: [] };
     this.values = /* @__PURE__ */ new Map();
+    this.typed = /* @__PURE__ */ new Map();
+    this.lastTree = null;
     const base = this.baseUrl();
     this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
     this.page = this.run.page;
@@ -300,23 +385,74 @@ var AuthoringSession = class {
     } else {
       await this.page.goto(new URL(input.startPath || "/", base).href, { waitUntil: "domcontentloaded", timeout: 45e3 });
     }
+    if (input.preparation?.length) {
+      const resolvers = await this.prepare(input.preparation);
+      for (const step of input.preparation) {
+        try {
+          this.page = await executeStep(this.page, step, {
+            pages: this.run.pages,
+            ...resolvers,
+            values: this.values,
+            baseUrl: base,
+            timeoutMs: 2e4,
+            navigationTimeoutMs: 45e3
+          });
+        } catch (error) {
+          throw new Error(`The flows this one starts after did not finish, at "${step.name || step.type}": ${error.message.split("\n")[0]}`);
+        }
+      }
+      await this.settle();
+    }
     return this.snapshot();
   }
   /** The page as Claude reads it: where it is, and what is on it by role and name. */
   async snapshot() {
+    return this.view(true);
+  }
+  /** WHAT CHANGED, after a step — not the whole page again.
+   *
+   * Every step used to answer with the full tree, which on a long storefront
+   * is twenty thousand characters repeated forty times to say "the box now
+   * has text in it". So a step answers with what it is about: an open dialog
+   * (with the navigation, which says who is signed in), or the lines that
+   * appeared and disappeared — and only after a real navigation, when most of
+   * the page is new, the page itself, capped. read_page is always the whole
+   * thing. */
+  async view(full) {
     const { page, draft } = this.requireOpen();
     await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
-    let tree = labelTree(
+    const tree = labelTree(
       await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
       await fieldNames(page)
     );
-    if (tree.length > MAX_TREE) tree = `${tree.slice(0, MAX_TREE)}
-\u2026 (cut \u2014 the page is long; act on what is above, or scroll with press "PageDown")`;
     const title = await page.title().catch(() => "");
-    return `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+    const head = `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
 Steps so far: ${draft.steps.length}
 
-${tree}`;
+`;
+    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);
+    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)";
+    }
+    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 + 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)"
+    ].filter(Boolean).join("\n");
   }
   /** Do one thing on the page, and keep it as a step if it worked. */
   async act(input) {
@@ -329,13 +465,17 @@ ${tree}`;
       throw new Error(`${input.action} needs a value`);
     }
     const target = navigating ? { role: "", name: "" } : 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({
-      id: `s${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      id,
       type: input.action,
       ...target,
       ...scopeOf(input.within),
-      value: input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
-      secret: false,
+      value: secret ? "" : input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
       legacySelector: "",
       proposals: [],
       // A path is the application's own, so the step replays on whichever
@@ -348,19 +488,21 @@ ${tree}`;
         values: this.values,
         baseUrl: this.baseUrl(),
         ...this.resolvers ?? {},
+        resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref),
         timeoutMs: STEP_TIMEOUT_MS,
         navigationTimeoutMs: 45e3
       });
     } catch (error) {
+      if (secret) this.typed.delete(`${TYPED}${id}`);
       throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
 
-${await this.snapshot()}`);
+${await this.view(false)}`);
     }
     await this.settle();
     draft.steps.push(step);
     return `Step ${draft.steps.length} kept: ${describe(step)}.
 
-${await this.snapshot()}`;
+${await this.view(false)}`;
   }
   /** Check something about the page now, and keep the check if it holds. */
   async check(input) {
@@ -437,7 +579,7 @@ ${await this.snapshot()}`;
     draft.steps.push(step);
     return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got.value}" (${got.detail}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
 
-${await this.snapshot()}` : "");
+${await this.view(false)}` : "");
   }
   list() {
     const draft = this.draft;
@@ -465,6 +607,7 @@ ${this.list()}`;
     const resolvers = await this.prepare();
     const steps = [
       ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: { ...draft.signIn, from: "loginPage" }, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
       ...draft.steps
     ];
     const outcome = await replayFlow({ steps, baseUrl: this.baseUrl(), startPath: draft.startPath, headless: true, ...resolvers });
@@ -473,25 +616,83 @@ ${this.list()}`;
 ${lines.join("\n")}`;
   }
   /** Save the draft as a flow on a new branch, for a person to review. */
-  async save(title) {
+  async save(title, where = {}) {
     const { draft } = this.requireOpen();
     if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
     if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
       throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
     }
-    const saved = await this.service.saveFlow(draft.projectId, title || `Write "${draft.name}" with Claude`, {
+    const checksOff = draft.steps.map((step) => step.type === "assert" ? { ...step, proposals: step.proposals.map((p) => ({ ...p, enabled: false })) } : step);
+    const checkCount = checksOff.filter((step) => step.type === "assert").length;
+    const secretValues = {};
+    for (const step of checksOff) {
+      const value = step.secretRef ? this.typed.get(step.secretRef) : void 0;
+      if (value !== void 0) secretValues[step.id] = value;
+    }
+    const saved = await this.service.saveFlow(draft.projectId, title || "Tests written with Claude", {
       name: draft.name,
       ...draft.featureId ? { featureId: draft.featureId } : { featureName: draft.featureName },
       startPath: draft.startPath,
-      steps: draft.steps,
-      ...draft.signIn ? { signIn: draft.signIn } : {}
-    });
+      steps: withoutTyped(checksOff),
+      ...draft.signIn ? { signIn: draft.signIn } : {},
+      ...draft.after?.length ? { prerequisites: draft.after.map((a) => ({ flowId: a.flowId })) } : {}
+    }, where, secretValues);
     const review = `${this.service.origin}/projects/${draft.projectId}/changes/${saved.changeId}`;
+    const what = saved.replaced ? `Replaced the earlier "${draft.name}"` : `Saved "${draft.name}"`;
+    const sealed = Object.keys(secretValues).length;
+    const vault = sealed ? ` ${sealed} secret value${sealed === 1 ? " was" : "s were"} put in the project's vault, not the flow.` : "";
+    const where_ = saved.newBranch ? `on a new branch, ${saved.branch}` : `on Claude's working branch, ${saved.branch}`;
     const others = await this.service.agentChanges(draft.projectId).then((r) => r.changes.filter((c) => c.id !== saved.changeId)).catch(() => []);
     const note = others.length ? `
-Claude also has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 list_my_branches shows them, if one is now superseded.` : "";
-    return `Saved "${draft.name}" on a new branch, ${saved.branch}. Nothing is published yet.
+Claude has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 gather_branches puts them into this one, for one review.` : "";
+    const after = draft.after?.length ? ` It starts after ${draft.after.map((a) => `"${a.name}"`).join(", ")}.` : "";
+    return `${what} ${where_}.${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 a test case switches on the ones it is about. Nothing is published yet.
 Review and publish it here: ${review}${note}`;
+  }
+  /** A test case built from flows, without saving: its rows and every check,
+   *  numbered, with which are on — what save_case's `checks` refer to. */
+  async previewCase(projectId, spec) {
+    const built = await this.service.buildCase(projectId, spec, true);
+    return `"${spec.name}" in ${spec.folder} would be:
+${describeRows(built.rows)}`;
+  }
+  /** RUN THE CASE, THEN SAVE IT. Built as a dry run, replayed in a fresh
+   *  browser exactly as a test run does it, and saved onto Claude's working
+   *  branch only when every row passed. */
+  async saveCase(projectId, spec, catalog) {
+    const built = await this.service.buildCase(projectId, spec, true);
+    const testCase = built.testCase;
+    const steps = testCase.occurrences.flatMap((o) => o.steps);
+    const prepared = await this.service.prepare(projectId, steps, null);
+    const runHelper = helperRunner(prepared.helpers, prepared.secrets);
+    const base = catalog.baseUrl;
+    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    const outcome = await replayCase({
+      occurrences: testCase.occurrences,
+      ...testCase.actors ? { actors: testCase.actors } : {},
+      ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {},
+      baseUrl: base,
+      headless: true,
+      resolveAuth: authenticationResolver(prepared.authentications),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      ...runHelper ? { runHelper } : {}
+    });
+    const lines = outcome.occurrences.map((o, i) => {
+      const failed = o.steps.find((st) => st.status === "failed");
+      const why = o.status === "failed" ? `: ${failed ? `step "${failed.name || failed.type}" \u2014 ${(failed.detail ?? "").split("\n")[0]}` : (o.error ?? "").split("\n")[0]}` : "";
+      return `${o.status === "passed" ? "\u2713" : o.status === "failed" ? "\u2717" : "\xB7"} row ${i + 1} \u2014 ${o.name}${why}`;
+    });
+    if (outcome.status !== "passed") {
+      return `The case did not pass, so it was NOT saved.
+${lines.join("\n")}
+
+${describeRows(built.rows)}`;
+    }
+    const saved = await this.service.buildCase(projectId, spec, false);
+    const review = `${this.service.origin}${saved.path}`;
+    return `The case passed from the start${saved.replaced ? " and replaced the earlier version" : ""}, and is saved on ${saved.newBranch ? "a new branch" : "Claude's working branch"}. Nothing is published yet.
+${lines.join("\n")}
+Review and publish it here: ${review}`;
   }
   async close() {
     const run = this.run;
@@ -511,43 +712,107 @@ Review and publish it here: ${review}${note}`;
 
 // src/mcp/tools.ts
 var INSTRUCTIONS = `Flowriki tools write UI tests by driving a real browser on this computer.
-Every step you take is performed first and kept only if it worked, so the flow
-you save already ran once. Saved flows go to a NEW branch that a person reviews
-and publishes in the Flowriki dashboard \u2014 nothing you do is published.
+Every step you take is performed first and kept only if it worked, so what you
+save already ran once. Everything goes to ONE working branch per project that a
+person reviews and publishes in the Flowriki dashboard \u2014 nothing you do is
+published.
 
 A new project \u2014 "set up Flowriki for this site, in this repository" \u2014 is made
 with create_project; it then becomes the project the other tools work on.
 
-How to write a good Flowriki test:
-1. Call project_catalog first. Reuse an existing feature for the flow when one
-   fits; otherwise name a new one. Check the existing flows so you do not write
-   one that already exists.
-2. One flow is one user journey with one purpose ("Sign up and verify email",
-   "Pay by card"), named the way a tester would say it.
-3. If the journey needs somebody signed in, pass signIn with a profile and an
-   account from the catalog to start_flow. Never type real credentials.
-4. Read the page with read_page and act using the role and name EXACTLY as the
-   page shows them (e.g. button "Continue", textbox "Email"). If a name appears
-   more than once, pass "within" with the name of the region, dialog or form
-   that holds the one you mean.
-5. For things outside the page \u2014 an emailed code or link, an authenticator
+THE MODEL \u2014 get this right before recording anything:
+- A FLOW is a reusable building block: one piece of a journey ("Open the account
+  dialog", "Fill the sign-up form", "Sign in with a wrong password"). A flow can
+  START AFTER other flows (start_flow's "after"), so it holds only its own new
+  steps and links to the ones before it. A path that behaves differently \u2014 a
+  wrong password, a duplicate email \u2014 is its own flow, because the page does
+  something different.
+- A flow records checks (add_check) that prove each thing happened, but they
+  are SAVED SWITCHED OFF: which ones matter depends on the test.
+- A TEST CASE is the test. It strings flows together as rows (in the same
+  browser, or a new one for a second person) and switches on the checks it is
+  about. Build it with preview_case, then save_case \u2014 which runs it first.
+- SIGN-IN is shared setup: a flow or case that needs somebody signed in uses a
+  sign-in profile from the catalog (start_flow's signIn), never typed login steps.
+  None yet? Make it: record the login as a flow that ends with a check proving
+  it worked (the account menu, a heading, the URL), then create_sign_in from it
+  and create_account for each person who signs in (a customer, an admin). The
+  login flow types into its fields; the account supplies the values.
+- HELPERS (an inbox for email codes, an authenticator, SMS, an API call) are made
+  with create_helper when the catalog has none that fits.
+- PASSWORDS AND KEYS never go into a flow or a reply. Typed into a password
+  field, a value is kept as a secret and saved to the project's vault; given to
+  create_account or create_helper, it is sealed there too and never shown back.
+  Only use credentials the person gave you or that the app itself shows for
+  testing (a demo login) \u2014 never guess or reuse anyone's real password.
+- FOLDERS do not nest. Name each one after the product area and what is in it,
+  the way a tester would look for it \u2014 "Account \u2013 Sign up", "Account \u2013 Sign in",
+  "Ordering \u2013 Pizza builder", "Checkout \u2013 Payment". Flows (features) and the
+  cases built from them use the same names. Keep one area per folder.
+
+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
+   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
    catalog, then type {{its saveAs name}} into the field that needs it.
-6. End with at least one check (add_check) that proves the journey worked:
-   a heading, a message, the URL. Saving is refused for a flow that checks nothing.
-7. Before saving, call replay_flow to run the whole flow from the start. If a
-   step fails there, fix it (remove_step, act again) and replay again.
-8. Save with save_flow and give the person the review link it returns.
-9. Redoing a flow? Each save is a new branch, so clear the superseded one with
-   list_my_branches and discard_branch \u2014 only after the person asks for it, or
-   agrees, because it deletes the branch. Only Claude's own unedited branches
-   can go this way; anything a person touched is theirs to delete.
+5. Add checks for what each step proves (a heading, a message, a value, the
+   URL). replay_flow, then save_flow. A flow must record at least one check.
+6. Build each test case: preview_case lists its rows and every check, numbered;
+   save_case with the numbers to switch on runs the whole case and saves it only
+   if it passed. Give the person the review link.
+7. Saving the same name again replaces it on the working branch. Old branches
+   of yours? gather_branches puts them into one; discard_branch deletes one \u2014
+   only after the person asks or agrees.
 Test data you invent (a new user's email or password for a sign-up) is fine to
 type. For anything that must be NEW on every run \u2014 a sign-up's email or
 username \u2014 use {{unique}}: it is different on every run and the same within
 one, e.g. qa+{{unique}}@ the domain of the project's mailbox helper, so the
 helper can read that address's verification email with {"email": "qa+{{unique}}@\u2026"}.
 A test that types a fixed new email passes once and fails every run after.`;
+var CASE_INPUT = {
+  type: "object",
+  properties: {
+    name: { type: "string", description: 'The test case: the scenario it proves, e.g. "Wrong password is refused".' },
+    folder: { type: "string", description: 'The case folder \u2014 area and topic, e.g. "Account \u2013 Sign in". Made if new.' },
+    description: { type: "string" },
+    rows: {
+      type: "array",
+      description: "The flows to run, in order. Each row runs in the same browser as the row above unless newBrowser is true (a second person).",
+      items: {
+        type: "object",
+        properties: {
+          flow: { type: "string", description: "A flow's name or id from project_catalog." },
+          newBrowser: { type: "boolean" },
+          checks: {
+            description: `Which of this row's checks to switch on: their numbers from preview_case, or "all". The rest stay off.`,
+            anyOf: [{ type: "array", items: { type: "number" } }, { type: "string", enum: ["all"] }]
+          }
+        },
+        required: ["flow"],
+        additionalProperties: false
+      }
+    },
+    branch: { type: "string", description: "Optional: save onto this branch (chg_\u2026) instead of the working one." },
+    projectId: { type: "string" }
+  },
+  required: ["name", "folder", "rows"],
+  additionalProperties: false
+};
+var caseSpec = (args) => ({
+  name: String(args["name"] ?? ""),
+  folder: String(args["folder"] ?? ""),
+  ...args["description"] ? { description: String(args["description"]) } : {},
+  rows: Array.isArray(args["rows"]) ? args["rows"] : [],
+  ...args["branch"] ? { changeId: String(args["branch"]) } : {}
+});
 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);
 function authoringTools(service, session) {
@@ -569,7 +834,7 @@ function authoringTools(service, session) {
     catalogs.set(projectId, catalog);
     return catalog;
   };
-  return [
+  const tools = [
     {
       name: "list_projects",
       title: "List Flowriki projects",
@@ -621,11 +886,23 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
 Features:${c.features.length ? "" : " none yet"}`,
           ...c.features.map((f) => `  - ${f.name} (id ${f.id})${f.description ? ` \u2014 ${f.description}` : ""}
 ${flowsBy(f.id)}`),
+          ...c.draft ? [
+            `
+On Claude's working branch "${c.draft.title}" (${c.draft.changeId}), not yet published:`,
+            ...c.draft.features.length ? [`  New features: ${c.draft.features.map((f) => `${f.name} (id ${f.id})`).join(", ")}`] : [],
+            ...c.draft.flows.length ? c.draft.flows.map((f) => `    - flow: ${f.name} (${f.steps} steps, feature ${f.featureId}${f.after?.length ? `, after ${f.after.map((a) => `"${a}"`).join(", ")}` : ""})`) : ["  (no flows yet)"],
+            ...c.draft.caseFolders?.length ? [`  New case folders: ${c.draft.caseFolders.map((f) => f.name).join(", ")}`] : [],
+            ...(c.draft.cases ?? []).map((t) => `    - case: ${t.name} (folder ${t.folderId}) \u2014 rows: ${t.rows.join(" \u2192 ")}`)
+          ] : [],
+          `
+Test cases:${(c.cases ?? []).length ? "" : " none published"}`,
+          ...(c.caseFolders ?? []).map((f) => `  - ${f.name} (id ${f.id})
+${(c.cases ?? []).filter((t) => t.folderId === f.id).map((t) => `    - ${t.name} \u2014 rows: ${t.rows.join(" \u2192 ")}`).join("\n")}`),
           `
 Sign-in profiles:${c.signIns.length ? "" : " none"}`,
-          ...c.signIns.map((s) => `  - ${s.name} (profileId ${s.profileId}): ${s.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
+          ...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 they are made on the Helpers screen"}`,
+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"));
       }
@@ -640,6 +917,11 @@ Helpers:${c.helpers.length ? "" : " none \u2014 they are made on the Helpers scr
           name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
           feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
           startPath: { type: "string", description: 'Where it starts, relative to the base URL. Default "/".' },
+          after: {
+            type: "array",
+            items: { type: "string" },
+            description: "Flows this one starts after (names or ids from project_catalog). They are replayed first, so recording begins where they end; what THEY start after is added too. The saved flow links to them."
+          },
           signIn: {
             type: "object",
             description: "Start signed in, with a profile (and optionally an account) from project_catalog.",
@@ -662,14 +944,18 @@ Helpers:${c.helpers.length ? "" : " none \u2014 they are made on the Helpers scr
         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 page = await session.start({
           projectId,
+          ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
           name: str(args["name"]) ?? "Untitled flow",
           ...feature ? { featureId: feature.id } : { featureName: featureAsked },
           startPath: str(args["startPath"]) || "/",
           ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
         }, catalog);
-        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}. The browser is open.
+        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} The browser is open.
 
 ${page}`);
       }
@@ -693,7 +979,8 @@ ${page}`);
           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." },
-          value: { type: "string" }
+          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." }
         },
         required: ["action"],
         additionalProperties: false
@@ -705,7 +992,8 @@ ${page}`);
           ...str(args["role"]) ? { role: str(args["role"]) } : {},
           ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
           ...str(args["within"]) ? { within: str(args["within"]) } : {},
-          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {}
+          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {},
+          ...typeof args["secret"] === "boolean" ? { secret: args["secret"] } : {}
         }));
       }
     },
@@ -783,9 +1071,20 @@ ${page}`);
     {
       name: "save_flow",
       title: "Save the flow to a branch",
-      description: "Save the flow to a new branch in the project's repository, for a person to review and publish. Returns the review link. Refused if the flow checks nothing.",
-      inputSchema: { type: "object", properties: { title: { type: "string", description: "The branch's title \u2014 what this change adds." } }, additionalProperties: false },
-      run: async (args) => text(await session.save(str(args["title"])))
+      description: "Save the flow onto Claude's working branch for this project (made on the first save), for a person to review and publish. Saving the same name again replaces the earlier version there. Returns the review link. Refused if the flow checks nothing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "The branch's title, used only when a new branch is started." },
+          branch: { type: "string", description: "Optional: a branch id (chg_\u2026) from list_my_branches to save onto instead." },
+          newBranch: { type: "boolean", description: "Start a separate branch instead of the working one. Only when the person asks for separate reviews." }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.save(str(args["title"]), {
+        ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {},
+        ...args["newBranch"] === true ? { newBranch: true } : {}
+      }))
     },
     {
       name: "list_my_branches",
@@ -800,6 +1099,30 @@ ${page}`);
         return text(changes.map((c) => `- ${c.id} \u2014 "${c.title}" (${new Date(c.createdAt).toISOString().slice(0, 16).replace("T", " ")}) ${service.origin}${c.path}`).join("\n"));
       }
     },
+    {
+      name: "gather_branches",
+      title: "Gather Claude's branches into one",
+      description: "Move the flows from Claude's open branches on this project into one branch, and delete the emptied ones \u2014 so the person reviews and publishes once. Only Claude's own, unedited branches; anything a person touched stops it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          into: { type: "string", description: "The branch to gather into (chg_\u2026). Default: Claude's oldest open branch." },
+          title: { type: "string", description: 'A title for the gathered branch, e.g. "Sign in and sign up tests".' },
+          projectId: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const done = await service.gatherChanges(projectId, {
+          ...str(args["into"]) ? { into: str(args["into"]) } : {},
+          ...str(args["title"]) ? { title: str(args["title"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`Gathered ${done.gathered.length} branch${done.gathered.length === 1 ? "" : "es"} into "${done.title}" (${done.changeId}). Review and publish it here: ${service.origin}${done.path}`);
+      }
+    },
     {
       name: "discard_branch",
       title: "Delete one of Claude's branches",
@@ -818,6 +1141,124 @@ ${page}`);
         return text(`Deleted ${changeId} and its branch ${deleted}.`);
       }
     },
+    {
+      name: "preview_case",
+      title: "Preview a test case",
+      description: "Build a test case from flows without saving or running it: its rows (each flow with what it starts after folded in, and which browser it runs in) and every check, numbered, with which are on. Use the numbers in save_case.",
+      inputSchema: CASE_INPUT,
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        return text(await session.previewCase(projectId, caseSpec(args)));
+      }
+    },
+    {
+      name: "save_case",
+      title: "Run and save a test case",
+      description: "Build the test case, run it from the start in a fresh browser exactly as a test run will, and \u2014 only if every row passed \u2014 save it onto Claude's working branch. Saving the same name in the same folder again replaces it. Refused if it switches on no checks.",
+      inputSchema: CASE_INPUT,
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const out = await session.saveCase(projectId, caseSpec(args), await catalogOf(projectId, true));
+        catalogs.delete(projectId);
+        return text(out);
+      }
+    },
+    {
+      name: "create_sign_in",
+      title: "Make a sign-in profile",
+      description: "Turn a saved login flow into a sign-in profile that flows and test cases can start signed in with. The flow must not itself sign in or start after other flows, and must end with a check proving the login worked \u2014 its last check is switched on here. Returns the fields an account fills in. Making the same name again replaces Claude's earlier one.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          flow: { type: "string", description: "The login flow's name or id (project_catalog)." },
+          name: { type: "string", description: `What a tester calls this way of signing in, e.g. "Customer sign-in". Default: the flow's name.` },
+          description: { type: "string" },
+          signOutFlow: { type: "string", description: "Optional: a flow that signs out, by name or id." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["flow"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.createSignIn(projectId, {
+          flow: str(args["flow"]) ?? "",
+          ...str(args["name"]) ? { name: str(args["name"]) } : {},
+          ...str(args["description"]) ? { description: str(args["description"]) } : {},
+          ...str(args["signOutFlow"]) ? { signOutFlow: str(args["signOutFlow"]) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Replaced" : "Made"} the sign-in "${made.name}" (profileId ${made.profileId}) from "${made.flow}", on ${made.newBranch ? "a new branch" : "Claude's working branch"} ${made.branch}.
+An account fills in: ${made.fields.map((f) => `"${f.label}"${f.secret ? " (secret)" : ""}`).join(", ") || "nothing \u2014 the flow types no values"}.
+Next: create_account for each person who signs in this way.`);
+      }
+    },
+    {
+      name: "create_account",
+      title: "Make a sign-in account",
+      description: "An account for a sign-in profile: who signs in, and the values its login flow types, by field label (create_sign_in and project_catalog list them). Secret fields are sealed in the project's vault and never shown again. Then start_flow / test cases can use signIn {profileId, accountId}. Making the same name again updates Claude's earlier one.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          signIn: { type: "string", description: "The sign-in profile's name or id." },
+          name: { type: "string", description: 'Who this is, e.g. "Demo customer", "Kitchen admin".' },
+          values: { type: "object", additionalProperties: { type: "string" }, description: 'Field label \u2192 value, e.g. {"Email": "demo@example.com", "Password": "\u2026"}.' },
+          environments: { type: "array", items: { type: "string" }, description: "Optional: the environments this account exists on. Default: all." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["signIn", "name", "values"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const values = Object.fromEntries(Object.entries(args["values"] && typeof args["values"] === "object" ? args["values"] : {}).map(([k, v]) => [k, String(v)]));
+        const made = await service.createAccount(projectId, {
+          signIn: str(args["signIn"]) ?? "",
+          name: str(args["name"]) ?? "",
+          values,
+          ...Array.isArray(args["environments"]) ? { environments: args["environments"].map(String) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Updated" : "Made"} the account "${made.name}" (accountId ${made.accountId}) for "${made.signIn}", on Claude's working branch ${made.branch}. Filled: ${made.filled.join(", ")} \u2014 secrets are in the vault, not the repository.
+Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accountId}"}.`);
+      }
+    },
+    {
+      name: "create_helper",
+      title: "Make a helper",
+      description: `A helper for things outside the page, as the Helpers screen makes one. config by kind \u2014 mailbox: {kind, host, port?, secure?, username, folder?, match?: {to, from, subject}, extract?: {take: code|link|subject|body, pattern}, waitSeconds?} with secretValues {passwordRef: the mailbox password}. totp: {kind, digits?, period?, algorithm?} with secretValues {secretRef: the base32 secret}. sms: {kind, accountSid, to, match?, extract?} with secretValues {authTokenRef: the Twilio token}. http: {kind, method, url, headers?, secretHeaders?: {name: ""}, body?, expectStatus?, extract?: {take: json|pattern|status|nothing, path, pattern}} with secretValues {"header:<name>": value}. Use {{name}} in fields for inputs a step supplies. Secrets are sealed in the vault and never shown again. Making the same name again updates Claude's earlier one.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          name: { type: "string", description: 'e.g. "QA inbox", "Admin authenticator".' },
+          description: { type: "string" },
+          config: { type: "object", description: "The helper's settings, by kind (see above). Never put a secret here." },
+          secretValues: { type: "object", additionalProperties: { type: "string" }, description: "The secret for the kind, keyed as above." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["name", "config"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.createHelper(projectId, {
+          name: str(args["name"]) ?? "",
+          ...str(args["description"]) ? { description: str(args["description"]) } : {},
+          config: args["config"] && typeof args["config"] === "object" ? args["config"] : {},
+          ...args["secretValues"] && typeof args["secretValues"] === "object" ? { secretValues: Object.fromEntries(Object.entries(args["secretValues"]).map(([k, v]) => [k, String(v)])) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Updated" : "Made"} the ${made.kind} helper "${made.name}" (id ${made.helperId}) on Claude's working branch ${made.branch}.${made.inputs.length ? ` A step supplies ${made.inputs.map((n) => `{{${n}}}`).join(", ")}.` : ""} Use it with use_helper.`);
+      }
+    },
     {
       name: "close_browser",
       title: "Close the browser",
@@ -831,6 +1272,18 @@ ${page}`);
       }
     }
   ];
+  return tools.map((tool) => ({
+    ...tool,
+    run: async (args) => {
+      let result;
+      try {
+        result = await tool.run(args);
+      } catch (error) {
+        throw new Error(session.redact(error.message));
+      }
+      return { ...result, content: result.content.map((c) => c.type === "text" && c.text !== void 0 ? { ...c, text: session.redact(c.text) } : c) };
+    }
+  }));
 }
 
 // src/mcp/index.ts

package/dist/engine.js

@@ -9,7 +9,7 @@ import {
   resolveCheckouts,
   start,
   status
-} from "./chunk-3UUCI66O.js";
+} from "./chunk-N3P4O3OH.js";
 export {
   AGENT_VERSION,
   browsersReady,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowriki/agent",
-  "version": "0.1.0-beta.33",
+  "version": "0.1.0-beta.36",
   "description": "Run Flowriki UI tests on your own computer. Connects this machine to your Flowriki account.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",