@deeeed/metamask-harness 0.73.0 → 0.75.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.75.0 - 2026-10-04
+
+### Added
+
+- `mm-harness pin` gives a task a harness that a global upgrade cannot change. It copies the running installed harness into an immutable, versioned store (`~/.local/share/mm-harness/pins/<version>-<hash>/`, APFS clone where available; `MM_HARNESS_PIN_ROOT` overrides) and prints the copy's executable for the task to record. Pins are keyed by the install's full content, so the same install returns the same pin and a same-version rebuild gets its own; absolute links into the install are re-pointed into the copy, and a pin whose content changed after it was created is refused rather than reused. A source checkout or an existing pin is printed as is; an install whose dependencies or links lead outside it is refused. `doctor` reports a pinned runner as `pinned-install`.
+
+### Changed
+
+- `run` and `call` reach platform behavior through the adapter surface instead of branching on the adapter name: new optional `AdapterSurface` members `run` (environment, runtime preparation and checks, dependency block, heal wording, executed browser), `recording`, `diagnostics` (console capture, wallet log, in-app issue buffer), `observation` (network and performance) and `sourceFingerprint`. The engine modules (`run-engine`, `run`, `call`, `run-report`, `run-recording`, `recording-target`, `heal-bounds`, `execution-provenance`, `run-diagnostics`, performance and network observation, `cdp-trace`) go from 48 adapter-name branches to 0. Each platform's implementation lives under `src/adapters/<adapter>/` (`run.ts`, and now `launch.ts` for the Extension and Mobile launch profiles). The test-only `example` adapter is reached by the run/call engine with no shared-file edit. Flags, output, and the CLI goldens are unchanged, with one ordering exception: for `run` and `call` on Mobile, an invalid release-artifact state file is now reported after the running-recipe check instead of before it.
+- The runner's action set comes from a required `AdapterSurface.actions` member instead of adapter-name branches: the bundled manifest, the semantic actions each platform bundles, when live adapter scripts run and under tsx, the `cdp.target` probe, the `ui.*` transport, wrappers around the action and `app.lifecycle` adapters, funded-mutation binding and recipe input checks. The device video recorder joins `AdapterSurface.recording`. `adapters.ts`, `runner.ts`, `metamask-action-validation.ts`, `live-adapter-contract.ts` and `manifest.ts` go from 45 adapter-name branches to 0. The Mobile bridge, HUD, native-provider, lifecycle and runtime-identity code moves to `src/adapters/mobile/` and loads on first use, as does the Extension page helper. The test-only `example` adapter runs a recipe through the runner (manifest, `cdp.target`, `ui.*`, a bundled action, a live script) with no shared-file edit. Flags, output, and the CLI goldens are unchanged.
+
+### Fixed
+
+- `pr-body render` counts the nodes of a Recipe v1 graph (`workflow.nodes`). The recipe summary read `recipe.json (0 steps …)` for every v1 recipe; it now reads `recipe.json (<n> nodes …)` with the authored nodes (a `call` node once), next to the run log's executed node count.
+- Several `mm-harness` commands starting at once no longer race on dependency links. The local Farmslot relink (`FARMSLOT_ROOT`, `dev:link-farmslot`) holds one `proper-lockfile` lock, reclaimed when its holder dies, and swaps each link with `rename()`, so runs no longer fail with `EEXIST`/`ENOENT` or see a package missing. The self-package link is renamed into place too, so a fresh install no longer gets a stray link inside the checkout.
+
+## 0.74.0 - 2026-10-03
+
+### Changed
+
+- Adapters register in an `AdapterRegistry` (`src/adapters/registry.ts`) instead of a compiled-in union: the adapter id is a string, the four built-in surfaces register themselves, and `launch` resolves `--adapter` through the registry (the CLI front door still accepts only the four built-ins). `launch` moves behind a new `AdapterSurface.launch` member, so the command keeps only the shared grammar and no longer branches on the adapter name (39 such branches in `commands/launch/index.ts`, now 0). A test-only `example` adapter registers and launches with no shared-file edit. Flags, output, and the CLI goldens are unchanged.
+
 ## 0.73.0 - 2026-10-03
 
 ### Changed

package/README.md

@@ -84,7 +84,7 @@ mm-harness fixtures init --from /secure/path/wallet-fixture.json
 mm-harness fixtures init --dev
 ```
 
-Use `mm-harness update` to update a published installation.
+Use `mm-harness update` to update a published installation. `npm i -g` and `update` rewrite the global install in place, so a task that must survive an upgrade records `mm-harness pin` instead: it copies the running install into an immutable, versioned store and prints the copy's executable.
 
 ## Operate
 

package/adapters/shared/ensure-runner-deps.sh

@@ -30,10 +30,22 @@ deps_ready() {
 # is not npm-installed into its own node_modules, so symlink self for resolution.
 ensure_self_package_link() {
   local link="$RUNNER_DIR/node_modules/@deeeed/metamask-harness"
-  /bin/mkdir -p "$RUNNER_DIR/node_modules/@deeeed"
-  if [ ! -e "$link" ]; then
-    ln -sf "$RUNNER_DIR" "$link"
+  if [ -e "$link" ]; then
+    return 0
   fi
+  # Several bins can start at once on a fresh install. `ln -sf` would follow a link another
+  # run just made and create a second one inside the runner checkout, so stage the link and
+  # rename it into place: rename() replaces a link without following it.
+  node -e '
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const [runnerDir, link] = process.argv.slice(1);
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    const staged = `${link}.${process.pid}`;
+    fs.rmSync(staged, { force: true });
+    fs.symlinkSync(runnerDir, staged, "dir");
+    fs.renameSync(staged, link);
+  ' "$RUNNER_DIR" "$link"
 }
 
 ensure_dev_package_condition() {

package/dist/action-values.js

@@ -0,0 +1,15 @@
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function traceText(value) {
+  if (value === void 0 || value === null) return "";
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+export {
+  isRecord,
+  traceText
+};

package/dist/adapters/core/actions.js

@@ -0,0 +1,20 @@
+import { manifestPath } from "../../paths.js";
+const coreActions = {
+  manifestPath: () => manifestPath("core"),
+  semantic: [
+    "metamask.perps.close_positions",
+    "metamask.perps.start_state",
+    "metamask.perps.read_snapshot",
+    "metamask.perps.read_account"
+  ],
+  // read_account is Core's alone, and only its live adapter implements it.
+  liveOnly: ["metamask.perps.read_account"],
+  tsxLiveScripts: {
+    env: async (projectRoot, tempDir) => (await import("./live-script-env.js")).coreLiveScriptEnv(projectRoot, tempDir)
+  },
+  // Core declares no cdp.target; the probe matches the Extension's.
+  cdpTarget: { transport: "chrome-extension-cdp", probePath: "json/version" }
+};
+export {
+  coreActions
+};

package/dist/adapters/core/live-script-env.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { corePnpNodeOptions } from "../../commands/core-readiness.js";
+const CORE_WORKSPACE_PACKAGES = [
+  "@metamask/base-controller",
+  "@metamask/messenger",
+  "@metamask/controller-utils",
+  "@metamask/keyring-controller"
+];
+async function coreLiveScriptEnv(projectRoot, tempDir) {
+  const paths = {};
+  for (const pkg of CORE_WORKSPACE_PACKAGES) {
+    const packageDir = path.join(projectRoot, "packages", pkg.replace("@metamask/", ""));
+    const distEntry = path.join(packageDir, "dist/index.cjs");
+    if (existsSync(distEntry)) continue;
+    const srcDir = path.join(packageDir, "src");
+    if (!existsSync(path.join(srcDir, "index.ts"))) continue;
+    paths[pkg] = [path.join(srcDir, "index.ts")];
+    paths[`${pkg}/*`] = [path.join(srcDir, "*")];
+  }
+  if (Object.keys(paths).length === 0) return {};
+  const tsconfigPath = path.join(tempDir, "core-adapter.tsconfig.json");
+  await writeFile(
+    tsconfigPath,
+    `${JSON.stringify({ compilerOptions: { baseUrl: projectRoot, paths } }, null, 2)}
+`
+  );
+  return {
+    TSX_TSCONFIG_PATH: tsconfigPath,
+    NODE_OPTIONS: corePnpNodeOptions(projectRoot, process.env.NODE_OPTIONS)
+  };
+}
+export {
+  coreLiveScriptEnv
+};

package/dist/adapters/core/run.js

@@ -0,0 +1,54 @@
+import { coreDependencyBlock } from "../../commands/core-readiness.js";
+import { isRecord } from "../../commands/parse-args.js";
+const coreRun = {
+  async dependencyBlock(target, { recipe, librarySources, action }) {
+    const usesController = action !== void 0 ? actionUsesCoreController(action) : await recipeUsesCoreController(recipe, librarySources);
+    return usesController ? coreDependencyBlock(target) : null;
+  },
+  violationUserAction: (violation) => violation.code === "WALLET_STATE_REQUIRED" ? "for signing, configure a reserved wallet-fixture.json account and pass its non-empty name; an explicit 0x address is supported only by read-only actions" : void 0
+};
+async function recipeUsesCoreController(recipe, librarySources) {
+  if (objectUsesCoreController(recipe)) return true;
+  const refs = collectCallRefs(recipe);
+  if (refs.length === 0) return false;
+  const sources = librarySources ?? [];
+  if (sources.length === 0) return false;
+  const { loadRecipeLibraries } = await import("@farmslot/recipe-harness");
+  const recipes = (await loadRecipeLibraries(sources, { adapter: "core" })).recipes;
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (ref) => {
+    if (visited.has(ref)) return false;
+    visited.add(ref);
+    const dependency = recipes.get(ref);
+    if (!dependency) return false;
+    if (objectUsesCoreController(dependency.document)) return true;
+    return collectCallRefs(dependency.document).some(visit);
+  };
+  return refs.some(visit);
+}
+function objectUsesCoreController(value) {
+  if (Array.isArray(value)) return value.some(objectUsesCoreController);
+  if (!isRecord(value)) return false;
+  if (actionUsesCoreController(value.action)) return true;
+  return Object.values(value).some(objectUsesCoreController);
+}
+function collectCallRefs(value) {
+  const refs = [];
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    if (!isRecord(node)) return;
+    if (node.action === "call" && typeof node.ref === "string" && node.ref) refs.push(node.ref);
+    for (const child of Object.values(node)) visit(child);
+  };
+  visit(value);
+  return [...new Set(refs)];
+}
+function actionUsesCoreController(action) {
+  return typeof action === "string" && action.startsWith("metamask.perps.");
+}
+export {
+  coreRun
+};

package/dist/adapters/core/surface.js

@@ -1,6 +1,9 @@
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { shellQuote } from "../../commands/parse-args.js";
+import { adapterRegistry } from "../registry.js";
+import { coreActions } from "./actions.js";
+import { coreRun } from "./run.js";
 const coreSurface = {
   adapter: "core",
   headless: true,
@@ -53,8 +56,12 @@ const coreSurface = {
     launch: "mm-harness run <recipe>   # run recipes against the headless core",
     relaunch: "mm-harness verify",
     runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
-  }
+  },
+  launch: async ({ usage }) => usage("core is headless; there is nothing to launch.", "mm-harness verify"),
+  actions: coreActions,
+  run: coreRun
 };
+adapterRegistry.register(coreSurface);
 export {
   coreSurface
 };

package/dist/adapters/extension/action-inputs.js

@@ -0,0 +1,206 @@
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function extensionActionInputFindings(nodeId, node) {
+  const findings = [];
+  const action = node.action;
+  const maximum = (name, limit) => {
+    if (typeof node[name] !== "number" || node[name] <= limit) return;
+    findings.push({
+      severity: "error",
+      code: "recipe.invalid_param",
+      path: `workflow.nodes.${nodeId}.${name}`,
+      message: `${action} ${name} must not exceed ${limit}`
+    });
+  };
+  if (action === "metamask.perps.read_snapshot") {
+    if (node.market !== void 0 && node.markets !== void 0) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.markets`,
+        message: `${action} accepts market or markets, not both`
+      });
+    }
+    if (isRecord(node.history)) {
+      const start = node.history.start_time_ms;
+      const end = node.history.end_time_ms;
+      if (typeof start === "number" && typeof end === "number" && start > end) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.history.start_time_ms`,
+          message: `${action} history.start_time_ms must not exceed history.end_time_ms`
+        });
+      }
+      if (typeof node.history.limit === "number" && node.history.limit > 500) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.history.limit`,
+          message: `${action} history.limit must not exceed 500`
+        });
+      }
+    }
+    if (typeof node.max_items_per_section === "number" && node.max_items_per_section > 500) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.max_items_per_section`,
+        message: `${action} max_items_per_section must not exceed 500`
+      });
+    }
+    if (typeof node.timeout_ms === "number" && node.timeout_ms > 6e4) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.timeout_ms`,
+        message: `${action} timeout_ms must not exceed 60000`
+      });
+    }
+    if (isRecord(node.sampling)) {
+      if (typeof node.sampling.count === "number" && node.sampling.count > 10) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.sampling.count`,
+          message: `${action} sampling.count must not exceed 10`
+        });
+      }
+      if (typeof node.sampling.interval_ms === "number" && node.sampling.interval_ms > 3e4) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.sampling.interval_ms`,
+          message: `${action} sampling.interval_ms must not exceed 30000`
+        });
+      }
+    }
+    if (isRecord(node.expect)) {
+      if (typeof node.expect.minimum_changed_market_count === "number" && node.expect.minimum_changed_market_count > 100) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.expect.minimum_changed_market_count`,
+          message: `${action} expect.minimum_changed_market_count must not exceed 100`
+        });
+      }
+      if (typeof node.expect.minimum_history_count === "number" && node.expect.minimum_history_count > 500) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.expect.minimum_history_count`,
+          message: `${action} expect.minimum_history_count must not exceed 500`
+        });
+      }
+    }
+  }
+  if (action === "metamask.perps.assert_visible_consistency") {
+    maximum("sample_count", 10);
+    maximum("sample_interval_ms", 3e4);
+    maximum("minimum_changed_count", 200);
+    maximum("minimum_recent_activity_count", 50);
+    maximum("timeout_ms", 12e4);
+    maximum("max_items", 200);
+  }
+  const fundedVisibleMutation = action === "metamask.perps.close_visible_position" || action === "metamask.perps.close_orders" || action === "metamask.perps.edit_margin" || action === "metamask.perps.update_position_tpsl" || action === "metamask.perps.place_order" && node.confirm_live === true;
+  if (fundedVisibleMutation) {
+    const required = (name, pattern, message) => {
+      if (typeof node[name] === "string" && pattern.test(node[name])) return;
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.${name}`,
+        message
+      });
+    };
+    const decimal = action === "metamask.perps.close_visible_position" || action === "metamask.perps.update_position_tpsl" ? node.funding_amount : node.amount ?? node.notional;
+    const decimalText = String(decimal ?? "");
+    const match = /^([1-9][0-9]*)(?:\.([0-9]{1,6}))?$/u.exec(decimalText);
+    if (!match) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.${action === "metamask.perps.close_visible_position" || action === "metamask.perps.update_position_tpsl" ? "funding_amount" : "amount"}`,
+        message: `${action} funded decimal amount must be positive plain decimal text with at most six places`
+      });
+    }
+    if (action === "metamask.perps.place_order" && node.submit_attempts !== void 0 && node.submit_attempts !== 1) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.submit_attempts`,
+        message: `${action} funded visible submission requires submit_attempts=1`
+      });
+    }
+    if (action === "metamask.perps.close_visible_position" || action === "metamask.perps.edit_margin" || action === "metamask.perps.update_position_tpsl") {
+      required("funding_side", /^(?:long|short)$/u, `${action} requires the authorized position side`);
+    }
+    if (action === "metamask.perps.edit_margin" || action === "metamask.perps.update_position_tpsl") {
+      required(
+        "funding_position_size",
+        /^(?=[0-9.]*[1-9])[0-9]+(?:\.[0-9]+)? [A-Z0-9:_-]{2,20}$/u,
+        `${action} requires the exact visible position size`
+      );
+    }
+    if (action === "metamask.perps.close_visible_position" && node.cleanup_only === true) {
+      required(
+        "funding_position_size",
+        /^(?=[0-9.]*[1-9])[0-9]+(?:\.[0-9]+)? [A-Z0-9:_-]{2,20}$/u,
+        `${action} cleanup requires the exact visible position size`
+      );
+      if (node.amount != null) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.amount`,
+          message: `${action} cleanup must close the full exact position`
+        });
+      }
+    }
+    if (action === "metamask.perps.edit_margin" && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(String(node.funding_amount ?? ""))) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.funding_amount`,
+        message: `${action} requires the authorized position amount`
+      });
+    }
+    if (action === "metamask.perps.close_orders") {
+      required("side", /^(?:long|short)$/u, `${action} requires the exact order side`);
+      const outputPrice = /^\{\{outputs\.[A-Za-z0-9_.-]+\}\}$/u.test(String(node.limit_price ?? ""));
+      if (!outputPrice && (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? "")) || !(Number(node.limit_price) > 0))) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.limit_price`,
+          message: `${action} requires an explicit positive limit_price for resumable cancellation`
+        });
+      }
+    }
+    if (action === "metamask.perps.place_order" && String(node.order_type ?? "market") === "limit" && (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/u.test(String(node.limit_price ?? "")) || !(Number(node.limit_price) > 0))) {
+      findings.push({
+        severity: "error",
+        code: "recipe.invalid_param",
+        path: `workflow.nodes.${nodeId}.limit_price`,
+        message: `${action} funded limit submission requires explicit limit_price; offset-only pricing is not resumable`
+      });
+    }
+    for (const name of ["identity_rounding_tolerance_base_units", "balance_reconciliation_tolerance_base_units"]) {
+      if (node[name] === void 0) continue;
+      const value = String(node[name]);
+      if (!/^(?:0|[1-9][0-9]{0,6})$/u.test(value) || BigInt(value) > 1000000n) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.${name}`,
+          message: `${action} ${name} must be an integer string from 0 through 1000000`
+        });
+      }
+    }
+  }
+  return findings;
+}
+export {
+  extensionActionInputFindings
+};

package/dist/adapters/extension/actions.js

@@ -0,0 +1,51 @@
+import { manifestPath } from "../../paths.js";
+import { extensionActionInputFindings } from "./action-inputs.js";
+const extensionActions = {
+  manifestPath: () => manifestPath("extension"),
+  semantic: [
+    "app.network_capture",
+    "app.network_assert",
+    "app.performance_capture",
+    "app.performance_assert",
+    "metamask.assets.prepare_send",
+    "metamask.assets.review_send",
+    "metamask.assets.set_custom_gas",
+    "metamask.assets.select_network_scope",
+    "metamask.networks.add_chainlist",
+    "metamask.perps.compare_provider_market",
+    "metamask.perps.read_eligibility",
+    "metamask.perps.open_position_action",
+    "metamask.perps.edit_margin",
+    "metamask.perps.update_position_tpsl",
+    "metamask.perps.assert_visible_consistency",
+    "metamask.settings.set_basic_functionality",
+    "metamask.perps.read_snapshot"
+  ],
+  liveNeedsCdpPort: true,
+  cdpTarget: { transport: "chrome-extension-cdp", probePath: "json/version" },
+  ui: (harness) => ({
+    base: harness.createCdpWebUiTransport({
+      async withPage(input, callback) {
+        const { withExtensionPage } = await import("../../../library/actions/extension/platform/cdp.mjs");
+        return withExtensionPage(
+          {
+            action: input.action,
+            node: input.node,
+            context: {
+              nodeId: input.context.nodeId,
+              projectRoot: input.context.projectRoot,
+              artifactsDir: input.context.artifactsDir
+            }
+          },
+          callback
+        );
+      }
+    })
+  }),
+  trustedMutation: true,
+  inputFindings: extensionActionInputFindings,
+  ensureChecksOnly: true
+};
+export {
+  extensionActions
+};

package/dist/adapters/extension/console-capture.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import { verifyCapture } from "../../../library/actions/shared/console-collector.mjs";
 import { recipeRuntimePath } from "../../paths.js";
 import { ensureConsoleCollector } from "../console-capture.js";
 function extensionCaptureFiles(target) {
@@ -25,8 +27,18 @@ async function ensureExtensionConsoleCapture(target) {
     cwd: target
   });
 }
+async function verifyExtensionConsoleControl(capture) {
+  let extensionId = null;
+  try {
+    extensionId = fs.readFileSync(recipeRuntimePath(capture.projectRoot, "extension.id"), "utf8").trim();
+  } catch {
+    extensionId = null;
+  }
+  return verifyCapture({ cdpPort: capture.cdpPort, log: capture.extensionLog, target: "extension", extensionId });
+}
 export {
   ensureExtensionConsoleCapture,
   extensionCaptureFiles,
-  extensionCdpPort
+  extensionCdpPort,
+  verifyExtensionConsoleControl
 };