@deeeed/metamask-harness 0.73.0 → 0.75.0

package/dist/adapters/extension/launch.js

@@ -0,0 +1,315 @@
+import path from "node:path";
+import { colorHumanMessage } from "../../cli-color.js";
+import {
+  extensionDepsBlock,
+  extensionRuntimeReusable,
+  installExtensionDeps,
+  launchExtension
+} from "../../commands/launch/extension.js";
+import { shellQuote } from "../../commands/launch/quote.js";
+import { EXIT, spawnScript } from "../../commands/shared.js";
+import {
+  fixtureFeatureFlags,
+  sameFeatureFlags,
+  toRemoteFlagSpec
+} from "../../feature-flags.js";
+import { RECOVERY_CODE } from "../../heal-bounds.js";
+import { runnerDir, walletFixturePath } from "../../paths.js";
+import { ensureExtensionConsoleCapture } from "./console-capture.js";
+import { readExtensionPinnedFlags } from "./feature-flags.js";
+import { extensionProductConfigBlock } from "./product-config.js";
+import { releaseArtifactState, runtimeDistCheck } from "./runtime-decision.js";
+const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
+function verifyExtensionPin(target, requested) {
+  const pinned = readExtensionPinnedFlags(target);
+  if (pinned.error) {
+    return {
+      ok: false,
+      flags: {},
+      code: "RUNTIME_MANIFEST_UNREADABLE",
+      message: `the launched dist snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}`
+    };
+  }
+  if (pinned.overrides !== null && pinned.pinned === null) {
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the launched dist snapshot manifest (${pinned.sourcePath ?? "unknown path"}) carries no harness pin record; it was not written by this launch.`
+    };
+  }
+  const actual = pinned.pinned ?? {};
+  if (!sameFeatureFlags(actual, requested)) {
+    const mismatched = [.../* @__PURE__ */ new Set([...Object.keys(requested), ...Object.keys(actual)])].filter(
+      (key) => JSON.stringify(actual[key]) !== JSON.stringify(requested[key])
+    );
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the remote feature-flag pin ${toRemoteFlagSpec(requested) || "(none)"} does not match the launched snapshot manifest: ` + mismatched.map((key) => `${key} expected ${JSON.stringify(requested[key])}, got ${JSON.stringify(actual[key])}`).join("; ")
+    };
+  }
+  return { ok: true, flags: actual, message: "" };
+}
+function extensionQuickReattachFailed(output) {
+  return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
+}
+function extensionRuntimeBlocked(output) {
+  return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
+}
+function extensionBrowserMissing(output) {
+  return /Playwright Chromium is not installed|No compatible Chromium binary selected/u.test(output);
+}
+function extensionProductConfigMissing(output) {
+  return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
+}
+function extensionEvmRpcUnreachable(output) {
+  return /EVM_RPC_UNREACHABLE|EVM RPC readiness probe failed|Infura configured ≠ RPC reachable/u.test(output);
+}
+const extensionLaunchProfile = {
+  refuseFlags({ target }, { watch, runway, clearMetro, remoteFlagSpec }) {
+    if (runway) return { message: "runway is mobile-only.", userAction: "drop --runway for the extension" };
+    if (clearMetro) return { message: "--clear-metro is mobile-only.", userAction: "drop --clear-metro for the extension" };
+    if (remoteFlagSpec !== void 0 && watch) {
+      return {
+        message: "--remote-flag cannot be applied with --watch: the watcher never re-creates the dist snapshot that carries the pin.",
+        userAction: `mm-harness launch --adapter extension --remote-flag ${remoteFlagSpec} --target ${shellQuote(target)}`
+      };
+    }
+    return void 0;
+  },
+  // --url: initial main-tab page for extension launches (dapp beside the
+  // sidepanel); travels to live.sh/launch-browser via env. Sidepanel mode has a
+  // useful default so `mm-harness launch --sidepanel` opens a working dapp, not
+  // just a wallet panel with no page to connect from.
+  start({ options, displayMode, machine, wantWatch, tier }) {
+    const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
+    if (requestedUrl || displayMode === "sidepanel") {
+      process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
+    }
+    if (machine) return;
+    const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
+    const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
+    console.error(colorHumanMessage(
+      `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
+    ));
+  },
+  nativeInputs: ["package.json", "yarn.lock", "webpack.config.js"],
+  rebuildCommand: () => "mm-harness launch --build",
+  // Source-development launch paths require checkout tooling. A verified local
+  // release artifact can reuse its healthy browser without building or watching.
+  async healthcheck(launch, state) {
+    const { target, tier, wantWatch, heal, stream } = launch;
+    const artifact = releaseArtifactState(target);
+    const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+    const verifiedReleaseReuse = artifact.status === "valid" && reusable;
+    const verifiedReleaseLaunch = !wantWatch && tier !== "build" && artifact.status === "valid" && runtimeDistCheck(target, artifact).status === "fresh";
+    const willBuild = !reusable;
+    if (willBuild) {
+      const productConfigBlock = extensionProductConfigBlock(target);
+      if (productConfigBlock) {
+        return launch.fail(state, {
+          code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+          message: productConfigBlock.message,
+          recoverable: false,
+          userAction: productConfigBlock.userAction,
+          exitCode: EXIT.infra
+        });
+      }
+    }
+    const depsBlock = verifiedReleaseReuse || verifiedReleaseLaunch ? null : extensionDepsBlock(target);
+    if (depsBlock) {
+      if (heal === "off") return launch.usage(depsBlock.message, depsBlock.userAction);
+      const recoveryCode = "deps.installed";
+      state.attemptedRecoveries.push(recoveryCode);
+      stream.phase("recover");
+      const repaired = await installExtensionDeps(target);
+      if (repaired.status !== 0 || extensionDepsBlock(target)) {
+        return launch.fail(state, {
+          code: "DEPENDENCY_INSTALL_FAILED",
+          message: depsBlock.message,
+          recoverable: false,
+          userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
+          originalError: repaired.output,
+          exitCode: EXIT.infra
+        });
+      }
+      state.recovered.push(recoveryCode);
+      state.mutations.push({ type: "dependencies", action: "installed", path: target });
+    }
+    return void 0;
+  },
+  compose: ({ target, wantWatch, displayMode, remoteFlagRequest }, tier) => launchExtension(target, tier, wantWatch, displayMode, remoteFlagRequest),
+  classify({ target, remoteFlagRequest }, output) {
+    if (output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
+      return {
+        code: "REMOTE_FLAG_NOT_PINNABLE",
+        message: `a verified release artifact cannot carry a remote feature-flag pin (${remoteFlagRequest?.spec ?? ""}); its manifest is signed evidence and is never rewritten. Validate the artifact as shipped (drop --remote-flag and the fixture's remoteFeatureFlags) or validate the variant on a source build.`,
+        recoverable: false,
+        // The next step must leave the artifact alone: a --build here would replace
+        // the artifact under validation with a source build.
+        userAction: Object.keys(fixtureFeatureFlags(walletFixturePath(target))).length > 0 ? `remove remoteFeatureFlags from ${shellQuote(walletFixturePath(target))}, then: mm-harness launch --adapter extension --target ${shellQuote(target)}` : `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+        exitCode: EXIT.infra,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (extensionProductConfigMissing(output)) {
+      const block = extensionProductConfigBlock(target);
+      return {
+        code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+        message: block?.message ?? "Extension product configuration was not ready when the build started.",
+        recoverable: false,
+        userAction: block?.userAction ?? `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (extensionBrowserMissing(output)) {
+      return {
+        code: "EXTENSION_BROWSER_REQUIRED",
+        message: "the checkout Playwright browser is not installed; system Chrome is not a compatible unpacked-extension fallback. Installing the browser cache requires user approval.",
+        recoverable: false,
+        userAction: `ask the user for approval, then run: cd ${shellQuote(target)} && yarn playwright install chromium`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") || output.includes("EXTENSION_STARTUP_UNVERIFIED:")) {
+      return {
+        code: output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED",
+        message: "Extension startup is not healthy; inspect the background error before restarting or resetting wallet state.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (output.includes("EVM_RPC_EXECUTION_FAILED:")) {
+      return {
+        code: "EVM_RPC_EXECUTION_FAILED",
+        message: "Background RPC fetch failed during JavaScript execution; this does not establish an Infura authentication or connectivity failure.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (extensionEvmRpcUnreachable(output)) {
+      return {
+        code: "EVM_RPC_UNREACHABLE",
+        message: "EVM RPC readiness failed; Infura configured does not mean RPC reachable.",
+        recoverable: false,
+        userAction: `Check the effective INFURA_PROJECT_ID from the environment, .metamaskprodrc, or ${shellQuote(path.join(target, ".metamaskrc"))}, then rerun: mm-harness launch --verify --target ${shellQuote(target)}`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    return void 0;
+  },
+  async beforeHeal(launch, attempt, state) {
+    if (launch.tier !== "quick" || !extensionQuickReattachFailed(attempt.output)) return void 0;
+    const recoveryCode = "chrome.relaunched";
+    state.attemptedRecoveries.push(recoveryCode);
+    launch.stream.phase("recover");
+    const rebuildAttempt = await launch.compose("build");
+    if (rebuildAttempt.status === 0) {
+      state.recovered.push(recoveryCode);
+      return await launch.settle(state, rebuildAttempt.remoteFeatureFlags);
+    }
+    return launch.fail(state, {
+      code: "EXTENSION_RELAUNCH_FAILED",
+      message: "quick reattach failed, and clean relaunch failed too.",
+      recoverable: false,
+      exitCode: EXIT.infra,
+      originalError: rebuildAttempt.output.trim() || void 0
+    });
+  },
+  recovery: () => ({ code: RECOVERY_CODE.extension, restartApp: false }),
+  // --watch only restarts the webpack watcher; the snapshot, and its pin, are
+  // untouched, so the live record is reported rather than verified against a
+  // request the watcher could never apply (--remote-flag is refused with it;
+  // the fixture baseline stays whatever the last launch pinned).
+  provenFlags({ target, wantWatch, remoteFlagRequest }, requested) {
+    if (wantWatch) return { flags: readExtensionPinnedFlags(target).pinned };
+    const pinned = verifyExtensionPin(target, requested);
+    if (pinned.ok) return { flags: pinned.flags };
+    const spec = remoteFlagRequest?.spec;
+    return {
+      code: pinned.code ?? "REMOTE_FLAG_NOT_APPLIED",
+      message: pinned.message,
+      recoverable: false,
+      // A rebuild re-creates the snapshot; the flag is repeated only when one was asked for.
+      userAction: `mm-harness launch --adapter extension --build${spec ? ` --remote-flag ${spec}` : ""} --target ${shellQuote(target)}`,
+      exitCode: EXIT.runtime
+    };
+  },
+  async finish(launch, state, sidepanelRecoveryAllowed) {
+    const { target, machine, displayMode, tier, stream } = launch;
+    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
+    if (displayMode === "fullscreen") {
+      const sidepanelArgs = ["close"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      const fullscreen = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (fullscreen.status !== 0) {
+        return launch.fail(state, {
+          code: "FULLSCREEN_OPEN_FAILED",
+          message: "app launched but restoring the fullscreen Extension surface failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh close --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: fullscreen.output.trim() || void 0
+        });
+      }
+    }
+    if (displayMode === "sidepanel") {
+      const sidepanelArgs = ["open"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      if (!machine) {
+        console.error(
+          `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
+        );
+      }
+      const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (sidepanel.status !== 0) {
+        const recoveryCode = "chrome.relaunched";
+        if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
+          state.attemptedRecoveries.push(recoveryCode);
+          stream.phase("recover");
+          const rebuildAttempt = await launch.compose("build");
+          if (rebuildAttempt.status === 0) {
+            state.recovered.push(recoveryCode);
+            return await launch.settle(state, void 0, false);
+          }
+          return launch.fail(state, {
+            code: "EXTENSION_RELAUNCH_FAILED",
+            message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
+            recoverable: false,
+            exitCode: EXIT.infra,
+            originalError: rebuildAttempt.output.trim() || void 0
+          });
+        }
+        return launch.fail(state, {
+          code: "SIDEPANEL_OPEN_FAILED",
+          message: "app launched but opening the side panel failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: sidepanel.output.trim() || void 0
+        });
+      }
+    }
+    try {
+      await ensureExtensionConsoleCapture(target);
+    } catch (error) {
+      if (!machine) {
+        console.error(`WARN: Extension console capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return void 0;
+  },
+  verifyArgs: () => process.env.CDP_PORT ? ["--cdp-port", process.env.CDP_PORT] : [],
+  platformLabel: ({ mobileTarget, displayMode }) => mobileTarget ?? displayMode,
+  deviceLabel: ({ displayMode }) => displayMode
+};
+export {
+  extensionLaunchProfile
+};

package/dist/adapters/extension/launched-browser.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { isRecord } from "../../commands/parse-args.js";
+import { recipeRuntimeDir } from "../../paths.js";
+function readRecord(file) {
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(recorded) ? recorded : null;
+  } catch {
+    return null;
+  }
+}
+const browserCdp = createRequire(import.meta.url)("../../../adapters/shared/browser-cdp.cjs");
+function verifyLaunch(record, cdpPort) {
+  const launch = isRecord(record.launch) ? record.launch : {};
+  const pid = Number(launch.pid);
+  const port = Number(launch.cdpPort);
+  if (!Number.isInteger(pid) || !Number.isInteger(port) || typeof launch.profile !== "string" || typeof launch.processStartedAt !== "string") {
+    return "the browser record has no process identity (pid, start time, profile, CDP port)";
+  }
+  if (cdpPort && port !== Number(cdpPort)) return `the browser record is for CDP port ${port}, not ${cdpPort}`;
+  try {
+    const owner = browserCdp.cdpOwner(port, launch.profile);
+    if (owner.pid !== pid || owner.startedAt !== launch.processStartedAt) {
+      return `CDP port ${port} is now held by another browser process than the recorded pid ${pid}`;
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  return null;
+}
+function launchedBrowser(target, artifactsDir, cdpPort) {
+  const runtime = readRecord(path.join(artifactsDir, "extension-runtime", "runtime.json"));
+  const autolaunched = runtime && isRecord(runtime.browser) ? runtime.browser : null;
+  const candidates = [];
+  if (autolaunched) candidates.push([autolaunched, "run-autolaunch"]);
+  const slot = readRecord(path.join(path.resolve(target), recipeRuntimeDir(), "browser-resolution.json"));
+  if (slot) candidates.push([slot, "slot-runtime"]);
+  if (candidates.length === 0) return null;
+  const reasons = [];
+  for (const [record, boundTo] of candidates) {
+    const problem = verifyLaunch(record, cdpPort);
+    if (problem === null) return { ...record, boundTo };
+    reasons.push(`${boundTo}: ${problem}`);
+  }
+  return { boundTo: "none", reason: reasons.join("; ") };
+}
+export {
+  launchedBrowser
+};

package/dist/adapters/extension/run.js

@@ -0,0 +1,105 @@
+import { optionString } from "../../commands/parse-args.js";
+import { resolveExtensionBrowserPid } from "../../recording-target.js";
+import {
+  ensureExtensionConsoleCapture,
+  extensionCaptureFiles,
+  extensionCdpPort,
+  verifyExtensionConsoleControl
+} from "./console-capture.js";
+import { launchedBrowser } from "./launched-browser.js";
+const extensionRun = {
+  async prepareRuntime(projectRoot, runtimeOptions) {
+    if (runtimeOptions.skipExtensionRuntimePrepare === true) return;
+    const { releaseArtifactState, runtimeDistCheck } = await import("./runtime-decision.js");
+    const artifact = releaseArtifactState(projectRoot);
+    const runtimeSnapshot = runtimeDistCheck(projectRoot, artifact);
+    if (artifact.status !== "none") {
+      if (artifact.status === "valid" && runtimeSnapshot.status === "fresh") return;
+      throw new Error(
+        "The loaded release artifact identity is invalid or stale. Next: rerun runtime-launch with the same artifact source."
+      );
+    }
+    const { prepareExtensionRuntime } = await import("./runtime.js");
+    await prepareExtensionRuntime({
+      projectRoot,
+      cdpPort: runtimeOptions.cdpPort,
+      slot: runtimeOptions.slot,
+      launchExistingDist: runtimeOptions.launchExistingDist === true,
+      validationRuntimeDir: runtimeOptions.validationRuntimeDir,
+      pageMode: "home-or-sidepanel"
+    });
+  },
+  // The proof runtime is checked on the run's own ports: explicit flags win over
+  // the slot's for the check, and the slot's come back afterwards.
+  runtimeCheck({ target, options, heal, state, json, onRecovery }) {
+    return async () => {
+      const cliOptions = options;
+      const previousCdpPort = process.env.CDP_PORT;
+      const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+      const previousWatcherPort = process.env.WATCHER_PORT;
+      const explicitCdpPort = optionString(cliOptions, "cdpPort");
+      const explicitWatcherPort = optionString(cliOptions, "watcherPort") ?? optionString(cliOptions, "metroPort");
+      if (explicitCdpPort) {
+        process.env.CDP_PORT = explicitCdpPort;
+        process.env.RECIPE_CDP_PORT = explicitCdpPort;
+      }
+      if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
+      try {
+        const { ensureExtensionProofRuntime } = await import("../../commands/run-engine.js");
+        return await ensureExtensionProofRuntime(target, heal, state, json, { onRecovery });
+      } finally {
+        restoreEnv("CDP_PORT", previousCdpPort);
+        restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
+        restoreEnv("WATCHER_PORT", previousWatcherPort);
+      }
+    };
+  },
+  launchedBrowser: (target, artifactsDir, cdpPort) => launchedBrowser(target, artifactsDir, cdpPort)
+};
+const extensionRecording = {
+  target: (context) => resolveExtensionRecordingTarget(context),
+  framed: {
+    browserPid: (projectRoot, artifactsDir, cdpPort) => resolveExtensionBrowserPid(projectRoot, artifactsDir, cdpPort)
+  }
+};
+async function resolveExtensionRecordingTarget(context) {
+  const pid = resolveExtensionBrowserPid(
+    context.projectRoot,
+    context.artifactsDir,
+    context.env.CDP_PORT ?? context.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT
+  );
+  if (!pid) {
+    throw new Error(
+      "Could not resolve the extension browser PID for --record-video. Ensure the slot browser is running and CDP_PORT is set."
+    );
+  }
+  return { kind: "pid", pid };
+}
+const extensionDiagnostics = {
+  console: {
+    start: (projectRoot) => ensureExtensionConsoleCapture(projectRoot),
+    files: (projectRoot) => extensionCaptureFiles(projectRoot),
+    cdpPort: () => extensionCdpPort(),
+    verifyControl: (capture) => verifyExtensionConsoleControl(capture)
+  }
+};
+const extensionObservation = {
+  network: {
+    backend: async (_target, env, artifactsDir) => (await import("../../network-observation.js")).createExtensionNetworkBackend(env, artifactsDir),
+    actions: true
+  },
+  performance: {
+    backend: async (target, env, ports) => (await import("../../performance-observation.js")).createExtensionPerformanceObserver(target, env, ports),
+    platform: () => "extension"
+  }
+};
+function restoreEnv(key, value) {
+  if (value === void 0) delete process.env[key];
+  else process.env[key] = value;
+}
+export {
+  extensionDiagnostics,
+  extensionObservation,
+  extensionRecording,
+  extensionRun
+};

package/dist/adapters/extension/surface.js

@@ -9,6 +9,9 @@ import {
 } from "../slot-ports.js";
 import { decideExtensionReadiness } from "./runtime-decision.js";
 import { extensionProductConfigBlock } from "./product-config.js";
+import { adapterRegistry } from "../registry.js";
+import { extensionActions } from "./actions.js";
+import { extensionDiagnostics, extensionObservation, extensionRecording, extensionRun } from "./run.js";
 function watcherStatus(buildLog) {
   if (buildLog === "ok") return "up";
   if (buildLog === "no-watch") return "down";
@@ -98,8 +101,21 @@ const extensionSurface = {
     launch: "mm-harness launch",
     relaunch: "mm-harness launch --build",
     runtimeProbeRecovery: (target) => `mm-harness launch --adapter extension --target ${shellQuote(path.resolve(target))}`
-  }
+  },
+  launch: async (context) => {
+    const [{ runDeviceLaunch }, { extensionLaunchProfile }] = await Promise.all([
+      import("../../commands/launch/device.js"),
+      import("./launch.js")
+    ]);
+    return runDeviceLaunch(context, extensionLaunchProfile);
+  },
+  actions: extensionActions,
+  run: extensionRun,
+  recording: extensionRecording,
+  diagnostics: extensionDiagnostics,
+  observation: extensionObservation
 };
+adapterRegistry.register(extensionSurface);
 export {
   extensionRuntimeNextAction,
   extensionSurface

package/dist/adapters/mobile/actions.js

@@ -0,0 +1,54 @@
+import { manifestPath } from "../../paths.js";
+const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.press",
+  "ui.key_press",
+  "ui.set_input",
+  "ui.scroll",
+  "ui.swipe",
+  "ui.pan",
+  "ui.drag",
+  "ui.long_press",
+  "ui.wait_for",
+  "ui.screenshot",
+  "ui.capture_surface"
+]);
+const mobileActions = {
+  manifestPath: () => manifestPath("mobile"),
+  semantic: [
+    "app.network_capture",
+    "app.network_assert",
+    "app.performance_capture",
+    "app.performance_assert",
+    "metamask.swap_bridge.submit_transaction",
+    "metamask.perps.close_positions",
+    "metamask.perps.start_state",
+    "metamask.perps.clear_performance_caches",
+    "metamask.perps.measure_homepage_visible",
+    "metamask.perps.prepare_local_snapshot_endpoint"
+  ],
+  cdpTarget: {
+    transport: "react-native-debug-bridge",
+    probePath: "json/list",
+    watcherPortFirst: true,
+    requiredProbe: async (node, context) => (await import("./ui.js")).probeMobileBridgeTarget(node, context)
+  },
+  ui: (harness) => ({
+    base: harness.createReactNativeBridgeUiTransport({
+      bridge: {
+        send: async (command, context) => (await import("./ui.js")).sendMobileBridgeCommand(command, context)
+      }
+    }),
+    async execute(action, node, context, standard) {
+      if (NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
+        const { executeNativeProviderAction } = await import("./ui.js");
+        return executeNativeProviderAction(action, node, context, harness.createNativeUiTransport);
+      }
+      return standard();
+    }
+  }),
+  wrap: async (adapters) => (await import("./runtime-identity.js")).withMobileNativeRuntimeIdentity(adapters),
+  lifecycle: async (adapters) => (await import("./lifecycle.js")).mobileSourceAwareLifecycleAdapters(adapters)
+};
+export {
+  mobileActions
+};