@kaleidorg/mind 0.0.1 → 0.2.0

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,122 @@
+/**
+ * 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.
+    for (const step of recipe.steps) {
+      if (step.skipIf?.(ctx)) continue;
+      const args = step.args(ctx);
+      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
+    );
+  }
+}

package/src/recipe/swap.ts

@@ -0,0 +1,74 @@
+/**
+ * Built-in "swap" recipe — quote → (confirm) → execute, over the contract tools.
+ *
+ *   "buy 0.001 btc with usdt"   → from USDT, to BTC
+ *   "swap 10 usdt for btc"      → from USDT, to BTC
+ *   "sell 100 usdt for sats"    → from USDT, to BTC
+ *
+ * The deterministic extractor handles the common phrasings; the runner falls
+ * back to one LLM extraction otherwise. execute_swap is a spend → the engine's
+ * confirmation gate fires before it runs.
+ */
+
+import type { Recipe } from './types.js';
+
+const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+
+function normAsset(a?: string): string | undefined {
+  if (!a) return undefined;
+  const x = a.toLowerCase();
+  if (/btc|bitcoin|sat/.test(x)) return 'BTC';
+  if (/usdt|tether/.test(x)) return 'USDT';
+  if (/xaut|gold/.test(x)) return 'XAUT';
+  return a.toUpperCase();
+}
+const num = (s?: string) => (s ? Number(s.replace(/,/g, '')) : undefined);
+
+/** "buy 0.001 btc with usdt" / "swap 10 usdt for btc" / "sell 100 usdt for sats". */
+export function extractSwap(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  let m: RegExpMatchArray | null;
+  // buy <amt> <to> with/using <from>  (amount is of the asset being bought)
+  if ((m = t.match(/buy\s+([\d.,]+)\s*([a-z]+)\s+(?:with|using|for)\s+([a-z]+)/i))) {
+    return { amount: num(m[1]), to_asset: normAsset(m[2]), from_asset: normAsset(m[3]) };
+  }
+  // swap/sell/convert/exchange/trade <amt> <from> for/to/into <to>
+  if ((m = t.match(/(?:swap|sell|convert|exchange|trade)\s+([\d.,]+)\s*([a-z]+)\s+(?:for|to|into)\s+([a-z]+)/i))) {
+    return { amount: num(m[1]), from_asset: normAsset(m[2]), to_asset: normAsset(m[3]) };
+  }
+  return null;
+}
+
+export const swapRecipe: Recipe = {
+  name: 'swap',
+  description: 'Swap between BTC and an RGB asset — quote, then execute (with confirmation).',
+  // A crypto swap intent — but NOT buying a gift card (that's commerce) or an invoice.
+  match: (t) => /\b(swap|exchange|convert|trade)\b/i.test(t) || (/\b(buy|sell)\b/i.test(t) && ASSET.test(t) && !/\b(gift\s?card|top-?up|esim|voucher|invoice|address)\b/i.test(t)),
+  triggers: ['swap', 'exchange', 'convert', 'trade'],
+  slots: [
+    { name: 'from_asset', type: 'string', description: 'Asset to spend (e.g. USDT, BTC)', required: true },
+    { name: 'to_asset', type: 'string', description: 'Asset to receive (e.g. BTC, USDT)', required: true },
+    { name: 'amount', type: 'number', description: 'Amount to swap' },
+  ],
+  extract: extractSwap,
+  confident: (s) => !!s.from_asset && !!s.to_asset,
+  steps: [
+    {
+      tool: 'get_swap_quote',
+      as: 'quote',
+      args: (ctx) => ({ from_asset: ctx.slots.from_asset, to_asset: ctx.slots.to_asset, amount: ctx.slots.amount }),
+    },
+  ],
+  final: {
+    tool: 'execute_swap',
+    args: (ctx) => {
+      const q = ctx.results.quote as { quote_id?: string } | undefined;
+      return { quote_id: q?.quote_id, from_asset: ctx.slots.from_asset, to_asset: ctx.slots.to_asset, amount: ctx.slots.amount };
+    },
+  },
+  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 `Swapped ${ctx.slots.amount} ${ctx.slots.from_asset} → ${ctx.slots.to_asset}${tail}.`;
+  },
+};

package/src/recipe/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Recipes — multi-step that works on a tiny model. "Recipes, not planning."
+ *
+ * A small model can't reliably PLAN a chain ("pay bob 3 EUR" = resolve → price
+ * → convert → send) from scratch. So a Recipe carries the plan; the model is
+ * used for ONE thing — extracting the request's slots (recipient, amount, …).
+ * The engine then runs the deterministic steps and the (confirmation-gated)
+ * final action. ~1 inference instead of 5; reliable on 0.6–4B.
+ *
+ * Pure data + interfaces — no deps. The provider + tools are injected.
+ */
+
+export interface RecipeSlot {
+  name: string;
+  type?: 'string' | 'number' | 'boolean';
+  description: string;
+  required?: boolean;
+}
+
+export interface RecipeContext {
+  /** The original user text. */
+  text: string;
+  /** Extracted slots (deterministic regex, else one LLM call). */
+  slots: Record<string, unknown>;
+  /** Results of completed steps, keyed by `as` (or tool name). */
+  results: Record<string, unknown>;
+}
+
+export interface RecipeStep {
+  /** Tool to call. */
+  tool: string;
+  /** Build the tool args from the accumulated context. */
+  args: (ctx: RecipeContext) => Record<string, unknown>;
+  /** Store the result under this key (default: the tool name). */
+  as?: string;
+  /** Skip this step when true (e.g. recipient is already an address). */
+  skipIf?: (ctx: RecipeContext) => boolean;
+}
+
+export interface Recipe {
+  name: string;
+  description?: string;
+  /** Selection: a predicate or trigger phrases. */
+  match?: (text: string) => boolean;
+  triggers?: string[];
+  /** Fields the model (or regex) extracts from the request. */
+  slots: RecipeSlot[];
+  /** Optional deterministic extractor tried BEFORE the LLM (Tier-0 fast-path). */
+  extract?: (text: string) => Record<string, unknown> | null;
+  /**
+   * Whether the recipe is confident enough to RUN deterministically given the
+   * extracted slots (vs falling back to the agentic loop). e.g. payments needs a
+   * recipient; receive needs an amount or asset. Default: any slot extracted.
+   */
+  confident?: (slots: Record<string, unknown>) => boolean;
+  /** Deterministic steps, run in order, results threaded into `ctx`. */
+  steps: RecipeStep[];
+  /** The terminal action (usually a spend → confirmation-gated by its tool). */
+  final: RecipeStep;
+  /** Render the outcome for the user. */
+  summary?: (ctx: RecipeContext, finalResult: unknown) => string;
+}
+
+export type RecipeStatus = 'done' | 'cancelled' | 'error';
+
+export interface RecipeResult {
+  recipe: string;
+  slots: Record<string, unknown>;
+  results: Record<string, unknown>;
+  final?: unknown;
+  text: string;
+  status: RecipeStatus;
+  error?: string;
+  /** Number of LLM inferences used (0 if extraction was deterministic). */
+  inferences: number;
+}

package/src/skills/bundle.ts

@@ -0,0 +1,42 @@
+/**
+ * Skill bundle — the RN-safe counterpart to the Node fs loader.
+ *
+ * React Native has no filesystem, so a skill folder can't be read at runtime.
+ * Instead a build step serialises the skills into a `SkillBundle` (plain JSON:
+ * each skill's raw SKILL.md text + its reference files), and the app rehydrates
+ * them here with `skillsFromBundle()`. Same skills, same SKILL.md authoring —
+ * just delivered as data instead of files.
+ *
+ * Pure, dependency-free, no fs/url imports — safe to import from the package's
+ * main entry on any host.
+ */
+
+import type { Skill, SkillReference } from './types.js';
+import { parseSkill } from './registry.js';
+
+/** One serialised skill: the SKILL.md text + its reference files. */
+export interface BundledSkill {
+  /** Folder name (informational; the real name comes from the frontmatter). */
+  dir?: string;
+  /** Raw SKILL.md contents. */
+  markdown: string;
+  /** references/*.md files. */
+  references?: SkillReference[];
+}
+
+/** A bundle of skills produced by the bundler script. */
+export interface SkillBundle {
+  version: 1;
+  skills: BundledSkill[];
+}
+
+/** Rehydrate Skills from a bundle (RN-safe — no filesystem). */
+export function skillsFromBundle(bundle: SkillBundle): Skill[] {
+  if (!bundle || bundle.version !== 1 || !Array.isArray(bundle.skills)) {
+    throw new Error('skillsFromBundle: not a valid v1 SkillBundle');
+  }
+  return bundle.skills.map((b) => ({
+    ...parseSkill(b.markdown, b.references),
+    dir: b.dir,
+  }));
+}

package/src/skills/loader.ts

@@ -0,0 +1,63 @@
+/**
+ * Skill loader — reads Claude-style Agent Skill folders from disk. NODE ONLY.
+ *
+ * Import from `@kaleidorg/mind/skills` on Node hosts (desktop sidecar,
+ * kaleidoagent). React Native has no filesystem — there, build skills with
+ * `SkillRegistry.addMarkdown(text, references)` from bundled strings instead.
+ *
+ * Layout (Anthropic Agent Skills spec, e.g. bitrefill/agents):
+ *
+ *   skills/
+ *     bitrefill/
+ *       SKILL.md
+ *       references/
+ *         mcp.md
+ *         cli.md
+ *         …
+ *
+ * `loadSkillsDir(root)` returns one Skill per SKILL.md found, with every
+ * reference markdown read into `skill.references` for progressive disclosure.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Skill, SkillReference } from './types.js';
+import { parseSkill } from './registry.js';
+
+/**
+ * Absolute path to the skills shipped inside this package
+ * (`@kaleidorg/mind/skills`). Resolves relative to the compiled loader, so it
+ * works from any host that installs the package. Override with an explicit dir
+ * when you keep skills elsewhere.
+ */
+export function packagedSkillsDir(): string {
+  // dist/skills/loader.js → ../../skills == <package root>/skills
+  return fileURLToPath(new URL('../../skills/', import.meta.url));
+}
+
+/** Load one skill folder containing a SKILL.md (+ optional references/). */
+export function loadSkillFromDir(dir: string): Skill {
+  const skillFile = join(dir, 'SKILL.md');
+  if (!existsSync(skillFile)) throw new Error(`No SKILL.md in ${dir}`);
+  const markdown = readFileSync(skillFile, 'utf8');
+
+  const refDir = join(dir, 'references');
+  const references: SkillReference[] = existsSync(refDir)
+    ? readdirSync(refDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((name) => ({ name, content: readFileSync(join(refDir, name), 'utf8') }))
+    : [];
+
+  return { ...parseSkill(markdown, references), dir };
+}
+
+/** Load every skill folder under `root` (each a dir with a SKILL.md). */
+export function loadSkillsDir(root: string): Skill[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(root, e.name, 'SKILL.md')))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((e) => loadSkillFromDir(join(root, e.name)));
+}