@deeeed/metamask-harness 0.33.2 → 0.34.0

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

@@ -61,6 +61,25 @@ async function waitForTargetStatus(input, timeoutMs = 20000) {
   );
 }
 
+async function waitForWalletState(input, initialStatus, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let last = initialStatus;
+  while (true) {
+    if (selectedAccount(last, input) || routeName(last, input) === 'Login') return last;
+    if (Date.now() >= deadline) break;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    try {
+      last = await status(input);
+    } catch {
+      // A rotating Hermes target during startup is transient. The target timeout
+      // still bounds this loop and the final error reports the last wallet state.
+    }
+  }
+  throw new Error(
+    `No wallet onboarded on this device (route ${routeName(last, input) || 'unknown'}, empty wallet status) — unlock has nothing to unlock.\n  Next: mm-harness fixtures set   # applies the fixture wallet, then re-run: mm-harness call ensure_unlocked`,
+  );
+}
+
 async function waitForUnlocked(input, timeoutMs = 15000) {
   const deadline = Date.now() + timeoutMs;
   let last = null;
@@ -110,12 +129,14 @@ async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
 }
 
 export async function ensureUnlocked(input) {
-  const before = await waitForTargetStatus(input, Number(input.node?.target_timeout_ms ?? 20000));
-  if (!selectedAccount(before, input) && routeName(before, input) !== 'Login') {
-    throw new Error(
-      `No wallet onboarded on this device (route ${routeName(before, input) || 'unknown'}, empty wallet status) — unlock has nothing to unlock.\n  Next: mm-harness fixtures set   # applies the fixture wallet, then re-run: mm-harness call ensure_unlocked`,
-    );
-  }
+  const targetTimeoutMs = Number(input.node?.target_timeout_ms ?? 20000);
+  const targetDeadline = Date.now() + targetTimeoutMs;
+  const targetStatus = await waitForTargetStatus(input, targetTimeoutMs);
+  const before = await waitForWalletState(
+    input,
+    targetStatus,
+    Math.max(0, targetDeadline - Date.now()),
+  );
   const stableBefore = await waitForStableUnlocked(input, before, Number(input.node?.stable_unlocked_ms ?? 750));
   if (stableBefore) {
     return {

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

@@ -1,4 +1,6 @@
-import { bridgeCommand, evalAsync, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 runAdapter(async (input) => {
   const requestedAddress = input.node?.address ? String(input.node.address).toLowerCase() : null;
@@ -23,26 +25,28 @@ runAdapter(async (input) => {
     throw new Error(`Requested mobile account was not found in list-accounts: ${JSON.stringify({ address: requestedAddress, id: requestedId, name: requestedName })}`);
   }
   const result = await bridgeCommand(input, ['switch-account', String(match.address)]);
-  const perps = await evalAsync(
-    input,
-    `(async function(){
-      var controller = Engine.context.PerpsController;
-      if (!controller) return JSON.stringify({ skipped: true, reason: 'PerpsController unavailable' });
-      if (typeof controller.disconnect === 'function') await controller.disconnect();
-      if (typeof controller.init === 'function') await controller.init();
-      var positions = typeof controller.getPositions === 'function' ? await controller.getPositions() : [];
-      var account = typeof controller.getAccountState === 'function' ? await controller.getAccountState() : null;
-      return JSON.stringify({ reinitialized: true, positions: positions.length, withdrawableBalance: account && account.withdrawableBalance });
-    })()`,
-  );
+  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 (String(selected?.address ?? selected ?? '').toLowerCase() !== String(match.address).toLowerCase()) {
+    throw new Error(`Mobile account selection did not converge to ${match.address} after ${timeoutMs}ms.`);
+  }
+
   return {
     action: input.action,
     selected: {
-      address: result.address,
-      id: result.id,
-      name: result.name,
+      address: selected?.address ?? result.address,
+      id: selected?.id ?? result.id,
+      name: selected?.name ?? result.name,
     },
-    perps,
     proofPath: 'agentic-account-selection',
   };
 });

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

@@ -855,7 +855,7 @@
       ]
     },
     "ui.wait_for": {
-      "description": "Wait for a mounted React Native testID/test_id. Optional text validates text returned by that testID; text alone is not supported on Mobile.",
+      "description": "Wait for a React Native testID/test_id or text target. expected=visible requires a measured viewport intersection; expected=present only requires the mounted tree.",
       "schema": {
         "type": "object",
         "properties": {
@@ -910,6 +910,13 @@
           "expected": "absent",
           "intent": "Confirm the requested application state is visible.",
           "next": "done"
+        },
+        {
+          "action": "ui.wait_for",
+          "text": "Limit long",
+          "expected": "visible",
+          "intent": "Confirm the requested text is actually inside the viewport.",
+          "next": "done"
         }
       ]
     },
@@ -1035,6 +1042,9 @@
           "timeout_ms": {
             "type": "integer"
           },
+          "runtime_ready_timeout_ms": {
+            "type": "integer"
+          },
           "platform": {
             "type": "string",
             "enum": [
@@ -1091,6 +1101,39 @@
         "additionalProperties": false
       }
     },
+    "app.network": {
+      "description": "Set the selected Android device offline or online for deterministic network-recovery recipes. iOS simulator network mutation is refused until a safe device-scoped mechanism exists.",
+      "examples": [
+        {
+          "action": "app.network",
+          "state": "offline",
+          "settle_ms": 3000,
+          "intent": "Disconnect the selected device before exercising recovery.",
+          "next": "restore-network"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": ["offline", "online"]
+          },
+          "settle_ms": {
+            "type": "integer"
+          },
+          "adb_serial": {
+            "type": "string"
+          },
+          "device": {
+            "type": "string"
+          }
+        },
+        "required": ["state"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": ["app-mutation"]
+    },
     "app.status": {
       "description": "Report the adapter's static status — platform, project root, resolved checkout shape, and headless compatibility mode (no live route or account).",
       "examples": [
@@ -1287,6 +1330,11 @@
           "name": {
             "type": "string",
             "description": "Display name of the account to select."
+          },
+          "cdp_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds for the mobile CDP command."
           }
         },
         "additionalProperties": false
@@ -2400,6 +2448,87 @@
         "external-mutation"
       ]
     },
+    "metamask.perps.capture_performance": {
+      "description": "Capture only run-window [HomepagePerf] DevLogger records and a parsed stage/lifecycle summary for Perps on-device validation.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "type": "string",
+            "enum": ["start", "end"]
+          },
+          "source_path": {
+            "type": "string"
+          },
+          "artifact_prefix": {
+            "type": "string"
+          },
+          "require_records": {
+            "type": "boolean"
+          },
+          "required_stages": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "required_lifecycles": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "required_sources": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "required_fresh_content_variants": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": ["phase"],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.capture_performance",
+          "phase": "start",
+          "intent": "Start the Perps Homepage performance evidence window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "metamask.perps.capture_performance",
+          "phase": "end",
+          "required_stages": ["viewport_demand", "next_frame_checkpoint"],
+          "intent": "Preserve the Perps Homepage performance evidence emitted during this run",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.perps.clear_performance_caches": {
+      "description": "mobile Clear only persisted Perps market/user performance caches in the development app before a cold-no-cache validation run.",
+      "schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.clear_performance_caches",
+          "intent": "Prepare a deterministic cold process start without Perps cache hydration",
+          "next": "restart-app"
+        }
+      ],
+      "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": {

package/library/recipes/mobile/perps/performance.homepage.android-background-reconnect.recipe.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Android Homepage Perps reconnect visible performance proof",
+  "description": "Establishes a visible live order on Wallet Home, backgrounds the physical Android app beyond the 20-second connection grace period, restores it, and validates the reconnect-to-fresh-visible pipeline.",
+  "workflow": {
+    "entry": "prepare-open-order",
+    "nodes": {
+      "prepare-open-order": {
+        "action": "metamask.perps.start_state",
+        "profile": "open_order_testnet",
+        "provider": "hyperliquid",
+        "network": "testnet",
+        "market": "ETH",
+        "page": "perps_home",
+        "side": "short",
+        "orders": {
+          "state": "open",
+          "mode": "matching",
+          "market": "ETH",
+          "side": "short",
+          "notional": 10,
+          "leverage": 2,
+          "timeout_ms": 90000
+        },
+        "positions": false,
+        "intent": "Prepare a deterministic live order before the reconnect proof",
+        "timeout_ms": 120000,
+        "next": "open-wallet-home"
+      },
+      "open-wallet-home": {
+        "action": "ui.navigate",
+        "page": "home",
+        "intent": "Open Wallet Home before the connection expires",
+        "timeout_ms": 30000,
+        "next": "wait-content-mounted"
+      },
+      "wait-content-mounted": {
+        "action": "ui.wait_for",
+        "test_id": "homepage-perps-positions",
+        "expected": "present",
+        "intent": "Confirm the data-backed Homepage section is rendered",
+        "timeout_ms": 30000,
+        "next": "show-content"
+      },
+      "show-content": {
+        "action": "ui.scroll",
+        "test_id": "homepage-perps-positions",
+        "scroll_into_view": true,
+        "animated": true,
+        "settle": true,
+        "intent": "Make the live order reviewable before disconnecting",
+        "timeout_ms": 30000,
+        "next": "wait-order-before"
+      },
+      "wait-order-before": {
+        "action": "ui.wait_for",
+        "text": "Limit short",
+        "expected": "visible",
+        "intent": "Prove the same live order is visible before reconnect",
+        "timeout_ms": 30000,
+        "next": "start-performance-capture"
+      },
+      "start-performance-capture": {
+        "action": "metamask.perps.capture_performance",
+        "phase": "start",
+        "intent": "Start the evidence window immediately before the long background interval",
+        "next": "background-app"
+      },
+      "background-app": {
+        "action": "app.lifecycle",
+        "command": "background",
+        "settle_ms": 25000,
+        "intent": "Keep the app inactive beyond the connection grace period",
+        "next": "foreground-app"
+      },
+      "foreground-app": {
+        "action": "app.lifecycle",
+        "command": "foreground",
+        "settle_ms": 15000,
+        "intent": "Restore the installed app and allow stream recovery",
+        "next": "wait-content-after"
+      },
+      "wait-content-after": {
+        "action": "ui.wait_for",
+        "test_id": "homepage-perps-positions",
+        "expected": "present",
+        "intent": "Confirm the Homepage Perps state remains rendered after reconnect",
+        "timeout_ms": 30000,
+        "next": "show-content-after"
+      },
+      "show-content-after": {
+        "action": "ui.scroll",
+        "test_id": "homepage-perps-positions",
+        "scroll_into_view": true,
+        "animated": true,
+        "settle": true,
+        "intent": "Make the recovered data directly reviewable",
+        "timeout_ms": 30000,
+        "next": "wait-order-after"
+      },
+      "wait-order-after": {
+        "action": "ui.wait_for",
+        "text": "Limit short",
+        "expected": "visible",
+        "intent": "Prove the live order is displayed after stream recovery",
+        "timeout_ms": 30000,
+        "next": "capture-after"
+      },
+      "capture-after": {
+        "action": "ui.screenshot",
+        "path": "screenshots/homepage-order-after-reconnect.png",
+        "intent": "Preserve reviewer-visible reconnect proof",
+        "next": "settle-frame"
+      },
+      "settle-frame": {
+        "action": "wait",
+        "duration_ms": 2500,
+        "intent": "Allow the fresh visible frame checkpoint to finish",
+        "next": "finish-performance-capture"
+      },
+      "finish-performance-capture": {
+        "action": "metamask.perps.capture_performance",
+        "phase": "end",
+        "required_stages": [
+          "viewport_demand",
+          "socket_received",
+          "react_commit",
+          "next_frame_checkpoint"
+        ],
+        "required_lifecycles": ["background_reconnect"],
+        "required_sources": ["resident_state", "fresh_socket"],
+        "required_fresh_content_variants": ["orders"],
+        "intent": "Preserve and validate the reconnect measurement cohort",
+        "next": "cleanup-order"
+      },
+      "cleanup-order": {
+        "action": "metamask.perps.teardown_state",
+        "provider": "hyperliquid",
+        "network": "testnet",
+        "market": "ETH",
+        "page": "home",
+        "positions": false,
+        "orders": {
+          "state": "none",
+          "mode": "matching",
+          "market": "ETH",
+          "timeout_ms": 60000
+        },
+        "intent": "Cancel the deterministic testnet order after evidence capture",
+        "timeout_ms": 90000,
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/mobile/perps/performance.homepage.android-background-short.recipe.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Android Homepage Perps short-background visible performance proof",
+  "description": "Establishes a visible live order on Wallet Home, backgrounds the physical Android app for less than the 20-second reconnect threshold, restores it, and correlates the resumed frame with run-scoped performance evidence.",
+  "workflow": {
+    "entry": "prepare-open-order",
+    "nodes": {
+      "prepare-open-order": {
+        "action": "metamask.perps.start_state",
+        "profile": "open_order_testnet",
+        "provider": "hyperliquid",
+        "network": "testnet",
+        "market": "ETH",
+        "page": "perps_home",
+        "side": "short",
+        "orders": {
+          "state": "open",
+          "mode": "matching",
+          "market": "ETH",
+          "side": "short",
+          "notional": 10,
+          "leverage": 2,
+          "timeout_ms": 90000
+        },
+        "positions": false,
+        "intent": "Prepare a deterministic live order before the lifecycle proof",
+        "timeout_ms": 120000,
+        "next": "open-wallet-home"
+      },
+      "open-wallet-home": {
+        "action": "ui.navigate",
+        "page": "home",
+        "intent": "Open Wallet Home before the lifecycle transition",
+        "timeout_ms": 30000,
+        "next": "wait-content-mounted"
+      },
+      "wait-content-mounted": {
+        "action": "ui.wait_for",
+        "test_id": "homepage-perps-positions",
+        "expected": "present",
+        "intent": "Confirm the data-backed Homepage section is rendered",
+        "timeout_ms": 30000,
+        "next": "show-content"
+      },
+      "show-content": {
+        "action": "ui.scroll",
+        "test_id": "homepage-perps-positions",
+        "scroll_into_view": true,
+        "animated": true,
+        "settle": true,
+        "intent": "Make the order card available before the app leaves the foreground",
+        "timeout_ms": 30000,
+        "next": "wait-order-before"
+      },
+      "wait-order-before": {
+        "action": "ui.wait_for",
+        "text": "Limit short",
+        "expected": "visible",
+        "intent": "Prove the same live order is visible before the lifecycle transition",
+        "timeout_ms": 30000,
+        "next": "start-performance-capture"
+      },
+      "start-performance-capture": {
+        "action": "metamask.perps.capture_performance",
+        "phase": "start",
+        "intent": "Start the evidence window immediately before backgrounding",
+        "next": "background-app"
+      },
+      "background-app": {
+        "action": "app.lifecycle",
+        "command": "background",
+        "settle_ms": 3000,
+        "intent": "Leave the app inactive for less than the reconnect grace period",
+        "next": "foreground-app"
+      },
+      "foreground-app": {
+        "action": "app.lifecycle",
+        "command": "foreground",
+        "settle_ms": 10000,
+        "intent": "Restore the same installed app and wallet session",
+        "next": "wait-content-after"
+      },
+      "wait-content-after": {
+        "action": "ui.wait_for",
+        "test_id": "homepage-perps-positions",
+        "expected": "present",
+        "intent": "Confirm the Homepage Perps state survived the short background interval",
+        "timeout_ms": 30000,
+        "next": "show-content-after"
+      },
+      "show-content-after": {
+        "action": "ui.scroll",
+        "test_id": "homepage-perps-positions",
+        "scroll_into_view": true,
+        "animated": true,
+        "settle": true,
+        "intent": "Make the restored data directly reviewable after foregrounding",
+        "timeout_ms": 30000,
+        "next": "wait-order-after"
+      },
+      "wait-order-after": {
+        "action": "ui.wait_for",
+        "text": "Limit short",
+        "expected": "visible",
+        "intent": "Prove the live order remains displayed after the short resume",
+        "timeout_ms": 30000,
+        "next": "capture-after"
+      },
+      "capture-after": {
+        "action": "ui.screenshot",
+        "path": "screenshots/homepage-order-after-short-background.png",
+        "intent": "Preserve reviewer-visible short-resume proof",
+        "next": "settle-frame"
+      },
+      "settle-frame": {
+        "action": "wait",
+        "duration_ms": 2500,
+        "intent": "Allow the visible frame checkpoint to finish",
+        "next": "finish-performance-capture"
+      },
+      "finish-performance-capture": {
+        "action": "metamask.perps.capture_performance",
+        "phase": "end",
+        "required_stages": [
+          "viewport_demand",
+          "react_commit",
+          "next_frame_checkpoint"
+        ],
+        "required_lifecycles": ["background_short"],
+        "required_sources": ["resident_state", "fresh_socket"],
+        "intent": "Preserve and validate the short-background measurement cohort",
+        "next": "cleanup-order"
+      },
+      "cleanup-order": {
+        "action": "metamask.perps.teardown_state",
+        "provider": "hyperliquid",
+        "network": "testnet",
+        "market": "ETH",
+        "page": "home",
+        "positions": false,
+        "orders": {
+          "state": "none",
+          "mode": "matching",
+          "market": "ETH",
+          "timeout_ms": 60000
+        },
+        "intent": "Cancel the deterministic testnet order after evidence capture",
+        "timeout_ms": 90000,
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}