@deeeed/metamask-harness 0.86.2 → 0.88.0

package/library/actions/mobile/platform/bridge.mjs

@@ -29,6 +29,13 @@ const { resolvePort } = configModule;
 // second import path into the cjs bridge-runtime.
 export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 export const MOBILE_BRIDGE_RESULT_ERROR_CODES = BRIDGE_RESULT_ERROR_CODES;
+// Budget exhaustion, kept apart from the bridge's CDP_TIMEOUT: ACTION_DEADLINE
+// is a bridge command its caller's deadline refused or cut short;
+// DOMAIN_SETUP_DEADLINE is a setup phase that ran out of its slice.
+export const MOBILE_BUDGET_ERROR_CODES = Object.freeze({
+  ACTION_DEADLINE: 'ACTION_DEADLINE',
+  DOMAIN_SETUP_DEADLINE: 'DOMAIN_SETUP_DEADLINE',
+});
 
 const execFileAsync = promisify(execFile);
 const ACTION_DEADLINE_FIELD = '_action_deadline_epoch_ms';
@@ -256,7 +263,11 @@ export function resolveMobileTarget(input) {
   const iosSimulator = input.node?.simulator ?? input.node?.ios_simulator ?? contextEnv.IOS_SIMULATOR ?? process.env.IOS_SIMULATOR;
   const androidDevice = input.node?.android_device ?? contextEnv.ANDROID_DEVICE ?? process.env.ANDROID_DEVICE;
   const androidTargetDeviceName = input.node?.android_target_device_name ?? input.node?.androidTargetDeviceName ?? contextEnv.ANDROID_TARGET_DEVICE_NAME ?? process.env.ANDROID_TARGET_DEVICE_NAME;
-  const adbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL ?? androidDevice;
+  const explicitAdbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const adbSerial = explicitAdbSerial ?? androidDevice;
+  // Only an explicit adb serial says which device class answers: ANDROID_DEVICE
+  // alone can be an AVD or Metro device name.
+  const physicalAndroid = Boolean(explicitAdbSerial) && !isAndroidEmulatorSerial(explicitAdbSerial);
   if (requestedPlatform === 'ios') {
     return {
       watcherPort,
@@ -264,6 +275,7 @@ export function resolveMobileTarget(input) {
       androidDevice: undefined,
       androidTargetDeviceName: undefined,
       adbSerial: undefined,
+      physicalAndroid: false,
       requestedPlatform,
     };
   }
@@ -274,6 +286,7 @@ export function resolveMobileTarget(input) {
       androidDevice,
       androidTargetDeviceName,
       adbSerial,
+      physicalAndroid,
       requestedPlatform,
     };
   }
@@ -283,10 +296,15 @@ export function resolveMobileTarget(input) {
     androidDevice,
     androidTargetDeviceName,
     adbSerial,
+    physicalAndroid,
     requestedPlatform,
   };
 }
 
+export function isAndroidEmulatorSerial(serial) {
+  return String(serial ?? '').startsWith('emulator-');
+}
+
 export async function openExternalDeeplink(input, url, timeout = 15000) {
   const target = resolveMobileTarget(input);
   const requestedPlatform = String(
@@ -470,17 +488,17 @@ export async function bridgeCommand(input, args) {
     ? actionDeadline - Date.now()
     : configuredTimeoutMs;
   if (remainingActionMs <= 0) {
-    throw coded(
-      new Error(
-        `Mobile CDP bridge command did not start before its action deadline: ${String(args[0] ?? 'unknown')}`,
-      ),
-      BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+    const error = new Error(
+      `ACTION_DEADLINE: bridge command ${String(args[0] ?? 'unknown')} was not started; its action deadline passed ${Math.round(-remainingActionMs)}ms ago (per-command limit ${configuredTimeoutMs}ms).`,
     );
+    error.deadlineEpochMs = actionDeadline;
+    throw coded(error, MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE);
   }
   const timeoutMs = Math.max(
     1,
     Math.min(configuredTimeoutMs, remainingActionMs),
   );
+  const cutByActionDeadline = timeoutMs < configuredTimeoutMs;
   const result = await new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
@@ -521,8 +539,20 @@ export async function bridgeCommand(input, args) {
   });
   if (result.timedOut) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
+    // A timer the action deadline shortened means the caller's budget ran out,
+    // not the bridge: say so, and keep it out of the target-transition codes
+    // so route waits stop instead of retrying refused commands.
+    if (cutByActionDeadline) {
+      const error = new Error(
+        `ACTION_DEADLINE: bridge command ${String(args[0] ?? 'unknown')} was stopped after ${result.timeoutMs}ms when its action deadline ended (per-command limit ${configuredTimeoutMs}ms): ${command}`,
+      );
+      error.deadlineEpochMs = actionDeadline;
+      throw coded(error, MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE);
+    }
     throw coded(
-      new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`),
+      new Error(
+        `Mobile CDP bridge command timed out after ${result.timeoutMs}ms (CDP_COMMAND_TIMEOUT: per-command limit ${configuredTimeoutMs}ms${Number.isFinite(actionDeadline) ? `, action budget had ${Math.max(0, Math.round(actionDeadline - Date.now()))}ms left` : ''}): ${command}`,
+      ),
       BRIDGE_ERROR_CODES.CDP_TIMEOUT,
     );
   }
@@ -628,6 +658,13 @@ export function isTargetTransition(error) {
   return TARGET_TRANSITION_CODES.has(error?.code);
 }
 
+// A read a target transition interrupted, or the action deadline cut short,
+// has no answer yet. Polling callers treat it as "not yet" so their own loop
+// ends at the deadline with its own timeout message.
+export function isUnansweredRead(error) {
+  return isTargetTransition(error) || error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE;
+}
+
 function valueContains(actual, expected) {
   if (Array.isArray(expected)) {
     return Array.isArray(actual) &&
@@ -675,19 +712,140 @@ export function earliestDeadline(input, deadline) {
 
 // The earlier of now + timeoutMs and the calling action's deadline. Route waits
 // use it because past the action deadline bridgeCommand refuses to start
-// get-route (CDP_TIMEOUT): polling on would only retry that refusal and could
-// never see a route that did arrive.
+// get-route (ACTION_DEADLINE): polling on would only retry that refusal and
+// could never see a route that did arrive.
 export function deadlineFromTimeout(input, timeoutMs) {
   return earliestDeadline(input, Date.now() + Math.max(0, Number(timeoutMs)));
 }
 
+// Default budgets by device class. A physical Android device over USB answers
+// bridge calls in 0.1-0.5 s when idle and slower while the app is busy; a Perps
+// market-details -> home navigation on a Pixel 6a took ~18 s. Emulators and
+// simulators keep the shorter budgets so a real hang there still fails fast.
+const MOBILE_BUDGET_DEFAULTS = Object.freeze({
+  virtual: { setupMs: 30_000, navigationMs: 15_000 },
+  physical: { setupMs: 60_000, navigationMs: 30_000 },
+});
+// Per bridge command inside a domain setup, so one hung command cannot spend
+// the whole setup budget. Recipes override it with cdp_timeout_ms.
+export const SETUP_COMMAND_TIMEOUT_MS = 15_000;
+
+function positiveMs(value) {
+  const ms = Number(value);
+  return value !== null && value !== '' && Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+
+// Env overrides (MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS,
+// MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS) replace the device-class defaults;
+// a node's own timeout_ms / navigation_timeout_ms still wins over both.
+export function mobileBudgetDefaults(input) {
+  const env = { ...process.env, ...(input.context?.env || {}) };
+  const deviceClass = resolveMobileTarget(input).physicalAndroid ? 'physical' : 'virtual';
+  const defaults = MOBILE_BUDGET_DEFAULTS[deviceClass];
+  return {
+    deviceClass,
+    setupMs: positiveMs(env.MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS) ?? defaults.setupMs,
+    navigationMs:
+      positiveMs(env.MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS) ?? defaults.navigationMs,
+  };
+}
+
+export function mobileNavigationTimeoutMs(input) {
+  return positiveMs(input.node?.navigation_timeout_ms) ?? mobileBudgetDefaults(input).navigationMs;
+}
+
+export function mobileSetupTimeoutMs(input) {
+  return positiveMs(input.node?.timeout_ms) ?? mobileBudgetDefaults(input).setupMs;
+}
+
+// One overall budget for a multi-step domain setup (unlock, navigation, state
+// convergence). Each phase runs on its own deadline: the rest of the setup
+// budget, or less when sliceMs bounds it. Each bridge command inside a phase
+// gets the per-command limit, capped by that phase deadline. A phase that runs
+// out of time fails as DOMAIN_SETUP_DEADLINE naming the phase and both limits,
+// not as a CDP timeout of whichever command happened to be running.
+export function createSetupBudget(input, action) {
+  const { deviceClass } = mobileBudgetDefaults(input);
+  const navigationMs = mobileNavigationTimeoutMs(input);
+  const commandMs =
+    positiveMs(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms) ??
+    SETUP_COMMAND_TIMEOUT_MS;
+  const startedAt = Date.now();
+  const deadline = deadlineFromTimeout(input, mobileSetupTimeoutMs(input));
+  const limitMs = deadline - startedAt;
+
+  function deadlineError(phase, phaseStartedAt, phaseLimitMs, sliced, cause) {
+    const now = Date.now();
+    const budget = {
+      action,
+      phase,
+      deviceClass,
+      phaseElapsedMs: now - phaseStartedAt,
+      phaseLimitMs,
+      setupElapsedMs: now - startedAt,
+      setupLimitMs: limitMs,
+    };
+    const phaseText = cause === null
+      ? `phase '${phase}' could not start`
+      : `phase '${phase}' ran ${budget.phaseElapsedMs}ms of its ${phaseLimitMs}ms ${sliced ? 'slice' : 'share of the setup budget'}`;
+    const error = new Error(
+      `DOMAIN_SETUP_DEADLINE: ${action} ${phaseText}; setup ran ${budget.setupElapsedMs}ms of ${limitMs}ms (${deviceClass} device). ` +
+        `Raise timeout_ms (setup) or navigation_timeout_ms (navigation slice) on the node, or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS / MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS.` +
+        (cause === null ? '' : `\n  Cause: ${String(cause?.message ?? cause)}`),
+      cause === null ? undefined : { cause },
+    );
+    error.budget = budget;
+    return coded(error, MOBILE_BUDGET_ERROR_CODES.DOMAIN_SETUP_DEADLINE);
+  }
+
+  return {
+    deadline,
+    limitMs,
+    navigationMs,
+    async phase(name, run, { sliceMs } = {}) {
+      const phaseStartedAt = Date.now();
+      const sliced = sliceMs !== undefined && phaseStartedAt + sliceMs < deadline;
+      const phaseDeadline = sliced ? phaseStartedAt + sliceMs : deadline;
+      const phaseLimitMs = phaseDeadline - phaseStartedAt;
+      if (phaseLimitMs <= 0) {
+        throw deadlineError(name, phaseStartedAt, phaseLimitMs, false, null);
+      }
+      const commandLimitMs = Math.min(commandMs, phaseLimitMs);
+      const phaseInput = {
+        ...input,
+        node: {
+          ...input.node,
+          [ACTION_DEADLINE_FIELD]: phaseDeadline,
+          timeout_ms: phaseLimitMs,
+          bridge_timeout_ms: commandLimitMs,
+          cdp_timeout_ms: commandLimitMs,
+          controller_ready_timeout_ms: phaseLimitMs,
+          navigation_timeout_ms: Math.min(navigationMs, phaseLimitMs),
+        },
+      };
+      try {
+        return await run(phaseInput);
+      } catch (error) {
+        if (error?.code === MOBILE_BUDGET_ERROR_CODES.DOMAIN_SETUP_DEADLINE) throw error;
+        // A nested wait with its own shorter deadline is not this phase running out.
+        const phaseRanOut =
+          Date.now() >= phaseDeadline ||
+          (error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE &&
+            error.deadlineEpochMs >= phaseDeadline);
+        if (!phaseRanOut) throw error;
+        throw deadlineError(name, phaseStartedAt, phaseLimitMs, sliced, error);
+      }
+    },
+  };
+}
+
 async function waitForNextRouteProbe(deadline) {
   const remaining = deadline - Date.now();
   if (remaining > 0) await sleep(Math.min(250, remaining));
 }
 
 export async function navigate(input, route, params = {}, expectedRoute) {
-  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15000);
+  const timeoutMs = mobileNavigationTimeoutMs(input);
   let requestedRoute = String(expectedRoute ?? route);
   let requestedParams = requestedRoute === String(route) ? params : undefined;
   const nestedTarget = expectedRoute == null && typeof params?.screen === 'string';
@@ -850,6 +1008,9 @@ export async function waitForRoute(
     try {
       lastRoute = await bridgeCommand(input, ['get-route']);
     } catch (error) {
+      // The action deadline cut the last poll short: report the route wait
+      // (expected and last route) rather than that one poll.
+      if (error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE) break;
       if (!isTargetTransition(error)) throw error;
       lastTransitionError = error;
       transitionCodes.push(error.code);

package/library/actions/mobile/wallet/home.mjs

@@ -1,5 +1,10 @@
 // Open wallet home through WalletView, with a verified HomeNav fallback for older navigators.
-import { bridgeCommand, navigate, waitForRoute } from '../platform/bridge.mjs';
+import {
+  bridgeCommand,
+  mobileNavigationTimeoutMs,
+  navigate,
+  waitForRoute,
+} from '../platform/bridge.mjs';
 
 /**
  * Navigate to the wallet home across MetaMask Mobile navigation generations.
@@ -19,7 +24,7 @@ export async function navigateWalletHome(input) {
     const currentRoute = await waitForRoute(
       input,
       'WalletView',
-      Number(input.node?.navigation_timeout_ms ?? 15000),
+      mobileNavigationTimeoutMs(input),
     );
     return {
       navigation: {

package/library/actions/mobile/wallet/select_account.mjs

@@ -5,14 +5,18 @@ import { pathToFileURL } from 'node:url';
 import {
   bridgeCommand,
   MOBILE_BRIDGE_ERROR_CODES,
+  MOBILE_BUDGET_ERROR_CODES,
   runAdapter,
 } from '../platform/bridge.mjs';
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A switch-account write cut short by the deadline may still have landed, so
+// ACTION_DEADLINE leaves the outcome as unknown as a transport failure does.
 const TRANSIENT_READ_CODES = new Set([
   MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
   MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
   MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE,
 ]);
 const READ_ATTEMPT_TIMEOUT_MS = 10_000;
 

package/library/actions/shared/app/live-adapter-deadline.mjs

@@ -0,0 +1,8 @@
+// The epoch ms by which a live adapter action must finish. The runner kills a
+// live adapter process liveAdapterProcessTimeoutMs(node) after starting it.
+
+import { liveAdapterProcessTimeoutMs } from '@farmslot/recipe-cli/harness';
+
+export function liveAdapterDeadline(node, reserveMs = 5_000) {
+  return performance.timeOrigin + liveAdapterProcessTimeoutMs(node ?? {}) - reserveMs;
+}