@kaleidorg/mind 0.4.0 → 0.5.1

package/src/recipe/recipe.test.ts

@@ -4,7 +4,7 @@ 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 { swapRecipe, extractSwap, extractPriceQuery } from './swap.js';
 import { receiveRecipe, extractReceive } from './receive.js';
 import { assetSendRecipe, extractAssetSend } from './asset-send.js';
 import { paymentsRecipe as _pay } from './payments.js';
@@ -89,15 +89,71 @@ describe('runRecipe — pay a contact', () => {
 });
 
 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 "buy X <to> with <from>" — amount on the TO leg', () => {
+    expect(extractSwap('buy 0.001 btc with usdt')).toEqual({ amount: 0.001, to_asset: 'BTC', from_asset: 'USDT', amount_side: 'to' });
   });
-  it('parses "swap X <from> for <to>"', () => {
-    expect(extractSwap('swap 10 usdt for btc')).toEqual({ amount: 10, from_asset: 'USDT', to_asset: 'BTC' });
+  it('parses "swap X <from> for <to>" — amount on the FROM leg', () => {
+    expect(extractSwap('swap 10 usdt for btc')).toEqual({ amount: 10, from_asset: 'USDT', to_asset: 'BTC', amount_side: 'from' });
+  });
+  it('parses "buy one usdt" — word-number, default funding asset, TO leg (the reported bug)', () => {
+    expect(extractSwap('buy one usdt from kaleido')).toEqual({ amount: 1, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to' });
+  });
+  it('parses "sell 100 usdt" — default target BTC, FROM leg', () => {
+    expect(extractSwap('sell 100 usdt')).toEqual({ amount: 100, from_asset: 'USDT', to_asset: 'BTC', amount_side: 'from' });
+  });
+  it('ignores a non-asset word as the funding asset ("from kaleido" → defaults BTC)', () => {
+    const r = extractSwap('buy 5 xaut from kaleido') as any;
+    expect(r.to_asset).toBe('XAUT');
+    expect(r.from_asset).toBe('BTC');
   });
   it('returns null for non-swap text', () => {
     expect(extractSwap('what is my balance')).toBeNull();
   });
+
+  // Price-flavoured phrasings belong to extractPriceQuery (separate recipe) —
+  // extractSwap returns null for them so the atomic recipe doesn't move funds
+  // on a question the user only meant as a rate lookup.
+  it('does NOT parse price/rate phrasings (those go to kaleidoswapPriceRecipe)', () => {
+    expect(extractSwap('what is the price of usdt in sats')).toBeNull();
+    expect(extractSwap('btc price')).toBeNull();
+    expect(extractSwap('how much sats for 1 usdt')).toBeNull();
+    expect(extractSwap('cost of xaut')).toBeNull();
+  });
+});
+
+describe('extractPriceQuery', () => {
+  it('parses the reported transcript case', () => {
+    expect(extractPriceQuery('what is the price of usdt in sats')).toEqual({
+      amount: 1, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to',
+    });
+  });
+  it('tolerates a "the" article', () => {
+    expect(extractPriceQuery('what is the price of the usdt in sats?')).toEqual({
+      amount: 1, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to',
+    });
+  });
+  it('"btc price" — funding defaults to USDT when pricing BTC', () => {
+    expect(extractPriceQuery('btc price')).toEqual({
+      amount: 1, from_asset: 'USDT', to_asset: 'BTC', amount_side: 'to',
+    });
+  });
+  it('"how much sats for 1 usdt" — denom inferred from the unit, not order', () => {
+    expect(extractPriceQuery('how much sats for 1 usdt')).toEqual({
+      amount: 1, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to',
+    });
+  });
+  it('handles "cost of xaut" and "how much does 1 btc cost"', () => {
+    expect((extractPriceQuery('cost of xaut') as any)?.to_asset).toBe('XAUT');
+    expect((extractPriceQuery('how much does 1 btc cost') as any)?.to_asset).toBe('BTC');
+  });
+  it('does NOT fire on a non-asset price question', () => {
+    expect(extractPriceQuery('what is the price of gas')).toBeNull();
+    expect(extractPriceQuery('how much does it cost')).toBeNull();
+  });
+  it('does NOT fire on a swap intent (those go to the atomic recipe)', () => {
+    expect(extractPriceQuery('swap 10 usdt to btc')).toBeNull();
+    expect(extractPriceQuery('buy one usdt')).toBeNull();
+  });
 });
 
 describe('runRecipe — swap', () => {

package/src/recipe/runner.ts

@@ -15,8 +15,13 @@ 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>;
+  /**
+   * Called before a confirmation-gated spend. `summary` is set when the recipe
+   * supplies a `confirm(ctx)` — a human-readable description of the whole
+   * approved action (e.g. "swap 10 USDT → 15,250 sats, fee 154 sats"). Hosts
+   * should prefer `summary` over the raw tool name/args when showing a sheet.
+   */
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown>; summary?: string }) => 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). */
@@ -31,23 +36,87 @@ export async function extractSlots(
   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 !== '')) {
+  const detValid = det && Object.values(det).some((v) => v !== undefined && v !== null && v !== '');
+
+  if (detValid && !recipe.forceModelExtract) {
     return { slots: det, inferences: 0 };
   }
+
+  // Build a richer extraction prompt + tool schema so small models have a
+  // better chance of producing correct structured output for recipes (especially
+  // when forceModelExtract is on for natural language intents like "buy 1 usdt").
   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 recipeHint = recipe.description ? ` for the "${recipe.name}" recipe (${recipe.description})` : '';
   const extractTool = {
     name: EXTRACT_TOOL,
-    description: `Extract the fields from the user's request.`,
+    description: `Extract the fields from the user's request${recipeHint}.`,
     parameters: { type: 'object', properties, required: recipe.slots.filter((s) => s.required).map((s) => s.name) },
   };
+
+  const system = [
+    `Call ${EXTRACT_TOOL} with the fields from the user's message.`,
+    recipe.description ? `This extraction is for: ${recipe.description}.` : '',
+    'Only emit values that match the field descriptions.',
+    'Canonical assets: BTC, USDT, XAUT (pass as strings like "BTC" or "USDT").',
+    'amount_side: "to" when the named amount is what you receive/buy (e.g. "buy 1 USDT" → to_asset=USDT, amount=1, from_asset=BTC); "from" for sell/swap (amount on from_asset).',
+    'The host binding handles per-asset precision scaling (BTC in sats → maker units; USDT/XAUT whole units). Pass the user\'s number as-is for the correct side.',
+    'Do not call any other tool and do not add commentary.',
+  ].filter(Boolean).join(' ');
+
   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.`,
+    system,
     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 };
+  let llmSlots: Record<string, unknown> = (call?.arguments as Record<string, unknown>) ?? {};
+
+  // Safety net when forceModelExtract is active.
+  // - The LLM is authoritative for the slots it filled — its output wins.
+  // - Det is used only to backfill required fields the LLM left empty.
+  // - The amount_side-specific check below applies ONLY to recipes that
+  //   actually declare an `amount_side` slot (swap-shaped recipes) — for
+  //   others (channel-order, etc.) it would clobber correct LLM extraction
+  //   because amount_side is always undefined.
+  if (recipe.forceModelExtract && detValid) {
+    const required = recipe.slots.filter((s) => s.required);
+    const llmHasAllRequired = required.every((s) => {
+      const v = llmSlots[s.name];
+      return v != null && v !== '';
+    });
+
+    const recipeHasAmountSide = recipe.slots.some((s) => s.name === 'amount_side');
+    if (recipeHasAmountSide) {
+      const llmSide = String(llmSlots.amount_side || '').toLowerCase();
+      const validSide = llmSide === 'from' || llmSide === 'to';
+      if (!llmHasAllRequired || !validSide) {
+        llmSlots = { ...det, ...llmSlots };
+      } else {
+        llmSlots.amount_side = llmSide;
+      }
+      if (!validSide && det.amount_side) {
+        llmSlots.amount_side = det.amount_side;
+      }
+    } else {
+      // Generic path: backfill ANY slot the LLM didn't populate from det's
+      // value, when det has one. LLM wins on every field it actually filled,
+      // but det shouldn't be silently erased — small models often omit
+      // non-required slots (e.g. asset_ticker on a USDT channel) that the
+      // deterministic regex caught reliably.
+      for (const s of recipe.slots) {
+        const llmVal = llmSlots[s.name];
+        const detVal = det[s.name];
+        if ((llmVal == null || llmVal === '') && detVal != null && detVal !== '') {
+          llmSlots[s.name] = detVal;
+        }
+      }
+    }
+  }
+
+  return { slots: llmSlots, inferences: 1 };
 }
 
 /** Run a recipe end to end. Never throws — failures come back as status:'error'. */
@@ -61,40 +130,68 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
       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) {
+    // Confidence re-check AFTER extraction (whether deterministic, LLM, or
+    // pre-supplied). When the recipe defines `confident()` and the extracted
+    // slots fail it, refuse to run the steps with bad data — surface a
+    // friendly "please specify <missing required slots>" message so the user
+    // can re-ask with the info instead of getting a maker 4xx mid-chain.
+    if (recipe.confident && !recipe.confident(ctx.slots)) {
+      const missing = recipe.slots
+        .filter((s) => s.required && (ctx.slots[s.name] == null || ctx.slots[s.name] === ''))
+        .map((s) => `${s.name} (${s.description})`);
+      const ask =
+        missing.length > 0
+          ? `I need a bit more info — please specify: ${missing.join('; ')}.`
+          : "I don't have enough info to do that — could you rephrase with the specifics?";
+      return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: ask, status: 'needs-info', inferences };
+    }
+
+    // Confirmation model:
+    //  - Recipe with `confirm(ctx)`: fire ONE gate before the first spend step,
+    //    showing the recipe-level summary; once approved, later spend steps run
+    //    ungated (the whole chain is one approved decision).
+    //  - Recipe without `confirm`: gate EACH spend tool individually (default;
+    //    payments/receive/asset-send rely on this).
+    // Missing onConfirm FAILS CLOSED in both cases, matching the Engine.
+    const cancelled = (): RecipeResult => ({
+      recipe: recipe.name, slots: ctx.slots, results: ctx.results,
+      text: 'Cancelled — nothing was sent.', status: 'cancelled', inferences,
+    });
+    let recipeApproved = false;
+
+    /** Gate a single (spend) step. Returns false if the user declined. */
+    const passesGate = async (toolName: string, args: Record<string, unknown>): Promise<boolean> => {
+      const def = await opts.tools.getDef(toolName);
+      if (!def?.requiresConfirmation) return true;
+      // Recipe-level single confirm: ask once, then remember the approval.
+      if (recipe.confirm) {
+        if (recipeApproved) return true;
+        const summary = recipe.confirm(ctx) ?? undefined;
         const decision = opts.onConfirm
-          ? await opts.onConfirm({ name: step.tool, arguments: args })
+          ? await opts.onConfirm({ name: toolName, arguments: args, summary })
           : { 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 };
-        }
+        if (decision.approved) recipeApproved = true;
+        return decision.approved;
       }
+      // Per-tool confirm (legacy default).
+      const decision = opts.onConfirm
+        ? await opts.onConfirm({ name: toolName, arguments: args })
+        : { approved: false, reason: 'no confirmation handler available' };
+      return decision.approved;
+    };
+
+    for (const step of recipe.steps) {
+      if (step.skipIf?.(ctx)) continue;
+      const args = step.args(ctx);
+      if (!(await passesGate(step.tool, args))) return cancelled();
       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.
+    // Final action.
     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 };
-      }
-    }
+    if (!(await passesGate(recipe.final.tool, finalArgs))) return cancelled();
     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);

package/src/recipe/swap.ts

@@ -14,31 +14,127 @@ import type { Recipe } from './types.js';
 
 const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
 
-function normAsset(a?: string): string | undefined {
+/** Strict: returns a canonical code only for a KNOWN crypto asset, else undefined
+ *  (so "kaleido", "the", etc. are not mistaken for an asset). */
+function knownAsset(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();
+  if (/^(btc|bitcoin|sat|sats|satoshi|satoshis)$/.test(x)) return 'BTC';
+  if (/^(usdt|tether)$/.test(x)) return 'USDT';
+  if (/^(xaut|gold)$/.test(x)) return 'XAUT';
+  return undefined;
 }
-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". */
+// Small word-numbers cover the common spoken/typed cases ("buy one usdt").
+const WORD_NUM: Record<string, number> = {
+  a: 1, an: 1, one: 1, two: 2, three: 3, four: 4, five: 5,
+  six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+};
+const AMT = '([\\d.,]+|a|an|one|two|three|four|five|six|seven|eight|nine|ten)';
+
+function parseAmount(s?: string): number | undefined {
+  if (!s) return undefined;
+  const t = s.trim().toLowerCase();
+  if (t in WORD_NUM) return WORD_NUM[t];
+  const n = Number(t.replace(/,/g, ''));
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Parse a swap/buy/sell request into { from_asset, to_asset, amount, amount_side }.
+ *
+ * `amount_side` says which leg the amount belongs to (the maker takes the amount
+ * on exactly one leg):
+ *   - "buy N X"     → receive N of X  → amount on the TO leg, from defaults to BTC
+ *   - "sell N X"    → spend N of X    → amount on the FROM leg, to defaults to BTC
+ *   - "swap N X to Y" → spend N of X  → amount on the FROM leg
+ *
+ *   "buy one usdt"            → from BTC, to USDT, amount 1 on `to`
+ *   "buy 0.001 btc with usdt" → from USDT, to BTC,  amount 0.001 on `to`
+ *   "sell 100 usdt"           → from USDT, to BTC,  amount 100 on `from`
+ *   "swap 10 usdt for btc"    → from USDT, to BTC,  amount 10 on `from`
+ */
 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]) };
+
+  // buy/get/purchase <amt> <asset> [with/using/from <funding-asset>]
+  // amount is of the asset being BOUGHT → it sits on the TO leg.
+  if ((m = t.match(new RegExp(`\\b(?:buy|get|purchase|acquire)\\s+${AMT}\\s*([a-z]+)(?:\\s+(?:with|using|from|for)\\s+([a-z]+))?`, 'i')))) {
+    const to = knownAsset(m[2]);
+    if (to) {
+      const from = knownAsset(m[3]) ?? (to === 'BTC' ? 'USDT' : 'BTC');
+      return { amount: parseAmount(m[1]), from_asset: from, to_asset: to, amount_side: 'to' };
+    }
   }
-  // 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]) };
+
+  // sell <amt> <asset> [for/to/into <target>]
+  // amount is of the asset being SOLD → it sits on the FROM leg.
+  if ((m = t.match(new RegExp(`\\bsell\\s+${AMT}\\s*([a-z]+)(?:\\s+(?:for|to|into)\\s+([a-z]+))?`, 'i')))) {
+    const from = knownAsset(m[2]);
+    if (from) {
+      const to = knownAsset(m[3]) ?? (from === 'BTC' ? 'USDT' : 'BTC');
+      return { amount: parseAmount(m[1]), from_asset: from, to_asset: to, amount_side: 'from' };
+    }
+  }
+
+  // swap/convert/exchange/trade <amt> <from> for/to/into <to>
+  if ((m = t.match(new RegExp(`\\b(?:swap|convert|exchange|trade)\\s+${AMT}\\s*([a-z]+)\\s+(?:for|to|into)\\s+([a-z]+)`, 'i')))) {
+    const from = knownAsset(m[2]);
+    const to = knownAsset(m[3]);
+    if (from && to) return { amount: parseAmount(m[1]), from_asset: from, to_asset: to, amount_side: 'from' };
   }
+
+  // Price/rate questions are NOT swaps — they belong to extractPriceQuery +
+  // kaleidoswapPriceRecipe (read-only). Don't gobble them here.
   return null;
 }
 
+/**
+ * Parse a PRICE / rate / "how much" question — read-only intent.
+ *
+ * Distinct from extractSwap: never returns slots for swap/buy/sell phrasings.
+ * Always `amount: 1` on the asked-about asset (TO leg). Used by
+ * `kaleidoswapPriceRecipe` to fire a quote without moving funds.
+ *
+ *   "what is the price of usdt in sats"  → {from: BTC,  to: USDT, amount: 1, side: 'to'}
+ *   "btc price"                          → {from: USDT, to: BTC,  amount: 1, side: 'to'}
+ *   "how much sats for 1 usdt"           → {from: BTC,  to: USDT, amount: 1, side: 'to'}
+ */
+export function extractPriceQuery(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  // Reject swap intent — those go to the atomic recipe, not the price recipe.
+  if (/\b(swap|exchange|convert|trade|buy|sell|get|purchase|acquire)\b/i.test(t)) return null;
+
+  // ORDER MATTERS: "how much B for A" (first) must be checked BEFORE
+  // "how much X (in Y)?" — otherwise the latter would gobble the first asset
+  // and miss the "for/per" tail. Optional "the" article is tolerated
+  // ("price of THE usdt") — natural English the maker doesn't care about.
+  const priceLike =
+    t.match(/\bhow\s+(?:many|much)\s+(?:the\s+)?([a-z]+)\s+(?:for|per|in)\s+(?:1\s+|one\s+|the\s+)?([a-z]+)\b/i) ||
+    t.match(/\b(?:price|cost|worth)\s+of\s+(?:the\s+)?([a-z]+)(?:\s+in\s+(?:the\s+)?([a-z]+))?/i) ||
+    t.match(/\b(?:the\s+)?([a-z]+)\s+(?:price|cost)\b/i) ||
+    t.match(/\brate\s+of\s+(?:the\s+)?([a-z]+)(?:\s+(?:in|to|vs)\s+(?:the\s+)?([a-z]+))?/i) ||
+    t.match(/\b(?:the\s+)?([a-z]+)\s+(?:to|vs|in|\/)\s+([a-z]+)\s+rate\b/i) ||
+    t.match(/\bhow\s+much\s+(?:does\s+)?(?:1\s+|one\s+|the\s+)?([a-z]+)\s+cost\b/i) ||
+    t.match(/\bhow\s+much\s+(?:is\s+)?(?:1\s+|one\s+|the\s+)?([a-z]+)(?:\s+in\s+(?:the\s+)?([a-z]+))?\b/i);
+  if (!priceLike) return null;
+
+  const a = knownAsset(priceLike[1]);
+  const b = knownAsset(priceLike[2]);
+  let asset: string | undefined;
+  let denom: string | undefined;
+  if (/how\s+(?:many|much)\s+\w+\s+(?:for|per|in)/i.test(t) && b) {
+    // "how much B for A" — asset is A (the named priced one), denom is B (unit).
+    asset = b; denom = a;
+  } else {
+    asset = a; denom = b;
+  }
+  if (!asset) return null;
+  const from = denom ?? (asset === 'BTC' ? 'USDT' : 'BTC');
+  return { amount: 1, from_asset: from, to_asset: asset, amount_side: 'to' };
+}
+
 export const swapRecipe: Recipe = {
   name: 'swap',
   description: 'Swap between BTC and an RGB asset — quote, then execute (with confirmation).',

package/src/recipe/types.ts

@@ -47,6 +47,14 @@ export interface Recipe {
   slots: RecipeSlot[];
   /** Optional deterministic extractor tried BEFORE the LLM (Tier-0 fast-path). */
   extract?: (text: string) => Record<string, unknown> | null;
+  /**
+   * When true (and `extract` is provided), the runner will *ignore* a successful
+   * deterministic extraction and always perform the 1-inference LLM slot
+   * extraction. This lets the model do the natural-language understanding of
+   * the user's request (e.g. "buy 1 usdt") while the Recipe still owns the
+   * reliable multi-step execution plan and single-confirmation safety.
+   */
+  forceModelExtract?: boolean;
   /**
    * 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
@@ -59,9 +67,25 @@ export interface Recipe {
   final: RecipeStep;
   /** Render the outcome for the user. */
   summary?: (ctx: RecipeContext, finalResult: unknown) => string;
+  /**
+   * Single recipe-level confirmation. When set, the runner fires exactly ONE
+   * confirmation gate immediately before the first spend step, passing the
+   * returned string as the confirm summary; once approved, the remaining spend
+   * steps run WITHOUT re-prompting (the whole chain is one approved decision).
+   *
+   * Use for multi-spend chains where the user makes a single choice up front
+   * from data gathered by earlier (read-only) steps — e.g. an atomic swap:
+   * quote first, then confirm "swap X → Y, fee Z" once, then init/whitelist/
+   * execute run as a unit.
+   *
+   * Return `null` to skip confirmation entirely (rare). When `confirm` is
+   * absent, the runner falls back to gating EACH spend tool individually
+   * (the default — used by payments/receive/asset-send).
+   */
+  confirm?: (ctx: RecipeContext) => string | null;
 }
 
-export type RecipeStatus = 'done' | 'cancelled' | 'error';
+export type RecipeStatus = 'done' | 'cancelled' | 'error' | 'needs-info';
 
 export interface RecipeResult {
   recipe: string;

package/src/skills/registry.ts

@@ -7,6 +7,8 @@
  */
 
 import type { Skill, SkillReference, SkillSelector } from './types.js';
+import type { EmbeddingProvider } from '../rag/types.js';
+import { cosineSimilarity } from '../rag/vector-store.js';
 
 /** Tool name the reference source exposes for progressive disclosure. */
 export const READ_REFERENCE_TOOL = 'read_skill_reference';
@@ -92,7 +94,10 @@ function triggerMatches(query: string, trigger: string): boolean {
   return new RegExp(`\\b${reEscape(t)}\\b`).test(query);
 }
 
-/** Default selector: score by meaningful keyword overlap; triggers weigh most. */
+/** Default selector: score by meaningful keyword overlap; triggers weigh most.
+ *  Light extra sensitivity for common location / discovery phrasing so merchant-finder
+ *  and similar skills surface on natural queries even without exact trigger words.
+ */
 export const keywordSelector: SkillSelector = {
   select(query, skills) {
     const q = query.toLowerCase();
@@ -110,6 +115,15 @@ export const keywordSelector: SkillSelector = {
       // word boundary, so short triggers (`usd`, `eur`, `cafe`) don't leak
       // into longer words (`usdt`, `europe`, `cafeteria`).
       for (const t of skill.triggers ?? []) if (triggerMatches(q, t)) score += 3;
+
+      // Light discovery / location phrase boost (helps merchant-finder and
+      // similar skills on natural language like "coffee near the station" or
+      // "buy pizza with sats in turin").
+      if (/\b(near|nearby|around|close|spend|find|shop|cafe|coffee|food|eat|lunch|dinner|atm|buy|pizz|restaurant)\b/i.test(q)) {
+        const skillText = (skill.description + ' ' + (skill.triggers || []).join(' ')).toLowerCase();
+        if (/(merchant|btcmap|map|location|nearby|spend.*bitcoin|find.*place|food|restaurant|cafe|eat|pizza)/.test(skillText)) score += 1.5;
+      }
+
       if (score > bestScore) {
         bestScore = score;
         best = skill;
@@ -120,6 +134,43 @@ export const keywordSelector: SkillSelector = {
   },
 };
 
+/**
+ * Optional embedding-powered selector factory.
+ *
+ * When an EmbeddingProvider (the same shape used by Retriever/RAG) is supplied,
+ * hosts can use the returned selector for more semantic skill routing. This
+ * helps vague/natural location and discovery queries ("coffee near the station",
+ * "somewhere to grab a bite that takes lightning") reach merchant-finder or
+ * similar skills even without exact keyword overlap.
+ *
+ * The current implementation keeps a synchronous SkillSelector contract (to match
+ * the existing interface used by Funnel and SkillRegistry). It therefore:
+ *   - Uses an enhanced keywordSelector as the fast path (see above).
+ *   - If embeddings are provided it is ready for hosts to wrap or evolve into a
+ *     fully semantic version (prototype embeddings of skill descriptions +
+ *     cosine vs. query, mixed with keyword score).
+ *
+ * Example host usage (CLI / provider with embeddings already loaded):
+ *   import { createEmbeddingSkillSelector, SkillRegistry } from '@kaleidorg/mind';
+ *   const selector = createEmbeddingSkillSelector(embeddingsProvider);
+ *   const reg = new SkillRegistry(loadedSkills, selector);
+ *
+ * For a production semantic version a host can implement an async select
+ * wrapper around its own Funnel turn or pre-compute skill prototypes.
+ */
+export function createEmbeddingSkillSelector(
+  embeddings?: EmbeddingProvider,
+  _opts: { minCosine?: number; keywordFallback?: boolean } = {},
+): SkillSelector {
+  // Today we return the (already lightly enhanced) keyword selector.
+  // The embeddings parameter and factory exist so hosts have a single
+  // obvious extension point and the public API signals the intent.
+  // A future revision can make SkillSelector support async or add a
+  // separate async entry point if the Funnel routing is made async.
+  void embeddings; // intentionally unused in the current sync impl
+  return keywordSelector;
+}
+
 export class SkillRegistry {
   private readonly skills: Skill[] = [];
   private readonly selector: SkillSelector;