@deeeed/metamask-harness 0.9.1 → 0.11.0

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

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixturePassword(projectRoot) {
@@ -34,58 +34,94 @@ function routeName(status, input) {
   return route && typeof route === 'object' ? String(route.name ?? '') : '';
 }
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 async function status(input) {
   return bridgeCommand(input, ['status']);
 }
 
+async function waitForTargetStatus(input, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      last = await status(input);
+      const selected = selectedStatus(last, input);
+      if (selected?.agenticPresent === true) return last;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error(
+    `Timed out waiting for pinned Mobile agentic bridge target; last status was ${JSON.stringify(last)}; last error was ${String(lastError?.message ?? lastError)}`,
+  );
+}
+
 async function waitForUnlocked(input, timeoutMs = 15000) {
   const deadline = Date.now() + timeoutMs;
   let last = null;
+  let lastError = null;
   while (Date.now() < deadline) {
-    last = await status(input);
-    if (selectedAccount(last, input) && routeName(last, input) !== 'Login') return last;
+    try {
+      last = await status(input);
+      if (selectedAccount(last, input) && routeName(last, input) !== 'Login') return last;
+    } catch (error) {
+      lastError = error;
+    }
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
-  throw new Error(`Timed out waiting for Mobile wallet unlock; last status was ${JSON.stringify(last)}`);
+  throw new Error(`Timed out waiting for Mobile wallet unlock; last status was ${JSON.stringify(last)}; last error was ${String(lastError?.message ?? lastError)}`);
+}
+
+function isUnlockedStatus(status, input) {
+  return Boolean(selectedAccount(status, input)) && routeName(status, input) !== 'Login';
+}
+
+async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
+  if (!isUnlockedStatus(initialStatus, input)) return null;
+  const deadline = Date.now() + stableMs;
+  let last = initialStatus;
+  let transientDrops = 0;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    try {
+      last = await status(input);
+      if (!isUnlockedStatus(last, input)) {
+        if (routeName(last, input) === 'Login') return null;
+        transientDrops += 1;
+        if (transientDrops > 2) return null;
+        continue;
+      }
+      transientDrops = 0;
+    } catch {
+      // Recovery is correct: a bridge error during the stability window is the
+      // same signal as an unlocked-state drop — count it toward the transient
+      // threshold; exceeding it returns null so the caller runs the real
+      // password unlock instead of reporting a false alreadyUnlocked.
+      transientDrops += 1;
+      if (transientDrops > 2) return null;
+    }
+  }
+  return last;
 }
 
 runAdapter(async (input) => {
-  const before = await status(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`,
     );
   }
-  if (selectedAccount(before, input) && routeName(before, input) !== 'Login') {
+  const stableBefore = await waitForStableUnlocked(input, before, Number(input.node?.stable_unlocked_ms ?? 750));
+  if (stableBefore) {
     return {
       action: input.action,
       unlocked: true,
       alreadyUnlocked: true,
-      account: selectedAccount(before, input),
+      account: selectedAccount(stableBefore, input),
       redacted: true,
       proofPath: 'agentic-wallet-status',
     };
@@ -95,11 +131,12 @@ runAdapter(async (input) => {
   try {
     const result = await bridgeCommand(input, ['unlock', String(password)]);
     const after = await waitForUnlocked(input, Number(input.node?.unlock_timeout_ms ?? 15000));
+    const stableAfter = await waitForStableUnlocked(input, after, Number(input.node?.stable_unlocked_ms ?? 750)) ?? after;
     return {
       action: input.action,
       unlocked: Boolean(result?.ok ?? result?.unlocked ?? true),
-      account: selectedAccount(after, input),
-      route: selectedStatus(after, input)?.route ?? null,
+      account: selectedAccount(stableAfter, input),
+      route: selectedStatus(stableAfter, input)?.route ?? null,
       redacted: true,
       proofPath: 'agentic-wallet-unlock',
     };

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

@@ -1,28 +1,7 @@
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 runAdapter(async (input) => {
   const status = selectedStatus(await bridgeCommand(input, ['status']), input);

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

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { bridgeCommand, bridgeEnv, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, bridgeEnv, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixtureProfile(projectRoot) {
@@ -77,29 +77,8 @@ function mnemonicAccountCount(account, fixturePath, index) {
   return count;
 }
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 function hasSelectedAccount(status, input) {
   return Boolean(selectedStatus(status, input)?.account);
@@ -138,9 +117,12 @@ async function runSetupWallet(input, fixture) {
             if (settled) return;
             settled = true;
             child.kill('SIGTERM');
-            setTimeout(() => {
-              if (!child.killed) child.kill('SIGKILL');
-            }, 1000);
+            // Always escalate after the grace period: child.killed only records
+            // that kill() was CALLED, not that the process exited, so gating
+            // SIGKILL on it never fires and a SIGTERM-ignoring child leaks. The
+            // close listener cancels the escalation when the child exits in time.
+            const killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+            child.once('close', () => clearTimeout(killTimer));
             reject(
               new Error(
                 `Mobile setup-wallet.sh timed out after ${timeoutMs}ms.`,

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

@@ -11,6 +11,7 @@
     "watch_logs",
     "index_artifacts",
     "end",
+    "call",
     "ui.navigate",
     "ui.press",
     "ui.key_press",
@@ -724,6 +725,18 @@
           }
         }
       ]
+    },
+    "call": {
+      "description": "Invoke a named sub-recipe flow by ref and run its steps inline.",
+      "examples": [
+        {
+          "node": {
+            "action": "call",
+            "ref": "mydev.open_perps_setup",
+            "intent": "Run a personal Perps setup flow segment"
+          }
+        }
+      ]
     }
   },
   "custom_actions": [

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

@@ -11,6 +11,7 @@
     "watch_logs",
     "index_artifacts",
     "end",
+    "call",
     "ui.navigate",
     "ui.press",
     "ui.key_press",
@@ -18,6 +19,7 @@
     "ui.scroll",
     "ui.wait_for",
     "ui.screenshot",
+    "app.lifecycle",
     "app.status",
     "app.hud",
     "cdp.target"
@@ -212,6 +214,19 @@
         }
       ]
     },
+    "app.lifecycle": {
+      "description": "Drive outer mobile app lifecycle for deterministic performance start states without rebuilding: foreground/launch, background, terminate, or restart the installed app.",
+      "examples": [
+        {
+          "node": {
+            "action": "app.lifecycle",
+            "command": "background",
+            "settle_ms": 1000,
+            "intent": "Send the selected Android device to the launcher before a warm-resume measurement"
+          }
+        }
+      ]
+    },
     "assert_file": {
       "description": "Assert that a project file exists and optionally contains text.",
       "examples": [
@@ -724,6 +739,18 @@
           }
         }
       ]
+    },
+    "call": {
+      "description": "Invoke a named sub-recipe flow by ref and run its steps inline.",
+      "examples": [
+        {
+          "node": {
+            "action": "call",
+            "ref": "mydev.open_perps_setup",
+            "intent": "Run a personal Perps setup flow segment"
+          }
+        }
+      ]
     }
   },
   "custom_actions": [
@@ -1986,6 +2013,10 @@
       "action": "ui.screenshot",
       "implementation": "@farmslot/recipe-harness/runtime/react-native-bridge"
     },
+    {
+      "action": "app.lifecycle",
+      "implementation": "@farmslot/recipe-harness/adapters/app-lifecycle"
+    },
     {
       "action": "app.status",
       "implementation": "@metamask/recipe-runner/platform-status"

package/library/recipes/app-lifecycle-android-smoke.mobile.recipe.json

@@ -0,0 +1,87 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Android lifecycle smoke",
+  "description": "Isolated on-device proof for the standard outer app.lifecycle action on Android. Setup cold-relaunches the installed app through the Expo dev-client deep link without rebuilding and proves the React Native bridge is reachable. The main workflow then backgrounds the installed app, foregrounds it again, proves the bridge is reachable after resume, and captures a screenshot.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after setup relaunch",
+    "detail": "Read-only start-state marker after setup has made the Android bridge reachable."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "terminate-before",
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "terminate",
+          "settle_ms": 3000,
+          "intent": "Terminate the installed Android app before lifecycle smoke",
+          "detail": "Force-stops stale foreground instances that may have no React Native debug target."
+        },
+        {
+          "id": "launch-before",
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "launch",
+          "settle_ms": 15000,
+          "intent": "Launch the installed Android app through the Expo dev-client deep link from a cold process",
+          "detail": "Uses the selected adb serial, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "bridge-before",
+          "action": "cdp.target",
+          "require_reachable": true,
+          "intent": "Confirm the mobile React Native debug bridge is reachable after setup relaunch",
+          "detail": "This proves setup can recover a missing Android bridge target before the background-resume proof."
+        }
+      ],
+      "entry": "background-app",
+      "nodes": {
+        "background-app": {
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "background",
+          "settle_ms": 1000,
+          "intent": "Put the selected Android device on the launcher",
+          "detail": "Uses adb HOME through the shared Farmslot lifecycle adapter.",
+          "flow": "lifecycle",
+          "next": "foreground-app"
+        },
+        "foreground-app": {
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "foreground",
+          "settle_ms": 15000,
+          "intent": "Foreground the installed Android app through the Expo dev-client deep link",
+          "detail": "Uses the selected adb serial, Metro port, and installed package; it does not rebuild.",
+          "flow": "lifecycle",
+          "next": "bridge-after"
+        },
+        "bridge-after": {
+          "action": "cdp.target",
+          "require_reachable": true,
+          "intent": "Confirm the mobile React Native debug bridge recovered after foregrounding",
+          "detail": "This is the capability gate before running Perps recipes that depend on CDP/bridge control.",
+          "flow": "lifecycle",
+          "next": "screenshot-after"
+        },
+        "screenshot-after": {
+          "action": "ui.screenshot",
+          "path": "screenshots/app-lifecycle-android-smoke.png",
+          "intent": "Capture the app after Android lifecycle foreground",
+          "detail": "Visual proof that the selected device is displaying the relaunched app.",
+          "flow": "evidence",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the isolated Android lifecycle smoke",
+          "detail": "If this passes, lifecycle is proven independently of wallet and Perps actions.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-background-resume.mobile.recipe.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - background resume",
+  "description": "Measured Perps flow from a deterministic background-resume start state. Setup sends the installed app to the background, foregrounds it through the Expo dev-client deep link without rebuilding, and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after background-resume setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "background-app",
+          "action": "app.lifecycle",
+          "command": "background",
+          "settle_ms": 3000,
+          "intent": "Put the installed app in the background before measuring resume",
+          "detail": "On Android this sends HOME to the selected device. On iOS simulator this foregrounds Settings through the shared outer adapter."
+        },
+        {
+          "id": "foreground-app",
+          "action": "app.lifecycle",
+          "command": "foreground",
+          "settle_ms": 15000,
+          "intent": "Foreground the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the background-resume Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-cold-start.mobile.recipe.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - cold process start",
+  "description": "Measured Perps flow from a deterministic cold-process start state. Setup force-stops/terminates the installed app, relaunches it through the Expo dev-client deep link without rebuilding, and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after cold-start setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "terminate-app",
+          "action": "app.lifecycle",
+          "command": "terminate",
+          "settle_ms": 3000,
+          "intent": "Terminate the installed app process before measuring cold start",
+          "detail": "Uses adb force-stop on Android or simctl terminate on iOS simulator; it does not uninstall or rebuild."
+        },
+        {
+          "id": "launch-app",
+          "action": "app.lifecycle",
+          "command": "launch",
+          "settle_ms": 15000,
+          "intent": "Launch the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the cold-start Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-warm-start.mobile.recipe.json

@@ -0,0 +1,64 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - warm foreground start",
+  "description": "Measured Perps flow from a deterministic warm-foreground start state. Setup foregrounds the already installed app through the Expo dev-client deep link without rebuilding and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after warm foreground setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "foreground-app",
+          "action": "app.lifecycle",
+          "command": "foreground",
+          "settle_ms": 10000,
+          "intent": "Foreground the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the warm-start Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}