@deeeed/metamask-harness 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 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
+
+- Rotate each harness-owned Metro start into a run-scoped evidence generation, bound retained archives, coalesce repetitive bundle progress, and keep bundle-error recovery state inside one launch invocation.
+
 ## 0.41.0 - 2026-08-19
 
 ### Added

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,12 @@ 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).
+
 ## Discover and prove
 
 ```bash

package/adapters/manifest.json

@@ -39,9 +39,25 @@
       "entry": "adapters/mobile/launch-metro.cjs",
       "kind": "node",
       "purpose": "Launch Metro detached from the invoking process group so the runtime survives command cleanup.",
-      "inputs": "--target --port --log --pid-file [--workers] [--clear]",
+      "inputs": "--target --port --log --pid-file --build-env --runner [--workers] [--clear]",
       "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
     },
+    {
+      "id": "mobile/metro-log-generation",
+      "entry": "adapters/mobile/metro-log-generation.cjs",
+      "kind": "module",
+      "purpose": "Rotate one Metro generation, retain bounded archives, and publish launch evidence.",
+      "inputs": "runtime directory, Metro port, rotation reason; env MM_HARNESS_METRO_LOG_ARCHIVE_COUNT, MM_HARNESS_METRO_LOG_ARCHIVE_BYTES",
+      "outputs": "metro.log, archived logs, metro-generation.json"
+    },
+    {
+      "id": "mobile/coalesce-metro-log",
+      "entry": "adapters/mobile/coalesce-metro-log.cjs",
+      "kind": "module",
+      "purpose": "Coalesce repetitive Metro percentage progress while preserving diagnostics.",
+      "inputs": "Metro output on stdin",
+      "outputs": "errors, completion, and timestamped meaningful progress on stdout"
+    },
     {
       "id": "mobile/metro-config",
       "entry": "adapters/mobile/metro-config.cjs",
@@ -58,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,16 @@
 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,
+  rankRuntimeCandidates,
+} = 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 +932,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);
+  },
+
 };
 
 // ---------------------------------------------------------------------------
@@ -937,6 +961,7 @@ const BRIDGE_LOCK_FILE = path.join(
   process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
   'cdp-bridge.lock',
 );
+const BROKER_SOCKET_FILE = brokerSocketPath(path.dirname(BRIDGE_LOCK_FILE));
 const BRIDGE_LOCK_OWNER_PID = /^\d+$/.test(
   process.env.CDP_BRIDGE_LOCK_OWNER_PID || '',
 )
@@ -1019,6 +1044,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 +1062,54 @@ 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 timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);
+  const brokerAvailable = fs.existsSync(BROKER_SOCKET_FILE);
+  if (!brokerAvailable) acquireBridgeLock();
+
+  async function brokerTargets() {
+    const response = await fetch(`http://127.0.0.1:${port}/json/list`);
+    if (!response.ok) throw new Error(`Metro target listing returned ${response.status}`);
+    const ranked = rankRuntimeCandidates(await response.json());
+    const picked = new Set();
+    return ranked.flatMap((target) => {
+      const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
+      if (picked.has(deviceId)) return [];
+      picked.add(deviceId);
+      return [{
+        wsUrl: target.webSocketDebuggerUrl,
+        deviceName: target.deviceName || '',
+      }];
+    });
+  }
+
+  async function clientFor(wsUrl) {
+    if (brokerAvailable) {
+      return createBrokerClient(
+        BROKER_SOCKET_FILE,
+        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 +1125,11 @@ Environment:
     return;
   }
 
-  const { wsUrl, deviceName } = await discoverTarget(port);
-  const client = await createWSClient(wsUrl, timeout);
+  const { wsUrl, deviceName } = await discoverTarget(port, {
+    probe: !brokerAvailable,
+  });
+  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,15 @@ 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');
 
-// 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
@@ -101,9 +107,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 +177,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)),
+  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 +281,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 +290,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 +307,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 +338,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 +367,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 +447,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);
 });