@deeeed/metamask-harness 0.43.0 → 0.44.0

package/library/actions/mobile/perps/perps.mjs

@@ -2,6 +2,7 @@ import { pathToFileURL } from 'node:url';
 import {
   bridgeCommand,
   evalAsync,
+  isTargetTransition,
   navigate,
   runAdapter,
 } from '../platform/bridge.mjs';
@@ -69,6 +70,126 @@ export async function measureHomepageVisible(input) {
   };
 }
 
+const MODE_TEST_IDS = {
+  lite: 'perps-mode-toggle-lite',
+  pro: 'perps-mode-toggle-pro',
+};
+const MODE_ROOT_TEST_IDS = {
+  lite: 'perps-market-details-view',
+  pro: 'perps-pro-market-scroll-view',
+};
+const READ_ATTEMPT_TIMEOUT_MS = 10_000;
+
+function withRemainingDeadline(input, deadline, attemptTimeoutMs) {
+  const remainingMs = Math.max(1, deadline - Date.now());
+  const boundedTimeout = (configured) =>
+    Math.min(
+      remainingMs,
+      Number(configured ?? remainingMs),
+      attemptTimeoutMs ?? remainingMs,
+    );
+  return {
+    ...input,
+    node: {
+      ...input.node,
+      _action_deadline_epoch_ms: deadline,
+      bridge_timeout_ms: boundedTimeout(input.node?.bridge_timeout_ms),
+      cdp_timeout_ms: boundedTimeout(input.node?.cdp_timeout_ms),
+      controller_ready_timeout_ms: boundedTimeout(
+        input.node?.controller_ready_timeout_ms,
+      ),
+    },
+  };
+}
+
+async function isModePresent(input, mode, deadline) {
+  const rootTarget = JSON.stringify({
+    testId: MODE_ROOT_TEST_IDS[mode],
+    visibility: 'viewport',
+  });
+  const controlTarget = JSON.stringify({
+    testId: MODE_TEST_IDS[mode],
+    visibility: 'tree',
+  });
+  const result = await evalAsync(
+    withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
+    `(function(){
+      const api = globalThis.__AGENTIC__;
+      if (!api || typeof api.queryUiTarget !== 'function') {
+        return Promise.resolve(JSON.stringify({ unsupported: true }));
+      }
+      return Promise.all([
+        api.queryUiTarget(${rootTarget}),
+        api.queryUiTarget(${controlTarget})
+      ]).then(function(values){
+        return JSON.stringify({ root: values[0], control: values[1] });
+      });
+    })()`,
+  );
+  if (result?.unsupported) {
+    throw new Error('metamask.perps.ensure_mode requires UI target queries.');
+  }
+  return result?.root?.visible === true && result?.control?.present === true;
+}
+
+async function readModePresence(input, mode, deadline) {
+  try {
+    return await isModePresent(input, mode, deadline);
+  } catch (error) {
+    if (!isTargetTransition(error)) throw error;
+    return null;
+  }
+}
+
+export async function ensureMode(input) {
+  const requestedMode = String(input.node?.mode ?? '');
+  if (!(requestedMode in MODE_TEST_IDS)) {
+    throw new Error('metamask.perps.ensure_mode requires mode=lite|pro.');
+  }
+  const otherMode = requestedMode === 'lite' ? 'pro' : 'lite';
+  const deadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
+  let switched = false;
+
+  while (Date.now() < deadline) {
+    const requestedModePresent = await readModePresence(
+      input,
+      requestedMode,
+      deadline,
+    );
+    if (requestedModePresent) {
+      return {
+        action: input.action,
+        mode: requestedMode,
+        alreadySelected: !switched,
+        proofPath: 'visible-market-detail-root-and-active-mode-control',
+      };
+    }
+    if (Date.now() >= deadline) break;
+    if (requestedModePresent !== null && !switched) {
+      const otherModePresent = await readModePresence(
+        input,
+        otherMode,
+        deadline,
+      );
+      if (otherModePresent && Date.now() < deadline) {
+        // The visible control names the mode it will switch to, not the mode
+        // currently selected.
+        const pressed = await bridgeCommand(withRemainingDeadline(input, deadline), [
+          'press-test-id',
+          MODE_TEST_IDS[otherMode],
+        ]);
+        if (pressed?.ok === false) {
+          throw new Error(String(pressed.error || 'Perps mode control press failed.'));
+        }
+        switched = true;
+      }
+    }
+    await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
+  }
+
+  throw new Error(`Perps did not reach ${requestedMode} mode before timeout.`);
+}
+
 export async function retryPerpsClientRead(
   read,
   { timeoutMs = 20000, intervalMs = 500, sleep: wait = sleep } = {},
@@ -1074,6 +1195,7 @@ const DIRECT_ACTIONS = new Map([
   ['metamask.perps.ensure_positions', ensurePositions],
   ['metamask.perps.ensure_orders', ensureOrders],
   ['metamask.perps.clear_performance_caches', clearPerformanceCaches],
+  ['metamask.perps.ensure_mode', ensureMode],
   ['metamask.perps.measure_homepage_visible', measureHomepageVisible],
   ['metamask.perps.start_state', startState],
   ['metamask.perps.teardown_state', teardownState],

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

@@ -26,6 +26,7 @@ const { resolvePort } = configModule;
 export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
+const ACTION_DEADLINE_FIELD = '_action_deadline_epoch_ms';
 
 let adapterActionActive = false;
 let actionBridgeLockPath = null;
@@ -117,14 +118,17 @@ function runtimeDir() {
  * Returns the trimmed ro.product.model value, or null when adb is unavailable
  * or the serial does not respond. Uses execFile (never shell interpolation).
  */
-async function resolveAndroidModel(adbSerial) {
+async function resolveAndroidModel(adbSerial, timeoutMs = 5_000) {
   const adbPath = resolveMobileToolPath('adb');
-  if (!adbPath) return null;
+  if (!adbPath || timeoutMs <= 0) return null;
   try {
     const { stdout } = await execFileAsync(
       adbPath,
       ['-s', adbSerial, 'shell', 'getprop', 'ro.product.model'],
-      { timeout: 5000, encoding: 'utf8' },
+      {
+        timeout: Math.max(1, Math.min(5_000, Math.floor(timeoutMs))),
+        encoding: 'utf8',
+      },
     );
     const model = stdout.trim();
     return model || null;
@@ -186,7 +190,11 @@ export async function bridgeEnv(input) {
       androidTargetDeviceName,
     )
   ) {
-    const model = await resolveAndroidModel(serialStr);
+    const deadline = Number(input.node?.[ACTION_DEADLINE_FIELD]);
+    const modelTimeoutMs = Number.isFinite(deadline)
+      ? deadline - Date.now()
+      : 5_000;
+    const model = await resolveAndroidModel(serialStr, modelTimeoutMs);
     if (model) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
     }
@@ -432,7 +440,6 @@ const TRANSIENT_NULL_COMMANDS = new Set(['get-route']);
 
 export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
-  // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
   const env = await bridgeEnv(input);
   const brokerSocket = brokerSocketPath(
     path.dirname(resolveBridgeLockPath(input, env)),
@@ -441,8 +448,33 @@ export async function bridgeCommand(input, args) {
   if (adapterActionActive && !existsSync(brokerSocket)) {
     env.CDP_BRIDGE_LOCK_OWNER_PID = await acquireActionBridgeLock(input, env);
   }
+  const actionDeadline = Number(input.node?.[ACTION_DEADLINE_FIELD]);
+  const configuredTimeoutValue = Number(
+    input.node?.bridge_timeout_ms ??
+      input.node?.cdp_timeout_ms ??
+      process.env.CDP_TIMEOUT ??
+      30000,
+  );
+  const configuredTimeoutMs =
+    Number.isFinite(configuredTimeoutValue) && configuredTimeoutValue > 0
+      ? configuredTimeoutValue
+      : 30_000;
+  const remainingActionMs = Number.isFinite(actionDeadline)
+    ? 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 timeoutMs = Math.max(
+    1,
+    Math.min(configuredTimeoutMs, remainingActionMs),
+  );
   const result = await new Promise((resolve, reject) => {
-    const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
       env: { ...env, APP_ROOT: input.context.projectRoot },
@@ -567,7 +599,7 @@ export async function evalAsync(input, expression) {
     } catch (error) {
       lastError = error;
       if (!String(error?.message ?? error).includes('CLIENT_NOT_INITIALIZED')) throw error;
-      await sleep(500);
+      await sleep(Math.min(500, Math.max(0, deadline - Date.now())));
     }
   }
   throw lastError ?? new Error('Timed out waiting for Mobile async evaluation.');
@@ -583,7 +615,7 @@ const TARGET_TRANSITION_CODES = new Set([
   BRIDGE_ERROR_CODES.WS_CLOSED,
 ]);
 
-function isTargetTransition(error) {
+export function isTargetTransition(error) {
   return TARGET_TRANSITION_CODES.has(error?.code);
 }
 

package/library/actions/mobile/platform/native-session.mjs

@@ -9,7 +9,7 @@ import {
 export function createNativeSession(input, domain, sessionSuffix = '') {
   const env = { ...process.env, ...(input.context?.env ?? {}) };
   const device = String(env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? '').trim();
-  if (!device) throw new Error(`Opaque Mobile ${domain} actions require one explicit Android device serial.`);
+  if (!device) throw new Error(`Mobile ${domain} native actions require one explicit Android device serial.`);
   const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
   const baseSession = nativeSessionName(env, device, app);
   const session = sessionSuffix

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

@@ -1,10 +1,7 @@
 import { runAdapter } from '../platform/bridge.mjs';
-import { isOpaqueMobileRuntime, lockWalletThroughNativeUi } from './native-ui.mjs';
+import { lockWalletThroughNativeUi } from './native-ui.mjs';
 
 runAdapter(async (input) => {
-  if (!isOpaqueMobileRuntime(input)) {
-    throw new Error('metamask.wallet.lock requires an opaque Mobile runtime.');
-  }
   return {
     action: input.action,
     ...await lockWalletThroughNativeUi(input),

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

@@ -1,7 +1,87 @@
 import { pathToFileURL } from 'node:url';
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import {
+  bridgeCommand,
+  MOBILE_BRIDGE_ERROR_CODES,
+  runAdapter,
+} from '../platform/bridge.mjs';
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const TRANSIENT_READ_CODES = new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+]);
+const READ_ATTEMPT_TIMEOUT_MS = 10_000;
+
+function withRemainingDeadline(input, deadline, attemptTimeoutMs) {
+  const remainingMs = Math.max(1, deadline - Date.now());
+  const boundedTimeout = (configured) =>
+    Math.min(
+      remainingMs,
+      Number(configured ?? remainingMs),
+      attemptTimeoutMs ?? remainingMs,
+    );
+  return {
+    ...input,
+    node: {
+      ...input.node,
+      _action_deadline_epoch_ms: deadline,
+      bridge_timeout_ms: boundedTimeout(input.node?.bridge_timeout_ms),
+      cdp_timeout_ms: boundedTimeout(input.node?.cdp_timeout_ms),
+    },
+  };
+}
+
+async function readSelectedAccount(input, deadline) {
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await bridgeCommand(
+        withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
+        ['get-selected-account'],
+      );
+    } catch (error) {
+      if (!TRANSIENT_READ_CODES.has(error?.code)) throw error;
+      lastError = error;
+      await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+    }
+  }
+  throw lastError ?? new Error('Timed out reading the selected Mobile account.');
+}
+
+async function readAccounts(input, deadline) {
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await bridgeCommand(
+        withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
+        ['list-accounts'],
+      );
+    } catch (error) {
+      if (!TRANSIENT_READ_CODES.has(error?.code)) throw error;
+      lastError = error;
+      await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+    }
+  }
+  throw lastError ?? new Error('Timed out reading Mobile accounts.');
+}
+
+function ambiguousWriteFailure(writeError, match, finalSelected, readError) {
+  const failure = new Error(
+    `Mobile account switch to ${match.address} returned an ambiguous ${String(writeError.code)} error and did not converge before the deadline; ` +
+      `writeError=${String(writeError.message ?? writeError)}; finalSelectedAccount=${JSON.stringify(finalSelected)}${
+        readError
+          ? `; finalReadError=${String(readError.message ?? readError)}`
+          : ''
+      }.`,
+    { cause: writeError },
+  );
+  failure.code = writeError.code;
+  failure.writeError = writeError;
+  failure.finalSelectedAccount = finalSelected;
+  if (readError) failure.finalReadError = readError;
+  return failure;
+}
 
 export async function selectAccount(input) {
   const requestedAddress = input.node?.address ? String(input.node.address).toLowerCase() : null;
@@ -10,7 +90,9 @@ export async function selectAccount(input) {
   if (!requestedAddress && !requestedId && !requestedName) {
     throw new Error('metamask.wallet.select_account mobile live adapter requires node.address, node.id, or node.name.');
   }
-  const accounts = await bridgeCommand(input, ['list-accounts']);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
+  const deadline = Date.now() + timeoutMs;
+  const accounts = await readAccounts(input, deadline);
   if (!Array.isArray(accounts)) {
     throw new Error(`metamask.wallet.select_account expected list-accounts to return an array, got ${typeof accounts}.`);
   }
@@ -25,7 +107,7 @@ export async function selectAccount(input) {
   if (!match?.address) {
     throw new Error(`Requested mobile account was not found in list-accounts: ${JSON.stringify({ address: requestedAddress, id: requestedId, name: requestedName })}`);
   }
-  const current = await bridgeCommand(input, ['get-selected-account']);
+  const current = await readSelectedAccount(input, deadline);
   const matchAddress = String(match.address).toLowerCase();
   if (String(current?.address ?? current ?? '').toLowerCase() === matchAddress) {
     return {
@@ -39,29 +121,59 @@ export async function selectAccount(input) {
       proofPath: 'agentic-account-selection',
     };
   }
-  const result = await bridgeCommand(input, ['switch-account', String(match.address)]);
-  const timeoutMs = Number(input.node?.timeout_ms ?? 5000);
-  const deadline = Date.now() + timeoutMs;
-  let selected = null;
-  do {
-    selected = await bridgeCommand(input, ['get-selected-account']);
-    if (String(selected?.address ?? selected ?? '').toLowerCase() === String(match.address).toLowerCase()) {
-      break;
-    }
-    await sleep(100);
-  } while (Date.now() < deadline);
+  if (Date.now() >= deadline) {
+    throw new Error(
+      `Mobile account selection did not leave enough time to switch to ${match.address} within ${timeoutMs}ms.`,
+    );
+  }
+  let result = null;
+  let ambiguousWriteError = null;
+  try {
+    result = await bridgeCommand(withRemainingDeadline(input, deadline), [
+      'switch-account',
+      String(match.address),
+    ]);
+  } catch (error) {
+    if (!TRANSIENT_READ_CODES.has(error?.code)) throw error;
+    ambiguousWriteError = error;
+  }
+  let selected = current;
+  let finalReadError = null;
+  try {
+    do {
+      selected = await readSelectedAccount(input, deadline);
+      if (String(selected?.address ?? selected ?? '').toLowerCase() === String(match.address).toLowerCase()) {
+        break;
+      }
+      await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+    } while (Date.now() < deadline);
+  } catch (error) {
+    if (!ambiguousWriteError) throw error;
+    finalReadError = error;
+  }
 
   if (String(selected?.address ?? selected ?? '').toLowerCase() !== String(match.address).toLowerCase()) {
+    if (ambiguousWriteError) {
+      throw ambiguousWriteFailure(
+        ambiguousWriteError,
+        match,
+        selected,
+        finalReadError,
+      );
+    }
     throw new Error(`Mobile account selection did not converge to ${match.address} after ${timeoutMs}ms.`);
   }
 
   return {
     action: input.action,
     selected: {
-      address: selected?.address ?? result.address,
-      id: selected?.id ?? result.id,
-      name: selected?.name ?? result.name,
+      address: selected?.address ?? result?.address ?? match.address,
+      id: selected?.id ?? result?.id ?? match.id,
+      name: selected?.name ?? result?.name ?? match.name,
     },
+    ...(ambiguousWriteError
+      ? { recoveredAfterAmbiguousWrite: true }
+      : {}),
     proofPath: 'agentic-account-selection',
   };
 }

package/library/manifests/mobile.action-manifest.json

@@ -1618,7 +1618,7 @@
       "execution_capabilities": ["app-mutation"]
     },
     "metamask.wallet.lock": {
-      "description": "Lock the Mobile wallet through the visible menu and confirm the login screen.",
+      "description": "Lock the Android Mobile wallet through the visible menu and confirm the login screen on development or opaque clients.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3115,6 +3115,9 @@
           "wait_for_lifecycle": {
             "type": "string"
           },
+          "wait_for_content_variant": {
+            "type": "string"
+          },
           "wait_timeout_ms": {
             "type": "number",
             "minimum": 1
@@ -3144,7 +3147,7 @@
           },
           "required_live_streams": {
             "type": "array",
-            "description": "Require values_ready records sourced from fresh_socket for each named Perps stream.",
+            "description": "Require app-emitted [PerpsLoadProof] values_ready records from fresh_socket with one complete session, lifecycle, account, context, and connection-generation identity.",
             "items": {
               "type": "string",
               "enum": ["prices", "positions", "orders", "account"]
@@ -3213,7 +3216,7 @@
         {
           "action": "metamask.perps.capture_performance",
           "phase": "end",
-          "require_records": false,
+          "require_records": true,
           "required_live_streams": ["positions", "orders", "account"],
           "intent": "Preserve production Perps loading and live-stream evidence emitted during this run",
           "next": "done"
@@ -3290,6 +3293,28 @@
       ],
       "execution_capabilities": ["app-mutation"]
     },
+    "metamask.perps.ensure_mode": {
+      "description": "Ensure the viewport-visible Perps market-detail root is Lite or Pro. The action presses the active mode control at most once and fails closed if that press opens another chooser or does not converge directly.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": ["lite", "pro"]
+          },
+          "timeout_ms": { "type": "integer", "minimum": 1000, "default": 30000 }
+        },
+        "required": ["mode"],
+        "additionalProperties": false
+      },
+      "examples": [{
+        "action": "metamask.perps.ensure_mode",
+        "mode": "pro",
+        "intent": "Reach Pro through the visible market-detail mode control",
+        "next": "done"
+      }],
+      "execution_capabilities": ["app-mutation"]
+    },
     "metamask.perps.start_state": {
       "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Recommended configurable Perps start state that first restores the fixture-backed unlocked wallet, then composes reusable domain operations before the proof window.",
       "schema": {