@deeeed/metamask-harness 0.41.1 → 0.43.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.43.0 - 2026-08-21
+
+### Added
+
+- Add platform-neutral `app.performance_capture` and `app.performance_assert` actions that attribute Mobile or Extension CDP trace samples to exact recipe-node boundaries and emit JSON plus self-contained HTML evidence.
+- Mobile native UI FPS requires a development client that reports `unstable_frameRecordingEnabled: true`; unpatched clients report partial or unavailable native coverage. Extension uses Chromium CDP and needs no client patch.
+
+### Fixed
+
+- Bound performance capture duration, discard raw samples after node attribution, correct iOS frame completion timestamps, fail closed on unresolved Extension renderers, and reset CDP collector state after trace failures.
+- Scope Mobile Hermes broker ownership by checkout runtime and Metro port so a forwarder from a prior port cannot intercept bridge, HUD, or observation commands after a slot port change.
+- Preserve explicit Mobile `--device` pins when slot defaults load so HUD and live-adapter child processes cannot target another device.
+- Resume broker commands on the next Hermes session generation without losing the pinned logical device.
+- Keep Hermes session recovery inside the caller's RPC deadline, pass only the remaining time to the recovered command, and classify broker connection or request timeouts so transient HUD updates do not abort a recipe.
+- Accept React Native trace response chunks up to 16 MiB while keeping broker requests capped at 8 MiB, and never retry the non-idempotent `Tracing.end` command.
+- Limit Mobile UI captures to clock and native-frame categories; keep browser timeline and JavaScript task categories on Extension.
+
+## 0.42.0 - 2026-08-20
+
+### Added
+
+- Add `app.network_capture` and `app.network_assert` for redacted Mobile HTTP request windows, indexed evidence, and assertions that preserve failed-run diagnostics.
+- Support the same bounded network observation contract on Extension and automatically index safe request metadata with recipe-node boundaries for live Mobile and Extension runs.
+- Add `mm-harness reload` for Metro-equivalent Mobile reloads and in-place Extension CDP refreshes.
+
+### Changed
+
+- Route Mobile console forwarding and recipe bridge commands through the same debugger connection so Network capture can coexist with HUD and wallet/domain actions.
+- Make the canonical Perps performance recipe close positions and orders outside timing for its market-only cohort instead of failing on inherited account state.
+
+### Fixed
+
+- Pass Expo `--clear` only for an explicit `mm-harness launch --clear-metro`, bound default Metro concurrency to four workers, and remove a stopped checkout from Watchman's root set.
+- Route React Native DevTools through the harness CDP broker so debugger use, recipe actions, and app reloads no longer evict one another.
+
 ## 0.41.1 - 2026-08-19
 
 ### Fixed

package/README.md

@@ -87,6 +87,7 @@ mm-harness status
 mm-harness stop
 mm-harness logs
 mm-harness debug
+mm-harness reload                 # Mobile Metro reload / Extension CDP refresh
 mm-harness fixtures set
 
 # Delete the current wallet, then reapply the canonical fixture from clean state.
@@ -109,6 +110,17 @@ mm-harness logs --source app        # Mobile app
 mm-harness logs --source metro      # Mobile bundler
 ```
 
+Live Mobile and Extension recipes automatically index a bounded, redacted
+`network/run-summary.json` with request timing and recipe-node boundaries. Use
+explicit `app.network_capture` and `app.network_assert` nodes for filtered
+windows and machine-checked request expectations. See
+[Recipe-scoped network capture](docs/NETWORK-CAPTURE.md).
+
+Mobile and Extension recipes can bracket explicit UI-smoothness windows with
+`app.performance_capture` and verify their evidence with
+`app.performance_assert`. Capture is never automatic. See
+[UI smoothness capture](docs/PERFORMANCE-CAPTURE.md).
+
 ## Discover and prove
 
 ```bash

package/adapters/manifest.json

@@ -74,6 +74,14 @@
       "inputs": "--target --port; env WATCHER_PORT",
       "outputs": "progress on stderr; exit 0 stopped-or-nothing / 1 stop failed / 2 bad args"
     },
+    {
+      "id": "mobile/reload-app",
+      "entry": "adapters/mobile/reload-app.mjs",
+      "kind": "node",
+      "purpose": "Request an in-place React Native app reload through Metro's protocol-v2 message endpoint.",
+      "inputs": "--port --json; env WATCHER_PORT, METRO_PORT",
+      "outputs": "reload result on stdout; exit 0 requested / 1 unavailable or invalid input"
+    },
     {
       "id": "mobile/prewarm-bundle",
       "entry": "adapters/mobile/prewarm-bundle.sh",

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -19,8 +19,15 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { loadPort } = require('./lib/config.cjs');
-const { discoverTarget } = require('./lib/target-discovery.cjs');
+const {
+  discoverTarget,
+} = require('./lib/target-discovery.cjs');
 const { createWSClient } = require('./lib/ws-client.cjs');
+const {
+  brokerSocketPath,
+  createBrokerClient,
+  deviceIdFromUrl,
+} = require('./lib/cdp-broker.cjs');
 const {
   EXIT_CODE_BY_ERROR_CODE,
   TEACHING_BY_ERROR_CODE,
@@ -924,6 +931,22 @@ const COMMANDS = {
     return result || { count: 0, entries: [] };
   },
 
+  async 'network-capture-start'(client, args) {
+    if (typeof client.control !== 'function') {
+      throw new Error('Network capture requires the CDP broker');
+    }
+    const options = JSON.parse(args[0] || '{}');
+    return client.control('capture-start', options);
+  },
+
+  async 'network-capture-end'(client, args) {
+    if (typeof client.control !== 'function') {
+      throw new Error('Network capture requires the CDP broker');
+    }
+    const options = JSON.parse(args[0] || '{}');
+    return client.control('capture-end', options);
+  },
+
 };
 
 // ---------------------------------------------------------------------------
@@ -1019,6 +1042,8 @@ Commands:
   issues-arm                           Install console/exception hooks that
                                        populate globalThis.__AGENTIC_ISSUES__
   issues-collect                       Snapshot + clear the in-app issue buffer
+  network-capture-start <json>         Start a broker-owned Network capture
+  network-capture-end <json>           End capture and return redacted summary
 
 Environment:
   WATCHER_PORT    Metro port (default: 8081)
@@ -1035,24 +1060,94 @@ Environment:
     process.exit(1);
   }
 
-  // Only a real command takes the debugger slot; help/unknown paths above never
-  // suppress the console forwarder.
-  acquireBridgeLock();
-
   const port = loadPort();
+  const brokerSocketFile = brokerSocketPath(
+    path.dirname(BRIDGE_LOCK_FILE),
+    port,
+  );
   const timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);
+  const brokerAvailable = fs.existsSync(brokerSocketFile);
+  if (!brokerAvailable) acquireBridgeLock();
+
+  function selectedTargetPin() {
+    const platform = String(process.env.MM_HARNESS_EXPLICIT_PLATFORM || '').toLowerCase();
+    const androidPin =
+      process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || '';
+    const iosPin = process.env.IOS_SIMULATOR || '';
+    return String(
+      platform === 'android'
+        ? androidPin
+        : platform === 'ios'
+          ? iosPin
+          : androidPin || iosPin,
+    ).trim();
+  }
+
+  async function brokerTargets({ retainIdentity = false } = {}) {
+    const discoveryClient = await createBrokerClient(
+      brokerSocketFile,
+      '',
+      timeout,
+    );
+    try {
+      const targets = await discoveryClient.control(
+        retainIdentity ? 'resolve-targets' : 'list-targets',
+        retainIdentity ? { nameIncludes: selectedTargetPin() } : {},
+        timeout,
+      );
+      return (Array.isArray(targets) ? targets : []).flatMap((target) => {
+        const deviceId = String(target?.deviceId || '');
+        return deviceId
+          ? [{ wsUrl: deviceId, deviceName: String(target?.name || '') }]
+          : [];
+      });
+    } finally {
+      discoveryClient.close();
+    }
+  }
+
+  function selectBrokerTarget(targets) {
+    const pin = selectedTargetPin();
+    const candidates = pin
+      ? targets.filter((target) =>
+          target.deviceName.toLowerCase().includes(pin.toLowerCase()),
+        )
+      : targets;
+    if (candidates.length !== 1) {
+      throw new Error(
+        `Mobile CDP broker target selection requires one target; found ${candidates.length}${pin ? ` for ${JSON.stringify(pin)}` : ''}.`,
+      );
+    }
+    return candidates[0];
+  }
+
+  async function clientFor(wsUrl) {
+    if (brokerAvailable) {
+      return createBrokerClient(
+        brokerSocketFile,
+        deviceIdFromUrl(wsUrl),
+        timeout,
+      );
+    }
+    if (command.startsWith('network-capture-')) {
+      throw new Error('Network capture requires a running CDP broker');
+    }
+    acquireBridgeLock();
+    return createWSClient(wsUrl, timeout);
+  }
 
   // `status` probes ALL connected targets so both platforms are visible.
   // `status-selected` falls through to the normal pinned discovery path for
   // action code that must survive one device's Hermes runtime rotation.
   if (command === 'status') {
-    const { discoverAllTargets } = require('./lib/target-discovery.cjs');
-    const allTargets = await discoverAllTargets(port);
+    const allTargets = brokerAvailable
+      ? await brokerTargets()
+      : await require('./lib/target-discovery.cjs').discoverAllTargets(port);
     const results = [];
     for (const target of allTargets) {
       let client;
       try {
-        client = await createWSClient(target.wsUrl, timeout);
+        client = await clientFor(target.wsUrl);
         const platform = await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
         const result = await handler(client, args.slice(1), { deviceName: target.deviceName, platform });
         results.push(result);
@@ -1068,8 +1163,11 @@ Environment:
     return;
   }
 
-  const { wsUrl, deviceName } = await discoverTarget(port);
-  const client = await createWSClient(wsUrl, timeout);
+  const { wsUrl, deviceName } = brokerAvailable
+    ? selectBrokerTarget(await brokerTargets({ retainIdentity: true }))
+    : await discoverTarget(port, { probe: true });
+  if (!wsUrl) throw new Error('No broker-owned Hermes target is available');
+  const client = await clientFor(wsUrl);
 
   try {
     // Detect platform from the running app (exposed by __AGENTIC__ bridge as Platform.OS)

package/adapters/mobile/bridge-runtime/console-forwarder.cjs

@@ -29,9 +29,16 @@ const http = require('node:http');
 const path = require('node:path');
 const { rankRuntimeCandidates } = require('./lib/target-discovery.cjs');
 const { formatArgs: formatConsoleArgs } = require('./lib/console-format.cjs');
+const {
+  brokerSocketPath,
+  createCdpBroker,
+  deviceIdFromUrl,
+} = require('./lib/cdp-broker.cjs');
+const { createDevtoolsProxy } = require('./lib/devtools-proxy.cjs');
+const { resolvePort } = require('./lib/config.cjs');
 
-// Built-in WebSocket (Node 22+), same zero-dependency transport choice as
-// lib/ws-client.cjs — the published package must not depend on `ws`.
+// Hermes uses Node's built-in WebSocket client. The local DevTools proxy uses
+// the package's pinned `ws` server implementation.
 const HANDSHAKE_TIMEOUT_MS = 3000;
 
 const DISCOVER_ACTIVE_MS = 1000; // a device is unattached — look for it quickly
@@ -40,7 +47,7 @@ const FLUSH_MS = 100;
 const MAX_LINE_CHARS = 4000;
 
 function parseArgs(argv) {
-  const args = { port: process.env.WATCHER_PORT || '8081', out: null };
+  const args = { port: resolvePort(), out: null };
   for (let i = 2; i < argv.length; i += 1) {
     if (argv[i] === '--port') args.port = argv[++i];
     else if (argv[i] === '--out') args.out = argv[++i];
@@ -101,9 +108,10 @@ function bridgeLockActive() {
 }
 
 function yieldSessions() {
-  for (const ws of sessions.values()) {
+  for (const session of sessions.values()) {
+    broker?.onSessionClose(session.deviceId);
     try {
-      ws.close();
+      session.ws.close();
     } catch {}
   }
   sessions.clear();
@@ -170,8 +178,56 @@ function serializeState() {
   return JSON.stringify(state);
 }
 
-/** deviceId -> live WebSocket session. */
+/** deviceId -> live WebSocket session state. */
 const sessions = new Map();
+let broker = null;
+let devtoolsProxy = null;
+
+function sendCommand(session, method, params = {}, timeoutMs = 10_000) {
+  return new Promise((resolve, reject) => {
+    if (!session.opened) {
+      reject(new Error('CDP session is not open'));
+      return;
+    }
+    const id = ++session.nextId;
+    const timer = setTimeout(() => {
+      session.pending.delete(id);
+      reject(new Error(`CDP command timed out: ${method}`));
+    }, timeoutMs);
+    session.pending.set(id, {
+      resolve: (result) => {
+        clearTimeout(timer);
+        resolve(result);
+      },
+      reject: (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    });
+    session.ws.send(JSON.stringify({ id, method, params }));
+  });
+}
+
+broker = createCdpBroker({
+  socketPath: brokerSocketPath(path.dirname(out), port),
+  sessions,
+  sendCommand,
+  requestDiscovery(deviceId) {
+    foreignDebuggerUntil.delete(deviceId);
+    discover();
+  },
+  onClientActivity: noteBridgeCoordination,
+});
+devtoolsProxy = createDevtoolsProxy({
+  descriptorPath: path.join(path.dirname(out), 'devtools-proxy.json'),
+  sessions,
+  sendCommand,
+  requestDiscovery: discover,
+  allowedOrigins: [
+    `http://127.0.0.1:${port}`,
+    `http://localhost:${port}`,
+  ],
+});
 
 /** deviceId -> epoch ms until which a foreign debugger owns the slot. */
 const foreignDebuggerUntil = new Map();
@@ -226,11 +282,6 @@ function deviceNameFromTitle(title) {
   return m ? m[1] : (title || 'device');
 }
 
-function deviceIdFromUrl(wsUrl) {
-  const m = /[?&]device=([^&]+)/.exec(wsUrl || '');
-  return m ? m[1] : wsUrl;
-}
-
 function connect(target) {
   const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
   const name = deviceNameFromTitle(target.title);
@@ -240,7 +291,16 @@ function connect(target) {
   } catch {
     return;
   }
-  sessions.set(deviceId, ws);
+  const session = {
+    deviceId,
+    name,
+    ws,
+    opened: false,
+    brokerReady: false,
+    nextId: 1,
+    pending: new Map(),
+  };
+  sessions.set(deviceId, session);
   // The built-in WebSocket has no handshake timeout; a hung connect would hold
   // the session slot forever and block every future re-attach for this device.
   const handshakeTimer = setTimeout(() => {
@@ -248,10 +308,29 @@ function connect(target) {
       ws.close();
     } catch {}
   }, HANDSHAKE_TIMEOUT_MS);
-  ws.addEventListener('open', () => {
+  ws.addEventListener('open', async () => {
     clearTimeout(handshakeTimer);
-    ws.send(JSON.stringify({ id: 1, method: 'Runtime.enable' }));
-    process.stderr.write(`console-forwarder: attached ${name}\n`);
+    session.opened = true;
+    try {
+      await sendCommand(session, 'Runtime.enable');
+      const evaluation = await sendCommand(session, 'Runtime.evaluate', {
+        expression: "typeof globalThis.__AGENTIC__ === 'object'",
+        returnByValue: true,
+        awaitPromise: false,
+      });
+      if (evaluation?.result?.value !== true) {
+        throw new Error('CDP target does not expose __AGENTIC__');
+      }
+      session.brokerReady = true;
+      broker.onSessionOpen(deviceId);
+      devtoolsProxy.onSessionOpen(deviceId, session);
+      process.stderr.write(`console-forwarder: attached ${name}\n`);
+    } catch (error) {
+      process.stderr.write(
+        `console-forwarder: rejected ${name}: ${String(error?.message || error).slice(0, 256)}\n`,
+      );
+      ws.close();
+    }
   });
   ws.addEventListener('message', (event) => {
     let msg;
@@ -260,6 +339,17 @@ function connect(target) {
     } catch {
       return;
     }
+    if (msg.id && session.pending.has(msg.id)) {
+      const entry = session.pending.get(msg.id);
+      session.pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(JSON.stringify(msg.error)));
+      else entry.resolve(msg.result);
+      return;
+    }
+    if (msg.method) {
+      broker.onCdpEvent(deviceId, msg.method, msg.params || {});
+      devtoolsProxy.onCdpEvent(deviceId, msg.method, msg.params || {});
+    }
     if (msg.method !== 'Runtime.consoleAPICalled') return;
     const text = formatArgs(msg.params.args);
     // dev-middleware emits this NOTE on every debugger attach (i.e. ours). Drop it.
@@ -278,8 +368,15 @@ function connect(target) {
   });
   const drop = () => {
     clearTimeout(handshakeTimer);
-    if (sessions.get(deviceId) === ws) {
+    session.opened = false;
+    session.brokerReady = false;
+    for (const entry of session.pending.values()) {
+      entry.reject(new Error('CDP session closed'));
+    }
+    session.pending.clear();
+    if (sessions.get(deviceId) === session) {
       sessions.delete(deviceId);
+      broker.onSessionClose(deviceId);
       process.stderr.write(`console-forwarder: detached ${name}; will re-attach\n`);
     }
   };
@@ -351,10 +448,14 @@ function schedule(ms) {
 
 process.on('SIGTERM', () => {
   flushSync();
+  devtoolsProxy.close();
+  broker.close();
   process.exit(0);
 });
 process.on('SIGINT', () => {
   flushSync();
+  devtoolsProxy.close();
+  broker.close();
   process.exit(0);
 });
 

package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs

@@ -63,6 +63,8 @@ const NEEDLE_CODES = [
   ['websocket error', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['cdp connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['cdp message timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['cdp broker connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['cdp broker request timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['evaluation timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
 ];