@swmansion/argent 0.24.0 → 0.24.1-next.1

package/dist/cli-cmds.mjs

@@ -7253,7 +7253,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.24.0";
+    return "0.24.1-next.1";
   }
   return "0.0.0";
 }
@@ -8588,10 +8588,13 @@ chromium (a lone \`{ chromium: ... }\` target, or --platform chromium); a
 multi-platform launch auto-detects a device instead. Pass --device to attach to
 a running instance.
 
-A directory run prints only failing steps plus a final flow summary;
---recursive walks subdirectories too (dot-directories and node_modules are
-skipped). An invalid flow file fails alone and the batch continues; an infra
-error stops the batch and counts the remaining flows skipped.
+A directory run prints each flow's failing steps and warnings, then its outcome,
+then a final flow summary; --recursive walks subdirectories too (dot-directories
+and node_modules are skipped). A flow that fails its steps keeps the batch
+running, as does one the server rejects up front \u2014 an invalid file, or a device
+it cannot resolve. A transport failure, a rejection the server does not mark as
+validation, or a reply that is not a report stops the batch and counts the
+remaining flows skipped.
 
 Runs require the auto-started local tool server;
 ARGENT_TOOLS_URL and \`argent link\` routing are not supported.
@@ -8614,8 +8617,10 @@ Options (run):
                          instead (with a warning), so no flow's evidence is
                          overwritten
   -r, --recursive        With a directory path, also run flows in subdirectories
-  --json                 Print the raw JSON report
-  --json-stream          Print progress and the final report as NDJSON (single flow only)
+  --json                 Print the flow's JSON report, or a directory run's JSON
+                         aggregate
+  --json-stream          Print each step and the final report as NDJSON (single
+                         flow only, never with --json)
   --help, -h             Show this help
   --                     End of options \u2014 only needed for a flow whose name
                          starts with "-" (\`argent flow run -- -nightly\`)
@@ -8981,14 +8986,16 @@ function buildRunPayload(flowPath, projectRoot, args) {
 function writeJsonStreamRecord(record) {
   console.log(JSON.stringify(record));
 }
+function failureSignal2(err) {
+  if (!(err instanceof ToolInvocationError)) return {};
+  return {
+    ...err.errorCode ? { error_code: err.errorCode } : {},
+    ...err.errorKind ? { error_kind: err.errorKind } : {}
+  };
+}
 function writeJsonStreamError(err) {
   const message = err instanceof Error ? err.message : String(err);
-  writeJsonStreamRecord({
-    event: "error",
-    error: message,
-    ...err instanceof ToolInvocationError && err.errorCode ? { error_code: err.errorCode } : {},
-    ...err instanceof ToolInvocationError && err.errorKind ? { error_kind: err.errorKind } : {}
-  });
+  writeJsonStreamRecord({ event: "error", error: message, ...failureSignal2(err) });
 }
 async function exportAndResolveArtifacts(report, outputDir, flowPath, baseUrl) {
   if (outputDir) {
@@ -8997,6 +9004,22 @@ async function exportAndResolveArtifacts(report, outputDir, flowPath, baseUrl) {
   }
   resolveArtifactDisplayPaths(report);
 }
+function rejectionVerdict(code) {
+  switch (code) {
+    case FAILURE_CODES.FLOW_FILE_INVALID:
+    case FAILURE_CODES.FLOW_ENTRY_UNRECOGNIZED:
+    case FAILURE_CODES.FLOW_E2E_HAS_PREREQUISITE:
+      return "not run (invalid flow)";
+    case FAILURE_CODES.FLOW_DEVICE_RESOLUTION:
+      return "not run (no device resolved)";
+    default:
+      return "not run (rejected)";
+  }
+}
+function isFlowReport(data) {
+  const steps = data?.steps;
+  return Array.isArray(steps) && steps.every((step) => !!step && typeof step === "object");
+}
 async function runFlowDirectory(dir, args, projectRoot, options) {
   let flows;
   try {
@@ -9032,18 +9055,24 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
         "flow-execute",
         buildRunPayload(path14.join(dir, rel), projectRoot, args)
       );
-      const data = resp.data;
-      if (data && typeof data === "object" && "steps" in data) report = data;
+      if (isFlowReport(resp.data)) report = resp.data;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      const toolErr = err instanceof ToolInvocationError ? err : void 0;
+      const rejectedThisFlowOnly = toolErr?.errorKind === "validation";
+      if (!args.json) {
+        console.log(
+          `  ${STATUS_GLYPH.error} ` + (rejectedThisFlowOnly ? rejectionVerdict(toolErr?.errorCode) : "did not finish (run error)")
+        );
+      }
       console.error(message);
-      results.push({ path: rel, status: "fail", error: message });
-      const rejectedThisFlowOnly = err instanceof ToolInvocationError && err.errorKind === "validation";
+      results.push({ path: rel, status: "fail", error: message, ...failureSignal2(err) });
       if (!rejectedThisFlowOnly) stopped = true;
       continue;
     }
     if (!report) {
       const message = `"${rel}" did not produce a run report.`;
+      if (!args.json) console.log(`  ${STATUS_GLYPH.error} did not finish (no run report)`);
       console.error(message);
       results.push({ path: rel, status: "fail", error: message });
       stopped = true;
@@ -9268,9 +9297,19 @@ ${recovery}`,
     );
     report = resp.data;
   } catch (err) {
+    if (!args.json && !args.jsonStream) {
+      if (liveSteps === 0) console.log(`Flow "${flowName}"`);
+      console.log(
+        `  ${STATUS_GLYPH.error} ` + (err instanceof ToolInvocationError && err.errorKind === "validation" ? rejectionVerdict(err.errorCode) : "did not finish (run error)")
+      );
+    }
     return fail(err instanceof Error ? err.message : String(err), 1, err);
   }
-  if (!report || typeof report !== "object" || !("steps" in report)) {
+  if (!isFlowReport(report)) {
+    if (!args.json && !args.jsonStream) {
+      if (liveSteps === 0) console.log(`Flow "${flowName}"`);
+      console.log(`  ${STATUS_GLYPH.error} did not finish (no run report)`);
+    }
     return fail(`"${flowName}" did not produce a run report.`, 2);
   }
   try {

package/dist/installer.mjs

@@ -16625,7 +16625,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.24.0";
+    return "0.24.1-next.1";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -93916,7 +93916,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.24.0";
+    return "0.24.1-next.1";
   }
   return "0.0.0";
 }
@@ -143956,11 +143956,25 @@ function selectorToYaml(sel) {
   }
   return out;
 }
+var INLINE_UNSAFE = /[\u0000-\u001f\u007f-\u009f]/g;
+var INLINE_SHORT = {
+  "\b": "\\b",
+  "	": "\\t",
+  "\n": "\\n",
+  "\f": "\\f",
+  "\r": "\\r"
+};
+function escapeInline(value) {
+  return value.replace(
+    INLINE_UNSAFE,
+    (c) => INLINE_SHORT[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
 function describeSelector(s) {
   const { loose: _loose, any: any2, within, after, next, ...rest } = s;
   const scopes = { within, after, next };
   const fields = Object.entries(rest).map(
-    ([k, v]) => k === "textMatches" ? `text=/${v}/` : `${k === "identifier" ? "id" : k}="${v}"`
+    ([k, v]) => k === "textMatches" ? `text=/${escapeInline(String(v))}/` : `${k === "identifier" ? "id" : k}=${JSON.stringify(String(v))}`
   ).join(" ");
   const parts2 = [any2 ? "*" : void 0, fields || void 0].filter((p) => p !== void 0);
   for (const relation of SELECTOR_RELATIONS) {
@@ -145612,7 +145626,7 @@ costs the finish the cross-tree verdicts anchored to them.`,
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
 init_zod();
-var fs54 = __toESM(require("node:fs/promises"));
+var fs53 = __toESM(require("node:fs/promises"));
 var path38 = __toESM(require("node:path"));
 init_src();
 
@@ -147407,10 +147421,8 @@ function assertReason(condition, selector, expectedText, textMatch, matches2) {
   }
 }
 
-// ../tool-server/src/tools/flows/flow-finish-recording.ts
-init_zod();
-var fs53 = __toESM(require("node:fs/promises"));
-function selectorLabel(sel) {
+// ../tool-server/src/tools/flows/flow-step-definitions.ts
+function yamlSelectorLabel(sel) {
   const yaml = selectorToYaml(sel);
   if (typeof yaml !== "object" || yaml === null) return JSON.stringify(yaml);
   const sorted = Object.fromEntries(
@@ -147418,116 +147430,54 @@ function selectorLabel(sel) {
   );
   return JSON.stringify(sorted);
 }
-function textConditionLabel(sel, expectedText, textMatch) {
-  const selector = selectorLabel(sel);
+function yamlTextConditionLabel(sel, expectedText, textMatch) {
+  const selector = yamlSelectorLabel(sel);
   const expected = expectedText ?? "";
   return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
 }
-function targetLabel(target) {
-  return "selector" in target ? selectorLabel(target.selector) : `(${target.x}, ${target.y})`;
-}
-var zodSchema62 = external_exports.object({
-  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
-  project_root: external_exports.string().describe(
-    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
-  )
-});
-function attachStepWarnings(summary, warnings) {
-  if (warnings.size === 0) return summary;
-  return summary.flatMap((line, i) => {
-    const recorded = warnings.get(i + 1);
-    return recorded ? [line, `   warning: ${recorded.warning}`] : [line];
-  });
+function yamlConditionLabel(cond) {
+  return cond.condition === "text" ? yamlTextConditionLabel(cond.selector, cond.expectedText, cond.textMatch) : `${cond.condition} ${yamlSelectorLabel(cond.selector)}`;
 }
-function warningHeadline(warnings, discarded) {
-  const counts = { conversion: 0, wait: 0 };
-  for (const { kind } of warnings.values()) counts[kind] += 1;
-  const clauses = [];
-  if (counts.conversion > 0) {
-    clauses.push(
-      `${counts.conversion} ${counts.conversion === 1 ? "step carries" : "steps carry"} a cross-tree warning about converting a recorded wait`
-    );
-  }
-  if (counts.wait > 0) {
-    clauses.push(
-      `${counts.wait} ${counts.wait === 1 ? "step" : "steps"} recorded a wait that did not pass`
-    );
+function selectorLabel(sel) {
+  const parts2 = [];
+  if (sel.any) parts2.push("*");
+  if (sel.text !== void 0) parts2.push(JSON.stringify(sel.text));
+  if (sel.textMatches !== void 0) parts2.push(`/${escapeInline(sel.textMatches)}/`);
+  if (sel.identifier) parts2.push(`id=${escapeInline(sel.identifier)}`);
+  if (sel.role) parts2.push(`role=${escapeInline(sel.role)}`);
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = sel[relation];
+    if (scope !== void 0) parts2.push(`${relation} (${selectorLabel(scope)})`);
   }
-  const carried = clauses.length === 0 ? "" : ` \u2014 ${clauses.join(", and ")}; read \`summary\` before converting or replaying`;
-  if (discarded === 0) return carried;
-  const one = discarded === 1;
-  const drop = `${discarded} ${one ? "warning" : "warnings"} raised during this recording ${one ? "is" : "are"} NOT in \`summary\`: a hand edit to the .yaml moved the ${one ? "step it judged" : "steps they judged"}, so which step ${one ? "it belongs" : "they belong"} to is no longer knowable \u2014 re-record ${one ? "that wait" : "those waits"} to see ${one ? "it" : "them"} again`;
-  return carried === "" ? ` \u2014 ${drop}` : `${carried}. ${drop}`;
+  return parts2.join(" ");
 }
-function anchoredWarnings(session, steps) {
-  const kept = /* @__PURE__ */ new Map();
-  const recorded = session.flow.steps;
-  if (recorded.length !== steps.length) return kept;
-  if (!steps.every((step, i) => stepAnchor(step) === stepAnchor(recorded[i]))) return kept;
-  for (const [n, verdict] of session.stepWarnings ?? []) {
-    const step = steps[n - 1];
-    if (step !== void 0 && stepAnchor(step) === verdict.step) kept.set(n, verdict);
+function conditionLabel(cond, renderSelector) {
+  const sel = renderSelector(cond.selector);
+  if (cond.condition === "text") {
+    return `${sel} ${describeTextExpectation(cond.expectedText, cond.textMatch)}`;
   }
-  return kept;
+  return `${cond.condition} ${sel}`;
+}
+function gestureTargetLabel(target, renderSelector) {
+  return "selector" in target ? renderSelector(target.selector) : `(${target.x}, ${target.y})`;
+}
+function swipeLabel(step, renderSelector) {
+  let travel;
+  if (step.direction !== void 0) travel = step.direction;
+  else if (step.by !== void 0) travel = `by ${swipeByLabel(step.by)}`;
+  else if (step.to !== void 0) travel = `to ${gestureTargetLabel(step.to, renderSelector)}`;
+  else return void 0;
+  return `${travel}${step.from ? ` from ${gestureTargetLabel(step.from, renderSelector)}` : ""}`;
+}
+function whenLabel(cond, renderUi) {
+  return cond.kind === "platform" ? `platform ${cond.platform}` : renderUi(cond);
+}
+function describeWhenCondition(cond) {
+  return whenLabel(cond, (ui) => conditionLabel(ui, describeSelector));
 }
-var flowFinishRecordingTool = {
-  id: "flow-finish-recording",
-  interaction: {
-    // Name the flow: other recordings stay live, so an unqualified message would
-    // not identify which one.
-    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
-    // `params.name` equals the basename of `result.path` on every branch
-    // (`assertSafeFlowName` admits no dots or separators), and matches the two
-    // formatters either side.
-    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
-    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
-  },
-  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
-A warning flow-add-step raised on a recorded \`await-ui-element\` is repeated in \`summary\` as a \`warning:\` line of its own, right below the step it judges, and \`message\` counts them by kind. A warning is repeated only while the step it judges is still identifiable by its number: hand-editing the .yaml during the recording moves the steps, so those warnings are DROPPED rather than pinned on whichever step inherited the number, and \`message\` says how many were dropped. A step that carries a cross-tree warning was re-probed against the runner's tree: read it before converting that wait to \`await:\`/\`assert:\`, which is what the verdict is about and what this moment is for. A step that recorded a wait which did not pass was never probed at all, and its own warning names the CAUSE, because only one of them judges the condition: an unmet wait was read and found false, and it stops the run at replay; a wait whose tree source could not be read, or one that was cancelled, observed nothing and leaves the condition UNKNOWN rather than known-bad. Read those before replaying.
-You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
-  zodSchema: zodSchema62,
-  services: () => ({}),
-  async execute(_services, params) {
-    const { filePath, flowFile, savedTo, flow, summary, headline } = await withFlowFileLock(
-      params.project_root,
-      params.name,
-      async () => {
-        const session = await requireRecordingSession(params.project_root, params.name);
-        const filePath2 = session.filePath;
-        let flowFile2;
-        let savedTo2;
-        if (session.persist === "client") {
-          flowFile2 = serializeFlow(session.flow);
-          savedTo2 = clientFileDirective(filePath2, flowFile2);
-        } else {
-          flowFile2 = await fs53.readFile(filePath2, "utf8");
-          savedTo2 = filePath2;
-        }
-        const flow2 = parseFlow(flowFile2);
-        const anchored = anchoredWarnings(session, flow2.steps);
-        const summary2 = attachStepWarnings(summarizeSteps(flow2), anchored);
-        const discarded = (session.discardedWarnings ?? 0) + (session.stepWarnings?.size ?? 0) - anchored.size;
-        const headline2 = warningHeadline(anchored, discarded);
-        clearRecordingSession(session);
-        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2, headline: headline2 };
-      }
-    );
-    return {
-      // Name the counts in `message` as well. A caller that reads only
-      // `message` would otherwise polish blind.
-      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)` + headline,
-      path: filePath,
-      executionPrerequisite: flow.executionPrerequisite,
-      steps: flow.steps.length,
-      summary,
-      flowFile,
-      savedTo
-    };
-  }
-};
 function renderToolArgs(args) {
   try {
-    return `${JSON.stringify(args)}`;
+    return JSON.stringify(args);
   } catch {
     return "[cyclic args]";
   }
@@ -147535,77 +147485,162 @@ function renderToolArgs(args) {
 function delayLabel(step) {
   if (!step.delayMs) return "";
   const ms = Number(step.delayMs);
-  return Number.isFinite(ms) && ms >= 1 ? ` (after ${ms}ms)` : "";
-}
-function summarizeSteps(flow) {
-  return flow.steps.map((step, i) => summarizeStep(step, i + 1));
-}
-function stepAnchor(step) {
-  return summarizeStep(step, 0);
-}
-function summarizeStep(step, n) {
-  switch (step.kind) {
-    case "echo":
-      return `${n}. echo: ${step.message}`;
-    case "launch":
-      return `${n}. launch: ${typeof step.app === "string" ? step.app : JSON.stringify(step.app)}`;
-    case "run":
-      return `${n}. run: ${step.flow}`;
-    case "tap":
-    case "long-press": {
-      const target = targetLabel(
-        step.selector ? { selector: step.selector } : { x: step.x, y: step.y }
-      );
-      const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
-      const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
-      return `${n}. ${step.kind}: ${target}${times}${held}`;
-    }
-    case "swipe": {
-      const travel = step.direction ?? (step.by ? `by ${swipeByLabel(step.by)}` : `to ${targetLabel(step.to)}`);
-      const from2 = step.from ? ` from ${targetLabel(step.from)}` : "";
+  return ms >= 1 && ms <= 2 ** 31 - 1 ? ` (after ${ms}ms)` : "";
+}
+var MAX_TARGET_TEXT_CHARS = 200;
+function typedTextLabel(text) {
+  const chars = Array.from(text);
+  if (chars.length <= MAX_TARGET_TEXT_CHARS) return JSON.stringify(text);
+  const elided = chars.length - MAX_TARGET_TEXT_CHARS;
+  return `${JSON.stringify(chars.slice(0, MAX_TARGET_TEXT_CHARS).join(""))}\u2026(+${elided} chars)`;
+}
+var POINT_GESTURE_STEP = {
+  // `times` (tap) and `duration` (long-press) change what replays, so a summary
+  // line that drops them misdescribes the file. `times` has a second reason:
+  // `tap` is one of the kinds the recorder builds, and the recorder echoes this
+  // line alone rather than the growing YAML, so it is the author's only per-step
+  // view of what was appended. `long-press` has no recorder path, so it reaches
+  // an author only through flow-finish-recording's `summary`, which returns
+  // `flowFile` beside it. Neither kind carries a `delayMs` (only `tool` steps
+  // do), so no delayLabel here.
+  //
+  // Four replay-affecting fields render on neither surface — `type.submit`,
+  // `await.timeout`, `idle.timeout`, `idle.stableFor` — so a summary line alone
+  // does not distinguish two steps differing only in those.
+  summary: (step) => {
+    const target = step.selector ? yamlSelectorLabel(step.selector) : `(${step.x}, ${step.y})`;
+    const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
+    const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
+    return `${target}${times}${held}`;
+  },
+  target: (step) => {
+    if (step.selector) return selectorLabel(step.selector);
+    if (step.x !== void 0 && step.y !== void 0) return `(${step.x}, ${step.y})`;
+    return void 0;
+  }
+};
+var UI_CONDITION_STEP = {
+  summary: (step) => yamlConditionLabel(step),
+  target: (step) => conditionLabel(step, selectorLabel)
+};
+var FLOW_STEP_DEFINITIONS = {
+  "tool": {
+    summary: (step) => `${step.name} ${renderToolArgs(step.args)}${delayLabel(step)}`,
+    // Carries its subject in a report field of its own (`tool`) that renderers
+    // print in the target's place.
+    target: () => void 0
+  },
+  "echo": {
+    summary: (step) => step.message,
+    // As for `tool`, but the field is `message`.
+    target: () => void 0
+  },
+  "launch": {
+    summary: (step) => typeof step.app === "string" ? step.app : JSON.stringify(step.app),
+    // A launch's app id may be per-platform (`appIdForPlatform`), and a step
+    // alone does not know the run device.
+    target: () => void 0
+  },
+  "run": {
+    summary: (step) => step.flow,
+    // The as-written path, so a report line shows exactly what the flow
+    // references (`run ../shared/login.yaml`), not just the attribution stem.
+    target: (step) => step.flow
+  },
+  "when": {
+    summary: (step) => {
+      const count2 = step.steps.length;
+      const cond = whenLabel(step.condition, yamlConditionLabel);
+      return `${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
+    },
+    target: (step) => whenLabel(step.condition, (ui) => conditionLabel(ui, selectorLabel))
+  },
+  "tap": POINT_GESTURE_STEP,
+  "long-press": POINT_GESTURE_STEP,
+  "swipe": {
+    // `momentum` and `duration` change what replays, so the summary spells them
+    // as it spells tap's `times`. A report target names what the step acts on,
+    // so they ride the summary alone.
+    summary: (step) => {
       const options = [
         ...step.momentum === false ? ["momentum-free"] : [],
         ...step.duration !== void 0 ? [`${step.duration}ms`] : []
       ];
       const tail = options.length > 0 ? ` (${options.join(", ")})` : "";
-      return `${n}. swipe: ${travel}${from2}${tail}`;
+      return `${swipeLabel(step, yamlSelectorLabel)}${tail}`;
+    },
+    target: (step) => swipeLabel(step, selectorLabel)
+  },
+  "type": {
+    summary: (step) => `${yamlSelectorLabel(step.into)} \u2190 ${JSON.stringify(step.text)}`,
+    // The typed text rides along, the way an await/assert target carries its
+    // expectation: two steps into the same field with different text would
+    // otherwise render identical targets.
+    target: (step) => `into ${selectorLabel(step.into)} \u2190 ${typedTextLabel(step.text)}`
+  },
+  "await": UI_CONDITION_STEP,
+  "assert": UI_CONDITION_STEP,
+  "idle": {
+    summaryKind: "await",
+    summary: () => "screen idle",
+    // The report already prints the kind, and this step addresses nothing
+    // beyond the screen itself: a target would render as "idle screen idle".
+    target: () => void 0
+  },
+  "wait": {
+    summary: (step) => `${step.ms}ms`,
+    target: () => void 0
+  },
+  "scroll-to": {
+    summary: (step) => `${yamlSelectorLabel(step.target)} (${step.direction})` + (step.within ? ` within ${yamlSelectorLabel(step.within)}` : ""),
+    target: (step) => {
+      const dir = step.direction !== "down" ? ` (${step.direction})` : "";
+      const container = step.within ? ` in scroll container (${selectorLabel(step.within)})` : "";
+      return `${selectorLabel(step.target)}${dir}${container}`;
     }
-    case "type":
-      return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
-    case "await":
-    case "assert": {
-      const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
-      return `${n}. ${step.kind}: ${tail}`;
+  },
+  "pinch": {
+    summary: (step) => `scale ${step.scale}${step.selector ? ` on ${yamlSelectorLabel(step.selector)}` : ""}`,
+    target: (step) => {
+      const scale = `scale ${step.scale}`;
+      return step.selector ? `${selectorLabel(step.selector)} (${scale})` : scale;
     }
-    case "wait":
-      return `${n}. wait: ${step.ms}ms`;
-    case "when": {
-      const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
-        step.condition.selector,
-        step.condition.expectedText,
-        step.condition.textMatch
-      ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
-      const count2 = step.steps.length;
-      return `${n}. when: ${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
+  },
+  "rotate": {
+    summary: (step) => `by ${step.by}\xB0${step.selector ? ` on ${yamlSelectorLabel(step.selector)}` : ""}`,
+    target: (step) => {
+      const by = `by ${step.by}\xB0`;
+      return step.selector ? `${selectorLabel(step.selector)} (${by})` : by;
     }
-    case "scroll-to":
-      return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
-    case "pinch":
-      return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-    case "rotate":
-      return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-    case "snapshot":
-      return `${n}. snapshot: ${step.name}`;
-    case "idle":
-      return `${n}. await: screen idle`;
-    case "tool":
-    default:
-      return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}${delayLabel(step)}`;
+  },
+  "snapshot": {
+    // `name` interpolates raw on both surfaces. It becomes a baseline filename,
+    // so `parseFlow` gates it on FLOW_NAME_PATTERN (letters, digits, `_`, `-`)
+    // — and that parse is the only thing that builds a snapshot step, so no
+    // quote, backslash or newline reaches here to escape.
+    summary: (step) => step.name + (step.cropOn ? ` cropOn ${yamlSelectorLabel(step.cropOn)}` : "") + (step.maxMismatch !== void 0 ? ` maxMismatch ${step.maxMismatch}` : ""),
+    target: (step) => step.cropOn ? `"${step.name}" cropOn ${selectorLabel(step.cropOn)}` : `"${step.name}"`
   }
+};
+function definitionOf(step) {
+  return FLOW_STEP_DEFINITIONS[step.kind];
+}
+function stepTarget(step) {
+  return definitionOf(step).target(step);
+}
+function summarizeStep(step, n) {
+  const def = definitionOf(step);
+  return `${n}. ${def.summaryKind ?? step.kind}: ${def.summary(step)}`;
+}
+function summarizeSteps(flow) {
+  return flow.steps.map((step, i) => summarizeStep(step, i + 1));
+}
+function stepAnchor(step) {
+  return summarizeStep(step, 0);
 }
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
-var zodSchema63 = external_exports.object({
+var zodSchema62 = external_exports.object({
   name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
   project_root: external_exports.string().describe(
     "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this step belongs to."
@@ -147819,7 +147854,7 @@ async function captureTapSelector(registry2, session, udid, point) {
 async function activeFlowState(session) {
   if (session.persist === "host") {
     try {
-      session.flow = parseFlow(await fs54.readFile(session.filePath, "utf8"));
+      session.flow = parseFlow(await fs53.readFile(session.filePath, "utf8"));
     } catch (err) {
       return {
         stepCount: session.flow.steps.length,
@@ -147960,7 +147995,7 @@ async function captureRunTarget(session, args) {
   }
   try {
     assertSafeFlowName(name);
-    const realFlowPath = await fs54.realpath(session.filePath);
+    const realFlowPath = await fs53.realpath(session.filePath);
     const flowsDir = path38.dirname(realFlowPath);
     const fragPath = path38.join(flowsDir, `${name}.yaml`);
     const projectRoot = args.project_root;
@@ -147976,10 +148011,10 @@ async function captureRunTarget(session, args) {
         warning: `kept the raw flow-execute step \u2014 no sibling is named "${name}.yaml" (this filesystem matched it case-insensitively to "${spelling.actual}"), so a run: ${name} step would name a flow no case-sensitive checkout can find \u2014 ${recovery}`
       };
     }
-    parseFlow(await fs54.readFile(fragPath, "utf8"));
+    parseFlow(await fs53.readFile(fragPath, "utf8"));
     let executedPath;
     try {
-      executedPath = await fs54.realpath(path38.join(flowsDirFor(projectRoot), `${name}.yaml`));
+      executedPath = await fs53.realpath(path38.join(flowsDirFor(projectRoot), `${name}.yaml`));
     } catch {
       executedPath = void 0;
     }
@@ -147988,7 +148023,7 @@ async function captureRunTarget(session, args) {
         warning: `kept the raw flow-execute step \u2014 could not verify which file the live flow-execute ran ("${name}" has no canonical file in project_root's flows dir to compare the sibling against)`
       };
     }
-    if (executedPath !== await fs54.realpath(fragPath)) {
+    if (executedPath !== await fs53.realpath(fragPath)) {
       return {
         warning: `kept the raw flow-execute step \u2014 project_root "${projectRoot}" resolves "${name}" to "${executedPath}", not the recording's sibling "${fragPath}", so "${name}.yaml" beside the recording's real file is not the file the live flow-execute ran and a run: ${name} step would replay a different flow than the one that just ran`
       };
@@ -148020,7 +148055,7 @@ If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-
     // more times — and every retry re-runs the action and appends another step,
     // because an aborted request still appends its first.
     longRunning: true,
-    zodSchema: zodSchema63,
+    zodSchema: zodSchema62,
     services: () => ({}),
     async execute(_services, params, ctx) {
       const session = await requireRecordingSession(params.project_root, params.name);
@@ -148125,7 +148160,7 @@ If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-
 
 // ../tool-server/src/tools/flows/flow-insert-echo.ts
 init_zod();
-var zodSchema64 = external_exports.object({
+var zodSchema63 = external_exports.object({
   name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
   project_root: external_exports.string().describe(
     "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this echo belongs to."
@@ -148143,7 +148178,7 @@ var flowInsertEchoTool = {
   description: `Record an echo step in the flow named by \`name\` + \`project_root\`. Echo steps print a message when the flow is replayed \u2014 useful as labels between tool calls.
 Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.
 Returns { message, stepCount, savedTo }. Fails if that flow has no recording in progress.`,
-  zodSchema: zodSchema64,
+  zodSchema: zodSchema63,
   services: () => ({}),
   async execute(_services, params) {
     const session = await requireRecordingSession(params.project_root, params.name);
@@ -148159,6 +148194,109 @@ Returns { message, stepCount, savedTo }. Fails if that flow has no recording in
   }
 };
 
+// ../tool-server/src/tools/flows/flow-finish-recording.ts
+init_zod();
+var fs54 = __toESM(require("node:fs/promises"));
+var zodSchema64 = external_exports.object({
+  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
+  project_root: external_exports.string().describe(
+    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
+  )
+});
+function attachStepWarnings(summary, warnings) {
+  if (warnings.size === 0) return summary;
+  return summary.flatMap((line, i) => {
+    const recorded = warnings.get(i + 1);
+    return recorded ? [line, `   warning: ${recorded.warning}`] : [line];
+  });
+}
+function warningHeadline(warnings, discarded) {
+  const counts = { conversion: 0, wait: 0 };
+  for (const { kind } of warnings.values()) counts[kind] += 1;
+  const clauses = [];
+  if (counts.conversion > 0) {
+    clauses.push(
+      `${counts.conversion} ${counts.conversion === 1 ? "step carries" : "steps carry"} a cross-tree warning about converting a recorded wait`
+    );
+  }
+  if (counts.wait > 0) {
+    clauses.push(
+      `${counts.wait} ${counts.wait === 1 ? "step" : "steps"} recorded a wait that did not pass`
+    );
+  }
+  const carried = clauses.length === 0 ? "" : ` \u2014 ${clauses.join(", and ")}; read \`summary\` before converting or replaying`;
+  if (discarded === 0) return carried;
+  const one = discarded === 1;
+  const drop = `${discarded} ${one ? "warning" : "warnings"} raised during this recording ${one ? "is" : "are"} NOT in \`summary\`: a hand edit to the .yaml moved the ${one ? "step it judged" : "steps they judged"}, so which step ${one ? "it belongs" : "they belong"} to is no longer knowable \u2014 re-record ${one ? "that wait" : "those waits"} to see ${one ? "it" : "them"} again`;
+  return carried === "" ? ` \u2014 ${drop}` : `${carried}. ${drop}`;
+}
+function anchoredWarnings(session, steps) {
+  const kept = /* @__PURE__ */ new Map();
+  const recorded = session.flow.steps;
+  if (recorded.length !== steps.length) return kept;
+  if (!steps.every((step, i) => stepAnchor(step) === stepAnchor(recorded[i]))) return kept;
+  for (const [n, verdict] of session.stepWarnings ?? []) {
+    const step = steps[n - 1];
+    if (step !== void 0 && stepAnchor(step) === verdict.step) kept.set(n, verdict);
+  }
+  return kept;
+}
+var flowFinishRecordingTool = {
+  id: "flow-finish-recording",
+  interaction: {
+    // Name the flow: other recordings stay live, so an unqualified message would
+    // not identify which one.
+    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
+    // `params.name` equals the basename of `result.path` on every branch
+    // (`assertSafeFlowName` admits no dots or separators), and matches the two
+    // formatters either side.
+    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
+  },
+  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
+A warning flow-add-step raised on a recorded \`await-ui-element\` is repeated in \`summary\` as a \`warning:\` line of its own, right below the step it judges, and \`message\` counts them by kind. A warning is repeated only while the step it judges is still identifiable by its number: hand-editing the .yaml during the recording moves the steps, so those warnings are DROPPED rather than pinned on whichever step inherited the number, and \`message\` says how many were dropped. A step that carries a cross-tree warning was re-probed against the runner's tree: read it before converting that wait to \`await:\`/\`assert:\`, which is what the verdict is about and what this moment is for. A step that recorded a wait which did not pass was never probed at all, and its own warning names the CAUSE, because only one of them judges the condition: an unmet wait was read and found false, and it stops the run at replay; a wait whose tree source could not be read, or one that was cancelled, observed nothing and leaves the condition UNKNOWN rather than known-bad. Read those before replaying.
+You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
+  zodSchema: zodSchema64,
+  services: () => ({}),
+  async execute(_services, params) {
+    const { filePath, flowFile, savedTo, flow, summary, headline } = await withFlowFileLock(
+      params.project_root,
+      params.name,
+      async () => {
+        const session = await requireRecordingSession(params.project_root, params.name);
+        const filePath2 = session.filePath;
+        let flowFile2;
+        let savedTo2;
+        if (session.persist === "client") {
+          flowFile2 = serializeFlow(session.flow);
+          savedTo2 = clientFileDirective(filePath2, flowFile2);
+        } else {
+          flowFile2 = await fs54.readFile(filePath2, "utf8");
+          savedTo2 = filePath2;
+        }
+        const flow2 = parseFlow(flowFile2);
+        const anchored = anchoredWarnings(session, flow2.steps);
+        const summary2 = attachStepWarnings(summarizeSteps(flow2), anchored);
+        const discarded = (session.discardedWarnings ?? 0) + (session.stepWarnings?.size ?? 0) - anchored.size;
+        const headline2 = warningHeadline(anchored, discarded);
+        clearRecordingSession(session);
+        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2, headline: headline2 };
+      }
+    );
+    return {
+      // Name the counts in `message` as well. A caller that reads only
+      // `message` would otherwise polish blind.
+      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)` + headline,
+      path: filePath,
+      executionPrerequisite: flow.executionPrerequisite,
+      steps: flow.steps.length,
+      summary,
+      flowFile,
+      savedTo
+    };
+  }
+};
+
 // ../tool-server/src/tools/flows/flow-run.ts
 init_zod();
 var fs57 = __toESM(require("node:fs/promises"));
@@ -151345,88 +151483,6 @@ function pushReport(state3, report) {
   state3.reports.push(report);
   state3.onStepReport?.(report);
 }
-function selectorLabel2(sel) {
-  const parts2 = [];
-  if (sel.any) parts2.push("*");
-  if (sel.text !== void 0) parts2.push(`"${sel.text}"`);
-  if (sel.textMatches !== void 0) parts2.push(`/${sel.textMatches}/`);
-  if (sel.identifier) parts2.push(`id=${sel.identifier}`);
-  if (sel.role) parts2.push(`role=${sel.role}`);
-  for (const relation of SELECTOR_RELATIONS) {
-    const scope = sel[relation];
-    if (scope !== void 0) parts2.push(`${relation} (${selectorLabel2(scope)})`);
-  }
-  return parts2.join(" ");
-}
-function conditionLabel(cond, renderSelector) {
-  const sel = renderSelector(cond.selector);
-  if (cond.condition === "text") {
-    return `${sel} ${describeTextExpectation(cond.expectedText, cond.textMatch)}`;
-  }
-  return `${cond.condition} ${sel}`;
-}
-function gestureTargetLabel(target) {
-  return "selector" in target ? selectorLabel2(target.selector) : `(${target.x}, ${target.y})`;
-}
-function stepTarget(step) {
-  switch (step.kind) {
-    case "tap":
-    case "long-press":
-      if (step.selector) return selectorLabel2(step.selector);
-      if (step.x !== void 0 && step.y !== void 0) return `(${step.x}, ${step.y})`;
-      return void 0;
-    case "swipe": {
-      let travel;
-      if (step.direction !== void 0) {
-        travel = step.direction;
-      } else if (step.by !== void 0) {
-        travel = `by ${swipeByLabel(step.by)}`;
-      } else if (step.to !== void 0) {
-        travel = `to ${gestureTargetLabel(step.to)}`;
-      } else {
-        return void 0;
-      }
-      return `${travel}${step.from ? ` from ${gestureTargetLabel(step.from)}` : ""}`;
-    }
-    case "type":
-      return `into ${selectorLabel2(step.into)}`;
-    case "await":
-    case "assert":
-      return conditionLabel(step, selectorLabel2);
-    case "idle":
-      return void 0;
-    case "when":
-      return step.condition.kind === "platform" ? `platform ${step.condition.platform}` : conditionLabel(step.condition, selectorLabel2);
-    case "scroll-to": {
-      const dir = step.direction !== "down" ? ` (${step.direction})` : "";
-      return `${selectorLabel2(step.target)}${dir}`;
-    }
-    case "pinch": {
-      const scale = `scale ${step.scale}`;
-      return step.selector ? `${selectorLabel2(step.selector)} (${scale})` : scale;
-    }
-    case "rotate": {
-      const by = `by ${step.by}\xB0`;
-      return step.selector ? `${selectorLabel2(step.selector)} (${by})` : by;
-    }
-    case "snapshot":
-      return step.cropOn ? `"${step.name}" cropOn ${selectorLabel2(step.cropOn)}` : `"${step.name}"`;
-    case "run":
-      return step.flow;
-    case "echo":
-    case "tool":
-      return void 0;
-    case "launch":
-      return void 0;
-    case "wait":
-      return void 0;
-    default: {
-      const unclassified = step;
-      void unclassified;
-      return void 0;
-    }
-  }
-}
 function scopeFlow(scope) {
   return scope.runStack[scope.runStack.length - 1].display;
 }
@@ -151514,10 +151570,6 @@ async function execSteps(state3, steps, scope) {
     if (report.status === "fail" || report.status === "error") state3.stopped = true;
   }
 }
-function describeWhenCondition(cond) {
-  if (cond.kind === "platform") return `platform ${cond.platform}`;
-  return conditionLabel(cond, describeSelector);
-}
 function reportBlockSkipped(state3, steps, scope, reason) {
   for (const step of steps) {
     pushReport(state3, {
@@ -152509,7 +152561,7 @@ var updateArgentTool = {
       });
       child.unref();
     }, 2e3);
-    const targetLabel2 = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
+    const targetLabel = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
     const otherHint = requested === "auto" && resolved !== "both" ? resolved === "local" ? ` If you also have a global install, call this tool again with target "global" to update it too.` : ` If you also have a project-local install, run \`argent update --local\` in that project to update it too.` : "";
     const bothDegradedNote = resolved === "both" && effectiveTarget === "global" ? ` The project-local install was skipped: no project declaring ${PACKAGE_NAME2} could be located from this server \u2014 run \`argent update --local\` in the project directory for it.` : "";
     const versionInfo = targetsOnlyRunningInstall ? `(v${currentVersion} -> v${installableVersion}) ` : "";
@@ -152517,7 +152569,7 @@ var updateArgentTool = {
     const coversRunningInstall = targetsOnlyRunningInstall || effectiveTarget === "both";
     const restartNote = coversRunningInstall ? ` The tool server will stop and restart automatically once the update is installed. Subsequent tool calls will reconnect to the updated server.` : ` This session's tool server is not affected and keeps running; the update applies only to the targeted install.`;
     return {
-      message: `Argent update initiated ${versionInfo}for the ${targetLabel2}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
+      message: `Argent update initiated ${versionInfo}for the ${targetLabel}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
     };
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.24.0",
+  "version": "0.24.1-next.1",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",