@deeeed/metamask-harness 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.22.0 - 2026-07-26
+
+### Added
+
+- Added `execution-template` as the thin public boundary for shared checklist discovery and materialization.
+
+### Fixed
+
+- `ui.navigate page=home` recognizes both the current bottom navigation and the selected legacy Tokens tab.
+- Extension readiness recovers deterministically from transient target-list failures.
+- Team-library calls retain their source provenance.
+
+## 0.21.0 - 2026-07-24
+
+### Changed
+
+- Simplified action manifests to one schema-backed keyed action map; action kind,
+  library identity, categories, and provenance are inferred from authoritative
+  runtime inputs.
+- Updated the Farmslot protocol, agent runtime, and recipe harness dependencies
+  for Recipe Protocol v1 trace consistency.
+
 ## 0.20.0 - 2026-07-24
 
 ### Added

package/adapters/core/inject.sh

@@ -111,9 +111,7 @@ install_v1_runner_assets() {
     rsync -a --delete "$METAMASK_RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
   fi
   rm -rf "$HARNESS_DIR/runner/flows"
-  if [ -f "$METAMASK_RUNNER_DIR/library/library.json" ]; then
-    cp "$METAMASK_RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
-  fi
+  rm -f "$HARNESS_DIR/runner/library.json"
   if [ ! -x "$HARNESS_DIR/runner/bin/mm-harness" ]; then
     echo "Refusing core recipe harness install: failed to make runner executable." >&2
     return 1

package/adapters/extension/inject.mjs

@@ -90,8 +90,8 @@ copyFile(path.join(runnerDir, 'library/manifests/mobile.action-manifest.json'),
 copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'runner/manifests/extension.action-manifest.json'));
 copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'action-manifest.json'));
 copyDir(path.join(runnerDir, 'library/recipes'), path.join(harnessDir, 'runner/recipes'));
-copyFile(path.join(runnerDir, 'library/library.json'), path.join(harnessDir, 'runner/library.json'));
 fs.rmSync(path.join(harnessDir, 'runner/flows'), { recursive: true, force: true });
+fs.rmSync(path.join(harnessDir, 'runner/library.json'), { force: true });
 // The installed overlay has a flat scripts/ runtime API independent of the
 // package's source layout.
 copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));

package/adapters/mobile/inject.sh

@@ -74,8 +74,8 @@ cp "$RUNNER_DIR/library/manifests/mobile.action-manifest.json" "$HARNESS_DIR/act
 cp "$RUNNER_DIR/library/manifests/mobile.action-manifest.json" "$HARNESS_DIR/runner/manifests/mobile.action-manifest.json"
 cp "$RUNNER_DIR/library/manifests/extension.action-manifest.json" "$HARNESS_DIR/runner/manifests/extension.action-manifest.json"
 rsync -a --delete "$RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
-cp "$RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
 rm -rf "$HARNESS_DIR/runner/flows"
+rm -f "$HARNESS_DIR/runner/library.json"
 cp "$RUNNER_DIR/adapters/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
 cp "$RUNNER_DIR/adapters/shared/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
 cp "$RUNNER_DIR/adapters/shared/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"

package/dist/adapters/extension/ensure-ready.js

@@ -36,9 +36,11 @@ async function openHome(port, extensionId) {
   try {
     let res = await fetch(endpoint, { method: "PUT", signal: AbortSignal.timeout(8e3) });
     if (res.status === 404 || res.status === 405) res = await fetch(endpoint, { signal: AbortSignal.timeout(8e3) });
-    return res.ok;
+    if (!res.ok) return null;
+    const value = await res.json();
+    return value && typeof value === "object" ? value : {};
   } catch {
-    return false;
+    return null;
   }
 }
 function homePages(targets, extensionId) {
@@ -94,7 +96,7 @@ async function ensureExtensionReady(target, options) {
         continue;
       }
       action = "opened";
-      opened = await openHome(cdpPort, extensionId) || opened;
+      opened = Boolean(await openHome(cdpPort, extensionId)) || opened;
       await sleep(1500);
     } else {
       action = "pruned";
@@ -149,20 +151,47 @@ async function ensureExtensionReady(target, options) {
   if (action === "pruned" && (health.status !== "PASS" || after !== 1)) {
     const listing = await jsonList(cdpPort);
     if (listing.ok) {
-      action = "reopened";
-      for (const h of homePages(listing.targets, extensionId)) {
-        await closeTab(cdpPort, String(h.id));
-        closed += 1;
-      }
-      await sleep(500);
-      opened = await openHome(cdpPort, extensionId) || opened;
+      const existingHomeIds = new Set(
+        homePages(listing.targets, extensionId).map((home) => String(home.id))
+      );
+      const replacement = await openHome(cdpPort, extensionId);
+      opened = Boolean(replacement) || opened;
       await sleep(1500);
-      const relisted = await jsonList(cdpPort);
-      if (!relisted.ok) {
-        return base({ extensionId, opened, action, homeTabs: { before, closed, after }, reasonCode: "cdp-unreachable" });
+      const replacementListing = await jsonList(cdpPort);
+      if (!replacementListing.ok) {
+        return base({
+          extensionId,
+          opened,
+          action,
+          homeTabs: { before, closed, after },
+          reasonCode: "cdp-unreachable"
+        });
+      }
+      const replacementHomes = homePages(replacementListing.targets, extensionId);
+      const replacementId = replacement?.id && replacementHomes.some((home) => home.id === replacement.id) ? String(replacement.id) : replacementHomes.find((home) => !existingHomeIds.has(String(home.id)))?.id;
+      if (replacementId) {
+        action = "reopened";
+        for (const home of replacementHomes) {
+          if (String(home.id) === replacementId) continue;
+          await closeTab(cdpPort, String(home.id));
+          closed += 1;
+        }
+        await sleep(500);
+        const relisted = await jsonList(cdpPort);
+        if (!relisted.ok) {
+          return base({
+            extensionId,
+            opened,
+            action,
+            homeTabs: { before, closed, after },
+            reasonCode: "cdp-unreachable"
+          });
+        }
+        after = homePages(relisted.targets, extensionId).length;
+        health = await checkHealth();
+      } else {
+        after = replacementHomes.length;
       }
-      after = homePages(relisted.targets, extensionId).length;
-      health = await checkHealth();
     }
   }
   let slotTitle;

package/dist/cli-commands.js

@@ -18,6 +18,7 @@ const SPEC = {
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action", "--library"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
+    { name: "execution-template", desc: "Discover and materialize shared agent checklists", args: ["list", "materialize", "lint", "new"], flags: ["--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--flow", "--run-mode", "--platform", "--domain", "--id", "--provenance", "--include-shadowed", "--no-include-shadowed", "--title", "--force", "--json"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },

package/dist/cli.js

@@ -20,6 +20,7 @@ import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
+import { handleExecutionTemplate } from "./commands/execution-template.js";
 import { handleLast } from "./commands/last.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 const COMMANDS = {
@@ -121,6 +122,7 @@ async function main(argv) {
   if (command === "recipe-quality") return handleRecipeQuality(argv.slice(1));
   if (command === "check") return handleCheck(argv.slice(1));
   if (command === "checklist") return handleChecklist(argv.slice(1));
+  if (command === "execution-template") return handleExecutionTemplate(argv.slice(1));
   if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);

package/dist/command-contract.js

@@ -88,6 +88,32 @@ const PUBLIC_COMMAND_CONTRACTS = {
     ],
     minimumPositionals: 2
   },
+  "execution-template": {
+    usage: "mm-harness execution-template <list|materialize|lint|new> [target] [options]",
+    options: options(HELP, JSON, {
+      "--dir": value(),
+      "--domain-dir": value(),
+      "--project-worker": value(),
+      "--project-name": value(),
+      "--package-templates": value(),
+      "--package-id": value(),
+      "--flow": value(),
+      "--run-mode": value(["autonomous", "interactive", "validation"]),
+      "--platform": value(),
+      "--domain": value(),
+      "--id": value(),
+      "--provenance": value(),
+      "--include-shadowed": bool(),
+      "--no-include-shadowed": bool(),
+      "--title": value(),
+      "--force": bool()
+    }),
+    positionals: [
+      { label: "action", choices: ["list", "materialize", "lint", "new"] }
+    ],
+    minimumPositionals: 1,
+    variadic: { label: "target", validate: (value2) => value2.length > 0 }
+  },
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
       "--action": value(),
@@ -360,6 +386,37 @@ function validatePublicInvocation(argv, examples = {}) {
       );
     }
   }
+  if (name === "execution-template") {
+    const action = positionals[0];
+    const validAction = ["list", "materialize", "lint", "new"].includes(action ?? "");
+    const targetCount = Math.max(0, positionals.length - 1);
+    if (validAction && action === "list" && targetCount > 0) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `execution-template list does not accept positional '${positionals[1]}'.`,
+        contract,
+        examples
+      );
+    }
+    if (validAction && (action === "materialize" || action === "lint" || action === "new") && targetCount === 0) {
+      return missingPositionalFailure(
+        name,
+        `execution-template ${action} requires <target>.`,
+        contract,
+        examples
+      );
+    }
+    if (validAction && targetCount > 1) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `unexpected positional '${positionals[2]}'; execution-template ${action} accepts one <target>.`,
+        contract,
+        examples
+      );
+    }
+  }
   if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
     const missing = contract.positionals?.[0]?.label ?? "argument";
     return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);

package/dist/commands/call.js

@@ -470,7 +470,7 @@ function renderCallExamples(short, examples) {
   if (!Array.isArray(examples)) return [];
   const out = [];
   for (const example of examples.slice(0, 2)) {
-    const node = isRecord(example) && isRecord(example.node) ? example.node : void 0;
+    const node = isRecord(example) ? example : void 0;
     if (!node) continue;
     const tokens = Object.entries(node).filter(([key]) => key !== "action" && key !== "intent").map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
     out.push(`mm-harness call ${short} ${tokens.join(" ")}`.trim());

package/dist/commands/execution-template.js

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+const require2 = createRequire(import.meta.url);
+async function handleExecutionTemplate(argv) {
+  let entrypoint;
+  try {
+    entrypoint = require2.resolve(
+      "@farmslot/agent-runtime/scripts/execution-template-cli.mjs"
+    );
+  } catch (error) {
+    console.error(
+      `mm-harness execution-template: installed @farmslot/agent-runtime does not expose the catalog command: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return 1;
+  }
+  const result = spawnSync(process.execPath, [entrypoint, ...argv], {
+    env: process.env,
+    stdio: "inherit"
+  });
+  if (result.error) {
+    console.error(`mm-harness execution-template: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+export {
+  handleExecutionTemplate
+};

package/dist/commands/manifest.js

@@ -12,10 +12,12 @@ import {
 import { resolveMetaMaskLibrarySources } from "./run-engine.js";
 import { isSensitiveKey, redactStructuredValue } from "../command-journal.js";
 import {
+  OFFICIAL_RECIPE_ACTIONS,
   officialRecipeActionCapabilities
 } from "@farmslot/protocol";
 import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
 import { closest } from "../command-contract.js";
+const OFFICIAL_ACTIONS = new Set(OFFICIAL_RECIPE_ACTIONS);
 async function handleActions({ options, positional }) {
   const { adapter, target } = resolveAdapter(options);
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
@@ -211,7 +213,7 @@ function authoredExampleNode(examples, preferredValues, schema) {
   if (!Array.isArray(examples)) return void 0;
   if (preferredValues && Object.keys(preferredValues).length > 0) {
     const normalizedValues = normalizePreferredValues(preferredValues, schema);
-    const nodes = examples.map((example) => isRecord(example) && isRecord(example.node) ? example.node : void 0).filter((node) => node !== void 0);
+    const nodes = examples.filter(isRecord);
     if (nodes.length === 0) return void 0;
     const ranked = nodes.map((node) => ({
       node,
@@ -226,7 +228,7 @@ function authoredExampleNode(examples, preferredValues, schema) {
     return { ...ranked[0].node, ...normalizedValues };
   }
   for (const example of examples) {
-    if (isRecord(example) && isRecord(example.node)) return example.node;
+    if (isRecord(example)) return example;
   }
   return void 0;
 }
@@ -305,22 +307,15 @@ function summarizeActionCategories(actions) {
 }
 function describeManifestActions(manifest, actionSources = /* @__PURE__ */ new Map()) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
-  const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
-  const official = Array.isArray(manifestRecord.supported_official_actions) ? manifestRecord.supported_official_actions.filter((value) => typeof value === "string") : [];
-  const custom = Array.isArray(manifestRecord.custom_actions) ? manifestRecord.custom_actions.flatMap((entry) => {
-    if (typeof entry === "string") return [{ name: entry, metadata: metadata[entry] }];
-    if (isRecord(entry) && typeof entry.name === "string") {
-      const entryMetadata = { ...entry };
-      const metadataOverride = metadata[entry.name];
-      if (isRecord(metadataOverride)) Object.assign(entryMetadata, metadataOverride);
-      return [{ name: entry.name, metadata: entryMetadata }];
-    }
-    return [];
-  }) : [];
-  return [
-    ...official.map((name) => describeManifestAction(name, "official", metadata[name], actionSources.get(name))),
-    ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata, actionSources.get(entry.name)))
-  ];
+  const actions = isRecord(manifestRecord.actions) ? manifestRecord.actions : {};
+  return Object.entries(actions).map(
+    ([name, metadata]) => describeManifestAction(
+      name,
+      OFFICIAL_ACTIONS.has(name) ? "official" : "custom",
+      metadata,
+      actionSources.get(name)
+    )
+  );
 }
 function describeManifestAction(name, kind, metadata, source) {
   const record = isRecord(metadata) ? metadata : {};
@@ -330,7 +325,7 @@ function describeManifestAction(name, kind, metadata, source) {
   return {
     name,
     kind,
-    category: actionCategory(name, record.category),
+    category: actionCategory(name),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
@@ -347,8 +342,7 @@ function describeManifestAction(name, kind, metadata, source) {
     ])]
   };
 }
-function actionCategory(name, configured) {
-  if (typeof configured === "string" && configured.trim()) return configured.trim().toLowerCase();
+function actionCategory(name) {
   const segments = name.split(".");
   if (segments[0] === "metamask" && segments.length > 2) return segments[1] ?? "metamask";
   if (segments[0] === "app" || segments[0] === "cdp") return "runtime";

package/dist/commands/run-engine.js

@@ -21,6 +21,7 @@ import {
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
 import { validateMetaMaskActionInputs } from "../metamask-action-validation.js";
+import { gitLibraryProvenance } from "../library-provenance.js";
 import {
   beginRunDiagnostics,
   finishRunDiagnostics
@@ -655,14 +656,22 @@ async function resolveMetaMaskLibrarySources(libraryEntry, recipePath) {
   if (!sources.some((source) => path.resolve(source.root) === canonicalRoot)) {
     sources.push({ name: "metamask", root: canonicalRoot });
   }
-  return sources.map((source) => ({
-    ...source,
-    provenance: source.provenance ?? {
-      kind: source.name === "metamask" ? "bundled" : "library",
-      trust: source.name === "metamask" ? "trusted" : "unknown",
-      name: source.name ?? path.basename(source.root)
-    }
-  }));
+  return Promise.all(
+    sources.map(async (source) => {
+      const isBundled = source.name === "metamask";
+      const detected = isBundled ? {} : await gitLibraryProvenance(source.root);
+      return {
+        ...source,
+        provenance: {
+          kind: isBundled ? "bundled" : "library",
+          trust: isBundled ? "trusted" : "unknown",
+          name: source.name ?? path.basename(source.root),
+          ...detected,
+          ...source.provenance
+        }
+      };
+    })
+  );
 }
 function synthesizeOneNodeRecipe(action, args) {
   return {

package/dist/library-provenance.js

@@ -0,0 +1,33 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function gitLibraryProvenance(root) {
+  try {
+    const { stdout: tracked } = await execFileAsync("git", ["-C", root, "ls-files", "--", "."], {
+      encoding: "utf8",
+      timeout: 5e3
+    });
+    if (!tracked.trim()) return {};
+    const [{ stdout: revision }, { stdout: status }] = await Promise.all([
+      execFileAsync("git", ["-C", root, "rev-parse", "HEAD"], {
+        encoding: "utf8",
+        timeout: 5e3
+      }),
+      execFileAsync(
+        "git",
+        ["-C", root, "status", "--porcelain=v1", "--untracked-files=normal", "--", "."],
+        {
+          encoding: "utf8",
+          timeout: 5e3
+        }
+      )
+    ]);
+    const trimmedRevision = revision.trim();
+    return trimmedRevision ? { revision: trimmedRevision, dirty: status.trim().length > 0 } : {};
+  } catch {
+    return {};
+  }
+}
+export {
+  gitLibraryProvenance
+};