@deeeed/metamask-harness 0.33.2 → 0.34.0

package/dist/mm-harness-cli.js

@@ -198,7 +198,7 @@ Example:
 
   --list                             List actions accepted by call for this adapter; no <action> needed
   --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
-  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
+  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (default: temp dir)
@@ -228,7 +228,7 @@ Discovery:
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
 
 Common overrides:
-  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
+  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --platform <ios|android>           Mobile platform preference; use --adapter for the product adapter
   --target <path>                    Checkout path (default: cwd)
@@ -453,6 +453,7 @@ Example:
   --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
 
   --build                            Full clean build + relaunch (escape hatch; skips extension reuse)
+  --clear-metro                      Mobile only: clear Metro's transform cache before launch
   --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
   --watch                            Persistent webpack watcher then relaunch (extension only)
@@ -469,6 +470,7 @@ Example:
 
 Example:
   mm-harness launch ios
+  mm-harness launch android --clear-metro --verify
   mm-harness launch ios --build
   mm-harness launch --verify --json`
   },

package/dist/recipe-security.js

@@ -28,6 +28,7 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
   "metamask.perps.ensure_orders",
+  "metamask.perps.clear_performance_caches",
   "metamask.perps.start_state",
   "metamask.perps.teardown_state",
   // Consent changes wallet state and is therefore an app mutation.

package/dist/recording-target.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+const ANDROID_RECORDING_TARGET_PREFIX = "android-device:";
+const IOS_SIMULATOR_RECORDING_TARGET_PREFIX = "ios-simulator:";
 function createMetaMaskRecordingTargetProvider(adapter) {
   return {
     async resolveRecordingTarget(context) {
@@ -19,8 +21,17 @@ function createMetaMaskRecordingTargetProvider(adapter) {
       }
       if (adapter === "mobile") {
         const platform = (context.env.PLATFORM ?? process.env.PLATFORM ?? "ios").trim().toLowerCase();
-        if (platform === "android" || context.env.ADB_SERIAL || process.env.ADB_SERIAL) {
-          throw new Error("--record-video is not implemented for mobile Android replay yet.");
+        const androidSerial = resolveAndroidDeviceSerial(context.env);
+        if (platform === "android" || androidSerial) {
+          if (!androidSerial) {
+            throw new Error(
+              "Could not resolve an Android device for --record-video. Set ADB_SERIAL or pass --device to mm-harness run."
+            );
+          }
+          return {
+            kind: "window-id",
+            windowId: `${ANDROID_RECORDING_TARGET_PREFIX}${androidSerial}`
+          };
         }
         const simulator = resolveMobileIosSimulatorName(context.env);
         if (!simulator) {
@@ -28,14 +39,18 @@ function createMetaMaskRecordingTargetProvider(adapter) {
             "Could not resolve an iOS simulator name for --record-video. Set IOS_SIMULATOR or pass --simulator to the recipe hook."
           );
         }
-        const pid = resolveMobileIosSimulatorPid(simulator);
-        if (pid) return { kind: "pid", pid };
-        return { kind: "app-window", appName: "Simulator", windowName: simulator };
+        return {
+          kind: "window-id",
+          windowId: `${IOS_SIMULATOR_RECORDING_TARGET_PREFIX}${simulator}`
+        };
       }
       throw new Error(`--record-video is not implemented for the ${adapter} adapter.`);
     }
   };
 }
+function resolveAndroidDeviceSerial(env = process.env) {
+  return env.ADB_SERIAL?.trim() || process.env.ADB_SERIAL?.trim() || void 0;
+}
 function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
   const result = spawnSync(captureHelperPath(), ["version", "--json"], {
     cwd: projectRoot,
@@ -125,8 +140,11 @@ function readTextFile(file) {
   }
 }
 export {
+  ANDROID_RECORDING_TARGET_PREFIX,
+  IOS_SIMULATOR_RECORDING_TARGET_PREFIX,
   captureHelperSupportsRecordSessionSnapshots,
   createMetaMaskRecordingTargetProvider,
+  resolveAndroidDeviceSerial,
   resolveExtensionBrowserPid,
   resolveMobileIosSimulatorName,
   resolveMobileIosSimulatorPid

package/dist/runner.js

@@ -1,17 +1,26 @@
 import { execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
+import { bridgeCommand } from "../library/actions/mobile/platform/bridge.mjs";
 import {
   mobileSourceFingerprint,
   recordMobileSourceBaseline
 } from "./adapters/mobile/source-freshness.js";
+import {
+  createAndroidVideoRecorder,
+  createIosSimulatorVideoRecorder
+} from "./adapters/mobile/video-recorder.js";
 import { resolveMetaMaskMobileLifecycleTarget } from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
 import { metaMaskActionExecutionCapabilities } from "./recipe-security.js";
 import {
   prepareLiveAdapterScript
 } from "./live-adapter-contract.js";
-import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
+import {
+  createMetaMaskRecordingTargetProvider,
+  resolveAndroidDeviceSerial,
+  resolveMobileIosSimulatorName
+} from "./recording-target.js";
 import {
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
@@ -85,6 +94,8 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     options.quietStdout ? new console.Console(process.stderr) : console,
     options.suppressLibraryResolutionLogs
   );
+  const androidRecordingSerial = adapter === "mobile" ? resolveAndroidDeviceSerial() : void 0;
+  const iosRecordingSimulator = adapter === "mobile" && !androidRecordingSerial ? resolveMobileIosSimulatorName() : void 0;
   return createRecipeRunner({
     actionManifest,
     adapters: withActionProgress(
@@ -96,7 +107,10 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     ),
     logger,
     recording: {
-      targetProvider: createMetaMaskRecordingTargetProvider(adapter)
+      targetProvider: createMetaMaskRecordingTargetProvider(adapter),
+      ...androidRecordingSerial ? { videoRecorder: createAndroidVideoRecorder(androidRecordingSerial) } : iosRecordingSimulator ? {
+        videoRecorder: createIosSimulatorVideoRecorder(iosRecordingSimulator)
+      } : {}
     },
     runner: runnerProvenance(),
     defaultSource: {
@@ -222,16 +236,32 @@ function isAutomaticHudProgress(action, node, nodeId) {
   const progress = payload.progress;
   return nodeId === "recipe-complete" && progress !== null && typeof progress === "object" && !Array.isArray(progress) && progress.complete === true;
 }
-function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
+function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe = probeMobileLifecycleRuntime, sourceFreshness = {
+  fingerprint: mobileSourceFingerprint,
+  record: recordMobileSourceBaseline
+}) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
     ...entry,
     async execute(node, context) {
       const command = node.command ?? node.event ?? node.state;
       const reloadsSource = command === "launch" || command === "foreground" || command === "restart";
-      const fingerprint = reloadsSource ? mobileSourceFingerprint(context.projectRoot) : void 0;
-      const result = await entry.execute(node, context);
-      if (fingerprint !== void 0 && !recordMobileSourceBaseline(context.projectRoot, fingerprint)) {
+      const fingerprint = reloadsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const androidRestart = command === "restart" && isAndroidLifecycle(node, context.env ?? {});
+      const initialNode = androidRestart ? { ...node, settle_ms: 0 } : node;
+      const initialResult = await entry.execute(initialNode, context);
+      let result = initialResult;
+      if (androidRestart) {
+        const foregroundResult = await entry.execute(
+          { ...node, command: "foreground" },
+          context
+        );
+        result = mergeAndroidRestartResults(initialResult, foregroundResult);
+      }
+      if (reloadsSource) {
+        await readinessProbe(node, context);
+      }
+      if (fingerprint !== void 0 && !sourceFreshness.record(context.projectRoot, fingerprint)) {
         throw new Error(
           "Mobile source changed while the app was reloading; the loaded-source baseline was not recorded. Next: retry app.lifecycle restart."
         );
@@ -240,6 +270,77 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
     }
   }));
 }
+function isAndroidLifecycle(node, env) {
+  const platform = node.platform ?? env.PLATFORM ?? process.env.PLATFORM;
+  if (platform === "android") return true;
+  if (platform === "ios") return false;
+  return Boolean(
+    node.adb_serial ?? node.android_device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL
+  );
+}
+function mergeAndroidRestartResults(initialResult, foregroundResult) {
+  const initial = asRecord(initialResult);
+  const foreground = asRecord(foregroundResult);
+  const initialOutput = asRecord(initial.output);
+  const foregroundOutput = asRecord(foreground.output);
+  return {
+    ...initial,
+    output: {
+      ...initialOutput,
+      command: "restart",
+      calls: [
+        ...Array.isArray(initialOutput.calls) ? initialOutput.calls : [],
+        ...Array.isArray(foregroundOutput.calls) ? foregroundOutput.calls : []
+      ],
+      settleMs: foregroundOutput.settleMs ?? initialOutput.settleMs ?? 0,
+      foregroundEnsured: true
+    }
+  };
+}
+async function probeMobileLifecycleRuntime(node, context) {
+  const command = node.command ?? node.event ?? node.state;
+  const defaultTimeoutMs = command === "restart" || command === "launch" ? 6e4 : 3e4;
+  const timeoutMs = lifecycleReadinessTimeout(
+    node.runtime_ready_timeout_ms,
+    defaultTimeoutMs
+  );
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      return await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(8e3, Math.max(1e3, deadline - Date.now()))
+          },
+          context
+        },
+        ["get-route"]
+      );
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    }
+  }
+  throw new Error(
+    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${timeoutMs}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+function lifecycleReadinessTimeout(value, fallback) {
+  if (value === void 0) return fallback;
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout < 1e3 || timeout > 12e4) {
+    throw new Error(
+      "app.lifecycle.runtime_ready_timeout_ms must be an integer from 1000 through 120000."
+    );
+  }
+  return timeout;
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 function runnerProvenance() {
   return {
     source: runnerDir,

package/dist/runtime-context.js

@@ -226,6 +226,38 @@ function hydrateRuntimeEnv(contextPath, context) {
 function setEnv(name, value) {
   if (value !== void 0 && value !== null && value !== "") process.env[name] = String(value);
 }
+function persistExplicitDevicePin(target, device) {
+  let repoRoot;
+  try {
+    repoRoot = fs.realpathSync(target);
+  } catch {
+    return;
+  }
+  const contextPath = path.join(repoRoot, recipeRuntimeDir(), "agentic-runtime.json");
+  if (!fs.existsSync(contextPath)) return;
+  let existing;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    existing = parsed;
+  } catch {
+    return;
+  }
+  const next = { ...existing };
+  if (device.platform === "ios") {
+    const simulatorName = device.name ? device.name.replace(/_/gu, " ").trim() : device.id;
+    next.simulator = simulatorName;
+    next.simulatorUdid = device.id;
+    delete next.adbSerial;
+  } else {
+    next.adbSerial = device.id;
+    delete next.simulator;
+    delete next.simulatorUdid;
+  }
+  removeEmptyValues(next);
+  writeJsonAtomic(contextPath, next);
+}
 export {
-  ensureRuntimeContext
+  ensureRuntimeContext,
+  persistExplicitDevicePin
 };

package/docs/RECIPES.md

@@ -58,6 +58,47 @@ mm-harness run recipe.json account="Account 2" --plan
 mm-harness run recipe.json account="Account 2"
 ```
 
+### Mobile device targeting
+
+Always pass `--device <name|udid|serial>` when more than one simulator/device may
+be connected. That pin:
+
+1. Sets `IOS_SIMULATOR` / `ADB_SERIAL` for the run.
+2. Rewrites the checkout `agentic-runtime.json` simulator/serial so the next
+   `resolveSlotPorts` does not revive a stale pin from another PR or slot.
+
+Do **not** shut down other connected devices to "force" selection — selection is
+by `--device`, not by exclusive boot.
+
+For visual PR proof, prefer a short simulator recording or GIF over still
+screenshots when the claim is a UI flow (timing / transitions). Use screenshots
+as supporting stills.
+
+### Perps Homepage visible performance
+
+The bundled `perps.performance.homepage.*` family preserves the device-proven
+Homepage TTC/DFD journeys. Run every recipe with an explicit device pin,
+healing disabled, and full-run video:
+
+```bash
+mm-harness run perps.performance.homepage.android-background-short --device <serial> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.android-background-reconnect --device <serial> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.android-cold-no-cache --device <serial> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.android-cold-disk-cache --device <serial> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.android-network-recovery --device <serial> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.ios-background-short --device <udid> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.ios-background-reconnect --device <udid> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.ios-cold-no-cache --device <udid> --heal off --record-video=full-run
+mm-harness run perps.performance.homepage.ios-cold-disk-cache --device <udid> --heal off --record-video=full-run
+```
+
+The Android variants use a deterministic Hyperliquid testnet order and cancel
+it after capture. The iOS variants use the existing fixture wallet and validate
+trending content without fabricating position/order state. `app.network` is
+Android-only because host-wide iOS network mutation cannot isolate one
+simulator safely. These recipes validate viewport-demand-to-visible TTC/DFD;
+they do not relabel process-start duration as TTC.
+
 Rules:
 
 - Validate with `--plan` before side effects.

package/library/actions/mobile/app/network-control.mjs

@@ -0,0 +1,135 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { resolveMobileToolPath } from '../platform/tool-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function selectedPlatform(input) {
+  const value = String(
+    input.node?.platform ?? input.context?.env?.PLATFORM ?? process.env.PLATFORM ?? '',
+  ).toLowerCase();
+  if (value === 'android' || value === 'ios') return value;
+  return selectedAndroidSerial(input) ? 'android' : 'ios';
+}
+
+function selectedAndroidSerial(input) {
+  const value =
+    input.node?.adb_serial ??
+    input.node?.device ??
+    input.context?.env?.ADB_SERIAL ??
+    input.context?.env?.ANDROID_SERIAL ??
+    process.env.ADB_SERIAL ??
+    process.env.ANDROID_SERIAL;
+  return value == null ? '' : String(value).trim();
+}
+
+function selectedAndroidPackage(input) {
+  return String(
+    input.node?.package_id ??
+      input.node?.app_id ??
+      input.context?.env?.ANDROID_PACKAGE_ID ??
+      process.env.ANDROID_PACKAGE_ID ??
+      'io.metamask',
+  ).trim();
+}
+
+async function defaultRun(file, args) {
+  return execFileAsync(file, args, { timeout: 15_000, encoding: 'utf8' });
+}
+
+export async function setMobileNetworkState(input, deps = {}) {
+  const state = String(input.node?.state ?? '').toLowerCase();
+  if (state !== 'offline' && state !== 'online') {
+    throw new Error('app.network.state must be offline or online.');
+  }
+  const platform = selectedPlatform(input);
+  if (platform !== 'android') {
+    throw new Error(
+      'app.network does not mutate iOS simulator host networking. A safe device-scoped iOS network capability is required before this lifecycle can be validated.',
+    );
+  }
+  const serial = selectedAndroidSerial(input);
+  if (!serial) {
+    throw new Error('Android app.network requires the selected ADB serial. Pass --device <serial>.');
+  }
+
+  const adb = deps.adb ?? resolveMobileToolPath('adb', { required: true });
+  const run = deps.run ?? defaultRun;
+  const appId = selectedAndroidPackage(input);
+  const airplaneMode = state === 'offline' ? 'enable' : 'disable';
+  await run(adb, [
+    '-s',
+    serial,
+    'shell',
+    'cmd',
+    'connectivity',
+    'airplane-mode',
+    airplaneMode,
+  ]);
+  const status = await run(adb, [
+    '-s',
+    serial,
+    'shell',
+    'settings',
+    'get',
+    'global',
+    'airplane_mode_on',
+  ]);
+  const expected = state === 'offline' ? '1' : '0';
+  const observed = String(status.stdout ?? '').trim();
+  if (observed !== expected) {
+    throw new Error(
+      `app.network requested ${state}, but Android airplane_mode_on was ${JSON.stringify(observed)} instead of ${expected}.`,
+    );
+  }
+
+
+  await run(adb, [
+    '-s',
+    serial,
+    'shell',
+    'monkey',
+    '-p',
+    appId,
+    '-c',
+    'android.intent.category.LAUNCHER',
+    '1',
+  ]);
+
+  const fallbackSettleMs = state === 'offline' ? 3000 : 10000;
+  const settleMs = Number(input.node?.settle_ms ?? fallbackSettleMs);
+  if (!Number.isInteger(settleMs) || settleMs < 0 || settleMs > 60_000) {
+    throw new Error('app.network.settle_ms must be an integer from 0 through 60000.');
+  }
+  await (deps.sleep ?? sleep)(settleMs);
+
+  const foreground = await run(adb, [
+    '-s',
+    serial,
+    'shell',
+    'dumpsys',
+    'activity',
+    'activities',
+  ]);
+  if (!String(foreground.stdout ?? '').includes(appId)) {
+    throw new Error(
+      `app.network changed Android networking but ${appId} was not foregrounded afterward.`,
+    );
+  }
+
+  return {
+    action: 'app.network',
+    platform,
+    deviceId: serial,
+    state,
+    appId,
+    airplaneMode: Number(expected),
+    settleMs,
+    foregroundEnsured: true,
+  };
+}

package/library/actions/mobile/app/network.mjs

@@ -0,0 +1,4 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { setMobileNetworkState } from './network-control.mjs';
+
+runAdapter(setMobileNetworkState);

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

@@ -0,0 +1,4 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { captureHomepagePerformance } from './performance-capture.mjs';
+
+runAdapter(captureHomepagePerformance);