@deeeed/metamask-harness 0.43.0 → 0.44.1

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

@@ -14,12 +14,25 @@ const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 const MAX_POST_DATA_BYTES = 64 * 1024;
 const MAX_REQUEST_FRAME_BYTES = 8 * 1024 * 1024;
 const MAX_RESPONSE_FRAME_BYTES = 16 * 1024 * 1024;
+const MAX_HUD_STEP_BYTES = 16 * 1024;
+const MAX_HUD_UPDATES = 64;
 const MAX_RETAINED_STRING_LENGTH = 256;
 const MAX_BROKER_TIMEOUT_MS = 60_000;
 const SENSITIVE_FIELD =
   /(?:address|authorization|cookie|key|password|secret|token|user|account)/iu;
 const SENSITIVE_VALUE =
   /(?:0x[a-f0-9]{40,}|[a-f0-9]{64,}|eyJ[a-z0-9_-]{20,}\.[a-z0-9_-]{20,})/iu;
+const APPLY_HUD_UPDATE_FUNCTION = `function(step) {
+  const bridge = this.__AGENTIC__;
+  if (step === null) {
+    if (typeof bridge?.hideStep !== 'function') return false;
+    setTimeout(() => bridge.hideStep(), 0);
+    return true;
+  }
+  if (typeof bridge?.showStep !== 'function') return false;
+  setTimeout(() => bridge.showStep(step), 0);
+  return true;
+}`;
 
 function brokerSocketPath(runtimeDir, endpointIdentity) {
   const runtimePath = path.resolve(
@@ -353,6 +366,9 @@ function createCdpBroker({
 }) {
   const captures = new Map();
   const completedCaptures = new Map();
+  const hudUpdates = new Map();
+  const appliedHudVersions = new Map();
+  const hudApplyChains = new Map();
   const clients = new Set();
   const subscriptions = new Map();
   const knownTargets = new Map(
@@ -482,6 +498,67 @@ function createCdpBroker({
     capturesFor(deviceId).delete(capture.id);
   }
 
+  async function applyHudUpdate(deviceId, timeoutMs, socket) {
+    if (!hudUpdates.has(deviceId)) return { status: 'none' };
+    const budgetMs = boundedTimeout(timeoutMs);
+    const deadline = Date.now() + budgetMs;
+    const session = await waitForSession(deviceId, budgetMs, socket);
+    const update = hudUpdates.get(deviceId);
+    if (!update) return { status: 'none' };
+    if (appliedHudVersions.get(deviceId) === update.version) {
+      return { status: 'applied', version: update.version };
+    }
+    let applied = false;
+    while (Date.now() < deadline) {
+      const globalObject = await sendCommand(
+        session,
+        'Runtime.evaluate',
+        { expression: 'globalThis', returnByValue: false, awaitPromise: false },
+        Math.max(1, deadline - Date.now()),
+      );
+      const objectId = globalObject?.result?.objectId;
+      if (!objectId) {
+        throw new Error('Mobile HUD runtime did not expose globalThis');
+      }
+      const evaluation = await sendCommand(
+        session,
+        'Runtime.callFunctionOn',
+        {
+          objectId,
+          functionDeclaration: APPLY_HUD_UPDATE_FUNCTION,
+          arguments: [{ value: update.step }],
+          returnByValue: true,
+          awaitPromise: false,
+        },
+        Math.max(1, deadline - Date.now()),
+      );
+      if (evaluation?.result?.value === true) {
+        applied = true;
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (!applied) {
+      throw new Error('Mobile HUD bridge was not installed before the update deadline');
+    }
+    if (hudUpdates.get(deviceId)?.version === update.version) {
+      appliedHudVersions.set(deviceId, update.version);
+    }
+    return { status: 'applied', version: update.version };
+  }
+
+  function scheduleHudUpdate(deviceId, timeoutMs, socket) {
+    const previous = hudApplyChains.get(deviceId) || Promise.resolve();
+    const next = previous
+      .catch(() => undefined)
+      .then(() => applyHudUpdate(deviceId, timeoutMs, socket));
+    hudApplyChains.set(deviceId, next);
+    void next.finally(() => {
+      if (hudApplyChains.get(deviceId) === next) hudApplyChains.delete(deviceId);
+    }).catch(() => undefined);
+    return next;
+  }
+
   function expireCapture(deviceId, capture) {
     if (capturesFor(deviceId).get(capture.id) !== capture) return;
     finishCapture(deviceId, capture, true);
@@ -539,6 +616,29 @@ function createCdpBroker({
     if (action === 'resolve-targets') {
       return resolveTargets(params, timeoutMs, socket);
     }
+    if (action === 'hud-update') {
+      const step = params.step ?? null;
+      if (step !== null && (typeof step !== 'object' || Array.isArray(step))) {
+        throw new Error('HUD update requires an object step or null');
+      }
+      if (Buffer.byteLength(JSON.stringify(step)) > MAX_HUD_STEP_BYTES) {
+        throw new Error('HUD update exceeds its bound');
+      }
+      const previousVersion = hudUpdates.get(deviceId)?.version || 0;
+      if (hudUpdates.has(deviceId)) {
+        hudUpdates.delete(deviceId);
+      }
+      while (hudUpdates.size >= MAX_HUD_UPDATES) {
+        const oldestDeviceId = hudUpdates.keys().next().value;
+        hudUpdates.delete(oldestDeviceId);
+        appliedHudVersions.delete(oldestDeviceId);
+      }
+      const version = previousVersion + 1;
+      hudUpdates.set(deviceId, { step, version });
+      requestDiscovery?.(deviceId);
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
+      return { status: 'queued', version };
+    }
     if (action === 'capture-start') {
       const capture = normalizeCapture(params);
       const deviceCaptures = capturesFor(deviceId);
@@ -726,11 +826,13 @@ function createCdpBroker({
         if (capture.reconnects > 0) capture.partial = true;
         void enableNetwork(deviceId, capture);
       }
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
     },
     onSessionClose(deviceId) {
       const previous = knownTargets.get(deviceId);
       if (previous) knownTargets.set(deviceId, { ...previous, ready: false });
       observedSessions.delete(deviceId);
+      appliedHudVersions.delete(deviceId);
       for (const capture of capturesFor(deviceId).values()) {
         capture.reconnects += 1;
         capture.partial = true;

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -300,6 +300,7 @@ async function discoverTarget(port, { probe = true } = {}) {
     for (const candidate of candidates) {
       if (candidate.webSocketDebuggerUrl === acceptedPinnedCandidate.webSocketDebuggerUrl) {
         return {
+          id: acceptedPinnedCandidate.id || '',
           wsUrl: acceptedPinnedCandidate.webSocketDebuggerUrl,
           deviceName: acceptedPinnedCandidate.deviceName || '',
         };
@@ -312,6 +313,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   // platform/device filtering and select the highest-ranked runtime instead.
   if (!probe) {
     return {
+      id: candidates[0].id || '',
       wsUrl: candidates[0].webSocketDebuggerUrl,
       deviceName: candidates[0].deviceName || '',
     };
@@ -331,7 +333,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   for (const candidate of candidates) {
     const hasAgentic = await probeTarget(candidate.webSocketDebuggerUrl);
     if (hasAgentic) {
-      return { wsUrl: candidate.webSocketDebuggerUrl, deviceName: candidate.deviceName || '' };
+      return { id: candidate.id || '', wsUrl: candidate.webSocketDebuggerUrl, deviceName: candidate.deviceName || '' };
     }
   }
 
@@ -348,7 +350,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   }
 
   // Fallback: return highest page number (most likely the JS runtime)
-  return { wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
+  return { id: candidates[0].id || '', wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
 }
 
 /**

package/adapters/mobile/reload-app.mjs

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 
+import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { resolveMobileToolPath } from '../../library/actions/mobile/platform/tool-paths.mjs';
 
 const require = createRequire(import.meta.url);
 const WebSocket = require('ws');
+const { discoverTarget } = require('./bridge-runtime/lib/target-discovery.cjs');
 
 function parseArgs(argv) {
-  const args = { port: process.env.WATCHER_PORT || process.env.METRO_PORT || '8081', json: false };
+  const args = {
+    port: process.env.WATCHER_PORT || process.env.METRO_PORT || '8081',
+    json: false,
+  };
   for (let index = 0; index < argv.length; index += 1) {
     if (argv[index] === '--port') args.port = argv[++index];
     else if (argv[index] === '--json') args.json = true;
@@ -25,6 +31,21 @@ async function reload(port) {
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
     throw new Error(`Metro port is invalid: ${port}`);
   }
+  const targetBefore = await readHermesTarget(numericPort);
+  if (!targetBefore?.id) {
+    throw new Error(
+      `No React Native debug target with a stable ID is connected to Metro on port ${numericPort}`,
+    );
+  }
+  const processBefore = readAndroidPid();
+  if (androidSerial() && !processBefore) {
+    throw new Error(`The Android app is not running on ${androidSerial()}`);
+  }
+  if (processBefore && hasAndroidThread(processBefore, 'hermes-sampling')) {
+    throw new Error(
+      'The Android Hermes sampling profiler is active, so a runtime reload can abort the app. Use an explicit app.lifecycle restart.',
+    );
+  }
   await new Promise((resolve, reject) => {
     const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
     const timeout = setTimeout(() => {
@@ -44,15 +65,92 @@ async function reload(port) {
       reject(new Error(`Metro is not reachable on port ${numericPort}`));
     });
   });
+  const targetAfter = await waitForReload(
+    numericPort,
+    targetBefore.id,
+    processBefore,
+  );
+  const processAfter = processBefore ? readAndroidPid() : null;
+  if (processBefore && processAfter !== processBefore) {
+    throw new Error(
+      `Android app process ${processBefore} changed to ${processAfter ?? 'none'} during reload.`,
+    );
+  }
   return {
     ok: true,
     adapter: 'mobile',
     method: 'metro-message',
     command: 'reload',
     port: numericPort,
+    targetBefore: targetBefore.id,
+    targetAfter: targetAfter.id,
+    ...(processBefore
+      ? {
+          processBefore,
+          processAfter,
+          processContinuity: 'preserved',
+        }
+      : {}),
   };
 }
 
+async function waitForReload(port, targetBefore, processBefore) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (processBefore && readAndroidPid() !== processBefore) {
+      throw new Error(
+        `Android app process ${processBefore} exited during reload. Inspect the native crash before using an explicit app.lifecycle restart.`,
+      );
+    }
+    const target = await readHermesTarget(port).catch(() => null);
+    if (target && target.id !== targetBefore) return target;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(
+    `React Native did not expose a new Hermes target after reload on port ${port}`,
+  );
+}
+
+async function readHermesTarget(port) {
+  return discoverTarget(port, { probe: false });
+}
+
+function androidSerial() {
+  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+}
+
+function readAndroidPid() {
+  const serial = androidSerial();
+  if (!serial) return null;
+  const adb = resolveMobileToolPath('adb', { required: true });
+  const result = spawnSync(
+    adb,
+    ['-s', serial, 'shell', 'pidof', process.env.ANDROID_PACKAGE_ID || 'io.metamask'],
+    { encoding: 'utf8', timeout: 5_000 },
+  );
+  if (result.status !== 0) return null;
+  const pid = Number.parseInt(
+    String(result.stdout).trim().split(/\s+/u)[0] ?? '',
+    10,
+  );
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function hasAndroidThread(pid, name) {
+  const adb = resolveMobileToolPath('adb', { required: true });
+  const result = spawnSync(
+    adb,
+    ['-s', androidSerial(), 'shell', 'ps', '-T', '-p', String(pid)],
+    { encoding: 'utf8', timeout: 5_000 },
+  );
+  return (
+    result.status === 0 &&
+    String(result.stdout)
+      .split(/\r?\n/u)
+      .some((line) => line.trim().endsWith(name))
+  );
+}
+
 const args = parseArgs(process.argv.slice(2));
 reload(args.port)
   .then((result) => {

package/dist/adapters/mobile/prepare.js

@@ -59,6 +59,18 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
+  const rebuildNative = preflightMode === "rebuild-native" || preflightMode === "clean";
+  if (report.decision === "ready" && rebuildNative) {
+    const launch = await dispatchActionSequence(
+      launchActions(path.resolve(target), clearMetro),
+      target,
+      platform,
+      json,
+      preflightMode,
+      opts.watcherPort
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+  }
   if (report.decision === "ready" && clearMetro) {
     const launch = await dispatchActionSequence(
       withAppRestart(

package/dist/adapters.js

@@ -526,6 +526,7 @@ const MOBILE_BRIDGE_HANDLERS = {
   status: handleMobileStatus,
   navigate: handleMobileNavigate,
   press: handleMobilePress,
+  keyPress: handleMobileKeyPress,
   setInput: handleMobileSetInput,
   scroll: handleMobileScroll,
   waitFor: handleMobileWaitFor,
@@ -585,6 +586,11 @@ async function handleMobilePress(payload, context) {
   if (text !== void 0) return bridgeCommand(input, ["press-text", target]);
   return bridgeCommand(input, [longPress ? "long-press-test-id" : "press-test-id", target]);
 }
+async function handleMobileKeyPress(payload, context) {
+  const key = scalarText(payload.key, "ui.key_press.key", "Enter");
+  const input = mobileUiInput(context, "key_press", payload);
+  return bridgeCommand(input, ["key-press", key]);
+}
 async function handleMobileSetInput(payload, context) {
   const input = mobileUiInput(context, "set_input", payload);
   const testId = firstScalarText(payload, ["test_id", "testID"], "ui.set_input");
@@ -753,7 +759,17 @@ async function handleMobileWaitFor(payload, context) {
   return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
 }
 async function handleMobileHud(payload, context) {
-  const input = mobileUiInput(context, "hud", payload);
+  const automaticProgress = typeof payload.action_name === "string" || context.nodeId === "recipe-complete" && isRecord(payload.progress) && payload.progress.complete === true;
+  const captureProgress = payload.action_name === "ui.screenshot" || payload.action_name === "ui.capture_surface";
+  const input = mobileUiInput(
+    context,
+    "hud",
+    automaticProgress ? {
+      ...payload,
+      bridge_timeout_ms: captureProgress ? 1e4 : 2e3,
+      cdp_timeout_ms: captureProgress ? 1e4 : 2e3
+    } : payload
+  );
   if (payload.clear === true) {
     try {
       return await bridgeCommand(input, ["hide-step"]);
@@ -763,7 +779,10 @@ async function handleMobileHud(payload, context) {
   }
   const hud = mobileHudPayload(payload, context);
   try {
-    const result = await bridgeCommand(input, ["show-step-json", JSON.stringify(hud.step)]);
+    const result = await bridgeCommand(input, [
+      automaticProgress && !captureProgress ? "show-step-json-deferred" : "show-step-json",
+      JSON.stringify(hud.step)
+    ]);
     return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
   } catch (error) {
     return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
@@ -777,7 +796,7 @@ async function hideMobileHudOnTeardown(projectRoot, env = {}) {
     context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
   };
   try {
-    await bridgeCommand(input, ["hide-step"]);
+    await bridgeCommand(input, ["hide-step-deferred"]);
   } catch {
   }
 }

package/dist/commands/call.js

@@ -33,6 +33,7 @@ import {
   emitHealViolation,
   executeWithHealBounds,
   prepareHeal,
+  persistRunEffects,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
   preflightRecipe,
@@ -52,6 +53,7 @@ import {
 import { recipeTrustFailure } from "../recipe-security.js";
 import { isSensitiveKey, recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 import { closest } from "../command-contract.js";
+import { ProvenanceDriftError } from "../execution-provenance.js";
 async function handleCall(argv) {
   if (argv.includes("--list")) {
     const { options: options2 } = parseArgs(argv, "call");
@@ -282,11 +284,20 @@ async function handleCall(argv) {
     return checkoutBusyOut(json, "call", lock.message, lock.path);
   }
   try {
+    const authoredMobileRestart = adapter === "mobile" && resolvedAction === "app.lifecycle" && args.command === "restart";
     const prepared = await prepareHeal(adapter, target, options, json, {
-      skipMobileSourceFreshness: adapter === "mobile" && (resolvedAction === "app.lifecycle" || readMobileReleaseArtifactState(target) !== null)
+      skipMobileSourceFreshness: authoredMobileRestart || adapter === "mobile" && readMobileReleaseArtifactState(target) !== null
     });
     if (typeof prepared === "number") return prepared;
     const { state, heal } = prepared;
+    preflightedExecution = await preflightRecipe(
+      adapter,
+      recipe,
+      artifactsDir,
+      target,
+      actionManifestOverride,
+      callRuntimeOptions
+    );
     networkObservation = await startRunNetworkObservation(
       adapter,
       target,
@@ -320,7 +331,8 @@ async function handleCall(argv) {
             target,
             actionManifestOverride,
             callRuntimeOptions,
-            execution
+            execution,
+            state
           );
         },
         adapter,
@@ -337,6 +349,31 @@ async function handleCall(argv) {
       networkObservation = void 0;
       await performanceObservation?.finalize().catch(() => void 0);
       performanceObservation = void 0;
+      if (error instanceof ProvenanceDriftError) {
+        const failure = {
+          code: error.code,
+          message: error.message,
+          userAction: error.userAction,
+          provenancePath: error.provenancePath,
+          drift: error.drift
+        };
+        if (json) {
+          console.log(JSON.stringify({
+            schemaVersion: 1,
+            command: "call",
+            adapter,
+            action: shortName,
+            resolvedAction,
+            status: "fail",
+            error: failure,
+            exitCode: error.exitCode
+          }, null, 2));
+        } else {
+          console.error(`\u2717 mm-harness call: ${error.message}`);
+          console.error(`  Next: ${error.userAction}`);
+        }
+        return error.exitCode;
+      }
       throw error;
     }
     const { result, violation } = executionResult;
@@ -344,6 +381,7 @@ async function handleCall(argv) {
     networkObservation = void 0;
     await performanceObservation?.finalize(result.artifactManifestPath);
     performanceObservation = void 0;
+    persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";
       const example = describedAction ? actionExampleCommand(