@kaleidorg/mind 0.1.0 → 0.3.0

package/src/recipe/kaleidoswap-atomic.ts

@@ -0,0 +1,117 @@
+/**
+ * Built-in "atomic swap on KaleidoSwap" recipe — trust-minimised chain.
+ *
+ * Most users want the simple market-order swap (`swapRecipe` over generic
+ * `get_swap_quote` / `execute_swap`). This recipe is the EXPLICIT atomic path:
+ * the user creates an RGB/LN receive invoice, the maker locks the swap, the
+ * user pays the maker's Lightning invoice, and the maker releases.
+ *
+ * Triggered only by explicit atomic-swap intent ("atomic swap", "trustless
+ * swap", "htlc swap") so it never preempts the simpler swap path for vague
+ * phrasings.
+ *
+ *   "atomic swap 100000 sats for usdt"
+ *     ↓ 1 model inference (slot extraction)
+ *   kaleidoswap_get_quote        ← maker prices the swap
+ *   rln_create_rgb_invoice       ← user's node prepares receive (if to_asset is RGB)
+ *   rln_create_ln_invoice        ← (alt) if to_asset is BTC
+ *   kaleidoswap_atomic_init  🔒 ← maker locks the swap, returns its invoice
+ *   rln_pay_invoice          🔒 ← user pays the maker
+ *   kaleidoswap_atomic_execute 🔒 ← (final) maker releases the asset
+ *
+ * Two-or-three confirmation gates are intentional: each represents a distinct
+ * decision point. The host's confirm UI describes what's about to happen.
+ */
+
+import type { Recipe } from './types.js';
+import { extractSwap } from './swap.js';
+
+const ATOMIC_INTENT =
+  /\b(atomic|trustless|htlc)\b.*\b(swap|exchange|convert|trade)\b|\b(swap|exchange|convert|trade)\b.*\b(atomic|trustless|htlc)\b/i;
+
+function isBtc(asset: unknown): boolean {
+  return String(asset ?? '').toUpperCase() === 'BTC';
+}
+
+export const kaleidoswapAtomicRecipe: Recipe = {
+  name: 'kaleidoswap-atomic',
+  description:
+    'Trust-minimised atomic swap on KaleidoSwap: quote, prepare a receive invoice on the user\'s node, lock the swap with the maker, pay, and execute.',
+  match: (t) => ATOMIC_INTENT.test(t),
+  triggers: ['atomic swap', 'trustless swap', 'htlc swap'],
+  slots: [
+    { name: 'from_asset', type: 'string', description: 'Asset to spend (BTC / USDT / XAUT)', required: true },
+    { name: 'to_asset', type: 'string', description: 'Asset to receive (BTC / USDT / XAUT)', required: true },
+    { name: 'amount', type: 'number', description: 'Amount of from_asset to swap' },
+  ],
+  extract: extractSwap,
+  confident: (s) => !!s.from_asset && !!s.to_asset && !!s.amount,
+  steps: [
+    // 1. Maker quotes the swap. Returns { quote_id, receive_amount, fees, ttl_ms, ... }.
+    {
+      tool: 'kaleidoswap_get_quote',
+      as: 'quote',
+      args: (ctx) => ({
+        from_asset: ctx.slots.from_asset,
+        to_asset: ctx.slots.to_asset,
+        amount: ctx.slots.amount,
+      }),
+    },
+    // 2a. User's node creates an RGB receive invoice (when to_asset is an RGB asset).
+    {
+      tool: 'rln_create_rgb_invoice',
+      as: 'receive_rgb',
+      args: (ctx) => {
+        const q = ctx.results.quote as { receive_amount?: number } | undefined;
+        return { asset: ctx.slots.to_asset, amount: q?.receive_amount };
+      },
+      skipIf: (ctx) => isBtc(ctx.slots.to_asset),
+    },
+    // 2b. User's node creates an LN receive invoice (when to_asset is BTC).
+    {
+      tool: 'rln_create_ln_invoice',
+      as: 'receive_ln',
+      args: (ctx) => {
+        const q = ctx.results.quote as { receive_amount?: number } | undefined;
+        return { amount_sats: q?.receive_amount };
+      },
+      skipIf: (ctx) => !isBtc(ctx.slots.to_asset),
+    },
+    // 3. Maker locks the swap. Returns { atomic_id, maker_invoice }. Spend-gated.
+    {
+      tool: 'kaleidoswap_atomic_init',
+      as: 'atomic',
+      args: (ctx) => {
+        const rgb = ctx.results.receive_rgb as { invoice?: string } | undefined;
+        const ln = ctx.results.receive_ln as { invoice?: string } | undefined;
+        const q = ctx.results.quote as { quote_id?: string } | undefined;
+        return {
+          quote_id: q?.quote_id,
+          receive_invoice: rgb?.invoice ?? ln?.invoice,
+        };
+      },
+    },
+    // 4. User pays the maker's Lightning invoice. Spend-gated by the wallet contract.
+    {
+      tool: 'rln_pay_invoice',
+      as: 'paid',
+      args: (ctx) => {
+        const a = ctx.results.atomic as { maker_invoice?: string } | undefined;
+        return { invoice: a?.maker_invoice };
+      },
+    },
+  ],
+  // 5. Maker releases the receive asset → swap completes. Spend-gated.
+  final: {
+    tool: 'kaleidoswap_atomic_execute',
+    args: (ctx) => {
+      const a = ctx.results.atomic as { atomic_id?: string } | undefined;
+      return { atomic_id: a?.atomic_id };
+    },
+  },
+  summary: (ctx) => {
+    const q = ctx.results.quote as { receive_amount?: number } | undefined;
+    const tail = q?.receive_amount ? ` ≈ ${q.receive_amount} ${ctx.slots.to_asset}` : '';
+    return `Atomic swap: ${ctx.slots.amount} ${ctx.slots.from_asset} → ${ctx.slots.to_asset}${tail}.`;
+  },
+};

package/src/recipe/payments.ts

@@ -0,0 +1,116 @@
+/**
+ * Built-in "pay a contact" recipe — the flagship mobile multi-step flow.
+ *
+ *   "pay bob 3 EUR"  →  resolve_contact → fiat_to_sats → send_payment 🔒
+ *   "send 5000 sats to alice"  →  resolve_contact → send_payment 🔒
+ *
+ * Uses the canonical contract tools. The deterministic extractor handles most
+ * phrasings with no LLM at all (Tier-0); the runner falls back to one LLM
+ * extraction otherwise.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+
+const CURRENCIES = /\b(sats?|sat|btc|usdt|xaut|eur|usd|gbp|dollars?|euros?|pounds?)\b/i;
+const isOnchainOrInvoice = (s: string) => /^(ln(bc|tb|bcrt)|bc1|tb1|lnurl|[a-z0-9._-]+@)/i.test(s.trim());
+
+function normCurrency(c?: string): string | undefined {
+  if (!c) return undefined;
+  const x = c.toLowerCase();
+  if (/^sat/.test(x)) return 'sats';
+  if (x === 'btc') return 'btc';
+  if (/dollar|^usd/.test(x)) return 'usd';
+  if (/euro|^eur/.test(x)) return 'eur';
+  if (/pound|^gbp/.test(x)) return 'gbp';
+  return x.toUpperCase();
+}
+
+/** "pay bob 3 eur", "send 5,000 sats to alice", "pay lnbc... ", "send 0.001 btc to bob" */
+export function extractPayment(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  if (!/\b(pay|send|transfer)\b/i.test(t)) return null;
+
+  // Amount with optional k/m shorthand: "5k" → 5000, "2m" → 2_000_000.
+  const amtMatch = t.match(/(\d[\d.,]*)\s*([km])?\b/i);
+  let amountNum = amtMatch ? Number(amtMatch[1]!.replace(/,/g, '')) : undefined;
+  if (amountNum != null && amtMatch?.[2]) amountNum *= amtMatch[2].toLowerCase() === 'k' ? 1_000 : 1_000_000;
+  const amount = amountNum != null && !Number.isNaN(amountNum) ? String(amountNum) : undefined;
+  const currency = normCurrency(t.match(CURRENCIES)?.[1]);
+
+  // recipient: prefer "to <x>", else the token right after pay/send that isn't a number/currency
+  let recipient = t.match(/\bto\s+([^\s,]+)/i)?.[1];
+  if (!recipient) {
+    const after = t.match(/\b(?:pay|send|transfer)\s+([^\s,]+)/i)?.[1];
+    if (after && !/^\d/.test(after) && !CURRENCIES.test(after)) recipient = after;
+  }
+  if (!recipient && !amount) return null;
+  return {
+    recipient,
+    amount: amount ? Number(amount) : undefined,
+    currency,
+  };
+}
+
+/** Compute the sats amount when no fiat conversion step is needed. */
+function directSats(ctx: RecipeContext): number | undefined {
+  const amount = Number(ctx.slots.amount);
+  if (!amount || Number.isNaN(amount)) return undefined;
+  const cur = String(ctx.slots.currency ?? 'sats').toLowerCase();
+  if (cur === 'btc') return Math.round(amount * 1e8);
+  return Math.round(amount); // sats (default)
+}
+
+const isFiat = (ctx: RecipeContext) => {
+  const c = String(ctx.slots.currency ?? '').toLowerCase();
+  return c !== '' && c !== 'sats' && c !== 'btc';
+};
+
+export const paymentsRecipe: Recipe = {
+  name: 'pay-contact',
+  description: 'Pay a contact or address — resolves the contact, converts fiat to sats, then sends (with confirmation).',
+  // A BTC/fiat spend intent — NOT a receive/invoice, and NOT an RGB-asset send
+  // ("send 10 USDT to bob" is handled by the asset-send recipe, so USDT/XAUT
+  // amounts are never mis-parsed as fiat).
+  match: (t) => /\b(pay|send|transfer)\b/i.test(t) && !/\b(invoice|receive|request|address|qr|deposit|usdt|tether|xaut|gold)\b/i.test(t),
+  triggers: ['pay', 'send', 'transfer'],
+  slots: [
+    { name: 'recipient', type: 'string', description: 'Who to pay: a contact name, Lightning address, or invoice', required: true },
+    { name: 'amount', type: 'number', description: 'The amount to send' },
+    { name: 'currency', type: 'string', description: 'Unit of the amount: sats, btc, or a fiat code like eur/usd' },
+  ],
+  extract: extractPayment,
+  confident: (s) => !!s.recipient,
+  steps: [
+    {
+      // Resolve a contact name → payable address (skip if already an address/invoice).
+      tool: 'resolve_contact',
+      as: 'contact',
+      args: (ctx) => ({ name: ctx.slots.recipient }),
+      skipIf: (ctx) => !ctx.slots.recipient || isOnchainOrInvoice(String(ctx.slots.recipient)),
+    },
+    {
+      // Convert fiat → sats (skip when the amount is already sats/btc or absent).
+      tool: 'fiat_to_sats',
+      as: 'conv',
+      args: (ctx) => ({ amount: ctx.slots.amount, currency: ctx.slots.currency }),
+      skipIf: (ctx) => !ctx.slots.amount || !isFiat(ctx),
+    },
+  ],
+  final: {
+    tool: 'send_payment',
+    args: (ctx) => {
+      const contact = ctx.results.contact as { ln_address?: string } | undefined;
+      const conv = ctx.results.conv as { sats?: number } | undefined;
+      return {
+        to: contact?.ln_address ?? ctx.slots.recipient,
+        amount_sats: conv?.sats ?? directSats(ctx),
+      };
+    },
+  },
+  summary: (ctx) => {
+    const conv = ctx.results.conv as { sats?: number } | undefined;
+    const sats = conv?.sats ?? directSats(ctx);
+    const to = (ctx.results.contact as { name?: string } | undefined)?.name ?? ctx.slots.recipient;
+    return sats ? `Sent ${sats.toLocaleString()} sats to ${to}.` : `Payment sent to ${to}.`;
+  },
+};

package/src/recipe/receive.ts

@@ -0,0 +1,98 @@
+/**
+ * Built-in "receive" recipe — create an invoice/address to get paid, in sats,
+ * BTC, an RGB asset, OR a fiat amount (converted to sats deterministically so a
+ * small model never mis-parses "$2.00").
+ *
+ *   "invoice for 5000 sats"            → BTC invoice, 5000 sats
+ *   "create a payment request of $2"   → fiat_to_sats(2, USD) → BTC invoice
+ *   "invoice for 25 USDT on Liquid"    → RGB asset invoice
+ *   "an invoice"                       → BTC invoice, any amount
+ */
+
+import type { Recipe } from './types.js';
+
+const LAYER = /\b(spark|arkade|liquid|rln|lightning|rgb)\b/i;
+const RECEIVE_INTENT = /\b(invoice|receive|deposit|get paid|pay me|payment request|request (a )?payment)\b/i;
+
+type Kind = 'sats' | 'btc' | 'fiat' | 'asset';
+
+function classify(text: string): { kind: Kind; code: string } {
+  if (/\$|\busd\b|dollar/i.test(text)) return { kind: 'fiat', code: 'USD' };
+  if (/€|\beur\b|euro/i.test(text)) return { kind: 'fiat', code: 'EUR' };
+  if (/£|\bgbp\b|pound/i.test(text)) return { kind: 'fiat', code: 'GBP' };
+  if (/usdt|tether/i.test(text)) return { kind: 'asset', code: 'USDT' };
+  if (/xaut|gold/i.test(text)) return { kind: 'asset', code: 'XAUT' };
+  if (/\bbtc\b|bitcoin/i.test(text)) return { kind: 'btc', code: 'BTC' };
+  return { kind: 'sats', code: 'BTC' }; // default: sats
+}
+function normLayer(l?: string): string | undefined {
+  if (!l) return undefined;
+  const x = l.toLowerCase();
+  if (x === 'lightning' || x === 'rgb') return 'rln';
+  if (['spark', 'arkade', 'liquid', 'rln'].includes(x)) return x;
+  return undefined;
+}
+function parseAmount(t: string): number | undefined {
+  const m = t.match(/(\d[\d.,]*)\s*([km])?\b/i);
+  if (!m) return undefined;
+  let n = Number(m[1]!.replace(/,/g, ''));
+  if (m[2]) n *= m[2].toLowerCase() === 'k' ? 1_000 : 1_000_000;
+  return Number.isNaN(n) ? undefined : n;
+}
+
+export function extractReceive(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  if (!RECEIVE_INTENT.test(t)) return null;
+  const amount = parseAmount(t);
+  const { kind, code } = classify(t);
+  const layer = normLayer(t.match(LAYER)?.[1]);
+  return { ...(amount != null ? { amount } : {}), kind, currency: code, ...(layer ? { layer } : {}) };
+}
+
+export const receiveRecipe: Recipe = {
+  name: 'receive',
+  description: 'Create an invoice/address to receive funds — sats, BTC, a fiat amount (converted), or an RGB asset.',
+  match: (t) => RECEIVE_INTENT.test(t) && !/\b(send|transfer|swap|buy|sell)\b/i.test(t),
+  triggers: ['invoice', 'receive', 'deposit', 'payment request'],
+  slots: [
+    { name: 'amount', type: 'number', description: 'Amount to receive (optional)' },
+    { name: 'currency', type: 'string', description: 'sats | BTC | USD | EUR | USDT | XAUT' },
+    { name: 'layer', type: 'string', description: 'Rail: spark, rln, liquid (optional)' },
+  ],
+  extract: extractReceive,
+  confident: () => true,
+  steps: [
+    {
+      // Fiat → sats, only when the amount is fiat-denominated.
+      tool: 'fiat_to_sats',
+      as: 'conv',
+      args: (ctx) => ({ amount: ctx.slots.amount, currency: ctx.slots.currency }),
+      skipIf: (ctx) => ctx.slots.kind !== 'fiat' || ctx.slots.amount == null,
+    },
+  ],
+  final: {
+    tool: 'create_invoice',
+    args: (ctx) => {
+      const kind = ctx.slots.kind as Kind;
+      const conv = ctx.results.conv as { sats?: number } | undefined;
+      let asset = 'BTC';
+      let amount = ctx.slots.amount as number | undefined;
+      if (kind === 'asset') asset = String(ctx.slots.currency);
+      else if (kind === 'fiat') amount = conv?.sats;
+      else if (kind === 'btc' && amount != null) amount = Math.round(amount * 1e8); // sats
+      return { asset, amount, layer: ctx.slots.layer };
+    },
+  },
+  summary: (ctx, result) => {
+    const r = result as { invoice?: string; address?: string } | undefined;
+    const dest = r?.invoice ?? r?.address ?? '';
+    const kind = ctx.slots.kind as Kind;
+    const conv = ctx.results.conv as { sats?: number } | undefined;
+    let amt = 'any amount';
+    if (kind === 'fiat' && ctx.slots.amount != null) amt = `${ctx.slots.currency} ${ctx.slots.amount} (${(conv?.sats ?? 0).toLocaleString()} sats)`;
+    else if (kind === 'asset' && ctx.slots.amount != null) amt = `${Number(ctx.slots.amount).toLocaleString()} ${ctx.slots.currency}`;
+    else if (ctx.slots.amount != null) amt = `${Number(ctx.slots.amount).toLocaleString()} ${kind === 'btc' ? 'BTC' : 'sats'}`;
+    const label = kind === 'asset' ? String(ctx.slots.currency) : 'BTC';
+    return dest ? `Here's your ${label} invoice for ${amt}:\n\n${dest}` : `Created an invoice for ${amt}.`;
+  },
+};

package/src/recipe/recipe.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ToolRegistry } from '../tools/registry.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { LLMProvider } from '../providers/types.js';
+import { runRecipe, RecipeRegistry } from './runner.js';
+import { paymentsRecipe, extractPayment } from './payments.js';
+import { swapRecipe, extractSwap } from './swap.js';
+import { receiveRecipe, extractReceive } from './receive.js';
+import { assetSendRecipe, extractAssetSend } from './asset-send.js';
+import { paymentsRecipe as _pay } from './payments.js';
+
+// Stub contract tools: resolve_contact, fiat_to_sats, send_payment (spend).
+function stubTools(spy?: { send?: (a: any) => void }) {
+  const src = new InProcessToolSource('wallet', [
+    { name: 'resolve_contact', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ name }) => ({ name, ln_address: `${name}@kaleidoswap.com` }) },
+    { name: 'fiat_to_sats', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ amount }) => ({ sats: Math.round(Number(amount) * 1000) }) },
+    { name: 'send_payment', description: '', parameters: { type: 'object', properties: {} }, requiresConfirmation: true, handler: async (a) => { spy?.send?.(a); return { status: 'SUCCESS', payment_hash: 'h' }; } },
+  ]);
+  return new ToolRegistry([src]);
+}
+
+const approve: LLMProvider = { name: 'x', runTurn: async () => ({ text: '', rawContent: '', toolCalls: [] }) };
+
+describe('extractPayment (deterministic Tier-0)', () => {
+  it('parses contact + fiat', () => {
+    expect(extractPayment('pay bob 3 eur')).toEqual({ recipient: 'bob', amount: 3, currency: 'eur' });
+  });
+  it('parses "send N sats to X"', () => {
+    expect(extractPayment('send 5,000 sats to alice')).toEqual({ recipient: 'alice', amount: 5000, currency: 'sats' });
+  });
+  it('parses btc + onchain-ish recipient', () => {
+    expect(extractPayment('send 0.001 btc to bob')).toEqual({ recipient: 'bob', amount: 0.001, currency: 'btc' });
+  });
+  it('expands k/m shorthand (no 1000x under-send)', () => {
+    expect(extractPayment('send 5k sats to bob')).toEqual({ recipient: 'bob', amount: 5000, currency: 'sats' });
+    expect(extractPayment('send 2m sats to alice')).toEqual({ recipient: 'alice', amount: 2_000_000, currency: 'sats' });
+  });
+  it('returns null for non-payment text', () => {
+    expect(extractPayment('what is my balance')).toBeNull();
+  });
+});
+
+describe('runRecipe — pay a contact', () => {
+  it('fiat path: resolve → fiat_to_sats → confirm → send', async () => {
+    const sent: any[] = [];
+    const tools = stubTools({ send: (a) => sent.push(a) });
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(paymentsRecipe, 'pay bob 3 eur', { provider: approve, tools, onConfirm });
+
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0); // deterministic extraction, no LLM
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(res.results.contact).toMatchObject({ ln_address: 'bob@kaleidoswap.com' });
+    expect(sent[0]).toEqual({ to: 'bob@kaleidoswap.com', amount_sats: 3000 }); // 3 * 1000
+    expect(res.text).toContain('3,000 sats');
+  });
+
+  it('sats path skips fiat_to_sats', async () => {
+    const sent: any[] = [];
+    const tools = stubTools({ send: (a) => sent.push(a) });
+    const res = await runRecipe(paymentsRecipe, 'send 5000 sats to alice', { provider: approve, tools, onConfirm: async () => ({ approved: true }) });
+    expect(res.status).toBe('done');
+    expect(res.results.conv).toBeUndefined(); // fiat step skipped
+    expect(sent[0]).toEqual({ to: 'alice@kaleidoswap.com', amount_sats: 5000 });
+  });
+
+  it('denied confirmation → cancelled, nothing sent', async () => {
+    const sent: any[] = [];
+    const tools = stubTools({ send: (a) => sent.push(a) });
+    const res = await runRecipe(paymentsRecipe, 'pay bob 3 eur', { provider: approve, tools, onConfirm: async () => ({ approved: false }) });
+    expect(res.status).toBe('cancelled');
+    expect(sent).toHaveLength(0);
+  });
+
+  it('falls back to ONE LLM extraction when regex misses', async () => {
+    const sent: any[] = [];
+    const tools = stubTools({ send: (a) => sent.push(a) });
+    // A recipe with no deterministic extractor → must use the provider.
+    const llmOnly = { ...paymentsRecipe, extract: undefined };
+    const provider: LLMProvider = {
+      name: 'mock',
+      runTurn: vi.fn(async () => ({ text: '', rawContent: '', toolCalls: [{ id: '1', name: 'extract_request', arguments: { recipient: 'bob', amount: 2, currency: 'usd' } }] })),
+    };
+    const res = await runRecipe(llmOnly, 'could you move a couple bucks to bob', { provider, tools, onConfirm: async () => ({ approved: true }) });
+    expect(res.inferences).toBe(1);
+    expect(provider.runTurn).toHaveBeenCalledOnce();
+    expect(sent[0]).toEqual({ to: 'bob@kaleidoswap.com', amount_sats: 2000 });
+  });
+});
+
+describe('extractSwap', () => {
+  it('parses "buy X <to> with <from>"', () => {
+    expect(extractSwap('buy 0.001 btc with usdt')).toEqual({ amount: 0.001, to_asset: 'BTC', from_asset: 'USDT' });
+  });
+  it('parses "swap X <from> for <to>"', () => {
+    expect(extractSwap('swap 10 usdt for btc')).toEqual({ amount: 10, from_asset: 'USDT', to_asset: 'BTC' });
+  });
+  it('returns null for non-swap text', () => {
+    expect(extractSwap('what is my balance')).toBeNull();
+  });
+});
+
+describe('runRecipe — swap', () => {
+  it('quote → confirm → execute', async () => {
+    const exec: any[] = [];
+    const tools = new ToolRegistry([new InProcessToolSource('w', [
+      { name: 'get_swap_quote', description: '', parameters: { type: 'object', properties: {} }, handler: async (a) => ({ quote_id: 'q1', receive_amount: 1500, ...a }) },
+      { name: 'execute_swap', description: '', parameters: { type: 'object', properties: {} }, requiresConfirmation: true, handler: async (a) => { exec.push(a); return { status: 'SUCCESS' }; } },
+    ])]);
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(swapRecipe, 'buy 0.001 btc with usdt', { provider: approve, tools, onConfirm });
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0);
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(res.results.quote).toMatchObject({ quote_id: 'q1' });
+    expect(exec[0]).toMatchObject({ quote_id: 'q1', from_asset: 'USDT', to_asset: 'BTC', amount: 0.001 });
+  });
+});
+
+describe('extractReceive', () => {
+  it('parses asset + layer', () => {
+    expect(extractReceive('create an invoice for 25 usdt on liquid')).toEqual({ amount: 25, kind: 'asset', currency: 'USDT', layer: 'liquid' });
+  });
+  it('amountless BTC invoice', () => {
+    expect(extractReceive('give me an invoice')).toEqual({ kind: 'sats', currency: 'BTC' });
+  });
+  it('sats with k shorthand', () => {
+    expect(extractReceive('invoice for 5k sats')).toEqual({ amount: 5000, kind: 'sats', currency: 'BTC' });
+  });
+  it('fiat: "$2.00" → 2 USD (not 2000)', () => {
+    expect(extractReceive('create a payment request of $2.00')).toEqual({ amount: 2, kind: 'fiat', currency: 'USD' });
+  });
+  it('null for non-receive text', () => {
+    expect(extractReceive('pay bob 3 eur')).toBeNull();
+  });
+});
+
+describe('runRecipe — receive', () => {
+  const tools = () => new ToolRegistry([new InProcessToolSource('w', [
+    { name: 'fiat_to_sats', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ amount }) => ({ sats: Math.round(Number(amount) * 1500) }) },
+    { name: 'create_invoice', description: '', parameters: { type: 'object', properties: {} }, handler: async (a) => ({ invoice: `lnbc-${a.asset}-${a.amount ?? 'any'}` }) },
+  ])]);
+  it('sats → create_invoice (no confirmation)', async () => {
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(receiveRecipe, 'invoice for 5000 sats', { provider: approve, tools: tools(), onConfirm });
+    expect(res.status).toBe('done');
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(res.text).toContain('lnbc-BTC-5000');
+  });
+  it('fiat "$2" → fiat_to_sats → invoice (3000 sats), never 2000', async () => {
+    const res = await runRecipe(receiveRecipe, 'create a payment request of $2', { provider: approve, tools: tools() });
+    expect(res.status).toBe('done');
+    expect(res.text).toContain('lnbc-BTC-3000'); // 2 * 1500
+    expect(res.text).toContain('USD 2');
+  });
+});
+
+describe('extractAssetSend + USDT bug fix', () => {
+  it('parses "send N USDT to contact"', () => {
+    expect(extractAssetSend('send 10 usdt to bob')).toEqual({ recipient: 'bob', asset: 'USDT', amount: 10 });
+  });
+  it('null for BTC/sats sends (payments owns those)', () => {
+    expect(extractAssetSend('send 5000 sats to bob')).toBeNull();
+  });
+  it('payments recipe NO LONGER matches an asset send (was the bug)', () => {
+    expect(_pay.match!('send 10 usdt to bob')).toBe(false);
+    expect(_pay.match!('send 5000 sats to bob')).toBe(true);
+    expect(assetSendRecipe.match!('send 10 usdt to bob')).toBe(true);
+  });
+});
+
+describe('runRecipe — asset send', () => {
+  it('resolve → rln_send_asset (confirmation-gated), no fiat conversion', async () => {
+    const sent: any[] = [];
+    const tools = new ToolRegistry([new InProcessToolSource('w', [
+      { name: 'resolve_contact', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ name }) => ({ name, ln_address: `${name}@x.com` }) },
+      { name: 'rln_send_asset', description: '', parameters: { type: 'object', properties: {} }, requiresConfirmation: true, handler: async (a) => { sent.push(a); return { status: 'SUCCESS' }; } },
+    ])]);
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(assetSendRecipe, 'send 10 usdt to bob', { provider: approve, tools, onConfirm });
+    expect(res.status).toBe('done');
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(sent[0]).toEqual({ asset: 'USDT', amount: 10, to: 'bob@x.com' });
+  });
+});
+
+describe('RecipeRegistry', () => {
+  it('selects by trigger', () => {
+    const reg = new RecipeRegistry([paymentsRecipe]);
+    expect(reg.select('pay bob 3 eur')?.name).toBe('pay-contact');
+    expect(reg.select('what is my balance')).toBeNull();
+  });
+});

package/src/recipe/runner.ts

@@ -0,0 +1,134 @@
+/**
+ * Recipe runner — executes a Recipe with ONE structured extraction (or a
+ * deterministic regex), then runs the deterministic step chain and the
+ * confirmation-gated final action. This is mobile multi-step: a tiny model
+ * fills slots; the engine does the planning.
+ */
+
+import type { LLMProvider } from '../providers/types.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ConfirmDecision } from '../types.js';
+import type { Recipe, RecipeContext, RecipeResult } from './types.js';
+
+const EXTRACT_TOOL = 'extract_request';
+
+export interface RunRecipeOptions {
+  provider: LLMProvider;
+  tools: ToolRegistry;
+  /** Called before the (spend) final action when its tool is confirmation-gated. */
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  /** Progress hook per completed step. */
+  onStep?: (name: string, args: Record<string, unknown>, result: unknown) => void;
+  /** Skip extraction and use these slots (deterministic Tier-0 / tests). */
+  slots?: Record<string, unknown>;
+  signal?: AbortSignal;
+}
+
+/** Extract the recipe's slots — deterministic regex first, else ONE LLM call. */
+export async function extractSlots(
+  provider: LLMProvider,
+  recipe: Recipe,
+  text: string,
+): Promise<{ slots: Record<string, unknown>; inferences: number }> {
+  const det = recipe.extract?.(text);
+  if (det && Object.values(det).some((v) => v !== undefined && v !== null && v !== '')) {
+    return { slots: det, inferences: 0 };
+  }
+  const properties: Record<string, { type: string; description: string }> = {};
+  for (const s of recipe.slots) properties[s.name] = { type: s.type ?? 'string', description: s.description };
+  const extractTool = {
+    name: EXTRACT_TOOL,
+    description: `Extract the fields from the user's request.`,
+    parameters: { type: 'object', properties, required: recipe.slots.filter((s) => s.required).map((s) => s.name) },
+  };
+  const out = await provider.runTurn({
+    system: `Call ${EXTRACT_TOOL} with the fields from the user's message. Do not call any other tool and do not add commentary.`,
+    messages: [{ role: 'user', content: text }],
+    tools: [extractTool],
+  });
+  const call = out.toolCalls?.find((c) => c.name === EXTRACT_TOOL) ?? out.toolCalls?.[0];
+  return { slots: (call?.arguments as Record<string, unknown>) ?? {}, inferences: 1 };
+}
+
+/** Run a recipe end to end. Never throws — failures come back as status:'error'. */
+export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOptions): Promise<RecipeResult> {
+  const ctx: RecipeContext = { text, slots: opts.slots ?? {}, results: {} };
+  let inferences = 0;
+  try {
+    if (!opts.slots) {
+      const ex = await extractSlots(opts.provider, recipe, text);
+      ctx.slots = ex.slots;
+      inferences = ex.inferences;
+    }
+
+    // Deterministic steps. Intermediate spend tools fire the same confirmation
+    // gate as the final step — recipes with multi-spend chains (e.g. atomic
+    // swaps) MUST have every money-moving call gated, never just the last one.
+    // Missing onConfirm fails closed, matching the Engine.
+    for (const step of recipe.steps) {
+      if (step.skipIf?.(ctx)) continue;
+      const args = step.args(ctx);
+      const def = await opts.tools.getDef(step.tool);
+      if (def?.requiresConfirmation) {
+        const decision = opts.onConfirm
+          ? await opts.onConfirm({ name: step.tool, arguments: args })
+          : { approved: false, reason: 'no confirmation handler available' };
+        if (!decision.approved) {
+          return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: 'Cancelled — nothing was sent.', status: 'cancelled', inferences };
+        }
+      }
+      const result = await opts.tools.execute(step.tool, args);
+      ctx.results[step.as ?? step.tool] = result;
+      opts.onStep?.(step.tool, args, result);
+    }
+
+    // Final action — confirmation-gated if the tool requires it. Like the
+    // Engine, a missing onConfirm FAILS CLOSED: the spend is declined, never
+    // silently executed.
+    const finalArgs = recipe.final.args(ctx);
+    const def = await opts.tools.getDef(recipe.final.tool);
+    if (def?.requiresConfirmation) {
+      const decision = opts.onConfirm
+        ? await opts.onConfirm({ name: recipe.final.tool, arguments: finalArgs })
+        : { approved: false, reason: 'no confirmation handler available' };
+      if (!decision.approved) {
+        return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: 'Cancelled — nothing was sent.', status: 'cancelled', inferences };
+      }
+    }
+    const finalResult = await opts.tools.execute(recipe.final.tool, finalArgs);
+    ctx.results[recipe.final.as ?? recipe.final.tool] = finalResult;
+    opts.onStep?.(recipe.final.tool, finalArgs, finalResult);
+
+    const out = recipe.summary?.(ctx, finalResult) ?? 'Done.';
+    return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, final: finalResult, text: out, status: 'done', inferences };
+  } catch (e) {
+    const msg = (e as Error)?.message ?? String(e);
+    return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: `Couldn't complete that: ${msg}`, status: 'error', error: msg, inferences };
+  }
+}
+
+/** Selects a recipe for a request. Use before falling back to the free agentic loop. */
+export class RecipeRegistry {
+  private recipes: Recipe[];
+  constructor(recipes: Recipe[] = []) {
+    this.recipes = [...recipes];
+  }
+  add(recipe: Recipe): void {
+    this.recipes.push(recipe);
+  }
+  list(): Recipe[] {
+    return [...this.recipes];
+  }
+  get(name: string): Recipe | undefined {
+    return this.recipes.find((r) => r.name === name);
+  }
+  /** First recipe whose match()/triggers fit the text, else null. */
+  select(text: string): Recipe | null {
+    const lc = text.toLowerCase();
+    return (
+      this.recipes.find((r) =>
+        r.match ? r.match(text) : (r.triggers ?? []).some((t) => lc.includes(t.toLowerCase())),
+      ) ?? null
+    );
+  }
+}