@deeeed/metamask-harness 0.19.1 → 0.21.0

package/dist/commands/run-engine.js

@@ -20,6 +20,7 @@ import {
 } from "../paths.js";
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
+import { validateMetaMaskActionInputs } from "../metamask-action-validation.js";
 import {
   beginRunDiagnostics,
   finishRunDiagnostics
@@ -276,7 +277,10 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
     manifest,
     validationOptions
   );
-  const findings = [...withManifest.findings];
+  const findings = [
+    ...withManifest.findings,
+    ...validateMetaMaskActionInputs(recipe)
+  ];
   if (withManifest.status === "valid" && isRecord(recipe) && libraryResolution) {
     try {
       const digest = protocol.digestRecipeDocument(recipe);
@@ -304,7 +308,8 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
             dependency.document,
             manifest,
             validationOptions
-          ).findings
+          ).findings,
+          ...validateMetaMaskActionInputs(dependency.document)
         );
       }
     } catch (error) {

package/dist/heal-bounds.js

@@ -62,7 +62,7 @@ async function ensureOverlay(adapter, target, heal, state, json) {
 }
 function classifyFailure(output) {
   if (/wallet|fixture|keyring|not seeded|\bsrp\b|password|onboard/iu.test(output)) return "wallet";
-  if (/metro|cdp|chrome|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
+  if (/metro|cdp|chrome|bridge|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
     return "infra";
   }
   return "app";

package/dist/manifest.js

@@ -1,10 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { manifestPath, readJson, importRecipeProtocol } from "./paths.js";
-import {
-  actionSourceIntegrity,
-  metaMaskActionExecutionCapabilities
-} from "./recipe-security.js";
+import { actionSourceIntegrity } from "./recipe-security.js";
 function loadMetaMaskMobileActionManifest() {
   return asActionManifest(readJson(manifestPath("mobile")));
 }
@@ -26,12 +24,12 @@ async function resolveActionManifest(adapter, overridePath, librarySources, task
     const implementationRoot = path.resolve(
       taskActionRoot ?? defaultImplementationRoot(manifestPath2)
     );
-    const manifest = withMetaMaskExecutionCapabilities(loadActionManifest(adapter, manifestPath2));
+    const manifest = loadActionManifest(adapter, manifestPath2);
     await validateManifest(manifest);
     const integrity = await actionSourceIntegrity(manifestPath2, "task", implementationRoot);
     return {
       manifest,
-      actionSources: describeManifestSources(manifest, {
+      actionSources: await describeManifestSources(manifest, {
         name: "task",
         tier: "task",
         manifestPath: manifestPath2,
@@ -41,109 +39,125 @@ async function resolveActionManifest(adapter, overridePath, librarySources, task
       })
     };
   }
-  const canonicalPath = manifestPath(adapter);
-  const sources = librarySources?.length ? librarySources : [{ name: "metamask", root: path.dirname(path.dirname(canonicalPath)) }];
+  const canonicalPath = path.resolve(manifestPath(adapter));
+  const canonicalRoot = path.dirname(path.dirname(canonicalPath));
+  const sources = librarySources?.length ? librarySources : [{ name: "metamask", root: canonicalRoot }];
   const manifests = [];
   for (const source of sources) {
-    const file = path.join(source.root, "manifests", `${adapter}.action-manifest.json`);
+    const file = path.resolve(source.root, "manifests", `${adapter}.action-manifest.json`);
     if (!fs.existsSync(file)) continue;
     const manifest = asActionManifest(readJson(file));
     await validateManifest(manifest);
     manifests.push({ source, file, manifest });
   }
-  if (!manifests.some((entry) => path.resolve(entry.file) === path.resolve(canonicalPath))) {
+  if (!manifests.some((entry) => entry.file === canonicalPath)) {
     const manifest = loadActionManifest(adapter);
     await validateManifest(manifest);
-    manifests.push({ source: { name: "metamask", root: path.dirname(path.dirname(canonicalPath)) }, file: canonicalPath, manifest });
+    manifests.push({
+      source: { name: "metamask", root: canonicalRoot },
+      file: canonicalPath,
+      manifest
+    });
   }
-  const canonical = manifests.find((entry) => entry.source.name === "metamask") ?? manifests.at(-1);
+  const canonical = manifests.find((entry) => entry.file === canonicalPath);
   if (!canonical) throw new Error(`No ${adapter} action manifest could be resolved.`);
-  const base = cloneManifest(canonical.manifest);
-  const official = new Set(stringArray(recordOf(base).supported_official_actions));
-  const custom = /* @__PURE__ */ new Map();
-  const customMetadata = /* @__PURE__ */ new Map();
-  const bindings = /* @__PURE__ */ new Map();
+  const official = new Set(OFFICIAL_RECIPE_ACTIONS);
+  const canonicalActions = actionsOf(canonical.manifest);
+  const mergedActions = {};
+  for (const [name, entry] of Object.entries(canonicalActions)) {
+    if (official.has(name)) mergedActions[name] = entry;
+  }
   const canonicalImplementationRoot = path.join(canonical.source.root, "actions");
   const canonicalIntegrity = await actionSourceIntegrity(
     canonical.file,
     "canonical",
     canonicalImplementationRoot
   );
-  const actionSources = describeManifestSources(base, {
-    name: "metamask",
-    tier: "canonical",
-    manifestPath: canonical.file,
-    implementationRoot: canonicalImplementationRoot,
-    trust: "trusted",
-    ...canonicalIntegrity
-  });
-  for (const entry of manifests) {
-    const sourceName = entry.source.name ?? path.basename(entry.source.root);
-    const tier = sourceName === "metamask" ? "canonical" : sourceName === "personal" ? "personal" : "team";
+  const actionSources = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(mergedActions)) {
+    actionSources.set(name, {
+      name: "official",
+      tier: "official",
+      manifestPath: canonical.file
+    });
+  }
+  const custom = /* @__PURE__ */ new Set();
+  const ordered = [
+    ...manifests.filter((entry) => entry.file !== canonicalPath),
+    canonical
+  ];
+  for (const entry of ordered) {
+    const isCanonical = entry.file === canonicalPath;
+    if (!isCanonical && entry.manifest.observers?.length) {
+      throw new Error(
+        `Library manifest ${entry.file} declares observers, but external library observers are not executable; remove observers or use an explicit task action manifest.`
+      );
+    }
+    const sourceName = isCanonical ? "metamask" : entry.source.name ?? path.basename(entry.source.root);
+    const tier = isCanonical ? "canonical" : sourceName === "personal" ? "personal" : "team";
     const implementationRoot = path.join(entry.source.root, "actions");
-    const integrity = await actionSourceIntegrity(entry.file, tier, implementationRoot);
+    const integrity = isCanonical ? canonicalIntegrity : await actionSourceIntegrity(entry.file, tier, implementationRoot);
     const sourceInfo = {
       name: sourceName,
       tier,
       manifestPath: entry.file,
       implementationRoot,
-      trust: entry.source.provenance?.trust ?? (tier === "canonical" ? "trusted" : "unknown"),
+      trust: entry.source.provenance?.trust ?? (isCanonical ? "trusted" : "unknown"),
       ...integrity
     };
-    const manifestRecord = recordOf(entry.manifest);
-    const metadata = recordOf(manifestRecord.action_metadata);
-    for (const action of customActions(manifestRecord.custom_actions)) {
-      if (official.has(action.name)) {
-        throw new Error(`Library action ${action.name} from ${entry.file} conflicts with an official action.`);
+    for (const [name, action] of Object.entries(actionsOf(entry.manifest))) {
+      if (official.has(name)) {
+        if (!isCanonical) {
+          throw new Error(
+            `Library action ${name} from ${entry.file} conflicts with an official action; team libraries may declare namespaced custom actions only.`
+          );
+        }
+        continue;
       }
-      if (custom.has(action.name)) {
-        const existing = actionSources.get(action.name);
+      if (custom.has(name)) {
+        const existing = actionSources.get(name);
         if (existing && existing.name !== sourceName) {
           existing.shadows = [...existing.shadows ?? [], sourceName];
         }
         continue;
       }
-      custom.set(action.name, action.value);
-      customMetadata.set(action.name, metadata[action.name]);
-      actionSources.set(action.name, { ...sourceInfo });
-    }
-    for (const binding of objectArray(manifestRecord.native_bindings)) {
-      const action = typeof binding.action === "string" ? binding.action : void 0;
-      if (action && !bindings.has(action)) bindings.set(action, binding);
+      custom.add(name);
+      mergedActions[name] = action;
+      actionSources.set(name, { ...sourceInfo });
     }
   }
-  const baseRecord = recordOf(base);
-  baseRecord.custom_actions = [...custom.values()];
-  const baseMetadata = recordOf(baseRecord.action_metadata);
-  for (const [name, metadata] of customMetadata) {
-    if (metadata !== void 0) baseMetadata[name] = metadata;
+  return {
+    manifest: {
+      $schema: canonical.manifest.$schema,
+      actions: mergedActions,
+      ...canonical.manifest.observers ? { observers: canonical.manifest.observers } : {}
+    },
+    actionSources
+  };
+}
+function actionsOf(manifest) {
+  return manifest.actions;
+}
+async function describeManifestSources(manifest, customSource) {
+  const official = new Set(OFFICIAL_RECIPE_ACTIONS);
+  const sources = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(actionsOf(manifest))) {
+    if (official.has(name)) {
+      sources.set(name, {
+        name: "official",
+        tier: "official",
+        manifestPath: customSource.manifestPath
+      });
+      continue;
+    }
+    sources.set(name, { ...customSource });
   }
-  baseRecord.action_metadata = baseMetadata;
-  baseRecord.native_bindings = [...bindings.values()];
-  return { manifest: withMetaMaskExecutionCapabilities(base), actionSources };
+  return sources;
 }
 function defaultImplementationRoot(selectedManifestPath) {
   const manifestDirectory = path.dirname(selectedManifestPath);
   return path.basename(manifestDirectory) === "manifests" ? path.join(path.dirname(manifestDirectory), "actions") : path.join(manifestDirectory, "actions");
 }
-function withMetaMaskExecutionCapabilities(manifest) {
-  const result = cloneManifest(manifest);
-  const record = recordOf(result);
-  if (!Array.isArray(record.custom_actions)) return result;
-  record.custom_actions = record.custom_actions.map((entry) => {
-    const name = typeof entry === "string" ? entry : recordOf(entry).name;
-    if (typeof name !== "string") return entry;
-    const capabilities = metaMaskActionExecutionCapabilities(name);
-    if (capabilities.length === 0) return entry;
-    const declaredValue = typeof entry === "string" ? void 0 : recordOf(entry).execution_capabilities;
-    const declared = Array.isArray(declaredValue) ? declaredValue.filter(
-      (capability) => typeof capability === "string"
-    ) : [];
-    const executionCapabilities = [.../* @__PURE__ */ new Set([...declared, ...capabilities])];
-    return typeof entry === "string" ? { name, execution_capabilities: executionCapabilities } : { ...recordOf(entry), execution_capabilities: executionCapabilities };
-  });
-  return result;
-}
 async function validateManifest(manifest) {
   const { validateRecipeActionManifestDocument } = await importRecipeProtocol();
   const result = validateRecipeActionManifestDocument(manifest);
@@ -157,41 +171,11 @@ async function validateManifest(manifest) {
 function asActionManifest(value) {
   return value;
 }
-function cloneManifest(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-function recordOf(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function stringArray(value) {
-  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-}
-function objectArray(value) {
-  return Array.isArray(value) ? value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
-}
-function customActions(value) {
-  if (!Array.isArray(value)) return [];
-  return value.flatMap((entry) => {
-    if (typeof entry === "string") return [{ name: entry, value: entry }];
-    const record = recordOf(entry);
-    return typeof record.name === "string" ? [{ name: record.name, value: entry }] : [];
-  });
-}
-function describeManifestSources(manifest, customSource) {
-  const record = recordOf(manifest);
-  const sources = /* @__PURE__ */ new Map();
-  for (const name of stringArray(record.supported_official_actions)) {
-    sources.set(name, { name: "official", tier: "official", manifestPath: customSource.manifestPath });
-  }
-  for (const action of customActions(record.custom_actions)) sources.set(action.name, { ...customSource });
-  return sources;
-}
 export {
   loadActionManifest,
   loadMetaMaskCoreActionManifest,
   loadMetaMaskExtensionActionManifest,
   loadMetaMaskMobileActionManifest,
   resolveActionManifest,
-  validateManifest,
-  withMetaMaskExecutionCapabilities
+  validateManifest
 };

package/dist/metamask-action-validation.js

@@ -0,0 +1,45 @@
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateMetaMaskActionInputs(recipe) {
+  if (!isRecord(recipe) || !isRecord(recipe.workflow)) return [];
+  const nodes = isRecord(recipe.workflow.nodes) ? recipe.workflow.nodes : void 0;
+  if (!nodes) return [];
+  const findings = [];
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    if (!isRecord(node)) continue;
+    const action = node.action;
+    const state = typeof node.state === "string" ? node.state.toLowerCase() : void 0;
+    const createsOrder = action === "metamask.perps.place_order" || (action === "metamask.perps.ensure_positions" || action === "metamask.perps.ensure_orders") && (state === "open" || state === "present");
+    if (!createsOrder) continue;
+    const requireOneOf = (names, message) => {
+      const present = names.some((name) => {
+        const value = node[name];
+        return value !== void 0 && value !== null && value !== "";
+      });
+      if (present) return;
+      findings.push({
+        severity: "error",
+        code: "recipe.missing_param",
+        path: `workflow.nodes.${nodeId}.${names[0]}`,
+        message
+      });
+    };
+    requireOneOf(
+      ["market", "symbol"],
+      `${action} requires market=<symbol> (or symbol=<symbol>) before it may create an order`
+    );
+    requireOneOf(
+      ["side"],
+      `${action} requires side=long or side=short before it may create an order`
+    );
+    requireOneOf(
+      ["amount", "notional"],
+      `${action} requires amount=<usd> or notional=<usd> before it may create an order`
+    );
+  }
+  return findings;
+}
+export {
+  validateMetaMaskActionInputs
+};

package/dist/mm-harness-cli.js

@@ -60,11 +60,13 @@ Example:
   },
   {
     name: "checklist",
-    summary: "Mark task-local checklist progress through the bundled agent runtime.",
+    summary: "Mark checklist progress and close out scrubbed learning packages.",
     example: "mm-harness checklist mark <task-dir> start",
-    helpText: `mm-harness checklist mark <task-dir> <step> [options]
+    helpText: `mm-harness checklist <mark|closeout> <task-dir> [step] [options]
 
-  Mark checklist progress through mm-harness's bundled @farmslot/agent-runtime.
+  mark delegates checklist state to @farmslot/agent-runtime. Successful complete
+  and no-change marks stage a learning package through @farmslot/handoff.
+  closeout exposes that same Handoff boundary directly; --share remains explicit.
   The task directory must contain CHECKLIST.md and checklist-target.json.
 
   Steps: start | 1 | 2 | ... | complete | no-change | blocked
@@ -72,7 +74,8 @@ Example:
 Example:
   mm-harness checklist mark temp/tasks/recipe-cook/<task> start
   mm-harness checklist mark temp/tasks/recipe-cook/<task> 1
-  mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last`
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last
+  mm-harness checklist closeout temp/tasks/recipe-cook/<task> --share`
   },
   {
     name: "actions",

package/dist/runner.js

@@ -1,4 +1,5 @@
 import { execSync } from "node:child_process";
+import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
 import {
   mobileSourceFingerprint,
@@ -6,11 +7,13 @@ import {
 } from "./adapters/mobile/source-freshness.js";
 import { resolveMetaMaskMobileLifecycleTarget } from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
+import { metaMaskActionExecutionCapabilities } from "./recipe-security.js";
 import {
   prepareLiveAdapterScript
 } from "./live-adapter-contract.js";
 import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
 import { importRecipeHarness, importRecipeHarnessAppLifecycle, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
+const OFFICIAL_ACTIONS = new Set(OFFICIAL_RECIPE_ACTIONS);
 async function createMetaMaskMobileRunner(options = {}) {
   return createMetaMaskRunner(
     "mobile",
@@ -32,9 +35,8 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const { createCdpWebUiTransport } = await importRecipeHarnessRuntimeCdp();
   const { createReactNativeBridgeUiTransport } = await importRecipeHarnessRuntimeReactNativeBridge();
   const { createAppLifecycleAdapters } = await importRecipeHarnessAppLifecycle();
-  const customActions = (actionManifest.custom_actions ?? []).map(
-    (entry) => typeof entry === "string" ? entry : entry.name
-  );
+  const actions = Object.keys(actionManifest.actions);
+  const customActions = actions.filter((action) => !OFFICIAL_ACTIONS.has(action));
   const actionSources = options.actionSources ? new Map([...options.actionSources].map(([action, source]) => [action, { ...source }])) : void 0;
   const preparedLiveAdapters = await prepareLiveAdapterImplementations(
     adapter,
@@ -42,7 +44,6 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     actionSources,
     options.trustTaskActions
   );
-  const actions = [...actionManifest.supported_official_actions, ...customActions];
   const declaredActions = new Set(actions);
   const core = createStandardCoreAdapters({ actions });
   const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status", "app.lifecycle"]);
@@ -144,8 +145,10 @@ async function prepareLiveAdapterImplementations(platform, actions, sources, tru
 }
 function adapterSecurity(action, sources, trustTaskActions = false) {
   const source = sources?.get(action);
+  const capabilities = !OFFICIAL_ACTIONS.has(action) ? { capabilities: metaMaskActionExecutionCapabilities(action) } : {};
   if (source?.tier === "task") {
     return {
+      ...capabilities,
       source: {
         kind: "custom-adapter",
         trust: trustTaskActions ? "trusted" : "untrusted",
@@ -158,6 +161,7 @@ function adapterSecurity(action, sources, trustTaskActions = false) {
   }
   if (source && source.tier !== "official") {
     return {
+      ...capabilities,
       source: {
         kind: source.tier === "canonical" ? "bundled" : "custom-adapter",
         trust: source.trust ?? (source.tier === "canonical" ? "trusted" : "unknown"),
@@ -169,6 +173,7 @@ function adapterSecurity(action, sources, trustTaskActions = false) {
     };
   }
   return {
+    ...capabilities,
     source: {
       kind: "bundled",
       trust: "trusted",

package/docs/CONTRIBUTING.md

@@ -8,6 +8,8 @@ both the machine contract and the visible human result.
 ```text
 bin/mm-harness
   -> src/                         typed CLI and product decisions
+  -> @farmslot/agent-runtime     checklist state
+  -> @farmslot/handoff           scrubbed learning capture/share
   -> @farmslot/recipe-harness    generic execution, UI transports, evidence
   -> @farmslot/protocol          schemas
   -> adapters/                   focused host/browser/device leaves
@@ -18,6 +20,8 @@ bin/mm-harness
 | Layer | Owns |
 |---|---|
 | `@farmslot/protocol` | recipe and evidence schemas |
+| `@farmslot/agent-runtime` | task-local checklist state and terminal contracts |
+| `@farmslot/handoff` | learning assembly, scrubbing, validation, approval, and publication |
 | `@farmslot/recipe-harness` | generic execution, recovery, traces, artifacts, `ui.*` |
 | `mm-harness` | MetaMask runtime control, diagnostics, durable domain actions |
 | skills/checklists | task workflow and proof expectations |
@@ -27,6 +31,10 @@ Generic bootstrap, trust, receipts, and recovery belong upstream. MetaMask
 platform behavior and risk classification belong here. Ticket assertions stay
 task-local.
 
+`mm-harness checklist` is only the MetaMask-facing dispatch layer. Terminal
+marks stage learnings through Handoff; sharing always requires a separate
+explicit `--share` call.
+
 ## Repository map
 
 | Path | Responsibility |

package/docs/RECIPES.md

@@ -89,21 +89,11 @@ The protocol is authoritative:
 
 ```text
 team-recipes/
-  library.json
   manifests/extension.action-manifest.json
   actions/extension/wallet/ensure_ready.mjs
   recipes/onboarding/smoke.extension.recipe.json
 ```
 
-```json
-{
-  "kind": "recipe-library",
-  "schema_version": 1,
-  "name": "wallet-team",
-  "owner": "wallet-team"
-}
-```
-
 ```bash
 export RECIPE_LIBRARY_PATH="wallet=$HOME/shared-library/wallet-team"
 mm-harness run --list
@@ -111,7 +101,8 @@ mm-harness run onboarding.smoke --describe
 mm-harness run onboarding.smoke --plan
 ```
 
-Use `--library wallet=/path/to/library` for one command. Resolution follows the
+Use `--library wallet=/path/to/library` for one command. The alias is the
+source name; without one, the directory name is used. Resolution follows the
 explicit library order, then bundled MetaMask. Adapter-specific variants are
 selected deterministically. Every run records the root recipe, exact resolved
 dependency documents, their digests, call edges, selected sources, and shadows.

package/library/actions/extension/platform/cdp.mjs

@@ -575,10 +575,15 @@ export class ExtensionPage extends CdpWebPage {
     this.port = port;
   }
 
-  async navigateHash(hash) {
+  async navigateHash(hash, timeoutMs = 10000) {
     const normalizedHash = String(hash || '').startsWith('#') ? hash : `#${hash || '/'}`;
-    const href = `${this.origin}/home.html${normalizedHash}`;
-    return this.navigate(href);
+    const navigation = await this.evaluate(`(() => {
+      const before = location.href;
+      location.hash = ${JSON.stringify(normalizedHash)};
+      return { before, href: location.href };
+    })()`);
+    await this.waitForDocumentReady({ expectedUrl: navigation.href, timeoutMs });
+    return { ...navigation, sameDocument: true };
   }
 
   async readPositions() {