@swmansion/argent 0.22.1-next.4 → 0.22.1-next.6

package/dist/cli-cmds.mjs

@@ -2675,11 +2675,13 @@ async function applyClientFileDirectives(result) {
 var ToolInvocationError = class extends Error {
   errorCode;
   errorKind;
+  issues;
   constructor(message, signal) {
     super(message);
     this.name = "ToolInvocationError";
     this.errorCode = signal?.errorCode;
     this.errorKind = signal?.errorKind;
+    this.issues = signal?.issues;
   }
 };
 function authHeaders2(token) {
@@ -2727,6 +2729,10 @@ async function consumeToolStream(body, onProgress) {
   const { result: data } = await applyClientFileDirectives(final.data);
   return { data, note: final.note };
 }
+function errorBodyMessage(body) {
+  if (Array.isArray(body.issues) && typeof body.message === "string") return body.message;
+  return body.error ?? body.message;
+}
 function createToolsClient(options = {}) {
   let cached2 = null;
   async function baseUrl() {
@@ -2781,13 +2787,11 @@ function createToolsClient(options = {}) {
     }
     const json = await res.json().catch(() => ({}));
     if (!res.ok) {
-      throw new ToolInvocationError(
-        json.error ?? json.message ?? `${res.status} ${res.statusText}`,
-        {
-          errorCode: json.error_code,
-          errorKind: json.error_kind
-        }
-      );
+      throw new ToolInvocationError(errorBodyMessage(json) ?? `${res.status} ${res.statusText}`, {
+        errorCode: json.error_code,
+        errorKind: json.error_kind,
+        issues: Array.isArray(json.issues) ? json.issues : void 0
+      });
     }
     const { result: data } = await applyClientFileDirectives(json.data);
     return { data, note: json.note };
@@ -2823,6 +2827,10 @@ var FLAG_REGISTRY = [
     name: "tool-server-event-log",
     description: "Write structured tool-server lifecycle events to a JSONL file."
   },
+  {
+    name: "boot-sound",
+    description: "Default boot-device's `sound` argument to true so Android emulators boot with audio output instead of muted. Only the argument's default changes \u2014 an explicit `sound: false` on a call still boots muted."
+  },
   {
     name: "microinteractions",
     description: "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default."
@@ -7202,7 +7210,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.4";
+    return "0.22.1-next.6";
   }
   return "0.0.0";
 }
@@ -8005,7 +8013,11 @@ function findMissingRequired(payload, schema) {
   }
   return names.filter((name) => !Object.hasOwn(payload, name));
 }
-function describeServerValidationFailure(err, payload, schema) {
+function serverIssueList(err) {
+  const carried = err?.issues;
+  if (Array.isArray(carried)) {
+    return carried.length > 0 && carried.every(isValidationIssue) ? carried : null;
+  }
   const message = err instanceof Error ? err.message : typeof err === "string" ? err : null;
   if (message === null) return null;
   let parsed;
@@ -8015,7 +8027,11 @@ function describeServerValidationFailure(err, payload, schema) {
     return null;
   }
   if (!Array.isArray(parsed) || parsed.length === 0) return null;
-  if (!parsed.every(isValidationIssue)) return null;
+  return parsed.every(isValidationIssue) ? parsed : null;
+}
+function describeServerValidationFailure(err, payload, schema) {
+  const parsed = serverIssueList(err);
+  if (parsed === null) return null;
   const properties = schema?.properties ?? {};
   const addressesThisTool = (issue) => issue.path.length === 0 || typeof issue.path[0] === "string" && Object.hasOwn(properties, issue.path[0]);
   if (!parsed.every(addressesThisTool)) return null;

package/dist/installer.mjs

@@ -16428,7 +16428,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.4";
+    return "0.22.1-next.6";
   }
   return "0.0.0";
 }

package/dist/mcp-server.mjs

@@ -16855,6 +16855,12 @@ async function applyClientFileDirectives(result) {
   return { result: rewritten, written };
 }
 
+// ../argent-tools-client/src/tools-client.ts
+function errorBodyMessage(body) {
+  if (Array.isArray(body.issues) && typeof body.message === "string") return body.message;
+  return body.error ?? body.message;
+}
+
 // ../argent-tools-client/src/artifacts.ts
 import { copyFile, mkdir as mkdir4, readFile as readFile4, realpath, rm as rm3, stat as stat3, writeFile as writeFile4 } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
@@ -18685,7 +18691,7 @@ async function startMcpServer(options) {
       fetchTimeoutMs: meta2?.longRunning ? null : FETCH_TIMEOUT_MS
     });
     const json = await res.json();
-    if (!res.ok) throw new Error(json.error ?? json.message ?? res.statusText);
+    if (!res.ok) throw new Error(errorBodyMessage(json) ?? res.statusText);
     const { result: data } = await applyClientFileDirectives(json.data);
     return { result: data, outputHint: meta2?.outputHint, note: json.note };
   }

package/dist/tool-server.cjs

@@ -16063,6 +16063,63 @@ function terminatingSignalCause(message) {
     error_kind: "unknown"
   });
 }
+function valueAtPath(root, path41) {
+  let current = root;
+  for (const key2 of path41) {
+    if (current === null || typeof current !== "object") return void 0;
+    if (!Object.hasOwn(current, key2)) return void 0;
+    current = current[key2];
+  }
+  return current;
+}
+function describeParamIssues(error52, params) {
+  const allKeys = params !== null && typeof params === "object" && !Array.isArray(params) ? Object.keys(params) : [];
+  const supplied = allKeys.slice(0, 24);
+  const truncated = allKeys.length > supplied.length;
+  const parts2 = error52.issues.map((issue2) => {
+    const at = issue2.path.length > 0 ? issue2.path.join(".") : "(root)";
+    if (issue2.code === "custom") {
+      return issue2.path.length > 0 ? `\`${at}\`: ${issue2.message}` : issue2.message;
+    }
+    if (valueAtPath(params, issue2.path) === void 0) {
+      const expected = issue2.expected;
+      const kind = typeof expected === "string" ? ` (${expected})` : "";
+      return `\`${at}\` is required${kind} and was not provided`;
+    }
+    if (issue2.code === "unrecognized_keys") {
+      const keys = issue2.keys ?? [];
+      const at2 = issue2.path.length > 0 ? `${issue2.path.join(".")}.` : "";
+      return `unknown parameter${keys.length === 1 ? "" : "s"} ${keys.map((k) => `\`${at2}${k}\``).join(", ")}`;
+    }
+    if (issue2.code === "invalid_union") {
+      const branches = issue2.errors ?? [];
+      const alternatives = [];
+      const seen = /* @__PURE__ */ new Set();
+      let moreAlternatives = false;
+      for (const branch of branches) {
+        for (const inner of branch) {
+          const innerAt = inner.path.length > 0 ? `${at}.${inner.path.join(".")}: ` : "";
+          const text = `${innerAt}${inner.message}`;
+          if (seen.has(text)) continue;
+          if (alternatives.length >= MAX_UNION_ALTERNATIVES) {
+            moreAlternatives = true;
+            break;
+          }
+          seen.add(text);
+          alternatives.push(text);
+        }
+        if (moreAlternatives) break;
+      }
+      if (alternatives.length > 0) {
+        return `\`${at}\`: ${alternatives.join("; or ")}${moreAlternatives ? "; or \u2026" : ""}`;
+      }
+    }
+    return `\`${at}\`: ${issue2.message}`;
+  });
+  const sent = supplied.length > 0 ? ` You sent: ${supplied.map((k) => `\`${k}\``).join(", ")}${truncated ? ", \u2026" : ""}.` : "";
+  const body = parts2.length > 0 ? `${parts2.map((p) => p.replace(/\.$/, "")).join("; ")}.` : "";
+  return `${body}${sent}`.trim() || "invalid parameters";
+}
 function formatInteractionMessage(format, fallback) {
   try {
     return format() ?? fallback;
@@ -16070,7 +16127,7 @@ function formatInteractionMessage(format, fallback) {
     return fallback;
   }
 }
-var import_node_crypto2, Registry;
+var import_node_crypto2, Registry, MAX_UNION_ALTERNATIVES;
 var init_registry = __esm({
   "../registry/src/registry.ts"() {
     "use strict";
@@ -16151,7 +16208,15 @@ var init_registry = __esm({
           if (definition.zodSchema) {
             const parsed = definition.zodSchema.safeParse(params ?? {});
             if (!parsed.success) {
-              throw new Error(`Invalid params for tool "${id}": ${parsed.error.message}`);
+              throw new FailureError(
+                `Invalid params for tool "${id}": ${describeParamIssues(parsed.error, params)}`,
+                {
+                  error_code: FAILURE_CODES.TOOL_INPUT_INVALID,
+                  failure_stage: "tool_params_parse",
+                  failure_area: "registry",
+                  error_kind: "validation"
+                }
+              );
             }
             effectiveParams = parsed.data;
           }
@@ -16388,6 +16453,7 @@ var init_registry = __esm({
         this._transition(node, cause ? "ERROR" /* ERROR */ : "IDLE" /* IDLE */, cause);
       }
     };
+    MAX_UNION_ALTERNATIVES = 12;
   }
 });
 
@@ -91789,6 +91855,10 @@ var FLAG_REGISTRY = [
     name: "tool-server-event-log",
     description: "Write structured tool-server lifecycle events to a JSONL file."
   },
+  {
+    name: "boot-sound",
+    description: "Default boot-device's `sound` argument to true so Android emulators boot with audio output instead of muted. Only the argument's default changes \u2014 an explicit `sound: false` on a call still boots muted."
+  },
   {
     name: "microinteractions",
     description: "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default."
@@ -95664,7 +95734,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.4";
+    return "0.22.1-next.6";
   }
   return "0.0.0";
 }
@@ -113871,14 +113941,23 @@ async function resolveFileInputs(def, body, lookupUpload) {
   };
   const specs = def.fileInputs;
   if (!specs || specs.length === 0 || typeof body !== "object" || body === null) {
-    return { args: body ?? {}, fileInputs: void 0, cleanup };
+    return {
+      args: body ?? {},
+      fileInputs: void 0,
+      derivedTargets: [],
+      cleanup
+    };
   }
   const args = { ...body };
   let resolved;
+  const derivedTargets = [];
   try {
     for (const spec of specs) {
       const value = args[spec.target];
       if (!isFileInputWire(value)) continue;
+      if (spec.path !== `\${${spec.target}}` && !derivedTargets.includes(spec.target)) {
+        derivedTargets.push(spec.target);
+      }
       if (spec.unwrapWhenSet !== void 0 && isParamSet(args[spec.unwrapWhenSet])) {
         args[spec.target] = value.path;
         continue;
@@ -113895,7 +113974,7 @@ async function resolveFileInputs(def, body, lookupUpload) {
     await cleanup();
     throw err;
   }
-  return { args, fileInputs: resolved, cleanup };
+  return { args, fileInputs: resolved, derivedTargets, cleanup };
 }
 
 // ../tool-server/src/utils/debugger/device-alias.ts
@@ -114186,6 +114265,14 @@ function isToolExposed(def) {
 function findDependencyMissing(err) {
   return findErrorInCauseChain(err, DependencyMissingError);
 }
+function omitKeys(args, keys) {
+  if (keys.length === 0 || args === null || typeof args !== "object" || Array.isArray(args)) {
+    return args;
+  }
+  const copy = { ...args };
+  for (const key2 of keys) delete copy[key2];
+  return copy;
+}
 function errorSignalFields(err) {
   const signal = getFailureSignal(err);
   return signal ? { error_code: signal.error_code, error_kind: signal.error_kind } : {};
@@ -114525,6 +114612,7 @@ function createHttpApp(registry2, options) {
       }
       let bodyArgs;
       let resolvedFileInputs;
+      let derivedTargets;
       try {
         const resolved = await resolveFileInputs(def, req.body, (id) => {
           const entry = uploads.get(id);
@@ -114533,6 +114621,7 @@ function createHttpApp(registry2, options) {
         });
         bodyArgs = resolved.args;
         resolvedFileInputs = resolved.fileInputs;
+        derivedTargets = resolved.derivedTargets;
         res.once("close", () => void resolved.cleanup());
       } catch (err) {
         if (err instanceof FileInputError) {
@@ -114556,7 +114645,11 @@ function createHttpApp(registry2, options) {
             req.body,
             { invalid_params: deriveInvalidParams(parseResult.error, declared) }
           );
-          res.status(400).json({ error: parseResult.error.message });
+          res.status(400).json({
+            error: parseResult.error.message,
+            message: describeParamIssues(parseResult.error, omitKeys(bodyArgs, derivedTargets)),
+            issues: parseResult.error.issues
+          });
           return;
         }
         parsedData = parseResult.data;
@@ -114697,6 +114790,10 @@ function createHttpApp(registry2, options) {
           res.status(400).json({ error: invalidInputErr.message, ...errorSignalFields(err) });
           return;
         }
+        if (getFailureSignal(err)?.error_code === FAILURE_CODES.TOOL_INPUT_INVALID) {
+          res.status(400).json({ error: formatErrorForAgent(err), ...errorSignalFields(err) });
+          return;
+        }
         const notImplementedErr = findErrorInCauseChain(err, NotImplementedOnPlatformError);
         if (notImplementedErr) {
           res.status(501).json({
@@ -118670,6 +118767,9 @@ var zodSchema9 = external_exports.object({
     "Android/Vega: overall budget for the boot sequence. Default 480000 (8 min) on Android, 120000 (2 min) on Vega. Clamped to [30s, 15min]. Ignored on iOS."
   ),
   force: external_exports.boolean().optional().describe("Shut down and re-boot the device even if already running."),
+  sound: external_exports.boolean().optional().describe(
+    "Android only: boot the emulator with audio output enabled. Defaults to false \u2014 argent boots emulators MUTED so several agent-driven devices don't all play sound on the host machine; pass `true` when the task involves playing, hearing, or testing audio. Takes effect at boot: if the emulator is already running muted, add `force: true` to reboot it with sound. A boot snapshot saved in the other audio mode can't be reused, so the first boot after toggling is a slower cold boot. The `boot-sound` argent flag flips this default to true. Ignored on iOS/Vega/Electron, which argent never mutes."
+  ),
   headless: external_exports.boolean().optional().describe(
     "iOS only: boot the simulator core WITHOUT opening the Simulator.app GUI window. The device still streams via simulator-server; used by Argent Lens. Set the `ARGENT_SIMULATOR_NO_WINDOW` env var (1/true/yes) to force this host-wide without passing the flag per call (the iOS analog of `ARGENT_EMULATOR_NO_WINDOW`). Ignored on Android/Vega/Electron, which have no equivalent GUI step."
   ),
@@ -118687,13 +118787,15 @@ function bootTarget(params) {
   return params.udid ?? params.avdName ?? params.vvdImage ?? params.electronAppPath ?? "device";
 }
 var LAUNCH_HARDENING_ARGS = [
-  "-noaudio",
   "-no-boot-anim",
   "-netfast",
   "-crash-report-mode",
   "never",
   "-no-metrics"
 ];
+function launchHardeningArgs(sound) {
+  return sound ? [...LAUNCH_HARDENING_ARGS] : ["-noaudio", ...LAUNCH_HARDENING_ARGS];
+}
 var STAGE_BUDGET = {
   adbRegister: 6e4,
   // adb devices sees the serial for this AVD
@@ -119125,6 +119227,7 @@ async function bootAndroidImpl(params) {
   await ensureDep("emulator");
   const gpuMode = selectGpuMode();
   const extraEmulatorArgs = androidHeadlessFromEnv() ? ["-no-window"] : [];
+  const hardeningArgs = launchHardeningArgs(params.sound);
   for (const msg of linuxBootDiagnostics(params.avdName) ?? []) {
     console.warn(`[boot-device:linux] ${msg}`);
   }
@@ -119203,7 +119306,7 @@ async function bootAndroidImpl(params) {
   } else {
     const RENDERER_ARGS = ["-gpu", gpuMode, ...extraEmulatorArgs];
     const probe3 = await checkSnapshotLoadable(params.avdName, "default_boot", {
-      extraArgs: [...RENDERER_ARGS, ...LAUNCH_HARDENING_ARGS]
+      extraArgs: [...RENDERER_ARGS, ...hardeningArgs]
     });
     if (!probe3.loadable) {
       hotBootFailureReason = `-check-snapshot-loadable: ${probe3.reason ?? "unknown"}`;
@@ -119214,7 +119317,7 @@ async function bootAndroidImpl(params) {
         "-force-snapshot-load",
         "-no-snapshot-save",
         ...RENDERER_ARGS,
-        ...LAUNCH_HARDENING_ARGS,
+        ...hardeningArgs,
         ...crashReportArgs
       ];
       const hotAttemptDeadline = Math.min(overallDeadline, Date.now() + HOT_BOOT_BUDGET_MS);
@@ -119258,7 +119361,7 @@ async function bootAndroidImpl(params) {
     "-gpu",
     gpuMode,
     ...extraEmulatorArgs,
-    ...LAUNCH_HARDENING_ARGS,
+    ...hardeningArgs,
     ...crashReportArgs
   ];
   let coldResult;
@@ -119455,7 +119558,11 @@ Android boots take 2\u201310 minutes depending on machine and cold/warm state; t
         return bootAndroid({
           avdName: params.avdName,
           bootTimeoutMs: params.bootTimeoutMs ?? 48e4,
-          force: params.force
+          force: params.force,
+          // An explicit argument always wins; the `boot-sound` flag only moves
+          // the default when the caller left `sound` unset. Read live per call
+          // so `argent enable/disable boot-sound` applies without a restart.
+          sound: params.sound ?? isFlagEnabled("boot-sound")
         });
       }
       if (hasVega) {
@@ -123240,6 +123347,7 @@ init_zod();
 
 // ../tool-server/src/utils/sub-invoke.ts
 var import_node_crypto7 = require("node:crypto");
+init_src();
 async function invokeSubTool(registry2, ctx, toolId, args) {
   const signal = ctx?.signal;
   const recordChildInvocation = ctx?.recordChildInvocation;
@@ -123258,6 +123366,14 @@ async function invokeSubTool(registry2, ctx, toolId, args) {
     release();
   }
 }
+function describeNestedParamError(registry2, err, toolId, dispatchedArgs, authoredArgs) {
+  if (getFailureSignal(err)?.error_code !== FAILURE_CODES.TOOL_INPUT_INVALID) return void 0;
+  const zodSchema76 = registry2.getTool(toolId)?.zodSchema;
+  if (!zodSchema76) return void 0;
+  const parsed = zodSchema76.safeParse(dispatchedArgs ?? {});
+  if (parsed.success) return void 0;
+  return `Invalid params for tool "${toolId}": ${describeParamIssues(parsed.error, authoredArgs)}`;
+}
 
 // ../tool-server/src/tools/await-ui-element/index.ts
 init_zod();
@@ -129736,8 +129852,8 @@ Stops on the first error (or unmet await-ui-element condition) and returns parti
             throw err;
           }
         }
+        const toolArgs = { ...step.args, udid };
         try {
-          const toolArgs = { ...step.args, udid };
           const result = await invokeSubTool(registry2, ctx, step.tool, toolArgs);
           if (isUnmetUiWaitResult(step.tool, result)) {
             const note = result.note;
@@ -129749,9 +129865,16 @@ Stops on the first error (or unmet await-ui-element condition) and returns parti
           }
           results.push({ tool: step.tool, result });
         } catch (err) {
+          const reframed = describeNestedParamError(
+            registry2,
+            err,
+            step.tool,
+            toolArgs,
+            step.args ?? {}
+          );
           results.push({
             tool: step.tool,
-            error: err instanceof Error ? err.message : String(err)
+            error: reframed ?? (err instanceof Error ? err.message : String(err))
           });
           break;
         }
@@ -145856,7 +145979,9 @@ var zodSchema63 = external_exports.object({
   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."
   ),
-  command: external_exports.string().describe('MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app")'),
+  command: external_exports.string().describe(
+    'MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app") \u2014 a TOOL, not a flow directive. A flow-file directive name ("tap", "launch", "run", "type", "await", "assert", "pinch", "echo", "wait", "long-press", "scroll-to", "snapshot", "when") is answered with guidance, and nothing runs or is recorded: most name the tool that records the directive, while "wait", "long-press", "scroll-to", "snapshot" and "when" have no recording tool at all and are answered with what to do instead. A recording tool (flow-add-step, flow-add-echo, flow-start-recording, flow-finish-recording) is refused the same way, each for its own reason \u2014 nesting one would erase this flow at replay, end the take, or write the step twice.'
+  ),
   args: external_exports.string().optional().describe(
     `Tool arguments as a JSON string, e.g. '{"udid": "ABC", "x": 0.5, "y": 0.3}'. Omit for tools with no arguments.`
   ),
@@ -146056,6 +146181,77 @@ async function captureTapSelector(registry2, session, udid, point) {
     };
   }
 }
+async function activeFlowState(session) {
+  if (session.persist === "host") {
+    try {
+      session.flow = parseFlow(await fs48.readFile(session.filePath, "utf8"));
+    } catch (err) {
+      return {
+        stepCount: session.flow.steps.length,
+        note: `The persisted flow could not be read and parsed (${err instanceof Error ? err.message : String(err)}); the step count is from the last valid in-memory snapshot.`
+      };
+    }
+  }
+  return { stepCount: session.flow.steps.length };
+}
+async function recordNothing(session, guidance) {
+  const { stepCount, note } = await activeFlowState(session);
+  return {
+    message: `${guidance} Nothing was executed and no step was recorded.${note ? ` ${note}` : ""}`,
+    toolResult: void 0,
+    stepCount,
+    savedTo: session.filePath
+  };
+}
+var DIRECTIVE_COMMAND_HINTS = {
+  tap: { tool: "gesture-tap", rewritten: true },
+  launch: {
+    tool: "restart-app",
+    rewritten: true,
+    rewriteCondition: "when it carries only the bundle id (a call with an extra arg, e.g. an Android `activity`, is kept as a raw `tool: restart-app` step to convert during polish)"
+  },
+  run: {
+    tool: "flow-execute",
+    rewritten: true,
+    rewriteCondition: "when the target resolves as a sibling flow in this recording's folder \u2014 a `name` that does not is kept as a raw `tool: flow-execute` step, and so is every target in a REMOTE recording (`run:` composition is host-resolved, so the host cannot validate the client's siblings); a `flow_path` that is not a sibling is refused outright and records nothing"
+  },
+  type: { tool: "keyboard", rewritten: false },
+  await: { tool: AWAIT_UI_ELEMENT_TOOL_ID, rewritten: false },
+  assert: { tool: AWAIT_UI_ELEMENT_TOOL_ID, rewritten: false },
+  pinch: { tool: "gesture-pinch", rewritten: false }
+};
+var NESTED_RECORDER_TOOLS = {
+  "flow-add-echo": "`flow-add-echo` records a step itself, so it must be called DIRECTLY, not through flow-add-step \u2014 nesting it would write the echo AND a `tool: flow-add-echo` step that fails on every replay.",
+  "flow-add-step": "flow-add-step cannot record itself. Pass the MCP tool you want to execute as `command`.",
+  "flow-start-recording": "`flow-start-recording` truncates the flow it names. Recording it as a step would erase this flow at replay; call it directly when you want to start a recording.",
+  "flow-finish-recording": "`flow-finish-recording` ends the recording, so it cannot also be a step in it. Call it directly when the walkthrough is complete."
+};
+function isToolNotFound(err, command) {
+  return err instanceof ToolNotFoundError && err.toolId === command;
+}
+function directiveCommandHint(command) {
+  if (command === "echo") {
+    return `"echo" is a flow directive, not a tool. Call \`flow-add-echo\` DIRECTLY \u2014 not through flow-add-step, which would run it as a nested tool AND record a \`tool: flow-add-echo\` step that fails on every replay.`;
+  }
+  if (command === "wait") {
+    return `"wait" is a flow directive, not a tool, and there is no tool that records one \u2014 a fixed sleep is not a readiness signal. Record the thing you are actually waiting for with \`${AWAIT_UI_ELEMENT_TOOL_ID}\` instead.`;
+  }
+  if (command === "long-press") {
+    return `"long-press" is a flow directive, not a tool, and no tool records one \u2014 there is no gesture-long-press. Record the rest of the path, then add the \`long-press:\` step by hand during polish and prove it with the replay.`;
+  }
+  if (command === "scroll-to") {
+    return `"scroll-to" is a flow directive, not a tool, and no tool records one \u2014 it SEARCHES, scrolling until the target is visible, which no single recorded gesture reproduces. Record the movement with \`gesture-swipe\` (\`gesture-scroll\` on chromium) if the path needs it, then add the \`scroll-to:\` step by hand during polish and prove it with the replay.`;
+  }
+  if (command === "snapshot") {
+    return `"snapshot" is a flow directive, not a tool, and no tool records one \u2014 it compares the screen against a stored baseline, which \`screenshot-diff\` does not manage. Add the \`snapshot:\` step by hand during polish, then adopt its baseline with a run that sets updateBaselines, and review the PNG before committing it.`;
+  }
+  if (command === "when") {
+    return `"when" is a flow directive, not a tool, and no tool records one \u2014 it GUARDS the steps nested under it, so there is no action of its own to run. Record those steps, then wrap them in the \`when:\` block by hand during polish and prove both branches with the replay.`;
+  }
+  const hint = Object.hasOwn(DIRECTIVE_COMMAND_HINTS, command) ? DIRECTIVE_COMMAND_HINTS[command] : void 0;
+  if (!hint) return void 0;
+  return `"${command}" is a flow directive, not a tool. Record it by calling \`${hint.tool}\` through flow-add-step` + (hint.rewritten ? ` \u2014 the recorder rewrites it into the \`${command}:\` step ${hint.rewriteCondition ?? "for you"}. Where the call is recorded at all, a \`delayMs\` on it opts out of the rewrite: the step is then kept in its raw \`tool: ${hint.tool}\` form (a replay delay has no directive form), so leave \`delayMs\` off if you want the \`${command}:\` step.` : `. It is stored as a raw \`tool: ${hint.tool}\` step; converting it to \`${command}:\` is part of the polish pass.`);
+}
 var RUN_TARGET_COMMAND = "flow-execute";
 async function rewriteSiblingFlowPath(session, args) {
   const flowPath = args.flow_path;
@@ -146173,12 +146369,12 @@ function createFlowAddStepTool(registry2) {
       // Name the flow: recordings are concurrent, so several of these lines can
       // interleave in one log and "the recorded flow" would not say which.
       startedMsg: ({ params }) => `Adding ${params.command} step to flow ${params.name}`,
-      completedMsg: ({ params }) => `Added ${params.command} step to flow ${params.name}`,
+      completedMsg: ({ params, result }) => result.recorded === void 0 ? `Recorded no ${params.command} step in flow ${params.name}` : `Added ${params.command} step to flow ${params.name}`,
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to flow ${params.name}: ${failureSignal2.error_code}`
     },
     description: `Execute a tool call and record it as a step in the flow named by \`name\` + \`project_root\` (the recording must already be open \u2014 see flow-start-recording). Use when recording a flow and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it).
 A recorded \`await-ui-element\` that PASSED is re-probed against the tree the RUNNER resolves \`await:\`/\`assert:\` directives against, which is NOT the tree the live call read; a wait that came back \`{ success: false }\` is not probed at all, and its warning says so; when the condition does not hold there the step is still recorded and \`message\` carries a warning to read before converting \u2014 whether the conversion actually breaks depends on WHY the two disagree, since a screen that moved on between the live wait and the re-probe reads the same way. If that tree could not be read at all, the warning says so instead: the conversion is UNKNOWN, not known-bad. The probe judges the selector exactly as recorded, so write the conversion in the strict map spelling (\`{ visible: { text: Continue } }\`, copying the step's \`selector:\`) \u2014 the bare-string spelling (\`{ visible: Continue }\`) re-parses as a loose selector that resolves identifier-first and falls back to text, which is a different check. \`message\` also warns when the live wait itself came back \`{ success: false }\` \u2014 that tool reports a failed wait by returning rather than throwing, so the step is recorded either way. That warning names the cause, because only one of them judges the condition: a genuine miss will stop the run at replay, while a wait whose tree source was unreadable, or one that was cancelled, observed nothing and leaves the condition UNKNOWN.
-Returns { message, toolResult, stepCount, recorded, savedTo } on success \u2014 \`message\` is \`Step added to "<name>" flow\` plus any warning about what was recorded (read it; a warning never means the step was skipped). If it fails an error is returned and nothing is recorded.
+Returns { message, toolResult, stepCount, recorded, savedTo } on success \u2014 \`message\` is \`Step added to "<name>" flow\` plus any warning about what was recorded (read it; a warning never means the step was skipped). If it fails an error is returned and nothing is recorded. Two calls SUCCEED while recording nothing, and omit \`recorded\` to say so: a \`command\` naming a recording tool, and one naming a flow-file directive rather than a tool. Both answer with what to do instead \u2014 usually the call to make (the tool that records that directive, or the recording tool called directly), but \`wait\`, \`long-press\`, \`scroll-to\`, \`snapshot\` and \`when\` have no recording tool, so those name no call and say what to record or add by hand in its place. Either way nothing runs at the device and the take is left untouched \u2014 read \`recorded\`, not the status, to know whether a step was appended.
 If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-recording\` rather than during the recording: against a remote client the in-memory copy is authoritative and every write serializes it over your edit, and in host mode a mid-recording edit renumbers the steps, which costs the finish the cross-tree verdicts anchored to them.`,
     // The recorded tool RUNS here, so this call lasts as long as whatever it
     // wraps, and the three it most often wraps declare this too. Without it the
@@ -146190,7 +146386,19 @@ If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-
     services: () => ({}),
     async execute(_services, params, ctx) {
       const session = await requireRecordingSession(params.project_root, params.name);
-      const args = params.args ? JSON.parse(params.args) : {};
+      const nested = Object.hasOwn(NESTED_RECORDER_TOOLS, params.command) ? NESTED_RECORDER_TOOLS[params.command] : void 0;
+      if (nested) return recordNothing(session, nested);
+      let args;
+      try {
+        args = params.args ? JSON.parse(params.args) : {};
+      } catch (err) {
+        if (registry2.getTool(params.command) === void 0) {
+          const hint = directiveCommandHint(params.command);
+          if (hint) return recordNothing(session, hint);
+        }
+        throw err;
+      }
+      const authoredArgs = { ...args };
       if (params.command === RUN_TARGET_COMMAND) await rewriteSiblingFlowPath(session, args);
       const isTap = params.command === "gesture-tap" && params.delayMs === void 0 && typeof args.udid === "string" && typeof args.x === "number" && typeof args.y === "number";
       let captured;
@@ -146200,7 +146408,27 @@ If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-
           y: args.y
         });
       }
-      const toolResult = await invokeSubTool(registry2, ctx, params.command, args);
+      let toolResult;
+      try {
+        toolResult = await invokeSubTool(registry2, ctx, params.command, args);
+      } catch (err) {
+        const hint = isToolNotFound(err, params.command) ? directiveCommandHint(params.command) : void 0;
+        if (hint) return recordNothing(session, hint);
+        const reframed = describeNestedParamError(
+          registry2,
+          err,
+          params.command,
+          args,
+          authoredArgs
+        );
+        if (reframed === void 0) throw err;
+        throw new FailureError(reframed, {
+          error_code: FAILURE_CODES.TOOL_INPUT_INVALID,
+          failure_stage: "flow_add_step_nested_params",
+          failure_area: "tool_server",
+          error_kind: "validation"
+        });
+      }
       let waitWarning;
       if (params.command === AWAIT_UI_ELEMENT_TOOL_ID) {
         if (isUnmetUiWaitResult(params.command, toolResult)) {
@@ -148742,8 +148970,10 @@ var zodSchema65 = external_exports.object({
   if (params.name === void 0 === (params.flow_path === void 0)) {
     ctx.addIssue({
       code: external_exports.ZodIssueCode.custom,
-      message: "Pass exactly one flow source: name or flow_path.",
-      path: ["flow_path"]
+      message: params.name !== void 0 ? "Pass exactly one flow source: name or flow_path." : "Pass exactly one flow source: name or flow_path. flow-execute needs the flow's name in `name` \u2014 it resolves <project_root>/.argent/flows/<name>.yaml.",
+      // The ROOT, not `flow_path`: the rule spans both source fields, and a
+      // path would prefix the message with "`flow_path`:".
+      path: []
     });
   }
 });
@@ -149833,7 +150063,8 @@ async function execLeafStep(state3, step, index, scope) {
         }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {
-        return { ...base, status: "error", tool: step.name, reason: errMsg3(err) };
+        const reframed = describeNestedParamError(registry2, err, step.name, args, step.args ?? {});
+        return { ...base, status: "error", tool: step.name, reason: reframed ?? errMsg3(err) };
       }
     }
     default:
@@ -149981,8 +150212,10 @@ var zodSchema66 = external_exports.object({
   if (params.name === void 0 === (params.flow_path === void 0)) {
     ctx.addIssue({
       code: external_exports.ZodIssueCode.custom,
-      message: "Pass exactly one flow source: name or flow_path.",
-      path: ["flow_path"]
+      message: params.name !== void 0 ? "Pass exactly one flow source: name or flow_path." : "Pass exactly one flow source: name or flow_path. flow-read-prerequisite needs the flow's name in `name` \u2014 it resolves <project_root>/.argent/flows/<name>.yaml.",
+      // The ROOT, matching flow-execute: the rule spans both source fields,
+      // so it must not be anchored on one of them.
+      path: []
     });
   }
 });
@@ -150014,7 +150247,7 @@ Use when you need to check what app/simulator state is required before executing
 source (name or flow_path) you will pass to flow-execute, so the prerequisite you read is the contract of
 the flow that will actually run.
 Fails if the flow file does not exist.
-Address the flow exactly as you will address it in flow-execute: name or flow_path, one and only one; supplying both or neither is rejected.`,
+Address the flow exactly as you will address it in flow-execute: name or flow_path, one and only one; supplying both or neither is rejected. The name goes in \`name\`, which resolves <project_root>/.argent/flows/<name>.yaml.`,
   zodSchema: zodSchema66,
   fileInputs: fileInputs4,
   services: () => ({}),

package/package.json

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