@swmansion/argent 0.25.1-next.34 → 0.25.1-next.35

package/dist/cli-cmds.mjs

@@ -2372,6 +2372,8 @@ var FAILURE_CODES = {
   ANDROID_DEVTOOLS_WRONG_PLATFORM: "ANDROID_DEVTOOLS_WRONG_PLATFORM",
   ANDROID_DEVTOOLS_DEVICE_ID_INVALID: "ANDROID_DEVTOOLS_DEVICE_ID_INVALID",
   ANDROID_DEVTOOLS_HELPER_TERMINATED: "ANDROID_DEVTOOLS_HELPER_TERMINATED",
+  ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED: "ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED",
+  ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED: "ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED",
   ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED: "ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED",
   ANDROID_DEVTOOLS_RPC_ERROR: "ANDROID_DEVTOOLS_RPC_ERROR",
   ANDROID_DEVTOOLS_RPC_TIMEOUT: "ANDROID_DEVTOOLS_RPC_TIMEOUT",
@@ -21857,7 +21859,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.34";
+    return "0.25.1-next.35";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -15744,6 +15744,8 @@ var FAILURE_CODES = {
   ANDROID_DEVTOOLS_WRONG_PLATFORM: "ANDROID_DEVTOOLS_WRONG_PLATFORM",
   ANDROID_DEVTOOLS_DEVICE_ID_INVALID: "ANDROID_DEVTOOLS_DEVICE_ID_INVALID",
   ANDROID_DEVTOOLS_HELPER_TERMINATED: "ANDROID_DEVTOOLS_HELPER_TERMINATED",
+  ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED: "ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED",
+  ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED: "ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED",
   ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED: "ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED",
   ANDROID_DEVTOOLS_RPC_ERROR: "ANDROID_DEVTOOLS_RPC_ERROR",
   ANDROID_DEVTOOLS_RPC_TIMEOUT: "ANDROID_DEVTOOLS_RPC_TIMEOUT",
@@ -16710,7 +16712,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.34";
+    return "0.25.1-next.35";
   }
   return "0.0.0";
 }

package/dist/mcp-server.mjs

@@ -16552,6 +16552,8 @@ var FAILURE_CODES = {
   ANDROID_DEVTOOLS_WRONG_PLATFORM: "ANDROID_DEVTOOLS_WRONG_PLATFORM",
   ANDROID_DEVTOOLS_DEVICE_ID_INVALID: "ANDROID_DEVTOOLS_DEVICE_ID_INVALID",
   ANDROID_DEVTOOLS_HELPER_TERMINATED: "ANDROID_DEVTOOLS_HELPER_TERMINATED",
+  ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED: "ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED",
+  ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED: "ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED",
   ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED: "ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED",
   ANDROID_DEVTOOLS_RPC_ERROR: "ANDROID_DEVTOOLS_RPC_ERROR",
   ANDROID_DEVTOOLS_RPC_TIMEOUT: "ANDROID_DEVTOOLS_RPC_TIMEOUT",

package/dist/tool-server.cjs

@@ -698,6 +698,8 @@ var init_failure_codes = __esm({
       ANDROID_DEVTOOLS_WRONG_PLATFORM: "ANDROID_DEVTOOLS_WRONG_PLATFORM",
       ANDROID_DEVTOOLS_DEVICE_ID_INVALID: "ANDROID_DEVTOOLS_DEVICE_ID_INVALID",
       ANDROID_DEVTOOLS_HELPER_TERMINATED: "ANDROID_DEVTOOLS_HELPER_TERMINATED",
+      ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED: "ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED",
+      ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED: "ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED",
       ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED: "ANDROID_DEVTOOLS_RPC_CLIENT_CLOSED",
       ANDROID_DEVTOOLS_RPC_ERROR: "ANDROID_DEVTOOLS_RPC_ERROR",
       ANDROID_DEVTOOLS_RPC_TIMEOUT: "ANDROID_DEVTOOLS_RPC_TIMEOUT",
@@ -77006,8 +77008,8 @@ async function emulatorSupportsFlag(flag, options = {}) {
   } catch {
     return false;
   }
-  const cacheKey3 = `${emulatorPath}|${flag}`;
-  const cached3 = emulatorFlagSupportCache.get(cacheKey3);
+  const cacheKey2 = `${emulatorPath}|${flag}`;
+  const cached3 = emulatorFlagSupportCache.get(cacheKey2);
   if (cached3 !== void 0) return cached3;
   let output;
   let failure = null;
@@ -77034,7 +77036,7 @@ async function emulatorSupportsFlag(flag, options = {}) {
     return false;
   }
   const supported = output.includes(flag);
-  emulatorFlagSupportCache.set(cacheKey3, supported);
+  emulatorFlagSupportCache.set(cacheKey2, supported);
   return supported;
 }
 function describeAdbFailure(args, err) {
@@ -94704,7 +94706,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.34";
+    return "0.25.1-next.35";
   }
   return "0.0.0";
 }
@@ -112897,10 +112899,6 @@ init_android_binary();
 
 // ../tool-server/src/utils/android-helper-install.ts
 init_adb();
-var installedHelpers = /* @__PURE__ */ new Map();
-function cacheKey(serial, versionCode) {
-  return `${serial}|${versionCode}`;
-}
 async function probeInstalledVersion(serial, packageName) {
   let out;
   try {
@@ -112923,17 +112921,17 @@ async function probeInstalledVersion(serial, packageName) {
   }
   return { installed: false, versionCode: null };
 }
-async function ensureAndroidDevtoolsInstalled(serial) {
+async function ensureAndroidDevtoolsInstalled(serial, options = {}) {
   const manifest = helperManifest();
-  const key2 = cacheKey(serial, manifest.versionCode);
-  if (installedHelpers.has(key2)) return;
-  const probe3 = await probeInstalledVersion(serial, manifest.packageName);
-  if (probe3.installed && probe3.versionCode !== null && probe3.versionCode >= manifest.versionCode) {
-    installedHelpers.set(key2, true);
-    return;
+  if (!options.force) {
+    const probe3 = await probeInstalledVersion(serial, manifest.packageName);
+    if (probe3.installed && (probe3.versionCode === null || probe3.versionCode >= manifest.versionCode)) {
+      return;
+    }
   }
   const apkPath = bundledHelperApkPath();
-  const args = ["-s", serial, "install", ...manifest.installFlags, apkPath];
+  const flags = options.force ? [...manifest.installFlags, "-d"] : manifest.installFlags;
+  const args = ["-s", serial, "install", ...flags, apkPath];
   try {
     await runAdb(args, { timeoutMs: 6e4 });
   } catch (err) {
@@ -112948,7 +112946,6 @@ async function ensureAndroidDevtoolsInstalled(serial) {
       throw err;
     }
   }
-  installedHelpers.set(key2, true);
 }
 
 // ../tool-server/src/utils/android-devtools-client.ts
@@ -113092,14 +113089,28 @@ function androidDevtoolsRef(device) {
   };
 }
 var READY_TIMEOUT_MS2 = 3e4;
+var EXIT_GRACE_MS = 200;
 var HELPER_PORT_MARKER = /^INSTRUMENTATION_STATUS:\s*port=(\d+)/;
 var ADB_FORWARD_PORT_MARKER = /^(\d+)\s*$/;
+var HELPER_STATUS_MARKER = /^INSTRUMENTATION_STATUS:\s*Error=/;
+var HELPER_STATUS_MAX_CHARS = 400;
+function classifyHelperSpawnFault(text) {
+  return /Unable to find instrumentation (?:info|target package)/i.test(text) ? "instrumentation-missing" : "unknown";
+}
+var HelperSpawnError = class extends FailureError {
+  fault;
+  constructor(message, signal, fault) {
+    super(message, signal);
+    this.name = "HelperSpawnError";
+    this.fault = fault;
+  }
+};
 async function spawnHelper(serial) {
   const manifest = helperManifest();
   const adbPath = await resolveAndroidBinary("adb");
   if (!adbPath) {
     throw new FailureError(
-      "`adb` not found on PATH or under `$ANDROID_HOME/platform-tools` while spawning android-devtools helper.",
+      "`adb` not found on PATH or under `$ANDROID_HOME/platform-tools` while spawning the argent android helper.",
       {
         error_code: FAILURE_CODES.ANDROID_DEVTOOLS_ADB_NOT_FOUND,
         failure_stage: "android_devtools_spawn_helper",
@@ -113118,10 +113129,13 @@ async function spawnHelper(serial) {
     let localPort = null;
     let settled = false;
     let stderrBuf = "";
+    let statusBuf = "";
+    let exitGrace;
     const settle = (fn, cleanup) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      clearTimeout(exitGrace);
       rl.close();
       cleanup?.();
       fn();
@@ -113129,6 +113143,9 @@ async function spawnHelper(serial) {
     const rl = readline2.createInterface({ input: proc.stdout });
     rl.on("line", async (rawLine) => {
       const line = rawLine.trim();
+      if (statusBuf.length < HELPER_STATUS_MAX_CHARS && HELPER_STATUS_MARKER.test(line)) {
+        statusBuf = (statusBuf ? `${statusBuf} ${line}` : line).slice(0, HELPER_STATUS_MAX_CHARS);
+      }
       const portMatch = HELPER_PORT_MARKER.exec(line);
       if (!portMatch || devicePort !== null) return;
       devicePort = parseInt(portMatch[1], 10);
@@ -113158,25 +113175,32 @@ async function spawnHelper(serial) {
       stderrBuf += data.toString("utf-8");
       if (stderrBuf.length > 4 * 1024) stderrBuf = stderrBuf.slice(-4 * 1024);
     });
-    proc.on("exit", (code, signal) => {
-      const detail = stderrBuf.trim() ? ` stderr=${stderrBuf.trim().slice(0, 400)}` : "";
-      settle(
-        () => reject(
-          new FailureError(
-            `am instrument exited before becoming ready (code=${code} signal=${signal}).${detail}`,
-            {
-              error_code: FAILURE_CODES.ANDROID_DEVTOOLS_HELPER_EXITED_BEFORE_READY,
-              failure_stage: "android_devtools_helper_ready",
-              failure_area: "tool_server",
-              error_kind: "subprocess",
-              failure_command: "android_devtools",
-              ...typeof code === "number" ? { failure_exit_code: code } : {},
-              ...signal === "SIGABRT" || signal === "SIGHUP" || signal === "SIGINT" || signal === "SIGKILL" || signal === "SIGQUIT" || signal === "SIGTERM" ? { failure_signal: signal } : {}
-            }
-          )
+    let exitCode = null;
+    let exitSignal = null;
+    const rejectExited = () => {
+      const detail = statusBuf ? statusBuf : stderrBuf.trim() ? `code=${exitCode} signal=${exitSignal}. stderr=${stderrBuf.trim().slice(0, 200)}` : `code=${exitCode} signal=${exitSignal}`;
+      reject(
+        new HelperSpawnError(
+          `am instrument exited before becoming ready: ${detail}`,
+          {
+            error_code: FAILURE_CODES.ANDROID_DEVTOOLS_HELPER_EXITED_BEFORE_READY,
+            failure_stage: "android_devtools_helper_ready",
+            failure_area: "tool_server",
+            error_kind: "subprocess",
+            failure_command: "android_devtools",
+            ...typeof exitCode === "number" ? { failure_exit_code: exitCode } : {},
+            ...exitSignal === "SIGABRT" || exitSignal === "SIGHUP" || exitSignal === "SIGINT" || exitSignal === "SIGKILL" || exitSignal === "SIGQUIT" || exitSignal === "SIGTERM" ? { failure_signal: exitSignal } : {}
+          },
+          classifyHelperSpawnFault(statusBuf)
         )
       );
+    };
+    proc.on("exit", (code, signal) => {
+      exitCode = code;
+      exitSignal = signal;
+      exitGrace = setTimeout(() => settle(rejectExited), EXIT_GRACE_MS);
     });
+    proc.on("close", () => settle(rejectExited));
     proc.on("error", (err) => {
       settle(
         () => reject(
@@ -113211,6 +113235,50 @@ async function spawnHelper(serial) {
     }, READY_TIMEOUT_MS2);
   });
 }
+async function installHelper(serial, options) {
+  try {
+    await ensureAndroidDevtoolsInstalled(serial, options);
+  } catch (err) {
+    const cause = err instanceof Error ? err : new Error(String(err));
+    const reason = cause.message.replace(/^.*? failed: /s, "").replace(/\s+/g, " ").trim().slice(0, 200);
+    throw new FailureError(
+      `the argent android helper is not installed on ${serial} and could not be installed: ${reason}`,
+      {
+        error_code: FAILURE_CODES.ANDROID_DEVTOOLS_HELPER_INSTALL_FAILED,
+        failure_stage: "android_devtools_helper_install",
+        failure_area: "tool_server",
+        error_kind: "subprocess",
+        failure_command: "adb"
+      },
+      { cause }
+    );
+  }
+}
+async function spawnHelperWithRepair(serial) {
+  await installHelper(serial, {});
+  try {
+    return await spawnHelper(serial);
+  } catch (err) {
+    if (!(err instanceof HelperSpawnError) || err.fault !== "instrumentation-missing") throw err;
+    await installHelper(serial, { force: true });
+    try {
+      return await spawnHelper(serial);
+    } catch (repairErr) {
+      if (!(repairErr instanceof HelperSpawnError)) throw repairErr;
+      throw new FailureError(
+        `the argent android helper could not start on ${serial} even after reinstalling it: ${repairErr.message}`,
+        {
+          error_code: FAILURE_CODES.ANDROID_DEVTOOLS_HELPER_REPAIR_FAILED,
+          failure_stage: "android_devtools_helper_repair",
+          failure_area: "tool_server",
+          error_kind: "subprocess",
+          failure_command: "android_devtools"
+        },
+        { cause: repairErr }
+      );
+    }
+  }
+}
 async function removeAdbForward(serial, localPort) {
   try {
     await runAdb(["-s", serial, "forward", "--remove", `tcp:${localPort}`], { timeoutMs: 5e3 });
@@ -113260,8 +113328,7 @@ var androidDevtoolsBlueprint = {
     }
     const serial = device.id;
     const events = new TypedEventEmitter();
-    await ensureAndroidDevtoolsInstalled(serial);
-    const spawned = await spawnHelper(serial);
+    const spawned = await spawnHelperWithRepair(serial);
     let ready2 = false;
     let disposed = false;
     let client2;
@@ -115528,13 +115595,13 @@ async function ensureRunnerArtifact(config2, opts = {}) {
     xcodeVersionFingerprint()
   ]);
   const staticArgs = runnerBuildStaticArgs(projectPath, config2);
-  const cacheKey3 = computeRunnerCacheKey(sourcesHash, xcodeVersion, staticArgs);
+  const cacheKey2 = computeRunnerCacheKey(sourcesHash, xcodeVersion, staticArgs);
   const derivedDataPath = derivedDir();
   const build = opts.build ?? buildRunnerArtifact;
   return withRunnerBuildLock(async () => {
     const stampPath = path21.join(derivedDataPath, CACHE_KEY_FILE);
     const stamped = await fsp.readFile(stampPath, "utf8").catch(() => null);
-    if (!opts.force && stamped === cacheKey3) {
+    if (!opts.force && stamped === cacheKey2) {
       const cached3 = findBaseXctestrun(derivedDataPath);
       const expiresAt = await readRunnerExpiryDate(derivedDataPath);
       const needsRenew = expiresAt !== null && profileNeedsRenewal(expiresAt, /* @__PURE__ */ new Date());
@@ -115546,14 +115613,14 @@ async function ensureRunnerArtifact(config2, opts = {}) {
         };
       }
     }
-    if (stamped !== cacheKey3) {
+    if (stamped !== cacheKey2) {
       await fsp.rm(derivedDataPath, {
         recursive: true,
         force: true
       });
     }
     const built = await build(derivedDataPath, staticArgs, opts.destinationUdid);
-    await fsp.writeFile(stampPath, cacheKey3);
+    await fsp.writeFile(stampPath, cacheKey2);
     return built;
   });
 }
@@ -119852,17 +119919,17 @@ var reactProfilerSessionBlueprint = {
   }
 };
 var profilerPathsCache = /* @__PURE__ */ new Map();
-function cacheKey2(port, deviceId) {
+function cacheKey(port, deviceId) {
   return `${port}:${deviceId}`;
 }
 function cacheProfilerPaths(port, paths, deviceId) {
-  profilerPathsCache.set(cacheKey2(port, deviceId), paths);
+  profilerPathsCache.set(cacheKey(port, deviceId), paths);
 }
 function getCachedProfilerPaths(port, deviceId) {
-  return profilerPathsCache.get(cacheKey2(port, deviceId));
+  return profilerPathsCache.get(cacheKey(port, deviceId));
 }
 function clearCachedProfilerPaths(port, deviceId) {
-  profilerPathsCache.delete(cacheKey2(port, deviceId));
+  profilerPathsCache.delete(cacheKey(port, deviceId));
 }
 
 // ../tool-server/src/tools/devices/boot-device.ts
@@ -148090,10 +148157,7 @@ async function queryAndroidFullHierarchy(registry2, device) {
     devtools = await registry2.resolveService(ref.urn, ref.options);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `the android devtools helper is unavailable (${msg}) \u2014 flows resolve testID selectors against the full hierarchy it serves; confirm the device is unlocked and the helper can be installed (\`adb install -t\`)`,
-      { cause: err }
-    );
+    throw new Error(`the argent android helper is unavailable: ${msg}`, { cause: err });
   }
   const [{ xml }, size] = await Promise.all([
     // clearCache: await/assert polls must see text changes, not cached reads.
@@ -149684,6 +149748,10 @@ function roleOnlySelectorWarning(selector) {
   if (selector.text !== void 0 || selector.textMatches !== void 0) return void 0;
   return `selector ${describeSelector(selector)} matches by role alone (the tapped element has no id or visible text) \u2014 replay takes whichever element of that role ranks first, so re-record against a labelled element if that is not reliably this one`;
 }
+function innermostTreeReason(message) {
+  const unwrapped = /helper is unavailable:\s*(.+)/s.exec(message)?.[1] ?? message;
+  return unwrapped.replace(/^\[[^\]]+\]\s*/, "").trim();
+}
 async function captureTapSelector(registry2, session, udid, point) {
   try {
     const device = resolveDevice(udid);
@@ -149715,8 +149783,9 @@ async function captureTapSelector(registry2, session, udid, point) {
     ].filter((w) => w !== void 0);
     return { selector, ...warnings.length > 0 ? { warning: warnings.join("; ") } : {} };
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     return {
-      warning: `selector capture failed (${err instanceof Error ? err.message : String(err)}); kept coordinates`
+      warning: `selector capture failed (${innermostTreeReason(message)}); kept coordinates`
     };
   }
 }
@@ -154224,9 +154293,9 @@ async function androidDevtoolsReady(registry2, device) {
   try {
     const ref = androidDevtoolsRef(device);
     const api = await registry2.resolveService(ref.urn, ref.options);
-    return api.isReady();
-  } catch {
-    return false;
+    return { ready: api.isReady() };
+  } catch (err) {
+    return { ready: false, reason: err instanceof Error ? err.message : String(err) };
   }
 }
 async function treeSourceGate(registry2, device, bundleId, signal) {
@@ -154246,9 +154315,9 @@ async function treeSourceGate(registry2, device, bundleId, signal) {
     }
   }
   if (device.platform === "android" && !signal?.aborted) {
-    const ready2 = await androidDevtoolsReady(registry2, device);
+    const { ready: ready2, reason } = await androidDevtoolsReady(registry2, device);
     if (!ready2 && !signal?.aborted) {
-      return `could not reach the Android devtools helper (full-hierarchy source for testID selectors). Confirm the device is unlocked and the argent helper can be installed (\`adb install -t\`); a locked device or a blocked install is the usual cause. Re-run once resolved.`;
+      return reason ? `the argent android helper is unavailable: ${reason}` : `the argent android helper is unavailable (full-hierarchy source for testID selectors).`;
     }
   }
   if (device.platform === "vega" && !signal?.aborted) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.25.1-next.34",
+  "version": "0.25.1-next.35",
   "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/reliability-and-recovery.md

@@ -74,11 +74,11 @@ A normally injectable app that is broken in the environment gets the same coordi
 
 While the required source is down, selector failures and raw-point capture are void. Restore the source and re-record affected taps.
 
-| Platform | Symptom                          | Recovery                                               |
-| -------- | -------------------------------- | ------------------------------------------------------ |
-| Android  | Cannot reach the devtools helper | Unlock the device, allow `adb install -t`, and rerun   |
-| Chromium | No reachable CDP session         | Boot again with `electronAppPath` and remote debugging |
-| Vega     | Toolkit returns no page source   | Relaunch an app built with automation support          |
+| Platform | Symptom                                | Recovery                                                                         |
+| -------- | -------------------------------------- | -------------------------------------------------------------------------------- |
+| Android  | Cannot reach the argent android helper | Argent reinstalls it once; if it persists, read the device's reason in the error |
+| Chromium | No reachable CDP session               | Boot again with `electronAppPath` and remote debugging                           |
+| Vega     | Toolkit returns no page source         | Relaunch an app built with automation support                                    |
 
 On Android, healthy `describe` output does not prove the flow tree is available. It can fall back to legacy `uiautomator`, while the runner refuses that trimmed fallback.