@swmansion/argent 0.32.1-next.10 → 0.32.1-next.11

package/dist/cli-cmds.mjs

@@ -8917,7 +8917,7 @@ var require_src = __commonJS({
 
 // ../argent-cli/src/run.ts
 import * as fs12 from "node:fs";
-import * as path17 from "node:path";
+import * as path18 from "node:path";
 
 // ../argent-tools-client/src/launcher.ts
 import * as net from "node:net";
@@ -10452,6 +10452,8 @@ var FAILURE_CODES = {
   CLI_RUN_ARGS_JSON_INVALID: "CLI_RUN_ARGS_JSON_INVALID",
   CLI_RUN_INPUT_VALIDATION_FAILED: "CLI_RUN_INPUT_VALIDATION_FAILED",
   CLI_RUN_TOOL_CALL_FAILED: "CLI_RUN_TOOL_CALL_FAILED",
+  // The result carried the tool-server's `failure` field.
+  CLI_RUN_TOOL_RESULT_FAILED: "CLI_RUN_TOOL_RESULT_FAILED",
   CLI_RUN_SAVE_IMAGE_FAILED: "CLI_RUN_SAVE_IMAGE_FAILED",
   TOOL_CAPABILITY_UNSUPPORTED_OPERATION: "TOOL_CAPABILITY_UNSUPPORTED_OPERATION",
   TOOL_PLATFORM_NOT_IMPLEMENTED: "TOOL_PLATFORM_NOT_IMPLEMENTED",
@@ -31651,7 +31653,8 @@ async function consumeToolStream(name, body, onProgress, signal) {
       final = {
         data: msg.data,
         note: msg.note,
-        ...msg.profiling === true ? { profiling: true } : {}
+        ...msg.profiling === true ? { profiling: true } : {},
+        ...typeof msg.failure === "string" ? { failure: msg.failure } : {}
       };
     } else if (msg.event === "error") {
       throw new ToolInvocationError(msg.error ?? "tool invocation failed", {
@@ -31703,7 +31706,8 @@ async function consumeToolStream(name, body, onProgress, signal) {
   return {
     data: final.data,
     note: final.note,
-    ...final.profiling ? { profiling: true } : {}
+    ...final.profiling ? { profiling: true } : {},
+    ...final.failure !== void 0 ? { failure: final.failure } : {}
   };
 }
 function errorBodyMessage(body) {
@@ -31868,6 +31872,7 @@ function createToolsClient(options = {}) {
     }
     const shadowWarning = await e2eShadowWarningFor(name, args);
     const baselineDirs = [];
+    let unwrittenBaselines2 = [];
     if (meta3?.fileInputs?.length) {
       if (remote) assertRequiredPresent(meta3, finalArgs);
       finalArgs = await prepareFileInputs(meta3.fileInputs, finalArgs ?? {}, {
@@ -31881,8 +31886,9 @@ function createToolsClient(options = {}) {
         signal: opts?.signal
       });
     }
-    const settle2 = async (data) => {
-      const applied = await applyClientFileDirectives(data, { allowedDirs: baselineDirs });
+    const settle2 = async (data2) => {
+      const applied = await applyClientFileDirectives(data2, { allowedDirs: baselineDirs });
+      unwrittenBaselines2 = applied.failed.map((f) => f.path);
       for (const { path: file2, error: error63 } of applied.failed) {
         diagnose(`The baseline ${file2} was not written on this client: ${error63}`);
       }
@@ -31899,6 +31905,7 @@ function createToolsClient(options = {}) {
       }
       return { ...result, warning: shadowWarning };
     };
+    const unwrittenFailure = () => unwrittenBaselines2.length > 0 ? `Baselines not written on this client: ${unwrittenBaselines2.join(", ")}` : void 0;
     const stream = opts?.onProgress !== void 0 || carriesMembers(finalArgs);
     const sentOnce = carriesUpload(finalArgs);
     const forwarded = remote ? await forwardedSecrets(finalArgs) : void 0;
@@ -31962,11 +31969,14 @@ function createToolsClient(options = {}) {
         }),
         opts?.signal
       );
+      const data2 = await settle2(streamed.data);
+      const failure3 = streamed.failure ?? unwrittenFailure();
       return {
-        data: await settle2(streamed.data),
+        data: data2,
         note: streamed.note,
         outputHint: meta3?.outputHint,
-        ...streamed.profiling ? { profiling: true } : {}
+        ...streamed.profiling ? { profiling: true } : {},
+        ...failure3 !== void 0 ? { failure: failure3 } : {}
       };
     }
     let json2;
@@ -32002,11 +32012,14 @@ function createToolsClient(options = {}) {
       });
     }
     opts?.signal?.throwIfAborted();
+    const data = await settle2(json2.data);
+    const failure2 = (typeof json2.failure === "string" ? json2.failure : void 0) ?? unwrittenFailure();
     return {
-      data: await settle2(json2.data),
+      data,
       note: json2.note,
       outputHint: meta3?.outputHint,
-      ...json2.profiling === true ? { profiling: true } : {}
+      ...json2.profiling === true ? { profiling: true } : {},
+      ...failure2 !== void 0 ? { failure: failure2 } : {}
     };
   }
   return { fetchTools, fetchTool, callTool, baseUrl };
@@ -36760,391 +36773,106 @@ function isValidationIssue(value) {
   return typeof issue2.code === "string" && Array.isArray(issue2.path) && typeof issue2.message === "string";
 }
 
-// ../argent-cli/src/run.ts
-function splitOptions(argv) {
-  let json2 = false;
-  let outPath = null;
-  const rest = [];
+// ../argent-cli/src/e2e.ts
+import * as fsp from "node:fs/promises";
+import { constants as fsConstants2 } from "node:fs";
+import { createHash as createHash5 } from "node:crypto";
+import * as path17 from "node:path";
+
+// ../argent-cli/src/command-args.ts
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+function listChoices(choices) {
+  const quoted = choices.map((c2) => `"${c2}"`);
+  if (quoted.length <= 1) return quoted.join("");
+  return `${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}`;
+}
+function resolveName(tok, specs) {
+  if (tok.startsWith("--")) return tok.slice(2) in specs ? tok.slice(2) : null;
+  const short = tok.slice(1);
+  for (const [name, spec] of Object.entries(specs)) {
+    if (spec.alias === short) return name;
+  }
+  return null;
+}
+function parseCommandArgs(argv, specs) {
+  const positionals = [];
+  const options = {};
   for (let i2 = 0; i2 < argv.length; i2++) {
     const tok = argv[i2];
-    if (tok === "--json") {
-      json2 = true;
-      continue;
+    if (tok === "--") {
+      positionals.push(...argv.slice(i2 + 1));
+      break;
     }
-    if (tok === "--out") {
-      const v = argv[i2 + 1];
-      if (!v) throw new FlagParseException("--out requires a path");
-      outPath = v;
-      i2 += 1;
+    if (!tok.startsWith("-") || tok === "-") {
+      positionals.push(tok);
       continue;
     }
-    if (tok.startsWith("--out=")) {
-      outPath = tok.slice("--out=".length);
+    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
+    const flag = eq === -1 ? tok : tok.slice(0, eq);
+    const inlineValue = eq === -1 ? void 0 : tok.slice(eq + 1);
+    const name = resolveName(flag, specs);
+    if (name === null) throw new UsageError(`Unknown flag: ${tok}`);
+    const spec = specs[name];
+    const display = `--${name}`;
+    if (spec.kind === "boolean") {
+      if (inlineValue !== void 0) throw new UsageError(`${display} does not take a value`);
+      const next = argv[i2 + 1]?.trim().toLowerCase();
+      if (next === "true" || next === "false") {
+        throw new UsageError(
+          `${display} does not take a value \u2014 it is a switch; omit it to leave the option off`
+        );
+      }
+      options[name] = true;
       continue;
     }
-    rest.push(tok);
-  }
-  return { json: json2, outPath, argvForFlags: rest };
-}
-async function readStdin() {
-  return new Promise((resolve13, reject) => {
-    let data = "";
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (chunk) => {
-      data += chunk;
-    });
-    process.stdin.on("end", () => resolve13(data));
-    process.stdin.on("error", reject);
-  });
-}
-function printToolHelp(meta3) {
-  const description = meta3.description?.trim() ?? "";
-  const schema = meta3.inputSchema;
-  const hasOwnArgsField = schema?.properties?.args !== void 0;
-  console.log(`argent run ${meta3.name} [flags]`);
-  if (description) console.log(`
-${description}
-`);
-  console.log("Flags:");
-  console.log(formatSchemaUsage(schema));
-  console.log("\nGlobal flags:");
-  if (!hasOwnArgsField) {
-    console.log("  --args <json>          Pass the entire payload as JSON (overrides flags)");
-    console.log("  --args -               Read the entire payload as JSON from stdin");
-  }
-  console.log("  --<field>-json <json>  Pass a single field as JSON (objects/nested arrays)");
-  console.log("  --json                 Print the raw JSON result");
-  console.log("  --out <path>           For image results, save to <path> instead of fetching URL");
-  console.log("  --help, -h             Show this help");
-}
-async function fetchImageToFile(result, outPath) {
-  const url2 = result.url;
-  if (!url2) {
-    throw new Error("Tool result did not include a `url`; cannot save image");
-  }
-  const res = await fetch(url2);
-  if (!res.ok) throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
-  const buf = Buffer.from(await res.arrayBuffer());
-  fs12.mkdirSync(path17.dirname(path17.resolve(outPath)), { recursive: true });
-  fs12.writeFileSync(outPath, buf);
-}
-function renderResult(result, outputHint, images, json2) {
-  if (json2) return JSON.stringify(result, null, 2);
-  if (outputHint === "image") {
-    if (images.length > 0) return `Saved screenshot: ${images[0].localPath}`;
-    if (result && typeof result === "object" && "path" in result && typeof result.path === "string") {
-      return `Saved screenshot: ${result.path}`;
+    let value = inlineValue;
+    if (value === void 0) {
+      const next = argv[i2 + 1];
+      if (next !== void 0 && (!next.startsWith("-") || next === "-")) {
+        value = next;
+        i2 += 1;
+      }
+    } else if (value === "") {
+      value = void 0;
+    }
+    if (value === void 0) throw new UsageError(`${display} requires a value`);
+    if (spec.choices && !spec.choices.includes(value)) {
+      throw new UsageError(`${display} must be ${listChoices(spec.choices)}, got "${value}"`);
     }
+    options[name] = value;
   }
-  if (typeof result === "string") return result;
-  return JSON.stringify(result, null, 2);
+  return { positionals, options };
 }
-var SAFE_TOOL_RE = /^[a-z][a-z0-9_-]{0,63}$/;
-function safeToolName(toolName) {
-  return toolName && SAFE_TOOL_RE.test(toolName) ? toolName : "unknown";
+
+// ../argent-cli/src/e2e.ts
+var STATUS_GLYPH = {
+  pass: "\u2713",
+  fail: "\u2717",
+  error: "\u2717",
+  skip: "\xB7"
+};
+var MAX_RENDER_DEPTH = 20;
+function stepIndent(depth) {
+  if (typeof depth !== "number" || !Number.isInteger(depth) || depth <= 0) return "";
+  return "  ".repeat(Math.min(depth, MAX_RENDER_DEPTH));
 }
-async function trackRunFailure(toolName, startedAt, signal) {
-  const tool = toolName ? canonicalToolId(toolName) : toolName;
-  track("cli:run_fail", {
-    tool: safeToolName(tool),
-    ...tool !== toolName ? { alias_used: true } : {},
-    duration_ms: performance.now() - startedAt,
-    ...signal
-  });
-  await shutdown();
+function durationSuffix(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) return "";
+  const tenths = Math.round(ms / 100);
+  if (tenths < 600) return ` (${(tenths / 10).toFixed(1)}s)`;
+  const seconds = Math.round(ms / 1e3);
+  return ` (${Math.floor(seconds / 60)}m ${seconds % 60}s)`;
 }
-async function run(argv, options) {
-  init("cli");
-  const startedAt = performance.now();
-  const { fetchTool, callTool, baseUrl } = createToolsClient({ paths: options.paths });
-  const [toolName, ...rest] = argv;
-  if (!toolName || toolName === "--help" || toolName === "-h") {
-    console.log(`Usage: argent run <tool> [flags]
+function printHelp(toStderr = false) {
+  const print = toStderr ? console.error : console.log;
+  print(`Usage: argent e2e <subcommand> [options]
 
-Invoke a tool exposed by the argent tool-server. Run \`argent tools\` to list
-available tools, or \`argent tools describe <name>\` to see one tool's flags.
-
-Examples:
-  argent run list-devices
-  argent run gesture-tap --udid <UDID> --x 0.5 --y 0.5
-  argent run screenshot --udid <UDID> --out ./screen.png
-  argent run run-sequence --udid <UDID> --steps-json '[{"tool":"button","args":{"button":"home"}}]'
-  argent run gesture-tap --args '{"udid":"<UDID>","x":0.5,"y":0.5}'
-`);
-    return;
-  }
-  let cliOptions;
-  try {
-    cliOptions = splitOptions(rest);
-  } catch (err) {
-    if (err instanceof FlagParseException) {
-      console.error(`Error: ${err.message}
-`);
-      console.error(`Run \`argent run ${toolName} --help\` to see this tool's flags.`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
-        failure_stage: "cli_run_split_options",
-        failure_area: "cli",
-        error_kind: "validation"
-      });
-      process.exit(2);
-    }
-    throw err;
-  }
-  const { json: json2, outPath, argvForFlags } = cliOptions;
-  const meta3 = await fetchTool(toolName);
-  if (!meta3) {
-    console.error(`Tool "${toolName}" not found. Run \`argent tools\` to list available tools.`);
-    await trackRunFailure(toolName, startedAt, {
-      error_code: FAILURE_CODES.CLI_RUN_TOOL_NOT_FOUND,
-      failure_stage: "cli_run_fetch_tool",
-      failure_area: "cli",
-      error_kind: "not_found"
-    });
-    process.exit(1);
-  }
-  const schema = meta3.inputSchema;
-  const failInvocation = async (summary, report, failure2) => {
-    if (json2) {
-      console.error(
-        JSON.stringify(
-          {
-            error: summary,
-            missing: report ? missingFlagNames(report, schema) : [],
-            issues: report?.rawIssues ?? []
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`Error: ${summary}
-`);
-      printToolHelp(meta3);
-    }
-    await trackRunFailure(toolName, startedAt, {
-      ...failure2,
-      failure_area: "cli",
-      error_kind: "validation"
-    });
-    process.exit(2);
-  };
-  const failValidation = (report, stage) => failInvocation(formatValidationError(report, schema), report, {
-    error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
-    failure_stage: stage
-  });
-  let parsed;
-  try {
-    parsed = parseFlags(argvForFlags, schema);
-  } catch (err) {
-    if (err instanceof FlagParseException) {
-      await failInvocation(err.message, null, {
-        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
-        failure_stage: "cli_run_parse_flags"
-      });
-    }
-    throw err;
-  }
-  if (parsed.helpRequested) {
-    printToolHelp(meta3);
-    return;
-  }
-  if (parsed.positional.length > 0) {
-    console.error(
-      `Note: ignoring unused argument(s): ${parsed.positional.join(", ")}. Pass values as --flag <value> or --flag=<value>.`
-    );
-  }
-  let payload = {};
-  if (parsed.rawArgs !== null) {
-    let rawJson = parsed.rawArgs;
-    if (rawJson === "-") {
-      rawJson = await readStdin();
-    }
-    try {
-      const parsedRaw = JSON.parse(rawJson);
-      if (parsedRaw === null || typeof parsedRaw !== "object" || Array.isArray(parsedRaw)) {
-        console.error("--args must be a JSON object");
-        await trackRunFailure(toolName, startedAt, {
-          error_code: FAILURE_CODES.CLI_RUN_ARGS_NOT_OBJECT,
-          failure_stage: "cli_run_parse_raw_args",
-          failure_area: "cli",
-          error_kind: "validation"
-        });
-        process.exit(2);
-      }
-      payload = parsedRaw;
-    } catch (err) {
-      console.error(`--args is not valid JSON: ${err instanceof Error ? err.message : err}`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_ARGS_JSON_INVALID,
-        failure_stage: "cli_run_parse_raw_args",
-        failure_area: "cli",
-        error_kind: "validation"
-      });
-      process.exit(2);
-    }
-  }
-  for (const [k, v] of Object.entries(parsed.args)) {
-    payload[k] = v;
-  }
-  const missing = findMissingRequired(payload, schema);
-  if (missing.length > 0) {
-    await failValidation({ missing, invalid: [], rawIssues: null }, "cli_run_required_flags");
-  }
-  let result;
-  let note;
-  let images = [];
-  try {
-    const resp = await callTool(toolName, payload);
-    const { url: url2, token } = await baseUrl();
-    const materialized = await materializeArtifacts(resp.data, {
-      toolsUrl: url2,
-      authToken: token,
-      deviceId: getDeviceIdFromArgs(payload)
-    });
-    result = materialized.result;
-    images = materialized.images;
-    note = resp.note;
-  } catch (err) {
-    const report = describeServerValidationFailure(err, payload, schema);
-    if (report) {
-      await failValidation(report, "cli_run_server_validation");
-    }
-    console.error(err instanceof Error ? err.message : String(err));
-    await trackRunFailure(toolName, startedAt, {
-      error_code: FAILURE_CODES.CLI_RUN_TOOL_CALL_FAILED,
-      failure_stage: "cli_run_call_tool",
-      failure_area: "cli",
-      error_kind: "unknown"
-    });
-    process.exit(1);
-  }
-  if (outPath && meta3.outputHint === "image") {
-    try {
-      if (images.length > 0) {
-        fs12.mkdirSync(path17.dirname(path17.resolve(outPath)), { recursive: true });
-        fs12.writeFileSync(outPath, images[0].data);
-      } else if (result && typeof result === "object") {
-        await fetchImageToFile(result, outPath);
-      }
-    } catch (err) {
-      console.error(`Failed to save image: ${err instanceof Error ? err.message : err}`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_SAVE_IMAGE_FAILED,
-        failure_stage: "cli_run_save_image",
-        failure_area: "cli",
-        error_kind: "unknown"
-      });
-      process.exit(1);
-    }
-  }
-  if (note) console.error(note);
-  console.log(renderResult(result, meta3.outputHint, images, json2));
-  if (outPath && meta3.outputHint === "image" && !json2) {
-    console.log(`Wrote: ${outPath}`);
-  }
-}
-
-// ../argent-cli/src/e2e.ts
-import * as fsp from "node:fs/promises";
-import { constants as fsConstants2 } from "node:fs";
-import { createHash as createHash5 } from "node:crypto";
-import * as path18 from "node:path";
-
-// ../argent-cli/src/command-args.ts
-var UsageError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UsageError";
-  }
-};
-function listChoices(choices) {
-  const quoted = choices.map((c2) => `"${c2}"`);
-  if (quoted.length <= 1) return quoted.join("");
-  return `${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}`;
-}
-function resolveName(tok, specs) {
-  if (tok.startsWith("--")) return tok.slice(2) in specs ? tok.slice(2) : null;
-  const short = tok.slice(1);
-  for (const [name, spec] of Object.entries(specs)) {
-    if (spec.alias === short) return name;
-  }
-  return null;
-}
-function parseCommandArgs(argv, specs) {
-  const positionals = [];
-  const options = {};
-  for (let i2 = 0; i2 < argv.length; i2++) {
-    const tok = argv[i2];
-    if (tok === "--") {
-      positionals.push(...argv.slice(i2 + 1));
-      break;
-    }
-    if (!tok.startsWith("-") || tok === "-") {
-      positionals.push(tok);
-      continue;
-    }
-    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
-    const flag = eq === -1 ? tok : tok.slice(0, eq);
-    const inlineValue = eq === -1 ? void 0 : tok.slice(eq + 1);
-    const name = resolveName(flag, specs);
-    if (name === null) throw new UsageError(`Unknown flag: ${tok}`);
-    const spec = specs[name];
-    const display = `--${name}`;
-    if (spec.kind === "boolean") {
-      if (inlineValue !== void 0) throw new UsageError(`${display} does not take a value`);
-      const next = argv[i2 + 1]?.trim().toLowerCase();
-      if (next === "true" || next === "false") {
-        throw new UsageError(
-          `${display} does not take a value \u2014 it is a switch; omit it to leave the option off`
-        );
-      }
-      options[name] = true;
-      continue;
-    }
-    let value = inlineValue;
-    if (value === void 0) {
-      const next = argv[i2 + 1];
-      if (next !== void 0 && (!next.startsWith("-") || next === "-")) {
-        value = next;
-        i2 += 1;
-      }
-    } else if (value === "") {
-      value = void 0;
-    }
-    if (value === void 0) throw new UsageError(`${display} requires a value`);
-    if (spec.choices && !spec.choices.includes(value)) {
-      throw new UsageError(`${display} must be ${listChoices(spec.choices)}, got "${value}"`);
-    }
-    options[name] = value;
-  }
-  return { positionals, options };
-}
-
-// ../argent-cli/src/e2e.ts
-var STATUS_GLYPH = {
-  pass: "\u2713",
-  fail: "\u2717",
-  error: "\u2717",
-  skip: "\xB7"
-};
-var MAX_RENDER_DEPTH = 20;
-function stepIndent(depth) {
-  if (typeof depth !== "number" || !Number.isInteger(depth) || depth <= 0) return "";
-  return "  ".repeat(Math.min(depth, MAX_RENDER_DEPTH));
-}
-function durationSuffix(ms) {
-  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) return "";
-  const tenths = Math.round(ms / 100);
-  if (tenths < 600) return ` (${(tenths / 10).toFixed(1)}s)`;
-  const seconds = Math.round(ms / 1e3);
-  return ` (${Math.floor(seconds / 60)}m ${seconds % 60}s)`;
-}
-function printHelp(toStderr = false) {
-  const print = toStderr ? console.error : console.log;
-  print(`Usage: argent e2e <subcommand> [options]
-
-Run a YAML e2e test without an LLM in the loop. \`run\` takes any of these forms:
+Run a YAML e2e test without an LLM in the loop. \`run\` takes any of these forms:
 
   a name   An e2e test saved under .argent/e2e or .argent/flows, resolved
            from the current directory. "checkout" runs
@@ -37405,14 +37133,14 @@ function shellQuoteArg(arg) {
   return `'${arg.replaceAll("'", "'\\''")}'`;
 }
 function rerunCommand(flowPath, rel, projectRoot, args) {
-  const pathArg = (p) => shellQuoteArg(p.startsWith("-") ? `.${path18.sep}${p}` : p);
-  const fromCwd = path18.relative(projectRoot, flowPath);
-  const shown = path18.isAbsolute(fromCwd) || fromCwd.split(/[\\/]+/).includes("..") ? flowPath : fromCwd;
+  const pathArg = (p) => shellQuoteArg(p.startsWith("-") ? `.${path17.sep}${p}` : p);
+  const fromCwd = path17.relative(projectRoot, flowPath);
+  const shown = path17.isAbsolute(fromCwd) || fromCwd.split(/[\\/]+/).includes("..") ? flowPath : fromCwd;
   const parts = ["argent e2e run", pathArg(shown)];
   if (args.device) parts.push("--device", shellQuoteArg(args.device));
   if (args.platform) parts.push("--platform", shellQuoteArg(args.platform));
   if (args.updateBaselines) parts.push("--update-baselines");
-  if (args.output) parts.push("--output", pathArg(path18.join(args.output, path18.dirname(rel))));
+  if (args.output) parts.push("--output", pathArg(path17.join(args.output, path17.dirname(rel))));
   return parts.join(" ");
 }
 var EXPORT_SOURCE_MARKER = ".argent-e2e-source";
@@ -37420,8 +37148,8 @@ var LEGACY_EXPORT_SOURCE_MARKER = ".argent-flow-source";
 var MARKER_READ_RETRIES = 4;
 var MARKER_READ_DELAY_MS = 5;
 async function readExportMarker(dir) {
-  const owner = await readMarkerFile(path18.join(dir, EXPORT_SOURCE_MARKER));
-  return owner !== void 0 ? owner : await readMarkerFile(path18.join(dir, LEGACY_EXPORT_SOURCE_MARKER));
+  const owner = await readMarkerFile(path17.join(dir, EXPORT_SOURCE_MARKER));
+  return owner !== void 0 ? owner : await readMarkerFile(path17.join(dir, LEGACY_EXPORT_SOURCE_MARKER));
 }
 async function readMarkerFile(marker) {
   for (let attempt = 0; ; attempt++) {
@@ -37458,7 +37186,7 @@ function occupiedBy(owner) {
 async function takeExportDir(dir, flowPath) {
   try {
     await fsp.mkdir(dir, { recursive: true });
-    await fsp.writeFile(path18.join(dir, EXPORT_SOURCE_MARKER), `${flowPath}
+    await fsp.writeFile(path17.join(dir, EXPORT_SOURCE_MARKER), `${flowPath}
 `, { flag: "wx" });
     return null;
   } catch (err) {
@@ -37477,7 +37205,7 @@ async function claimExportDirName(outputDir, flowPath, stem) {
   }
   const avoided = [];
   for (const name of candidates) {
-    const dir = path18.join(outputDir, name);
+    const dir = path17.join(outputDir, name);
     const claim2 = await classifyExportDir(dir, flowPath);
     const reason = claim2.state === "foreign" ? occupiedBy(claim2.owner) : await takeExportDir(dir, flowPath);
     if (reason !== null) {
@@ -37497,7 +37225,7 @@ async function claimExportDirName(outputDir, flowPath, stem) {
   return null;
 }
 async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
-  const stem = path18.basename(flowPath, ".yaml");
+  const stem = path17.basename(flowPath, ".yaml");
   if (!SAFE_ARTIFACT_NAME.test(stem)) {
     console.error(
       `warning: skipping artifact export for unsafe e2e test filename ${JSON.stringify(stem)}`
@@ -37530,11 +37258,11 @@ async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
       if (dir === null) {
         const dirName = await claimExportDirName(outputDir, flowPath, stem);
         if (dirName === null) return;
-        dir = path18.join(outputDir, dirName);
+        dir = path17.join(outputDir, dirName);
       }
-      const dest = path18.join(dir, fileName(role));
-      const rel = path18.relative(outputDir, dest);
-      if (rel.startsWith("..") || path18.isAbsolute(rel)) continue;
+      const dest = path17.join(dir, fileName(role));
+      const rel = path17.relative(outputDir, dest);
+      if (rel.startsWith("..") || path17.isAbsolute(rel)) continue;
       try {
         await fsp.copyFile(value, dest);
         s.artifacts[role] = dest;
@@ -37549,7 +37277,7 @@ async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
 function keyFromBaselinePath(artifacts) {
   const baseline = artifacts.baseline;
   if (typeof baseline !== "string") return null;
-  return path18.basename(baseline).replace(/\.png$/, "");
+  return path17.basename(baseline).replace(/\.png$/, "");
 }
 function resolveArtifactDisplayPaths(report) {
   for (const s of report.steps) {
@@ -37606,17 +37334,17 @@ async function collectRunnableFlowPaths(dir, relDir = "") {
   const found = [];
   const entries = await fsp.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const rel = relDir ? path18.join(relDir, entry.name) : entry.name;
+    const rel = relDir ? path17.join(relDir, entry.name) : entry.name;
     if (entry.isDirectory()) {
       if (entry.name === "__baselines__") continue;
       found.push(
-        ...await collectRunnableFlowPaths(path18.join(dir, entry.name), rel).catch(() => [])
+        ...await collectRunnableFlowPaths(path17.join(dir, entry.name), rel).catch(() => [])
       );
       continue;
     }
     if (!entry.name.endsWith(".yaml")) continue;
-    if (!SAFE_FLOW_NAME.test(path18.basename(entry.name, ".yaml"))) continue;
-    if (await isRunnableFlowFile(path18.join(dir, entry.name))) found.push(rel);
+    if (!SAFE_FLOW_NAME.test(path17.basename(entry.name, ".yaml"))) continue;
+    if (await isRunnableFlowFile(path17.join(dir, entry.name))) found.push(rel);
   }
   return found;
 }
@@ -37624,26 +37352,26 @@ async function resolveFlowRef(ref, projectRoot) {
   if (!SAFE_FLOW_NAME.test(ref)) return { suppliedPath: ref, fromName: false };
   const picked = await resolveE2eFile(projectRoot, ref);
   return {
-    suppliedPath: path18.relative(projectRoot, picked.path),
+    suppliedPath: path17.relative(projectRoot, picked.path),
     fromName: true,
-    ...picked.shadowed === void 0 ? {} : { shadowed: path18.relative(projectRoot, picked.shadowed) }
+    ...picked.shadowed === void 0 ? {} : { shadowed: path17.relative(projectRoot, picked.shadowed) }
   };
 }
 async function savedFlowHint(projectRoot, missingPath) {
-  const dirs = E2E_DIRS.map((rel) => ({ rel, abs: path18.resolve(projectRoot, rel) }));
+  const dirs = E2E_DIRS.map((rel) => ({ rel, abs: path17.resolve(projectRoot, rel) }));
   for (const { abs } of dirs) {
-    const within = path18.relative(abs, missingPath);
-    if (!within.startsWith("..") && !path18.isAbsolute(within)) return "";
+    const within = path17.relative(abs, missingPath);
+    if (!within.startsWith("..") && !path17.isAbsolute(within)) return "";
   }
-  const wanted = `${path18.basename(missingPath, ".yaml")}.yaml`;
+  const wanted = `${path17.basename(missingPath, ".yaml")}.yaml`;
   for (const { rel, abs } of dirs) {
     const entries = await fsp.readdir(abs).catch(() => null);
     if (entries === null) continue;
     const actual = entries.includes(wanted) ? wanted : entries.find((name2) => name2.toLowerCase() === wanted.toLowerCase());
     if (actual === void 0) continue;
-    const name = path18.basename(actual, ".yaml");
+    const name = path17.basename(actual, ".yaml");
     if (!SAFE_FLOW_NAME.test(name)) return "";
-    if (!await isRunnableFlowFile(path18.join(abs, actual))) return "";
+    if (!await isRunnableFlowFile(path17.join(abs, actual))) return "";
     return `
 An e2e test named "${name}" is saved under ${rel} \u2014 did you mean: argent e2e run ${name}`;
   }
@@ -37653,17 +37381,17 @@ async function collectFlowFiles(dir, recursive2) {
   const found = [];
   const walk = async (current, rel) => {
     for (const entry of await fsp.readdir(current, { withFileTypes: true })) {
-      const entryRel = rel ? path18.join(rel, entry.name) : entry.name;
+      const entryRel = rel ? path17.join(rel, entry.name) : entry.name;
       if (entry.isDirectory()) {
         if (recursive2 && !entry.name.startsWith(".") && entry.name !== "node_modules") {
-          await walk(path18.join(current, entry.name), entryRel).catch(() => {
+          await walk(path17.join(current, entry.name), entryRel).catch(() => {
           });
         }
         continue;
       }
       if (!entry.name.endsWith(".yaml")) continue;
-      if (!SAFE_FLOW_NAME.test(path18.basename(entry.name, ".yaml"))) continue;
-      if (await isRunnableFlowFile(path18.join(current, entry.name))) found.push(entryRel);
+      if (!SAFE_FLOW_NAME.test(path17.basename(entry.name, ".yaml"))) continue;
+      if (await isRunnableFlowFile(path17.join(current, entry.name))) found.push(entryRel);
     }
   };
   await walk(dir, "");
@@ -37810,7 +37538,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     );
   }
   const { callTool, baseUrl } = runToolsClient(args, options);
-  const outputBase = args.output ? path18.resolve(args.output) : void 0;
+  const outputBase = args.output ? path17.resolve(args.output) : void 0;
   const results = [];
   const failures = [];
   const batchStartedAt = Date.now();
@@ -37823,7 +37551,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
       if (!args.json) console.log(`  ${STATUS_GLYPH.skip} not run (batch stopped)`);
       continue;
     }
-    const flowPath = path18.join(dir, rel);
+    const flowPath = path17.join(dir, rel);
     const rerun = rerunCommand(flowPath, rel, projectRoot, args);
     let report;
     try {
@@ -37865,7 +37593,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     printWarnings(nestedStepWarnings(report.steps), args.json);
     await exportAndResolveArtifacts(
       report,
-      outputBase ? path18.join(outputBase, path18.dirname(rel)) : void 0,
+      outputBase ? path17.join(outputBase, path17.dirname(rel)) : void 0,
       flowPath,
       baseUrl
     );
@@ -37931,14 +37659,14 @@ async function e2e(argv, options) {
     for (const dir of E2E_DIRS) {
       let rels;
       try {
-        rels = (await collectRunnableFlowPaths(path18.join(process.cwd(), dir))).sort();
+        rels = (await collectRunnableFlowPaths(path17.join(process.cwd(), dir))).sort();
       } catch {
         continue;
       }
       anyDir = true;
       for (const rel of rels) {
-        const shown = path18.join(dir, rel);
-        const name = path18.dirname(rel) === "." ? path18.basename(rel, ".yaml") : void 0;
+        const shown = path17.join(dir, rel);
+        const name = path17.dirname(rel) === "." ? path17.basename(rel, ".yaml") : void 0;
         const usedByName = name === void 0 ? void 0 : byName.get(name);
         if (name !== void 0 && usedByName === void 0) byName.set(name, shown);
         lines.push(shown);
@@ -38009,10 +37737,10 @@ async function e2e(argv, options) {
   }
   if (suppliedPath.split(/[\\/]+/).includes("..")) {
     let recovery = "Pass the fully resolved path to the e2e test's YAML.";
-    const suppliedBase2 = path18.basename(suppliedPath);
+    const suppliedBase2 = path17.basename(suppliedPath);
     if (suppliedBase2 !== ".." && suppliedBase2 !== ".") {
       try {
-        const resolved = path18.join(await fsp.realpath(path18.dirname(suppliedPath)), suppliedBase2);
+        const resolved = path17.join(await fsp.realpath(path17.dirname(suppliedPath)), suppliedBase2);
         await fsp.stat(resolved);
         recovery = `Did you mean: argent e2e run ${shellQuoteArg(resolved)}`;
       } catch {
@@ -38024,7 +37752,7 @@ async function e2e(argv, options) {
       2
     );
   }
-  const resolvedPath = path18.resolve(projectRoot, suppliedPath);
+  const resolvedPath = path17.resolve(projectRoot, suppliedPath);
   let isDirectory = false;
   try {
     isDirectory = (await fsp.stat(resolvedPath)).isDirectory();
@@ -38047,16 +37775,16 @@ async function e2e(argv, options) {
   }
   const separatorTrimmedPath = suppliedPath.replace(/[\\/]+$/, "");
   if (separatorTrimmedPath !== suppliedPath && separatorTrimmedPath !== "") {
-    const hint = SAFE_FLOW_NAME.test(separatorTrimmedPath) ? `.${path18.sep}${separatorTrimmedPath}` : separatorTrimmedPath;
+    const hint = SAFE_FLOW_NAME.test(separatorTrimmedPath) ? `.${path17.sep}${separatorTrimmedPath}` : separatorTrimmedPath;
     return fail(
       `E2E test path must not end in a path separator \u2014 the separator claims a directory, which the kernel would refuse to open as a file, so the CLI would run a file this string does not name: ${suppliedPath}
 Did you mean: argent e2e run ${shellQuoteArg(hint)}`,
       2
     );
   }
-  if (path18.extname(suppliedPath) !== ".yaml") {
-    const looksLikeName = !suppliedPath.includes("/") && !suppliedPath.includes("\\") && path18.extname(suppliedPath) === "";
-    if (path18.basename(suppliedPath).toLowerCase() === ".yaml") {
+  if (path17.extname(suppliedPath) !== ".yaml") {
+    const looksLikeName = !suppliedPath.includes("/") && !suppliedPath.includes("\\") && path17.extname(suppliedPath) === "";
+    if (path17.basename(suppliedPath).toLowerCase() === ".yaml") {
       return fail(
         `E2E test filename must have a non-empty name containing only letters, numbers, "_", or "-": ${suppliedPath}`,
         2
@@ -38069,15 +37797,15 @@ Names run \`${E2E_DIRS.map((dir) => `${dir}/<name>.yaml`).join("` or `")}\`; pas
         2
       );
     }
-    if (path18.extname(suppliedPath).toLowerCase() === ".yaml") {
+    if (path17.extname(suppliedPath).toLowerCase() === ".yaml") {
       return fail(
-        `E2E test extension must be lowercase .yaml, not ${path18.extname(suppliedPath)}: ${suppliedPath}`,
+        `E2E test extension must be lowercase .yaml, not ${path17.extname(suppliedPath)}: ${suppliedPath}`,
         2
       );
     }
     return fail(`E2E test path must end in .yaml: ${suppliedPath}`, 2);
   }
-  const flowName = path18.basename(suppliedPath, ".yaml");
+  const flowName = path17.basename(suppliedPath, ".yaml");
   if (!SAFE_FLOW_NAME.test(flowName)) {
     return fail(
       `E2E test filename must have a non-empty name containing only letters, numbers, "_", or "-": ${suppliedPath}`,
@@ -38101,12 +37829,12 @@ No e2e test named "${args.flowRef}" is saved in ${E2E_DIRS.join(" or ")} \u2014
     }
     return fail(`${detail}: ${flowPath}${recovery}`, 2);
   }
-  const suppliedBase = path18.basename(flowPath);
-  const siblings = await fsp.readdir(path18.dirname(flowPath)).catch(() => null);
+  const suppliedBase = path17.basename(flowPath);
+  const siblings = await fsp.readdir(path17.dirname(flowPath)).catch(() => null);
   if (siblings !== null && !siblings.includes(suppliedBase)) {
     const actual = siblings.find((name) => name.toLowerCase() === suppliedBase.toLowerCase());
-    const actualRunnable = actual !== void 0 && path18.extname(actual) === ".yaml" && SAFE_FLOW_NAME.test(path18.basename(actual, ".yaml"));
-    const recovery = actualRunnable ? fromName ? `Did you mean: argent e2e run ${path18.basename(actual, ".yaml")}` : `Did you mean: argent e2e run ${shellQuoteArg(path18.join(path18.dirname(suppliedPath), actual))}` : actual !== void 0 ? `Rename ${actual} to ${suppliedBase} to run it \u2014 e2e test files must be lowercase .yaml.` : "Pass the e2e test file's name exactly as it appears on disk.";
+    const actualRunnable = actual !== void 0 && path17.extname(actual) === ".yaml" && SAFE_FLOW_NAME.test(path17.basename(actual, ".yaml"));
+    const recovery = actualRunnable ? fromName ? `Did you mean: argent e2e run ${path17.basename(actual, ".yaml")}` : `Did you mean: argent e2e run ${shellQuoteArg(path17.join(path17.dirname(suppliedPath), actual))}` : actual !== void 0 ? `Rename ${actual} to ${suppliedBase} to run it \u2014 e2e test files must be lowercase .yaml.` : "Pass the e2e test file's name exactly as it appears on disk.";
     return fail(
       `E2E test path must name the file as it appears on disk \u2014 this filesystem matched ${JSON.stringify(suppliedBase)} case-insensitively${actual !== void 0 ? ` to ${JSON.stringify(actual)}` : ""}, so the test name (which keys the report, __baselines__/, and --output) would be one no file carries: ${suppliedPath}
 ${recovery}`,
@@ -38165,7 +37893,7 @@ ${recovery}`,
   try {
     await exportAndResolveArtifacts(
       report,
-      args.output ? path18.resolve(args.output) : void 0,
+      args.output ? path17.resolve(args.output) : void 0,
       flowPath,
       baseUrl
     );
@@ -38194,6 +37922,313 @@ ${renderSummary(report, { withDevice: true })}`);
   return exitAfterFlush(report.ok && unwritten.length === 0 ? 0 : 1);
 }
 
+// ../argent-cli/src/run.ts
+function splitOptions(argv) {
+  let json2 = false;
+  let outPath = null;
+  const rest = [];
+  for (let i2 = 0; i2 < argv.length; i2++) {
+    const tok = argv[i2];
+    if (tok === "--json") {
+      json2 = true;
+      continue;
+    }
+    if (tok === "--out") {
+      const v = argv[i2 + 1];
+      if (!v) throw new FlagParseException("--out requires a path");
+      outPath = v;
+      i2 += 1;
+      continue;
+    }
+    if (tok.startsWith("--out=")) {
+      outPath = tok.slice("--out=".length);
+      continue;
+    }
+    rest.push(tok);
+  }
+  return { json: json2, outPath, argvForFlags: rest };
+}
+async function readStdin() {
+  return new Promise((resolve13, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve13(data));
+    process.stdin.on("error", reject);
+  });
+}
+function printToolHelp(meta3) {
+  const description = meta3.description?.trim() ?? "";
+  const schema = meta3.inputSchema;
+  const hasOwnArgsField = schema?.properties?.args !== void 0;
+  console.log(`argent run ${meta3.name} [flags]`);
+  if (description) console.log(`
+${description}
+`);
+  console.log("Flags:");
+  console.log(formatSchemaUsage(schema));
+  console.log("\nGlobal flags:");
+  if (!hasOwnArgsField) {
+    console.log("  --args <json>          Pass the entire payload as JSON (overrides flags)");
+    console.log("  --args -               Read the entire payload as JSON from stdin");
+  }
+  console.log("  --<field>-json <json>  Pass a single field as JSON (objects/nested arrays)");
+  console.log("  --json                 Print the raw JSON result");
+  console.log("  --out <path>           For image results, save to <path> instead of fetching URL");
+  console.log("  --help, -h             Show this help");
+}
+async function fetchImageToFile(result, outPath) {
+  const url2 = result.url;
+  if (!url2) {
+    throw new Error("Tool result did not include a `url`; cannot save image");
+  }
+  const res = await fetch(url2);
+  if (!res.ok) throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  fs12.mkdirSync(path18.dirname(path18.resolve(outPath)), { recursive: true });
+  fs12.writeFileSync(outPath, buf);
+}
+function renderResult(result, outputHint, images, json2) {
+  if (json2) return JSON.stringify(result, null, 2);
+  if (outputHint === "image") {
+    if (images.length > 0) return `Saved screenshot: ${images[0].localPath}`;
+    if (result && typeof result === "object" && "path" in result && typeof result.path === "string") {
+      return `Saved screenshot: ${result.path}`;
+    }
+  }
+  if (typeof result === "string") return result;
+  return JSON.stringify(result, null, 2);
+}
+var SAFE_TOOL_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+function safeToolName(toolName) {
+  return toolName && SAFE_TOOL_RE.test(toolName) ? toolName : "unknown";
+}
+async function trackRunFailure(toolName, startedAt, signal) {
+  const tool = toolName ? canonicalToolId(toolName) : toolName;
+  track("cli:run_fail", {
+    tool: safeToolName(tool),
+    ...tool !== toolName ? { alias_used: true } : {},
+    duration_ms: performance.now() - startedAt,
+    ...signal
+  });
+  await shutdown();
+}
+async function run(argv, options) {
+  init("cli");
+  const startedAt = performance.now();
+  const { fetchTool, callTool, baseUrl } = createToolsClient({ paths: options.paths });
+  const [toolName, ...rest] = argv;
+  if (!toolName || toolName === "--help" || toolName === "-h") {
+    console.log(`Usage: argent run <tool> [flags]
+
+Invoke a tool exposed by the argent tool-server. Run \`argent tools\` to list
+available tools, or \`argent tools describe <name>\` to see one tool's flags.
+
+Examples:
+  argent run list-devices
+  argent run gesture-tap --udid <UDID> --x 0.5 --y 0.5
+  argent run screenshot --udid <UDID> --out ./screen.png
+  argent run run-sequence --udid <UDID> --steps-json '[{"tool":"button","args":{"button":"home"}}]'
+  argent run gesture-tap --args '{"udid":"<UDID>","x":0.5,"y":0.5}'
+
+Exits 1 when the tool fails. Also exits 1 when the result reports that the
+call did not do its job: an e2e test that does not pass, an await-ui-element
+wait with success=false, a run-sequence that a step stopped, a debugger tool
+with no connection or an error, a native-devtools precheck that stopped the
+tool, a native-profiler-analyze with status analysis_failed, an e2e recording
+call that recorded nothing, or a baseline that was not written on this client.
+Other results exit 0, also a negative answer such as await-screen-idle's
+settled=false or debugger-status's not_connected.
+`);
+    return;
+  }
+  let cliOptions;
+  try {
+    cliOptions = splitOptions(rest);
+  } catch (err) {
+    if (err instanceof FlagParseException) {
+      console.error(`Error: ${err.message}
+`);
+      console.error(`Run \`argent run ${toolName} --help\` to see this tool's flags.`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
+        failure_stage: "cli_run_split_options",
+        failure_area: "cli",
+        error_kind: "validation"
+      });
+      process.exit(2);
+    }
+    throw err;
+  }
+  const { json: json2, outPath, argvForFlags } = cliOptions;
+  const meta3 = await fetchTool(toolName);
+  if (!meta3) {
+    console.error(`Tool "${toolName}" not found. Run \`argent tools\` to list available tools.`);
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_NOT_FOUND,
+      failure_stage: "cli_run_fetch_tool",
+      failure_area: "cli",
+      error_kind: "not_found"
+    });
+    process.exit(1);
+  }
+  const schema = meta3.inputSchema;
+  const failInvocation = async (summary, report, failure3) => {
+    if (json2) {
+      console.error(
+        JSON.stringify(
+          {
+            error: summary,
+            missing: report ? missingFlagNames(report, schema) : [],
+            issues: report?.rawIssues ?? []
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`Error: ${summary}
+`);
+      printToolHelp(meta3);
+    }
+    await trackRunFailure(toolName, startedAt, {
+      ...failure3,
+      failure_area: "cli",
+      error_kind: "validation"
+    });
+    process.exit(2);
+  };
+  const failValidation = (report, stage) => failInvocation(formatValidationError(report, schema), report, {
+    error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
+    failure_stage: stage
+  });
+  let parsed;
+  try {
+    parsed = parseFlags(argvForFlags, schema);
+  } catch (err) {
+    if (err instanceof FlagParseException) {
+      await failInvocation(err.message, null, {
+        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
+        failure_stage: "cli_run_parse_flags"
+      });
+    }
+    throw err;
+  }
+  if (parsed.helpRequested) {
+    printToolHelp(meta3);
+    return;
+  }
+  if (parsed.positional.length > 0) {
+    console.error(
+      `Note: ignoring unused argument(s): ${parsed.positional.join(", ")}. Pass values as --flag <value> or --flag=<value>.`
+    );
+  }
+  let payload = {};
+  if (parsed.rawArgs !== null) {
+    let rawJson = parsed.rawArgs;
+    if (rawJson === "-") {
+      rawJson = await readStdin();
+    }
+    try {
+      const parsedRaw = JSON.parse(rawJson);
+      if (parsedRaw === null || typeof parsedRaw !== "object" || Array.isArray(parsedRaw)) {
+        console.error("--args must be a JSON object");
+        await trackRunFailure(toolName, startedAt, {
+          error_code: FAILURE_CODES.CLI_RUN_ARGS_NOT_OBJECT,
+          failure_stage: "cli_run_parse_raw_args",
+          failure_area: "cli",
+          error_kind: "validation"
+        });
+        process.exit(2);
+      }
+      payload = parsedRaw;
+    } catch (err) {
+      console.error(`--args is not valid JSON: ${err instanceof Error ? err.message : err}`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_ARGS_JSON_INVALID,
+        failure_stage: "cli_run_parse_raw_args",
+        failure_area: "cli",
+        error_kind: "validation"
+      });
+      process.exit(2);
+    }
+  }
+  for (const [k, v] of Object.entries(parsed.args)) {
+    payload[k] = v;
+  }
+  const missing = findMissingRequired(payload, schema);
+  if (missing.length > 0) {
+    await failValidation({ missing, invalid: [], rawIssues: null }, "cli_run_required_flags");
+  }
+  let result;
+  let note;
+  let failure2;
+  let images = [];
+  try {
+    const resp = await callTool(toolName, payload);
+    const { url: url2, token } = await baseUrl();
+    const materialized = await materializeArtifacts(resp.data, {
+      toolsUrl: url2,
+      authToken: token,
+      deviceId: getDeviceIdFromArgs(payload)
+    });
+    result = materialized.result;
+    images = materialized.images;
+    note = resp.note;
+    failure2 = resp.failure;
+  } catch (err) {
+    const report = describeServerValidationFailure(err, payload, schema);
+    if (report) {
+      await failValidation(report, "cli_run_server_validation");
+    }
+    console.error(err instanceof Error ? err.message : String(err));
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_CALL_FAILED,
+      failure_stage: "cli_run_call_tool",
+      failure_area: "cli",
+      error_kind: "unknown"
+    });
+    process.exit(1);
+  }
+  if (outPath && meta3.outputHint === "image") {
+    try {
+      if (images.length > 0) {
+        fs12.mkdirSync(path18.dirname(path18.resolve(outPath)), { recursive: true });
+        fs12.writeFileSync(outPath, images[0].data);
+      } else if (result && typeof result === "object") {
+        await fetchImageToFile(result, outPath);
+      }
+    } catch (err) {
+      console.error(`Failed to save image: ${err instanceof Error ? err.message : err}`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_SAVE_IMAGE_FAILED,
+        failure_stage: "cli_run_save_image",
+        failure_area: "cli",
+        error_kind: "unknown"
+      });
+      process.exit(1);
+    }
+  }
+  if (note) console.error(note);
+  console.log(renderResult(result, meta3.outputHint, images, json2));
+  if (outPath && meta3.outputHint === "image" && !json2) {
+    console.log(`Wrote: ${outPath}`);
+  }
+  if (failure2) {
+    await new Promise((resolve13) => process.stdout.write("", () => resolve13()));
+    console.error(failure2);
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_RESULT_FAILED,
+      failure_stage: "cli_run_tool_result",
+      failure_area: "cli",
+      error_kind: "unknown"
+    });
+    await exitAfterFlush(1, [process.stderr]);
+  }
+}
+
 // ../argent-cli/src/tools.ts
 function summarize(description, max = 80) {
   if (!description) return "";