@deeeed/metamask-harness 0.18.0 → 0.19.1

package/library/README.md

@@ -1,8 +1,8 @@
 # Recipe library
 
 - An **action** performs one typed operation.
-- A **flow** packages a reusable parameterized sequence of actions.
-- A **recipe** is a complete proof that may call actions and flows.
+- A **recipe** is a parameterized, composable graph that may call actions and
+  other recipes.
 
 - `actions/<adapter>/<group>/<name>.mjs` — executable action modules.
   **Importing an action module RUNS it**: each ends with `runAdapter(main)` at top
@@ -13,6 +13,6 @@
 - Actions load harness helpers ONLY through `actions/harness-exports.mjs` (the
   dist-preferring bridge) — never deep-import `src/` (published installs have no
   src/, and the entrypoint would close an import cycle through adapters.ts).
-- `recipes/` — runnable smoke/validation recipes (`mm-harness run <file>`).
-- Flow resolution order is personal > team > canonical; shadowing is recorded in
-  summary.json (never silent).
+- `recipes/` — runnable recipes (`mm-harness run <name-or-file>`).
+- Recipe resolution is explicit library order, then bundled MetaMask; selected
+  variants and shadows are recorded in run evidence.

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

@@ -246,6 +246,14 @@ export function resolveNetwork(input) {
   return raw;
 }
 
+export function requireRuntimeExport(moduleNamespace, exportName, sourceLabel) {
+  const value = moduleNamespace?.[exportName] ?? moduleNamespace?.default?.[exportName];
+  if (value === undefined) {
+    throw new Error(`${sourceLabel} does not export ${exportName}.`);
+  }
+  return value;
+}
+
 /**
  * Instantiate the PerpsController headlessly against the resolved core checkout.
  * Returns the controller plus the resolved read account address. Cached per
@@ -261,10 +269,25 @@ export async function getCoreController(input) {
     return { ...cached, accountAddress };
   }
 
-  const [{ PerpsController }, { Messenger, MOCK_ANY_NAMESPACE }] = await Promise.all([
+  const [controllerModule, messengerModule] = await Promise.all([
     import(controllerEntry(projectRoot)),
     import(messengerEntry(projectRoot)),
   ]);
+  const PerpsController = requireRuntimeExport(
+    controllerModule,
+    'PerpsController',
+    'Core perps-controller entrypoint',
+  );
+  const Messenger = requireRuntimeExport(
+    messengerModule,
+    'Messenger',
+    'Core messenger entrypoint',
+  );
+  const MOCK_ANY_NAMESPACE = requireRuntimeExport(
+    messengerModule,
+    'MOCK_ANY_NAMESPACE',
+    'Core messenger entrypoint',
+  );
 
   const stubbed = new Set();
   const infrastructure = buildInfrastructure(stubbed);
@@ -558,6 +581,15 @@ export function configuredSymbols(input, items) {
   return single ? [normalizeMarketSymbol(single)] : [];
 }
 
+export function requireExplicitSelection(input) {
+  const selector =
+    input.node?.selector && typeof input.node.selector === 'object' ? input.node.selector : {};
+  const mode = String(input.node?.mode ?? selector.mode ?? '').toLowerCase();
+  if (configuredSymbols(input, []).length === 0 && mode !== 'all') {
+    throw new Error(`${input.action} requires market=<symbol> or mode=all.`);
+  }
+}
+
 /**
  * Filter live items to the recipe-selected subset using the same market/side
  * vocabulary as the extension perps adapter. With no selector and no

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

@@ -2,6 +2,7 @@ import {
   getCoreController,
   isDirectRun,
   redactOrder,
+  requireExplicitSelection,
   runAdapter,
   selectedItems,
 } from './_controller.mjs';
@@ -12,30 +13,39 @@ import {
 // assert_positions.mjs.
 
 export function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.order ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);
 }
 
 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) {
-    throw new Error(
-      `Expected selected Perps open order(s), but none matched ${JSON.stringify(input.node)}.`,
-    );
+    throw new Error('Expected at least one matching open Perps order, but found none.');
   }
   if (!expectOpen && hasOrder) {
-    throw new Error(
-      `Expected no selected Perps open orders, but ${matching.length} matched ${JSON.stringify(input.node)}.`,
-    );
+    throw new Error(`Expected no matching open Perps orders, but found ${matching.length}.`);
   }
 
   return {

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

@@ -2,6 +2,7 @@ import {
   getCoreController,
   isDirectRun,
   redactPosition,
+  requireExplicitSelection,
   runAdapter,
   selectedItems,
 } from './_controller.mjs';
@@ -11,30 +12,39 @@ import {
 // throws on mismatch so the recipe fails loudly.
 
 export function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.position ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_positions received unsupported state: ${state}`);
 }
 
 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) {
-    throw new Error(
-      `Expected selected Perps position(s), but none matched ${JSON.stringify(input.node)}.`,
-    );
+    throw new Error('Expected at least one matching open Perps position, but found none.');
   }
   if (!expectOpen && hasPosition) {
-    throw new Error(
-      `Expected no selected Perps positions, but ${matching.length} matched ${JSON.stringify(input.node)}.`,
-    );
+    throw new Error(`Expected no matching open Perps positions, but found ${matching.length}.`);
   }
 
   return {

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

@@ -2,6 +2,7 @@ import {
   getCoreControllerWithSigner,
   isDirectRun,
   redactOrder,
+  requireExplicitSelection,
   runAdapter,
   selectedItems,
   symbolForItem,
@@ -37,6 +38,7 @@ async function waitForOrdersAbsent(controller, accountAddress, symbols, timeoutM
 }
 
 export async function closeOrders(input) {
+  requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
   const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
 

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

@@ -3,6 +3,7 @@ import {
   getCoreControllerWithSigner,
   isDirectRun,
   redactPosition,
+  requireExplicitSelection,
   runAdapter,
   selectedItems,
   symbolForItem,
@@ -36,6 +37,7 @@ async function waitForPositionsAbsent(controller, accountAddress, symbols, timeo
 }
 
 export async function closePositions(input) {
+  requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
   const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
   const maxSlippageBps = Number(

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

@@ -1,4 +1,4 @@
-import { getCoreController, isDirectRun, runAdapter, selectedItems } from './_controller.mjs';
+import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertOrders } from './assert_orders.mjs';
 import { closeOrders } from './close_orders.mjs';
 import { placeOrder } from './place_order.mjs';
@@ -8,7 +8,9 @@ import { placeOrder } from './place_order.mjs';
 // order state. Mirrors ensure_positions.mjs.
 
 export async function ensureOrders(input) {
-  const state = String(input.node?.state ?? input.node?.order ?? 'none').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.ensure_orders requires state=open or state=none.');
+  requireExplicitSelection(input);
+  const state = String(input.node.state).toLowerCase();
 
   if (state === 'none' || state === 'closed' || state === 'absent') {
     const close = await closeOrders(input);

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

@@ -1,4 +1,4 @@
-import { getCoreController, isDirectRun, runAdapter, selectedItems } from './_controller.mjs';
+import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertPositions } from './assert_positions.mjs';
 import { closePositions } from './close_positions.mjs';
 import { placeOrder } from './place_order.mjs';
@@ -8,7 +8,9 @@ import { placeOrder } from './place_order.mjs';
 // state. Mirrors the extension ensure_positions semantics.
 
 export async function ensurePositions(input) {
-  const state = String(input.node?.state ?? input.node?.position ?? 'none').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.ensure_positions requires state=open or state=none.');
+  requireExplicitSelection(input);
+  const state = String(input.node.state).toLowerCase();
 
   if (state === 'none' || state === 'closed' || state === 'absent') {
     const close = await closePositions(input);

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

@@ -81,12 +81,16 @@ function resolveLimitPrice(input, isBuy, mid) {
 }
 
 export async function placeOrder(input) {
-  const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
   const symbol = resolveSymbol(input);
-  const side = String(input.node?.side ?? 'long').toLowerCase();
+  if (input.node?.side == null) throw new Error('metamask.perps.place_order requires side=long or side=short.');
+  if (input.node?.amount == null && input.node?.notional == null) {
+    throw new Error('metamask.perps.place_order requires amount=<usd> or notional=<usd>.');
+  }
+  const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
+  const side = String(input.node.side).toLowerCase();
   const isBuy = side !== 'short';
   const orderType = resolveOrderType(input);
-  const usdAmount = String(input.node?.amount ?? input.node?.notional ?? '11');
+  const usdAmount = String(input.node.amount ?? input.node.notional);
   const leverage = Number(input.node?.leverage ?? 3);
   const maxSlippageBps = Number(
     input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300,

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

@@ -2,7 +2,8 @@ import { runAdapter } from '../platform/cdp.mjs';
 import { assertOrders } from './perps.mjs';
 
 function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.orders ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);

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

@@ -2,7 +2,8 @@ import { runAdapter } from '../platform/cdp.mjs';
 import { assertPositions } from './perps.mjs';
 
 function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.position ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_positions received unsupported state: ${state}`);

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) {
@@ -24,20 +27,68 @@ function configuredSymbols(input, items) {
   const explicit = input.node?.markets ?? input.node?.symbols ?? selector.markets ?? selector.symbols;
   if (Array.isArray(explicit) && explicit.length > 0) return uniqueSymbols(explicit.map(normalizeMarketSymbol));
   if (typeof explicit === 'string' && explicit.length > 0) return uniqueSymbols(explicit.split(',').map((part) => normalizeMarketSymbol(part.trim())).filter(Boolean));
-  return [marketSymbol(input)];
+  const single = input.node?.market ?? input.node?.symbol ?? selector.market ?? selector.symbol;
+  return single ? [normalizeMarketSymbol(single)] : [];
 }
 
-function selectedItems(input, items) {
-  const symbols = new Set(configuredSymbols(input, items));
+export function selectedItems(input, items) {
+  const requested = configuredSymbols(input, items);
+  const symbols = requested.length > 0 ? new Set(requested) : null;
   const selector = input.node?.selector && typeof input.node.selector === 'object' ? input.node.selector : {};
   const side = input.node?.side ?? selector.side;
   return items.filter((item) => {
-    if (!symbols.has(symbolForItem(item))) return false;
+    if (symbols && !symbols.has(symbolForItem(item))) return false;
     if (side && sideForItem(item) && sideForItem(item) !== String(side).toLowerCase()) return false;
     return true;
   });
 }
 
+function requireExplicitSelection(input) {
+  const node = input.node ?? {};
+  const selector = node.selector && typeof node.selector === 'object' ? node.selector : {};
+  const values = [node.market, node.symbol, node.markets, node.symbols, selector.market, selector.symbol, selector.markets, selector.symbols];
+  const selected = values.some((value) => Array.isArray(value) ? value.length > 0 : value != null && String(value).trim() !== '');
+  if (!selected && node.mode !== 'all' && selector.mode !== 'all') {
+    throw new Error(`${input.action} requires market=<symbol> or mode=all.`);
+  }
+}
+
+function requirePlaceOrderInputs(input) {
+  const node = input.node ?? {};
+  if (node.market == null && node.symbol == null) throw new Error(`${input.action} requires market=<symbol>.`);
+  if (node.side == null) throw new Error(`${input.action} requires side=long or side=short.`);
+  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 };
 }
@@ -78,40 +129,41 @@ 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) };
   });
 }
 
 export async function assertPositions(input, expectedOpen) {
+  requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
     const timeoutMs = Number(input.node?.timeout_ms ?? 0);
-    if (expectedOpen && timeoutMs > 0) {
-      await waitForPositionPresent(page, marketSymbol(input), 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;
-    if (expectedOpen && !hasPosition) throw new Error(`Expected selected Perps position(s), but none matched ${JSON.stringify(input.node)}.`);
-    if (!expectedOpen && hasPosition) throw new Error(`Expected no selected Perps positions, but ${matching.length} matched ${JSON.stringify(input.node)}.`);
+    if (expectedOpen && !hasPosition) throw new Error('Expected at least one matching open Perps position, but found none.');
+    if (!expectedOpen && hasPosition) throw new Error(`Expected no matching open Perps positions, but found ${matching.length}.`);
     return { action: input.action, expectedOpen, matchingCount: matching.length, positions: matching.map(redactPosition), source: state.source ?? 'perps-stream-manager-cache' };
   });
 }
 
 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 selected Perps order(s), but none matched ${JSON.stringify(input.node)}.`);
-    if (!expectedOpen && hasOrders) throw new Error(`Expected no selected Perps orders, but ${matching.length} matched ${JSON.stringify(input.node)}.`);
-    return { action: input.action, expectedOpen, matchingCount: matching.length, orders: matching.map(redactOrder), source: 'perps-stream-manager-cache' };
+    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: state.source };
   });
 }
 
 export async function closePositions(input) {
+  requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
     const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
     const state = await page.readPositions();
@@ -147,6 +199,7 @@ export async function closePositions(input) {
 }
 
 export async function closeOrders(input) {
+  requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
     const timeoutMs = Number(input.node?.timeout_ms ?? 30000);
     const before = await readOpenOrders(page);
@@ -282,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?.();
@@ -302,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) {
@@ -369,11 +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 ?? 'long').toLowerCase();
-  const amount = String(input.node?.amount ?? input.node?.notional ?? '11');
+  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 () => {
@@ -390,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;
@@ -401,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))},
       };
@@ -421,13 +525,19 @@ 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' };
   });
 }
 
 export async function ensurePositions(input) {
-  const state = String(input.node?.state ?? input.node?.position ?? 'none').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.ensure_positions requires state=open or state=none.');
+  requireExplicitSelection(input);
+  const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
     const close = await closePositions(input);
     return { ...(await assertPositions(input, false)), close };
@@ -445,12 +555,23 @@ export async function ensurePositions(input) {
 }
 
 export async function ensureOrders(input) {
-  const state = String(input.node?.state ?? input.node?.orders ?? 'none').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.ensure_orders requires state=open or state=none.');
+  requireExplicitSelection(input);
+  const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
     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/mobile/perps/assert_orders.mjs

@@ -2,7 +2,8 @@ import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders } from './perps.mjs';
 
 function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.orders ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);

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

@@ -2,7 +2,8 @@ import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions } from './perps.mjs';
 
 function expectedOpen(input) {
-  const state = String(input.node?.state ?? input.node?.position ?? 'open').toLowerCase();
+  if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
+  const state = String(input.node.state).toLowerCase();
   if (state === 'open' || state === 'present') return true;
   if (state === 'none' || state === 'closed' || state === 'absent') return false;
   throw new Error(`metamask.perps.assert_positions received unsupported state: ${state}`);