@swmansion/argent 0.27.1-next.16 → 0.27.1-next.18

package/assets/manifest.json

@@ -1,7 +1,7 @@
 {
   "packageName": "com.argent.androiddevtools",
   "instrumentationRunner": "com.argent.androiddevtools/.SnapshotInstrumentation",
-  "versionName": "0.1.0",
-  "versionCode": 1,
+  "versionName": "0.2.0",
+  "versionCode": 2,
   "installFlags": ["-r", "-t"]
 }

package/dist/cli-cmds.mjs

@@ -21916,7 +21916,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.27.1-next.16";
+    return "0.27.1-next.18";
   }
   return "0.0.0";
 }
@@ -23267,8 +23267,11 @@ 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.
+The CLI sends a run to its tool-server: the local one that starts
+automatically, or the one that \`argent link\` or ARGENT_TOOLS_URL names. With
+either, the CLI uploads the flow file, and the tool-server rejects a flow with
+run:, script: or snapshot: steps, or with tool: steps that take a file or
+record a flow, before the first step. With neither, all step kinds run.
 
 Subcommands:
   run <flow|flow.yaml|dir>   Run a saved flow by name, a YAML file by path, or
@@ -23282,6 +23285,7 @@ Options (run):
                          auto-detection (ios never picks a remote simulator)
   --update-baselines     Write/refresh screenshot baselines instead of diffing
   --output <dir>         Also write failed snapshot images (baseline/current/diff)
+                         and failed-step screenshots (step-<n>-screen.png)
                          under <dir>/<flow>/ \u2014 a stable path for CI artifact
                          upload; a directory run keys nested flows as
                          <dir>/<subdir>/<flow>/. A different flow file with the
@@ -23557,23 +23561,34 @@ async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
     return;
   }
   let dir = null;
+  let n2 = 0;
   for (const s of report.steps) {
-    if (s.kind !== "snapshot" || s.status !== "fail" || !s.artifacts) continue;
-    const key = s.snapshotKey ?? keyFromBaselinePath(s.artifacts);
-    if (!key || !SAFE_ARTIFACT_NAME.test(key)) continue;
-    const { result } = await materializeArtifacts(s.artifacts, ctx);
-    s.artifacts = result;
-    for (const [role, value] of Object.entries(s.artifacts)) {
+    if (s.kind !== "echo") n2++;
+    if (!s.artifacts) continue;
+    let artifacts;
+    let fileName;
+    if (s.kind === "snapshot" && s.status === "fail") {
+      const key = s.snapshotKey ?? keyFromBaselinePath(s.artifacts);
+      if (!key || !SAFE_ARTIFACT_NAME.test(key)) continue;
+      artifacts = s.artifacts;
+      const remote = s.snapshotRemote === true ? "-remote" : "";
+      fileName = (role) => `${key}${remote}-${role}.png`;
+    } else if ((s.status === "fail" || s.status === "error") && s.artifacts.screen != null) {
+      artifacts = { screen: s.artifacts.screen };
+      fileName = () => `step-${n2}-screen.png`;
+    } else {
+      continue;
+    }
+    const { result } = await materializeArtifacts(artifacts, ctx);
+    Object.assign(s.artifacts, result);
+    for (const [role, value] of Object.entries(result)) {
       if (typeof value !== "string") continue;
       if (dir === null) {
         const dirName = await claimExportDirName(outputDir, flowPath, stem);
         if (dirName === null) return;
         dir = path14.join(outputDir, dirName);
       }
-      const dest = path14.join(
-        dir,
-        `${key}${s.snapshotRemote === true ? "-remote" : ""}-${role}.png`
-      );
+      const dest = path14.join(dir, fileName(role));
       const rel = path14.relative(outputDir, dest);
       if (rel.startsWith("..") || path14.isAbsolute(rel)) continue;
       try {
@@ -23700,13 +23715,6 @@ async function collectFlowFiles(dir, recursive) {
   await walk(dir, "");
   return found.sort();
 }
-async function requireLocalToolServer() {
-  const routing = await getResolvedToolsUrl();
-  if (routing.source === "none") return void 0;
-  const recovery = routing.source === "env" ? routing.shadowedLink ? `Unset ARGENT_TOOLS_URL and run \`argent unlink\`, then try again \u2014 a link to ${routing.shadowedLink.url} is also configured and takes over once the env var is unset.` : "Unset ARGENT_TOOLS_URL and try again." : "Run `argent unlink` and try again.";
-  return `argent flow run requires the auto-started local tool server; ${routing.source} routing is configured.
-${recovery}`;
-}
 function buildRunPayload(flowPath, projectRoot, args) {
   const payload = {
     flow_path: flowPath,
@@ -23722,16 +23730,51 @@ function buildRunPayload(flowPath, projectRoot, args) {
 function writeJsonStreamRecord(record2) {
   console.log(JSON.stringify(record2));
 }
+var ToolServerUnreachableError = class extends Error {
+  errorCode = "TOOL_SERVER_UNREACHABLE";
+  errorKind = "network";
+};
+var UNREACHABLE_VERDICT = "not run (tool-server unreachable)";
+var CONNECT_FAILURES = /* @__PURE__ */ new Map([
+  ["ECONNREFUSED", "connection refused"],
+  ["ENOTFOUND", "host not found"],
+  ["EAI_AGAIN", "host not found"],
+  ["ETIMEDOUT", "timed out"],
+  ["UND_ERR_CONNECT_TIMEOUT", "timed out"],
+  ["EHOSTUNREACH", "host unreachable"],
+  ["ENETUNREACH", "host unreachable"]
+]);
+async function toolServerUnreachable(err) {
+  if (!(err instanceof TypeError)) return void 0;
+  const cause = err.cause;
+  const reason = typeof cause?.code === "string" ? CONNECT_FAILURES.get(cause.code) : void 0;
+  const syscall = cause?.syscall;
+  if (!reason || syscall !== void 0 && syscall !== "connect" && syscall !== "getaddrinfo") {
+    return void 0;
+  }
+  const routing = await getResolvedToolsUrl();
+  if (routing.source === "none") return void 0;
+  const recovery = routing.source === "link" ? "Start the tool-server on the linked machine, or run `argent unlink`." : routing.shadowedLink ? `Start that tool-server, or unset ARGENT_TOOLS_URL and run \`argent unlink\` to use the local one. A link to ${routing.shadowedLink.url} is also configured and takes over once the env var is unset.` : "Start that tool-server, or unset ARGENT_TOOLS_URL to use the local one.";
+  const setBy = routing.source === "env" ? "ARGENT_TOOLS_URL" : "argent link";
+  return new ToolServerUnreachableError(
+    `Could not reach the tool-server at ${routing.url} (set by ${setBy}): ${reason}.
+${recovery}`
+  );
+}
 function failureSignal2(err) {
-  if (!(err instanceof ToolInvocationError)) return {};
+  if (!(err instanceof ToolInvocationError) && !(err instanceof ToolServerUnreachableError)) {
+    return {};
+  }
   return {
     ...err.errorCode ? { error_code: err.errorCode } : {},
     ...err.errorKind ? { error_kind: err.errorKind } : {}
   };
 }
+function errorRecord(err, message = err instanceof Error ? err.message : String(err)) {
+  return { event: "error", error: message, ...failureSignal2(err) };
+}
 function writeJsonStreamError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  writeJsonStreamRecord({ event: "error", error: message, ...failureSignal2(err) });
+  writeJsonStreamRecord(errorRecord(err));
 }
 async function exportAndResolveArtifacts(report, outputDir, flowPath, baseUrl) {
   if (outputDir) {
@@ -23757,22 +23800,23 @@ function isFlowReport(data) {
   return Array.isArray(steps) && steps.every((step) => !!step && typeof step === "object");
 }
 async function runFlowDirectory(dir, args, projectRoot, options) {
+  const printError = (message, err = message) => {
+    console.error(args.json ? JSON.stringify(errorRecord(err, message)) : message);
+  };
+  const reject = (message) => {
+    printError(message);
+    return exitAfterFlush(2);
+  };
   let flows;
   try {
     flows = await collectFlowFiles(dir, args.recursive);
   } catch {
-    console.error(`Could not read flow directory: ${dir}`);
-    return exitAfterFlush(2);
+    return reject(`Could not read flow directory: ${dir}`);
   }
   if (flows.length === 0) {
-    console.error(`No flows found in ${dir}`);
-    if (!args.recursive) console.error("Pass -r/--recursive to include subdirectories.");
-    return exitAfterFlush(2);
-  }
-  const refusal = await requireLocalToolServer();
-  if (refusal) {
-    console.error(refusal);
-    return exitAfterFlush(2);
+    return reject(
+      `No flows found in ${dir}` + (args.recursive ? "" : "\nPass -r/--recursive to include subdirectories.")
+    );
   }
   const { callTool, baseUrl } = createToolsClient({ paths: options.paths });
   const outputBase = args.output ? path14.resolve(args.output) : void 0;
@@ -23780,6 +23824,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
   const failures = [];
   const batchStartedAt = Date.now();
   let stopped = false;
+  let unreachable = false;
   for (const [i2, rel] of flows.entries()) {
     if (!args.json) console.log(`[${i2 + 1}/${flows.length}] ${rel}`);
     if (stopped) {
@@ -23793,23 +23838,26 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     try {
       const resp = await callTool("flow-execute", buildRunPayload(flowPath, projectRoot, args));
       if (isFlowReport(resp.data)) report = resp.data;
-    } catch (err) {
+    } catch (thrown) {
+      const unreachableErr = await toolServerUnreachable(thrown);
+      const err = unreachableErr ?? thrown;
       const message = err instanceof Error ? err.message : String(err);
       const toolErr = err instanceof ToolInvocationError ? err : void 0;
       const rejectedThisFlowOnly = toolErr?.errorKind === "validation";
-      const verdict = rejectedThisFlowOnly ? rejectionVerdict(toolErr?.errorCode) : "did not finish (run error)";
+      const verdict = unreachableErr ? UNREACHABLE_VERDICT : rejectedThisFlowOnly ? rejectionVerdict(toolErr?.errorCode) : "did not finish (run error)";
       if (!args.json) console.log(`  ${STATUS_GLYPH.error} ${verdict}`);
-      console.error(message);
+      printError(message, err);
       results.push({ path: rel, status: "fail", error: message, ...failureSignal2(err) });
       failures.push({ path: rel, headline: verdict, detail: message, rerun });
       if (!rejectedThisFlowOnly) stopped = true;
+      if (unreachableErr) unreachable = true;
       continue;
     }
     if (!report) {
       const message = `"${rel}" did not produce a run report.`;
       const verdict = "did not finish (no run report)";
       if (!args.json) console.log(`  ${STATUS_GLYPH.error} ${verdict}`);
-      console.error(message);
+      printError(message);
       results.push({ path: rel, status: "fail", error: message });
       failures.push({ path: rel, headline: verdict, detail: message, rerun });
       stopped = true;
@@ -23844,7 +23892,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     console.log(`
 ${renderBatchSummary(counts, durationMs)}`);
   }
-  return exitAfterFlush(counts.failed === 0 ? 0 : 1);
+  return exitAfterFlush(unreachable ? 2 : counts.failed === 0 ? 0 : 1);
 }
 async function flow(argv, options) {
   const [sub, ...rest] = argv;
@@ -23867,38 +23915,42 @@ async function flow(argv, options) {
     console.error(`Unknown flow subcommand "${sub}". Run \`argent flow --help\`.`);
     return exitAfterFlush(2);
   }
-  const jsonStream = rest.some(
-    (tok) => tok === "--json-stream" || tok.startsWith("--json-stream=")
-  );
+  const flagGiven = (flag) => rest.some((tok) => tok === flag || tok.startsWith(`${flag}=`));
+  const jsonStream = flagGiven("--json-stream");
+  const json2 = !jsonStream && flagGiven("--json");
   if (rest.includes("--help") || rest.includes("-h")) {
     printHelp(jsonStream);
     return;
   }
-  const fail = (message, code, err = message) => {
-    if (jsonStream) writeJsonStreamError(err);
-    console.error(message);
-    return exitAfterFlush(code);
+  const usageError = (message, prose) => {
+    if (json2) {
+      console.error(JSON.stringify(errorRecord(message)));
+      return exitAfterFlush(2);
+    }
+    if (jsonStream) writeJsonStreamError(message);
+    console.error(prose);
+    printHelp(jsonStream);
+    return exitAfterFlush(2);
   };
   let args;
   try {
     args = parseRunArgs(rest);
   } catch (err) {
     if (err instanceof FlagParseException) {
-      if (jsonStream) writeJsonStreamError(err);
-      console.error(`Error: ${err.message}
+      return usageError(err.message, `Error: ${err.message}
 `);
-      printHelp(jsonStream);
-      return exitAfterFlush(2);
     }
     throw err;
   }
   if (!args.flowRef) {
     const message = "argent flow run <flow|flow.yaml|dir> requires a flow name, a YAML file path, or a directory path.";
-    if (jsonStream) writeJsonStreamError(message);
-    console.error(message);
-    printHelp(jsonStream);
-    return exitAfterFlush(2);
+    return usageError(message, message);
   }
+  const fail = (message, code, err = message) => {
+    if (jsonStream) writeJsonStreamError(err);
+    console.error(args.json ? JSON.stringify(errorRecord(err, message)) : message);
+    return exitAfterFlush(code);
+  };
   const projectRoot = process.cwd();
   const { suppliedPath, fromName } = resolveFlowRef(args.flowRef);
   if (suppliedPath.split(/[\\/]+/).includes("..")) {
@@ -24007,8 +24059,6 @@ ${recovery}`,
       2
     );
   }
-  const refusal = await requireLocalToolServer();
-  if (refusal) return fail(refusal, 2);
   const { callTool, baseUrl } = createToolsClient({ paths: options.paths });
   const payload = buildRunPayload(flowPath, projectRoot, args);
   let liveSteps = 0;
@@ -24040,12 +24090,14 @@ ${recovery}`,
     );
     report = resp.data;
   } catch (err) {
+    const unreachableErr = await toolServerUnreachable(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)")
+        `  ${STATUS_GLYPH.error} ` + (unreachableErr ? UNREACHABLE_VERDICT : err instanceof ToolInvocationError && err.errorKind === "validation" ? rejectionVerdict(err.errorCode) : "did not finish (run error)")
       );
     }
+    if (unreachableErr) return fail(unreachableErr.message, 2, unreachableErr);
     return fail(err instanceof Error ? err.message : String(err), 1, err);
   }
   if (!isFlowReport(report)) {

package/dist/installer.mjs

@@ -16730,7 +16730,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.27.1-next.16";
+    return "0.27.1-next.18";
   }
   return "0.0.0";
 }

package/dist/tool-args.generated.d.ts

@@ -225,7 +225,7 @@ export interface ArgentToolArgs {
         project_root: string;
         /** Path to the flow .yaml as readable by the tool-server. Internal — the argent client derives it from project_root and name automatically; leave unset. */
         flow_file?: string;
-        /** Omit when name is set. Absolute path to a co-located flow .yaml on the client and tool server's shared filesystem. This must be supplied through the file-input boundary. For remote execution, pass name + project_root instead. */
+        /** Omit when name is set. Absolute path to a flow .yaml on the client. Over a link (argent link or ARGENT_TOOLS_URL), the argent client uploads the file and the tool-server runs the uploaded copy. An uploaded flow must be self-contained: no run:, script: or snapshot: steps, and no tool: steps that take a file or record a flow. Without a link, the tool-server reads the file in place and all step kinds run. */
         flow_path?: string;
         /** Device id to run against (iOS UDID, Android/Vega serial, Chromium id) — the id list-devices reports. Auto-detected when omitted, but only when exactly one booted device matches (optionally narrowed by `platform`); with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up. */
         device?: string;
@@ -249,7 +249,7 @@ export interface ArgentToolArgs {
         project_root: string;
         /** Path to the flow .yaml as readable by the tool-server. Internal — the argent client derives it from project_root and name automatically; leave unset. */
         flow_file?: string;
-        /** Omit when name is set. Absolute path to a co-located flow .yaml on the client and tool server's shared filesystem. This must be supplied through the file-input boundary. Pass the same flow source here as to flow-execute, so the prerequisite you read belongs to the flow that will run; for remote reads, pass name + project_root instead. */
+        /** Omit when name is set. Absolute path to a flow .yaml on the client. Over a link (argent link or ARGENT_TOOLS_URL), the argent client uploads the file and the tool-server reads the uploaded copy; without a link, the tool-server reads the file in place. Pass the path through the argent client; a raw path that the file-input boundary did not verify is rejected. Pass the same flow source here as to flow-execute, so the prerequisite you read belongs to the flow that will run. */
         flow_path?: string;
     };
     "flow-start-recording": {

package/dist/tool-server.cjs

@@ -1108,6 +1108,18 @@ var init_artifacts = __esm({
 function isFileInputWire(value) {
   return !!value && typeof value === "object" && value[FILE_INPUT_MARKER] === true && typeof value.path === "string";
 }
+function interpolateFileInputPath(template, args) {
+  let missing = false;
+  const out = template.replace(/\$\{([A-Za-z0-9_]+)\}/g, (_m, name) => {
+    const v = args[name];
+    if (typeof v !== "string" || v.length === 0) {
+      missing = true;
+      return "";
+    }
+    return v;
+  });
+  return missing ? null : out;
+}
 var FILE_INPUT_MARKER, FLOW_NAME_CHARSET, FLOW_NAME_PATTERN, FLOW_FILE_NAME_PATTERN, SCRIPT_FILE_NAME_PATTERN, CLIENT_FILE_MARKER;
 var init_file_inputs = __esm({
   "../registry/src/file-inputs.ts"() {
@@ -79147,16 +79159,16 @@ var require_path_is_absolute = __commonJS({
     function posix6(path51) {
       return path51.charAt(0) === "/";
     }
-    function win32(path51) {
+    function win322(path51) {
       var splitDeviceRe = /^([a-zA-Z]:|[\\\/]{2}[^\\\/]+[\\\/]+[^\\\/]+)?([\\\/])?([\s\S]*?)$/;
       var result = splitDeviceRe.exec(path51);
       var device = result[1] || "";
       var isUnc = Boolean(device && device.charAt(1) !== ":");
       return Boolean(result[2] || isUnc);
     }
-    module2.exports = process.platform === "win32" ? win32 : posix6;
+    module2.exports = process.platform === "win32" ? win322 : posix6;
     module2.exports.posix = posix6;
-    module2.exports.win32 = win32;
+    module2.exports.win32 = win322;
   }
 });
 
@@ -94814,7 +94826,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.27.1-next.16";
+    return "0.27.1-next.18";
   }
   return "0.0.0";
 }
@@ -113595,26 +113607,30 @@ init_android_binary();
 // ../tool-server/src/utils/android-helper-install.ts
 init_adb();
 async function probeInstalledVersion(serial, packageName) {
-  let out;
   try {
-    out = await adbShell(serial, `cmd package list packages --show-versioncode ${packageName}`, {
-      timeoutMs: 5e3
-    });
-  } catch {
-    try {
-      out = await adbShell(serial, `pm list packages ${packageName}`, { timeoutMs: 5e3 });
-    } catch {
-      return { installed: false, versionCode: null };
+    const out2 = await adbShell(
+      serial,
+      `cmd package list packages --show-versioncode ${packageName}`,
+      { timeoutMs: 5e3 }
+    );
+    for (const line of out2.split("\n")) {
+      const match = line.trim().match(/^package:([^\s]+)\s+versionCode:(\d+)$/);
+      if (match?.[1] === packageName) {
+        return { installed: true, versionCode: parseInt(match[2], 10) };
+      }
     }
+  } catch {
   }
-  for (const line of out.split("\n")) {
-    const match = line.trim().match(/^package:([^\s]+)(?:\s+versionCode:(\d+))?$/);
-    if (!match) continue;
-    if (match[1] !== packageName) continue;
-    const versionCode = match[2] ? parseInt(match[2], 10) : null;
-    return { installed: true, versionCode: Number.isFinite(versionCode) ? versionCode : null };
+  let out;
+  try {
+    out = await adbShell(serial, `dumpsys package ${packageName}`, { timeoutMs: 5e3 });
+  } catch {
+    return { installed: false, versionCode: null };
   }
-  return { installed: false, versionCode: null };
+  const block = out.split(`Package [${packageName}]`)[1];
+  if (block === void 0) return { installed: false, versionCode: null };
+  const versionCode = block.match(/versionCode=(\d+)/);
+  return { installed: true, versionCode: versionCode ? parseInt(versionCode[1], 10) : null };
 }
 async function ensureAndroidDevtoolsInstalled(serial, options = {}) {
   const manifest = helperManifest();
@@ -114906,6 +114922,14 @@ async function resolveOne(spec, wire, tempDirs, lookupUpload) {
       `Path "${wire.path}" does not exist on the tool-server host and no upload was provided. Update argent to a version that supports uploads for remote sessions.`
     );
   }
+  if (spec.kind === "file" && typeof wire.content === "string") {
+    const { filePath, dir } = await materializeUpload(wire);
+    tempDirs.push(dir);
+    return {
+      value: filePath,
+      meta: { clientPath: wire.path, presentOnHost: probe3.present, viaUpload: true }
+    };
+  }
   if (meta3.presentOnHost) {
     return { value: wire.path, meta: meta3 };
   }
@@ -114914,11 +114938,6 @@ async function resolveOne(spec, wire, tempDirs, lookupUpload) {
       `Directory "${wire.path}" does not exist on the tool-server host. This tool reads a directory tree from the tool-server's filesystem, which cannot be uploaded with the call \u2014 when the tool-server runs on a different machine, pass a path that exists on that machine (e.g. the server-side checkout of the project).`
     );
   }
-  if (typeof wire.content === "string") {
-    const { filePath, dir } = await materializeUpload(wire);
-    tempDirs.push(dir);
-    return { value: filePath, meta: { ...meta3, viaUpload: true } };
-  }
   if (wire.contentOmitted === "size-limit") {
     throw new FileInputError(
       `File "${wire.path}" is ${formatBytes(wire.size)} \u2014 larger than the ${formatBytes(MAX_UPLOAD_BYTES)} file-input transfer limit, so the client did not upload it, and it was not found on the tool-server host. Copy the file to the tool-server machine and pass that path, or use a smaller file.`
@@ -147148,7 +147167,22 @@ function selectRotateCandidate(candidates) {
 
 // ../tool-server/src/tools/flows/flow-utils.ts
 var FLOWS_DIR_NAME = path38.join(".argent", "flows");
+function windowsPathRefusal(label, value) {
+  if (process.platform === "win32" || path38.isAbsolute(value) || !path38.win32.isAbsolute(value)) {
+    return void 0;
+  }
+  return `${label} "${value}" is a Windows path. A tool-server on macOS or Linux cannot open Windows paths. Use argent on the computer that runs the tool-server, or start the tool-server on the Windows computer.`;
+}
 function assertValidProjectRoot(root) {
+  const windows = windowsPathRefusal("project_root", root);
+  if (windows) {
+    throw new FailureError(windows, {
+      error_code: FAILURE_CODES.FLOW_PROJECT_ROOT_INVALID,
+      failure_stage: "flow_project_root_set",
+      failure_area: "tool_server",
+      error_kind: "validation"
+    });
+  }
   if (!path38.isAbsolute(root)) {
     throw new FailureError(
       `project_root must be an absolute path (got "${root}"). Pass the absolute path to the project root directory \u2014 the same cwd the calling agent is working in.`,
@@ -151775,6 +151809,7 @@ var NESTED_RECORDER_TOOLS = {
   "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."
 };
+var RECORDING_TOOL_IDS = new Set(Object.keys(NESTED_RECORDER_TOOLS));
 function isToolNotFound(err, command) {
   return err instanceof ToolNotFoundError && err.toolId === command;
 }
@@ -156152,7 +156187,7 @@ var zodSchema68 = external_exports.object({
     "Path to the flow .yaml as readable by the tool-server. Internal \u2014 the argent client derives it from project_root and name automatically; leave unset."
   ),
   flow_path: external_exports.string().optional().describe(
-    "Omit when name is set. Absolute path to a co-located flow .yaml on the client and tool server's shared filesystem. This must be supplied through the file-input boundary. For remote execution, pass name + project_root instead."
+    "Omit when name is set. Absolute path to a flow .yaml on the client. Over a link (argent link or ARGENT_TOOLS_URL), the argent client uploads the file and the tool-server runs the uploaded copy. An uploaded flow must be self-contained: no run:, script: or snapshot: steps, and no tool: steps that take a file or record a flow. Without a link, the tool-server reads the file in place and all step kinds run."
   ),
   device: external_exports.string().optional().describe(
     "Device id to run against (iOS UDID, Android/Vega serial, Chromium id) \u2014 the id list-devices reports. Auto-detected when omitted, but only when exactly one booted device matches (optionally narrowed by `platform`); with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up."
@@ -156532,42 +156567,69 @@ function findRetiredToolArg(registry2, steps) {
 function retiredArgReason(use) {
   return `${use.where} as written (echo included) passes ${use.tool}'s retired \`${use.key}\` key${use.guidance ? `: ${use.guidance}` : ""}`;
 }
-function assertUploadSelfContained(flow) {
-  for (const { step } of walkSteps(flow.steps)) {
+var UPLOAD_STAGE_BY_KIND = {
+  run: "flow_upload_run_composition",
+  script: "flow_upload_script_step",
+  snapshot: "flow_upload_snapshot_baseline",
+  nested: "flow_upload_nested_flow",
+  toolFile: "flow_upload_tool_file_input",
+  recording: "flow_upload_recording_tool"
+};
+function nestedFlowRef(args) {
+  if (typeof args.name === "string") return ` (name: ${args.name})`;
+  if (typeof args.flow_path === "string") return ` (flow_path: ${args.flow_path})`;
+  return "";
+}
+function toolStepFilePaths(registry2, tool, args) {
+  const paths = [];
+  for (const spec of registry2.getTool(tool)?.fileInputs ?? []) {
+    if (spec.skipWhenSet !== void 0 && args[spec.skipWhenSet] !== void 0) continue;
+    const filled = interpolateFileInputPath(spec.path, args);
+    if (filled !== null) paths.push(filled);
+  }
+  return paths;
+}
+function assertUploadSelfContained(registry2, flow) {
+  const offending = [];
+  for (const { step, where } of walkSteps(flow.steps)) {
     if (step.kind === "run") {
-      throw new FailureError(
-        `This flow uses run: composition ("run: ${step.flow}"), which requires a co-located client and tool server \u2014 an uploaded flow's referenced files are not available on this host.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_upload_run_composition",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
-    }
-    if (step.kind === "script") {
-      throw new FailureError(
-        `This flow uses a script step ("script: { path: ${step.path} }"), whose .mjs file lives beside the flow's file on the CLIENT \u2014 an uploaded flow carries only its own YAML, so the script is not on this host and never could be. Use name + project_root with a co-located client and tool server for flows that run scripts.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_upload_script_step",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
-    }
-    if (step.kind === "snapshot") {
-      throw new FailureError(
-        `This flow uses a snapshot step ("snapshot: ${step.name}"), whose baselines live beside the flow's file \u2014 an uploaded flow materializes to a fresh temp directory each call, so a plain snapshot can never find a baseline and updateBaselines (--update-baselines) writes PNGs no later run can read. Use name + project_root with a co-located client and tool server for snapshot flows.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_upload_snapshot_baseline",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
+      offending.push({ kind: "run", line: `${where}: run: ${step.flow}` });
+    } else if (step.kind === "script") {
+      offending.push({ kind: "script", line: `${where}: script: { path: ${step.path} }` });
+    } else if (step.kind === "snapshot") {
+      offending.push({ kind: "snapshot", line: `${where}: snapshot: ${step.name}` });
+    } else if (step.kind === "tool" && step.name === "flow-execute") {
+      offending.push({
+        kind: "nested",
+        line: `${where}: tool: flow-execute${nestedFlowRef(step.args)}`
+      });
+    } else if (step.kind === "tool" && RECORDING_TOOL_IDS.has(step.name)) {
+      offending.push({
+        kind: "recording",
+        line: `${where}: tool: ${step.name} (records a flow)`
+      });
+    } else if (step.kind === "tool") {
+      const paths = toolStepFilePaths(registry2, step.name, step.args);
+      if (paths.length > 0) {
+        offending.push({
+          kind: "toolFile",
+          line: `${where}: tool: ${step.name} (${paths.join(", ")})`
+        });
+      }
     }
   }
+  if (offending.length === 0) return;
+  throw new FailureError(
+    `This flow is not self-contained, and it arrived as an upload. The steps below read or write project files, which stay on the client:
+` + offending.map((o) => `  - ${o.line}`).join("\n") + `
+Run the flow on the computer that runs the tool-server, with no link and no ARGENT_TOOLS_URL, so that the tool-server reads the files in place.`,
+    {
+      error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+      failure_stage: UPLOAD_STAGE_BY_KIND[offending[0].kind],
+      failure_area: "tool_server",
+      error_kind: "validation"
+    }
+  );
 }
 function createRunFlowTool(registry2) {
   return {
@@ -156597,7 +156659,7 @@ Returns a per-step report: the first failure stops the run and the rest report a
       const canonicalPath = await canonicalFlowPath2(filePath);
       const flowsDir = path46.dirname(canonicalPath);
       const flow = parseFlow(await fs62.readFile(canonicalPath, "utf8"));
-      if (viaUpload) assertUploadSelfContained(flow);
+      if (viaUpload) assertUploadSelfContained(registry2, flow);
       const retiredArg = findRetiredToolArg(registry2, flow.steps);
       if (retiredArg) {
         throw new FailureError(`Flow "${flowName}" ${retiredArgReason(retiredArg)}`, {
@@ -156800,7 +156862,7 @@ async function resolveAppPath(specPath, flowDir) {
 async function bootChromiumForFlow(spec, flowDir, viaUpload) {
   if (viaUpload && !path46.isAbsolute(spec.path)) {
     throw new FailureError(
-      `A relative chromium app path ("${spec.path}") resolves against the flow file's directory, which requires a co-located client and tool server \u2014 an uploaded flow has no real flow directory on this host. Use an absolute tool-server path instead.`,
+      `A relative chromium app path ("${spec.path}") resolves against the flow file's directory, which requires a run with no link and no ARGENT_TOOLS_URL \u2014 an uploaded flow has no real flow directory on this host. Use an absolute tool-server path instead.`,
       {
         error_code: FAILURE_CODES.FLOW_FILE_INVALID,
         failure_stage: "flow_upload_chromium_app_path",
@@ -157349,6 +157411,55 @@ async function execLeafStep(state3, step, index, scope) {
 function errMsg4(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function assertFlowPathShape(flowPath) {
+  const windows = windowsPathRefusal("flow_path", flowPath);
+  if (windows) {
+    throw new FailureError(windows, {
+      error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+      failure_stage: "flow_path_absolute",
+      failure_area: "tool_server",
+      error_kind: "validation"
+    });
+  }
+  if (!path46.isAbsolute(flowPath)) {
+    throw new FailureError(
+      `Invalid flow_path "${flowPath}": flow paths must be absolute \u2014 a relative path is resolved against the tool server's working directory, not the caller's. Pass the absolute path to the flow's YAML.`,
+      {
+        error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+        failure_stage: "flow_path_absolute",
+        failure_area: "tool_server",
+        error_kind: "validation"
+      }
+    );
+  }
+  if (flowPath.split(/[\\/]+/).includes("..")) {
+    throw new FailureError(
+      `Invalid flow_path "${flowPath}": flow paths must not contain ".." segments \u2014 a ".." after a symlinked directory can name a different file than the spelling suggests, and the argent client always sends fully resolved paths. Pass the fully resolved absolute path to the flow's YAML.`,
+      {
+        error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+        failure_stage: "flow_path_dotdot",
+        failure_area: "tool_server",
+        error_kind: "validation"
+      }
+    );
+  }
+}
+function flowNameOf(clientPath) {
+  const clientExt = path46.extname(clientPath);
+  const bareExtension = path46.basename(clientPath).toLowerCase() === ".yaml";
+  if (!bareExtension && clientExt !== ".yaml") {
+    const detail = clientExt.toLowerCase() === ".yaml" ? `flow files must use the lowercase .yaml extension, not "${clientExt}".` : `flow files must use the .yaml extension.`;
+    throw new FailureError(`Invalid flow_path "${clientPath}": ${detail}`, {
+      error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+      failure_stage: "flow_path_extension",
+      failure_area: "tool_server",
+      error_kind: "validation"
+    });
+  }
+  const flowName = bareExtension ? "" : path46.basename(clientPath, ".yaml");
+  assertSafeFlowName(flowName);
+  return flowName;
+}
 async function resolveFlowSource(params, fileInput, flowPathInput) {
   if (params.name === void 0 === (params.flow_path === void 0)) {
     throw new FailureError("Pass exactly one flow source: name or flow_path.", {
@@ -157361,15 +157472,9 @@ async function resolveFlowSource(params, fileInput, flowPathInput) {
   assertValidProjectRoot(params.project_root);
   if (params.flow_path !== void 0) {
     if (flowPathInput?.viaUpload) {
-      throw new FailureError(
-        `Invalid flow_path "${flowPathInput.clientPath}": explicit flow paths require a co-located client and tool server with a shared filesystem, and this one arrived as an upload \u2014 sibling run: files, baselines, and baseline write-back all resolve beside the copy this server materialized, alone in a temp directory. Pass name + project_root to run a self-contained flow from a remote client; name uploads the same way, so a flow with run:, script: or snapshot: steps needs the client and tool server on one filesystem.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_path_shared_filesystem",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
+      const clientPath2 = flowPathInput.clientPath;
+      assertFlowPathShape(clientPath2);
+      return { filePath: params.flow_path, flowName: flowNameOf(clientPath2), viaUpload: true };
     }
     const isVerifiedHostPath = flowPathInput?.presentOnHost === true && flowPathInput.statVerified === true && path46.resolve(params.flow_path) === path46.resolve(flowPathInput.clientPath);
     if (!isVerifiedHostPath) {
@@ -157383,42 +157488,9 @@ async function resolveFlowSource(params, fileInput, flowPathInput) {
         }
       );
     }
-    if (!path46.isAbsolute(params.flow_path)) {
-      throw new FailureError(
-        `Invalid flow_path "${params.flow_path}": flow paths must be absolute \u2014 a relative path is resolved against the tool server's working directory, not the caller's. Pass the absolute path to the flow's YAML.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_path_absolute",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
-    }
-    if (params.flow_path.split(/[\\/]+/).includes("..")) {
-      throw new FailureError(
-        `Invalid flow_path "${params.flow_path}": flow paths must not contain ".." segments \u2014 a ".." after a symlinked directory can name a different file than the spelling suggests, and the argent client always sends fully resolved paths. Pass the fully resolved absolute path to the flow's YAML.`,
-        {
-          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-          failure_stage: "flow_path_dotdot",
-          failure_area: "tool_server",
-          error_kind: "validation"
-        }
-      );
-    }
+    assertFlowPathShape(params.flow_path);
     const clientPath = flowPathInput.clientPath;
-    const clientExt = path46.extname(clientPath);
-    const bareExtension = path46.basename(clientPath).toLowerCase() === ".yaml";
-    if (!bareExtension && clientExt !== ".yaml") {
-      const detail = clientExt.toLowerCase() === ".yaml" ? `flow files must use the lowercase .yaml extension, not "${clientExt}".` : `flow files must use the .yaml extension.`;
-      throw new FailureError(`Invalid flow_path "${clientPath}": ${detail}`, {
-        error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-        failure_stage: "flow_path_extension",
-        failure_area: "tool_server",
-        error_kind: "validation"
-      });
-    }
-    const flowName2 = bareExtension ? "" : path46.basename(clientPath, ".yaml");
-    assertSafeFlowName(flowName2);
+    const flowName2 = flowNameOf(clientPath);
     const suppliedBase = path46.basename(clientPath);
     const spelling2 = await classifyOnDiskSpelling(path46.dirname(params.flow_path), suppliedBase);
     if (spelling2.state !== "listed") {
@@ -157481,7 +157553,7 @@ var zodSchema69 = external_exports.object({
     "Path to the flow .yaml as readable by the tool-server. Internal \u2014 the argent client derives it from project_root and name automatically; leave unset."
   ),
   flow_path: external_exports.string().optional().describe(
-    "Omit when name is set. Absolute path to a co-located flow .yaml on the client and tool server's shared filesystem. This must be supplied through the file-input boundary. Pass the same flow source here as to flow-execute, so the prerequisite you read belongs to the flow that will run; for remote reads, pass name + project_root instead."
+    "Omit when name is set. Absolute path to a flow .yaml on the client. Over a link (argent link or ARGENT_TOOLS_URL), the argent client uploads the file and the tool-server reads the uploaded copy; without a link, the tool-server reads the file in place. Pass the path through the argent client; a raw path that the file-input boundary did not verify is rejected. Pass the same flow source here as to flow-execute, so the prerequisite you read belongs to the flow that will run."
   )
 }).superRefine((params, ctx) => {
   if (params.name === void 0 === (params.flow_path === void 0)) {

package/package.json

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

package/skills/argent-create-flow/references/live-authoring.md

@@ -266,7 +266,7 @@ Resolve every hit and confirm:
 
 Run `flow-execute` on the complete YAML with the absolute project root. For a fragment, verify its prerequisite before setting `prerequisiteAcknowledged: true`.
 
-`flow-execute` takes exactly one flow source: `name`, for a flow saved under `.argent/flows/`, or `flow_path`, an absolute path to any flow `.yaml`. `run:` targets and baselines resolve on the tool server's filesystem, beside the YAML it actually reads. `flow_path` therefore requires the agent and the tool server to share a filesystem and is refused when they do not. `name` still runs remotely, but the server receives only that one YAML in a fresh temp directory. It checks the whole flow first and refuses a `run:`, `script:`, or `snapshot:` step at any depth, naming the missing co-location rather than a missing fragment, script, or baseline. Replay self-contained flows remotely; a composing, scripting, or snapshotting flow needs one shared filesystem.
+`flow-execute` takes exactly one flow source: `name`, for a flow saved under `.argent/flows/`, or `flow_path`, an absolute path to any flow `.yaml`. Over `argent link` or `ARGENT_TOOLS_URL`, either source sends only that one YAML file, and the tool server runs that copy. The server checks the whole flow before it runs the first step. It refuses a flow with a `run:`, `script:`, or `snapshot:` step, or with a `tool:` step that takes a file (such as `screenshot-diff`, `reinstall-app`, or `flow-execute`) or records a flow, at any depth. The error lists each such step. Replay only a self-contained flow over a link. A flow that composes, runs a script, or takes a snapshot runs only with no link and no `ARGENT_TOOLS_URL`, on the computer that runs the tool server.
 
 Manual rescue invalidates the pass. An `errored` step was never evaluated: an `idle` wait whose tree source could not be read, a step that threw, an unresolvable `run:` target, or a `launch:` that did not start the app. Read the reason — most name the environment, but a failed `launch:` is a verdict about the app. Unconfirmed focus is not in this class at all: the replay focus poll has no failure return, so a `type:` step whose focus was never confirmed is scored a **pass**, and only the value check after typing catches it.