@deeeed/metamask-harness 0.19.0 → 0.20.0

package/dist/live-adapter-contract.js

@@ -312,6 +312,7 @@ async function runLiveAdapterScript({ platform, action, node, context, prepared
 `);
   const command = prepared ? commandForPrepared(context.projectRoot, platform) : commandFor(script, context.projectRoot, platform);
   const platformEnv = await platformAdapterEnv(platform, context.projectRoot, tempDir);
+  const processTimeoutMs = liveAdapterProcessTimeoutMs(node);
   const result = await runProcess(command.command, [...command.args, inputPath], {
     cwd: context.projectRoot,
     env: {
@@ -321,12 +322,12 @@ async function runLiveAdapterScript({ platform, action, node, context, prepared
       METAMASK_RECIPE_ADAPTER_INPUT: inputPath,
       METAMASK_RECIPE_ADAPTER_OUTPUT: outputPath
     },
-    timeoutMs: Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 6e4),
+    timeoutMs: processTimeoutMs,
     ...prepared ? { stdin: prepared.sourceText } : {}
   });
   try {
     if (result.timedOut) {
-      throw new Error(`Live adapter ${script} timed out after ${Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 6e4)}ms.`);
+      throw new Error(`Live adapter ${script} timed out after ${processTimeoutMs}ms.`);
     }
     if (result.exitCode !== 0) {
       throw new Error(`Live adapter ${script} exited ${result.exitCode}: ${result.stderr || result.stdout}`);
@@ -344,6 +345,17 @@ async function runLiveAdapterScript({ platform, action, node, context, prepared
     await rm(tempDir, { recursive: true, force: true });
   }
 }
+function liveAdapterProcessTimeoutMs(node) {
+  if (node.live_adapter_timeout_ms != null) {
+    const timeoutMs = Number(node.live_adapter_timeout_ms);
+    return Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 6e4;
+  }
+  if (node.timeout_ms != null) {
+    const timeoutMs = Number(node.timeout_ms);
+    return Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs + 5e3 : 6e4;
+  }
+  return 6e4;
+}
 function commandForPrepared(projectRoot, platform) {
   if (platform !== "core") {
     return { command: process.execPath, args: ["--input-type=module", "-"] };
@@ -364,6 +376,7 @@ function isPathWithin(root, candidate) {
   return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
 export {
+  liveAdapterProcessTimeoutMs,
   prepareLiveAdapterScript,
   resolveLiveAdapter,
   runLiveAdapterScript

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/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

@@ -67,6 +67,21 @@ Rules:
 - Parameterize repeated behavior instead of multiplying names.
 - Keep secrets out of recipes, libraries, and evidence.
 
+Keep responsibilities narrow:
+
+- **Parameters** expose caller choices that may vary without changing the
+  journey's meaning.
+- **Recipes** compose actions and own journey order, safe defaults, invariants,
+  and proof.
+- **Actions** translate one stable operation to existing UI, CDP, or controller
+  capabilities; they do not reimplement product business logic.
+- **Product/controllers** remain the source of truth for state transitions,
+  validation, transactions, and domain behavior.
+
+If changing a value would violate the recipe's postcondition, keep it as a
+documented recipe invariant rather than a parameter. Add a shared action only
+when repeated direct access has a stable cross-task contract.
+
 The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 

package/library/actions/core/perps/assert_orders.mjs

@@ -23,11 +23,22 @@ export function expectedOpen(input) {
 export async function assertOrders(input, expectOpen = expectedOpen(input)) {
   requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreController(input);
-  const orders = await controller.getOpenOrders({
-    standalone: true,
-    userAddress: accountAddress,
-  });
-  const matching = selectedItems(input, orders);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let orders;
+  let matching;
+  while (true) {
+    orders = await controller.getOpenOrders({
+      standalone: true,
+      userAddress: accountAddress,
+    });
+    matching = selectedItems(input, orders);
+    if (expectOpen ? matching.length > 0 : matching.length === 0) break;
+    if (Date.now() >= deadline) break;
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
+    );
+  }
   const hasOrder = matching.length > 0;
 
   if (expectOpen && !hasOrder) {

package/library/actions/core/perps/assert_positions.mjs

@@ -22,11 +22,22 @@ export function expectedOpen(input) {
 export async function assertPositions(input, expectOpen = expectedOpen(input)) {
   requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreController(input);
-  const positions = await controller.getPositions({
-    standalone: true,
-    userAddress: accountAddress,
-  });
-  const matching = selectedItems(input, positions);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let positions;
+  let matching;
+  while (true) {
+    positions = await controller.getPositions({
+      standalone: true,
+      userAddress: accountAddress,
+    });
+    matching = selectedItems(input, positions);
+    if (expectOpen ? matching.length > 0 : matching.length === 0) break;
+    if (Date.now() >= deadline) break;
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
+    );
+  }
   const hasPosition = matching.length > 0;
 
   if (expectOpen && !hasPosition) {

package/library/actions/extension/perps/perps.mjs

@@ -10,7 +10,10 @@ function symbolForItem(item) {
 }
 
 function sideForItem(item) {
-  return String(item?.side ?? item?.direction ?? '').toLowerCase();
+  const side = String(item?.side ?? item?.direction ?? '').toLowerCase();
+  if (side === 'buy' || side === 'b') return 'long';
+  if (side === 'sell' || side === 'a' || side === 's') return 'short';
+  return side;
 }
 
 function uniqueSymbols(symbols) {
@@ -57,6 +60,35 @@ function requirePlaceOrderInputs(input) {
   if (node.amount == null && node.notional == null) throw new Error(`${input.action} requires amount=<usd> or notional=<usd>.`);
 }
 
+function resolveOrderType(input) {
+  const value = String(input.node?.order_type ?? input.node?.orderType ?? 'market').toLowerCase();
+  if (value !== 'market' && value !== 'limit') {
+    throw new Error(`${input.action} received unsupported order_type: ${value}.`);
+  }
+  return value;
+}
+
+function resolveLimitPrice(input, isBuy, currentPrice) {
+  const explicit = input.node?.limit_price ?? input.node?.limitPrice ?? input.node?.price;
+  if (explicit != null && String(explicit).length > 0) {
+    const value = Number(explicit);
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(`${input.action} received invalid limit_price: ${explicit}.`);
+    }
+    return value;
+  }
+  const rawOffset = input.node?.offset_pct ?? input.node?.offsetPct;
+  const offset = rawOffset == null ? (isBuy ? -30 : 30) : Number(rawOffset);
+  if (!Number.isFinite(offset)) {
+    throw new Error(`${input.action} received invalid offset_pct: ${rawOffset}.`);
+  }
+  const value = currentPrice * (1 + offset / 100);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${input.action} computed a non-positive limit price (${value}).`);
+  }
+  return value;
+}
+
 export function positionSelectionState(input, positions) {
   return { hasMatching: selectedItems(input, positions).length > 0 };
 }
@@ -97,9 +129,9 @@ export async function readPositions(input) {
 
 export async function readOrders(input) {
   return withExtensionPage(input, async (page) => {
-    const orders = await readOpenOrders(page);
-    const matching = selectedItems(input, orders);
-    return { action: input.action, source: 'perps-stream-manager-cache', count: orders.length, matchingCount: matching.length, orders: matching.map(redactOrder) };
+    const state = await readOpenOrdersState(page);
+    const matching = selectedItems(input, state.orders);
+    return { action: input.action, source: state.source, count: state.orders.length, matchingCount: matching.length, orders: matching.map(redactOrder) };
   });
 }
 
@@ -107,11 +139,7 @@ export async function assertPositions(input, expectedOpen) {
   requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
     const timeoutMs = Number(input.node?.timeout_ms ?? 0);
-    const requested = configuredSymbols(input, []);
-    if (expectedOpen && timeoutMs > 0 && requested.length === 1) {
-      await waitForPositionPresent(page, requested[0], timeoutMs);
-    }
-    const state = await page.readPositions();
+    const state = await waitForSelectedPositionState(page, input, expectedOpen, timeoutMs);
     if (!state.available) throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot assert live Perps positions.');
     const matching = selectedItems(input, state.positions);
     const hasPosition = matching.length > 0;
@@ -124,12 +152,13 @@ export async function assertPositions(input, expectedOpen) {
 export async function assertOrders(input, expectedOpen) {
   requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
-    const orders = await readOpenOrders(page);
-    const matching = selectedItems(input, orders);
+    const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+    const state = await waitForSelectedOrderState(page, input, expectedOpen, timeoutMs);
+    const matching = selectedItems(input, state.orders);
     const hasOrders = matching.length > 0;
     if (expectedOpen && !hasOrders) throw new Error('Expected at least one matching open Perps order, but found none.');
     if (!expectedOpen && hasOrders) throw new Error(`Expected no matching open Perps orders, but found ${matching.length}.`);
-    return { action: input.action, expectedOpen, matchingCount: matching.length, orders: matching.map(redactOrder), source: 'perps-stream-manager-cache' };
+    return { action: input.action, expectedOpen, matchingCount: matching.length, orders: matching.map(redactOrder), source: state.source };
   });
 }
 
@@ -306,6 +335,10 @@ async function readCurrentMarketPrice(page, symbol, explicitPrice) {
 }
 
 async function readOpenOrders(page) {
+  return (await readOpenOrdersState(page)).orders;
+}
+
+async function readOpenOrdersState(page) {
   const state = await page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
@@ -326,7 +359,7 @@ async function readOpenOrders(page) {
     };
   })()`);
   if (!state.available) throw new Error('Perps orders are unavailable from both background and stream manager cache.');
-  return state.orders;
+  return state;
 }
 
 async function readAccountState(page) {
@@ -393,12 +426,41 @@ async function waitForPositionPresent(page, symbol, timeoutMs) {
   return lastState;
 }
 
+async function waitForSelectedPositionState(page, input, expectedOpen, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let state;
+  while (true) {
+    state = await page.readPositions();
+    if (!state.available) {
+      throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot assert live Perps positions.');
+    }
+    const matching = selectedItems(input, state.positions);
+    if (expectedOpen ? matching.length > 0 : matching.length === 0) return state;
+    if (Date.now() >= deadline) return state;
+    await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+  }
+}
+
+async function waitForSelectedOrderState(page, input, expectedOpen, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let state;
+  while (true) {
+    state = await readOpenOrdersState(page);
+    const matching = selectedItems(input, state.orders);
+    if (expectedOpen ? matching.length > 0 : matching.length === 0) return state;
+    if (Date.now() >= deadline) return state;
+    await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+  }
+}
+
 export async function placeOrder(input) {
   requirePlaceOrderInputs(input);
   const symbol = marketSymbol(input);
   const side = String(input.node.side).toLowerCase();
   const amount = String(input.node.amount ?? input.node.notional);
   const leverage = Number(input.node?.leverage ?? 3);
+  const isBuy = side !== 'short';
+  const orderType = resolveOrderType(input);
   return withExtensionPage(input, async (page) => {
     await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
     await page.evaluate(`(async () => {
@@ -415,6 +477,9 @@ export async function placeOrder(input) {
       symbol,
       input.node?.current_price ?? input.node?.currentPrice,
     );
+    const limitPrice = orderType === 'limit'
+      ? resolveLimitPrice(input, isBuy, resolvedPrice)
+      : null;
     await page.navigateHash(`#/perps/trade/${encodeURIComponent(symbol)}?direction=${encodeURIComponent(side)}&mode=new`);
     await page.waitForSelector(dataTestId('perps-order-entry-page'), { timeoutMs: 20000 });
     let order;
@@ -426,13 +491,27 @@ export async function placeOrder(input) {
       if (!Number.isFinite(currentPrice) || currentPrice <= 0) throw new Error('Unable to determine current Perps price for order placement.');
       const usdAmount = ${JSON.stringify(amount)};
       const leverage = ${JSON.stringify(leverage)};
-      const orderParams = {
+      const orderType = ${JSON.stringify(orderType)};
+      const limitPrice = ${JSON.stringify(limitPrice)};
+      const orderParams = orderType === 'limit' ? {
         symbol: ${JSON.stringify(symbol)},
-        isBuy: ${JSON.stringify(side !== 'short')},
+        isBuy: ${JSON.stringify(isBuy)},
+        size: ((Number(usdAmount) * Number(leverage)) / Number(limitPrice)).toString(),
+        orderType,
+        price: String(limitPrice),
+        timeInForce: 'GTC',
+        leverage,
+        currentPrice,
+        priceAtCalculation: currentPrice,
+        maxSlippageBps: ${JSON.stringify(Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300))},
+      } : {
+        symbol: ${JSON.stringify(symbol)},
+        isBuy: ${JSON.stringify(isBuy)},
         size: ((Number(usdAmount) * Number(leverage)) / currentPrice).toString(),
-        orderType: 'market',
+        orderType,
         leverage,
         currentPrice,
+        priceAtCalculation: currentPrice,
         usdAmount,
         maxSlippageBps: ${JSON.stringify(Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300))},
       };
@@ -446,8 +525,12 @@ export async function placeOrder(input) {
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(`${message} (resolvedPrice=${resolvedPrice})`);
     }
-    await waitForPositionPresent(page, symbol, Number(input.node?.timeout_ms ?? 30000));
-    return { action: input.action, market: symbol, side, amount, leverage, submitted: true, order, proofPath: 'background-perpsPlaceOrder' };
+    if (orderType === 'limit') {
+      await waitForSelectedOrderState(page, input, true, Number(input.node?.timeout_ms ?? 30000));
+    } else {
+      await waitForPositionPresent(page, symbol, Number(input.node?.timeout_ms ?? 30000));
+    }
+    return { action: input.action, market: symbol, side, orderType, amount, leverage, limitPrice, submitted: true, order, proofPath: 'background-perpsPlaceOrder' };
   });
 }
 
@@ -479,7 +562,16 @@ export async function ensureOrders(input) {
     const close = await closeOrders(input);
     return { ...(await assertOrders(input, false)), close };
   }
-  if (state === 'open' || state === 'present') return assertOrders(input, true);
+  if (state === 'open' || state === 'present') {
+    const current = await withExtensionPage(input, async (page) => ({
+      orders: await readOpenOrders(page),
+    }));
+    let order = null;
+    if (selectedItems(input, current.orders).length === 0) {
+      order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } });
+    }
+    return { ...(await assertOrders(input, true)), order };
+  }
   throw new Error(`metamask.perps.ensure_orders received unsupported state: ${state}`);
 }
 

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() {