@kaleidorg/mind 0.2.0 → 0.3.0

package/src/memory/memory.test.ts

@@ -61,6 +61,61 @@ describe('InMemoryMemoryStore', () => {
     const hits = await store.search({ text: 'how many sats do I have', limit: 1 });
     expect(hits[0].text).toMatch(/wallet balance/);
   });
+
+  // Embedding-only dedup: same vector → near-dup → newer supersedes older. No LLM.
+  it('consolidate (dedup): near-duplicates supersede instead of appending', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9 },
+      now: () => ++t,
+    });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'user prefers EUR for fiat display', kind: 'preference' });
+
+    const all = await store.all();
+    expect(all).toHaveLength(1); // folded, not appended
+    expect(all[0].text).toBe('user prefers EUR for fiat display'); // newer wins
+  });
+
+  it('consolidate (dedup): distinct facts are kept separate', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'it is sunny today', kind: 'note' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  it('consolidate (dedup): different kinds are never merged', async () => {
+    const embed = async (): Promise<number[]> => [1, 0]; // identical vectors
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'EUR', kind: 'preference' });
+    await store.add({ text: 'EUR', kind: 'fact' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  // LLM merge: injected merger rewrites old + new into one consolidated item, with unioned tags.
+  it('consolidate (merge): injected merger folds near-dups into one item', async () => {
+    const embed = async (): Promise<number[]> => [1, 0];
+    const merge = vi.fn(async (existing: string, incoming: string) => `${existing}; ${incoming}`);
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9, merge },
+      now: () => ++t,
+    });
+    await store.add({ text: 'likes EUR', kind: 'preference', tags: ['fiat'] });
+    await store.add({ text: 'and CHF', kind: 'preference', tags: ['currency'] });
+
+    expect(merge).toHaveBeenCalledWith('likes EUR', 'and CHF');
+    const all = await store.all();
+    expect(all).toHaveLength(1);
+    expect(all[0].text).toBe('likes EUR; and CHF');
+    expect(all[0].tags).toEqual(['fiat', 'currency']); // unioned
+  });
 });
 
 describe('memory tool source', () => {

package/src/memory/store.ts

@@ -9,6 +9,7 @@
 
 import { cosineSimilarity } from '../rag/vector-store.js';
 import type {
+  MemoryConsolidation,
   MemoryIO,
   MemoryItem,
   MemoryQuery,
@@ -16,11 +17,18 @@ import type {
   NewMemory,
 } from './types.js';
 
+const DEFAULT_DEDUP_THRESHOLD = 0.92;
+
 export interface MemoryStoreOptions {
   /** Persistence (load on first use, save on writes). Omit for ephemeral memory. */
   io?: MemoryIO;
   /** Embed text for semantic recall. Omit to fall back to substring matching. */
   embed?: (text: string) => Promise<number[]>;
+  /**
+   * Fold near-duplicate writes into one item instead of appending. Needs `embed`.
+   * Omit for append-only. See {@link MemoryConsolidation}.
+   */
+  consolidate?: MemoryConsolidation;
   /** Clock — injectable for deterministic tests. */
   now?: () => number;
 }
@@ -31,11 +39,13 @@ export class InMemoryMemoryStore implements MemoryStore {
   private counter = 0;
   private readonly io?: MemoryIO;
   private readonly embed?: (text: string) => Promise<number[]>;
+  private readonly consolidate?: MemoryConsolidation;
   private readonly now: () => number;
 
   constructor(opts: MemoryStoreOptions = {}) {
     this.io = opts.io;
     this.embed = opts.embed;
+    this.consolidate = opts.consolidate;
     this.now = opts.now ?? (() => Date.now());
   }
 
@@ -58,16 +68,45 @@ export class InMemoryMemoryStore implements MemoryStore {
 
   async add(item: NewMemory): Promise<MemoryItem> {
     await this.hydrate();
-    const embedding =
-      item.embedding ?? (this.embed ? await this.embed(item.text).catch(() => undefined) : undefined);
+    let text = item.text;
+    let embedding =
+      item.embedding ?? (this.embed ? await this.embed(text).catch(() => undefined) : undefined);
+    let tags = item.tags;
+    let supersedeId: string | undefined;
+
+    // Consolidation: fold a same-kind near-duplicate into this write instead of
+    // appending — embedding-only by default, LLM rewrite when `merge` is set.
+    if (this.consolidate && embedding) {
+      const threshold = this.consolidate.threshold ?? DEFAULT_DEDUP_THRESHOLD;
+      let best: { item: MemoryItem; score: number } | undefined;
+      for (const m of this.items) {
+        if (m.kind !== item.kind || !m.embedding) continue;
+        const score = cosineSimilarity(embedding, m.embedding);
+        if (!best || score > best.score) best = { item: m, score };
+      }
+      if (best && best.score >= threshold) {
+        supersedeId = best.item.id;
+        tags = unionTags(best.item.tags, item.tags);
+        if (this.consolidate.merge) {
+          const merged = await this.consolidate.merge(best.item.text, text).catch(() => null);
+          if (merged && merged.trim()) {
+            text = merged.trim();
+            if (this.embed) embedding = await this.embed(text).catch(() => embedding);
+          }
+        }
+        // No merger → the incoming (newer) text supersedes the older item as-is.
+      }
+    }
+
     const full: MemoryItem = {
       id: item.id ?? `mem_${this.now()}_${++this.counter}`,
-      text: item.text,
+      text,
       kind: item.kind,
-      tags: item.tags,
+      tags,
       createdAt: item.createdAt ?? this.now(),
       ...(embedding ? { embedding } : {}),
     };
+    if (supersedeId) this.items = this.items.filter((m) => m.id !== supersedeId);
     this.items.push(full);
     await this.persist();
     return full;
@@ -127,3 +166,9 @@ export class InMemoryMemoryStore implements MemoryStore {
     await this.persist();
   }
 }
+
+/** Merge two optional tag lists, de-duplicated. Returns undefined when both empty. */
+function unionTags(a?: string[], b?: string[]): string[] | undefined {
+  if (!a?.length && !b?.length) return undefined;
+  return [...new Set([...(a ?? []), ...(b ?? [])])];
+}

package/src/memory/types.ts

@@ -61,3 +61,16 @@ export interface MemoryIO {
   load(): Promise<MemoryItem[]>;
   save(items: MemoryItem[]): Promise<void>;
 }
+
+/**
+ * Consolidation — fold same-kind near-duplicate memories into one item instead
+ * of bloating with "user likes EUR" ×5. Needs embeddings (the dup check is
+ * cosine). Omit for append-only. Two tiers: embedding-only dedup (zero
+ * inference, mobile-safe) and, when `merge` is set, an LLM rewrite.
+ */
+export interface MemoryConsolidation {
+  /** Cosine threshold above which two same-kind memories are "the same". Default 0.92. */
+  threshold?: number;
+  /** Optional LLM merger; without it the newer item simply supersedes the older. */
+  merge?: (existing: string, incoming: string) => Promise<string>;
+}

package/src/recipe/kaleidoswap-atomic.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../tools/registry.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { LLMProvider } from '../providers/types.js';
+import { runRecipe } from './runner.js';
+import { kaleidoswapAtomicRecipe } from './kaleidoswap-atomic.js';
+
+// LLM provider that should never be called when slots are extracted deterministically.
+const refusingProvider: LLMProvider = {
+  name: 'refusing',
+  runTurn: async () => {
+    throw new Error('provider should NOT be called when extractSwap succeeds');
+  },
+};
+
+// Stub tools that record every call so we can assert the chain ran end-to-end.
+function buildStubs(captured: { name: string; args: any }[]) {
+  const tool = (name: string, response: any, spend = false) => ({
+    name,
+    description: '',
+    parameters: { type: 'object', properties: {} },
+    requiresConfirmation: spend,
+    handler: async (a: any) => {
+      captured.push({ name, args: a });
+      return typeof response === 'function' ? response(a) : response;
+    },
+  });
+  return new ToolRegistry([
+    new InProcessToolSource('kaleidoswap', [
+      tool('kaleidoswap_get_quote', { quote_id: 'q-1', receive_amount: 100, fees: 250 }),
+      tool('kaleidoswap_atomic_init', { atomic_id: 'a-1', maker_invoice: 'lnbc1maker' }, /* spend */ true),
+      tool('kaleidoswap_atomic_execute', { status: 'completed' }, /* spend */ true),
+    ]),
+    new InProcessToolSource('rln', [
+      tool('rln_create_rgb_invoice', { invoice: 'rgb:invoice:USDT:100' }),
+      tool('rln_create_ln_invoice', { invoice: 'lnbc1user' }),
+      tool('rln_pay_invoice', { status: 'SUCCESS', payment_hash: 'h' }, /* spend */ true),
+    ]),
+  ]);
+}
+
+describe('kaleidoswapAtomicRecipe — selection (match + triggers)', () => {
+  it('triggers on explicit atomic-swap phrasings', () => {
+    expect(kaleidoswapAtomicRecipe.match!('atomic swap 100000 sats for usdt')).toBe(true);
+    expect(kaleidoswapAtomicRecipe.match!('trustless swap btc to usdt')).toBe(true);
+    expect(kaleidoswapAtomicRecipe.match!('htlc swap 1000 sats to USDT')).toBe(true);
+  });
+
+  it('does NOT fire on a plain swap (those go to swapRecipe)', () => {
+    expect(kaleidoswapAtomicRecipe.match!('swap 10 usdt for btc')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('exchange 1000 sats for usdt')).toBe(false);
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — RGB receive leg', () => {
+  it('runs quote → rgb_invoice → atomic_init → pay → atomic_execute (one inference)', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100000 sats for usdt', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0); // extractSwap handled it deterministically
+
+    // The chain: quote → rgb_invoice → atomic_init → pay → atomic_execute (5 calls).
+    expect(captured.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'rln_create_rgb_invoice',
+      'kaleidoswap_atomic_init',
+      'rln_pay_invoice',
+      'kaleidoswap_atomic_execute',
+    ]);
+
+    // RGB invoice fed into atomic_init.
+    const init = captured.find((c) => c.name === 'kaleidoswap_atomic_init')!;
+    expect(init.args).toEqual({ quote_id: 'q-1', receive_invoice: 'rgb:invoice:USDT:100' });
+
+    // Maker invoice fed into pay step.
+    const pay = captured.find((c) => c.name === 'rln_pay_invoice')!;
+    expect(pay.args).toEqual({ invoice: 'lnbc1maker' });
+
+    // Final execute carried the atomic id.
+    const exe = captured.find((c) => c.name === 'kaleidoswap_atomic_execute')!;
+    expect(exe.args).toEqual({ atomic_id: 'a-1' });
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — BTC receive leg', () => {
+  it('uses rln_create_ln_invoice (not rgb) when to_asset is BTC', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100 usdt for btc', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(res.status).toBe('done');
+    expect(captured.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'rln_create_ln_invoice',
+      'kaleidoswap_atomic_init',
+      'rln_pay_invoice',
+      'kaleidoswap_atomic_execute',
+    ]);
+    const init = captured.find((c) => c.name === 'kaleidoswap_atomic_init')!;
+    expect(init.args.receive_invoice).toBe('lnbc1user');
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — confirmation gate', () => {
+  it('cancels the chain when the user declines a spend gate', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+    let firstSpendSeen = false;
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100000 sats for usdt', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => {
+        if (firstSpendSeen) return { approved: true };
+        firstSpendSeen = true;
+        return { approved: false, reason: 'user said no' };
+      },
+    });
+
+    expect(res.status).not.toBe('done');
+    // The first spend tool (atomic_init) should NOT have completed successfully —
+    // the chain stops before pay/execute.
+    expect(captured.some((c) => c.name === 'rln_pay_invoice')).toBe(false);
+    expect(captured.some((c) => c.name === 'kaleidoswap_atomic_execute')).toBe(false);
+  });
+});

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/runner.ts

@@ -61,10 +61,22 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
       inferences = ex.inferences;
     }
 
-    // Deterministic steps.
+    // 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);

package/src/skills/registry.ts

@@ -75,6 +75,23 @@ const STOPWORDS = new Set([
   'show', 'tell', 'how', 'much', 'many', 'about', 'into', 'over',
 ]);
 
+/** Escape a string for safe inclusion in a regex. */
+function reEscape(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Match a trigger phrase in the query with WORD BOUNDARIES — so the
+ * `usd` trigger on a wallet skill doesn't fire on `usdt`/`usdc`, and
+ * `cafe` doesn't fire on `cafeteria`. Multi-word triggers ("near me")
+ * still work because spaces are already word boundaries.
+ */
+function triggerMatches(query: string, trigger: string): boolean {
+  const t = trigger.toLowerCase().trim();
+  if (!t) return false;
+  return new RegExp(`\\b${reEscape(t)}\\b`).test(query);
+}
+
 /** Default selector: score by meaningful keyword overlap; triggers weigh most. */
 export const keywordSelector: SkillSelector = {
   select(query, skills) {
@@ -89,8 +106,10 @@ export const keywordSelector: SkillSelector = {
       const hayWords = haystack.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
       let score = 0;
       for (const w of hayWords) if (words.has(w)) score += 1;
-      // Strong boost for an explicit trigger appearing in the query.
-      for (const t of skill.triggers ?? []) if (q.includes(t.toLowerCase())) score += 3;
+      // Strong boost for an explicit trigger appearing in the query — at a
+      // 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;
       if (score > bestScore) {
         bestScore = score;
         best = skill;

package/src/skills/skills.test.ts

@@ -75,6 +75,48 @@ Manage Lightning channels via LSPS1.`);
   });
 });
 
+describe('SkillRegistry selection — trigger word boundaries', () => {
+  // Regression: short triggers must NOT match inside longer words.
+  // Bug observed in the CLI: a wallet skill with `usd` as a trigger was
+  // picked for "what is the quote of usdt to btc" because the old
+  // q.includes("usd") was true for "usdt", outranking the trading skill.
+  const reg = new SkillRegistry();
+  reg.addMarkdown(`---
+name: wallet-fiat
+description: Check the BTC price and convert fiat to sats. Fiat support: usd, eur, gbp.
+triggers: price, eur, usd, gbp
+---
+Wallet — fiat conversion.`);
+  reg.addMarkdown(`---
+name: trading
+description: Quote and execute swaps between BTC, USDT and XAUT on KaleidoSwap.
+triggers: quote, swap, trade, usdt, xaut
+---
+Trading on the maker.`);
+
+  it("doesn't fire the `usd` trigger inside `usdt`", () => {
+    const sel = reg.select('what is the quote of usdt to btc')?.name;
+    expect(sel).toBe('trading'); // not wallet-fiat
+  });
+
+  it('still fires the `usd` trigger when the user actually said `usd`', () => {
+    const sel = reg.select('how many sats is 30 usd')?.name;
+    expect(sel).toBe('wallet-fiat');
+  });
+
+  it("doesn't fire a short trigger inside a longer word — `cafe` not in `cafeteria`", () => {
+    const r2 = new SkillRegistry();
+    r2.addMarkdown(`---
+name: merchants
+description: Find merchants that accept Bitcoin.
+triggers: cafe, restaurant, bar
+---
+Merchant finder.`);
+    expect(r2.select('the cafeteria menu')).toBeNull(); // no match
+    expect(r2.select('any bitcoin cafe nearby')?.name).toBe('merchants');
+  });
+});
+
 describe('parseSkill — real Agent-Skills spec', () => {
   it('unquotes the description, captures metadata, tolerates no tools', () => {
     const s = parseSkill(BITREFILL_SKILL);

package/src/wallet/confirm.test.ts

@@ -0,0 +1,57 @@
+/** Confirm-sheet readback — deterministic, voice-first spend summaries. */
+
+import { describe, it, expect } from 'vitest';
+import { confirmReadback } from './confirm.js';
+
+describe('confirmReadback', () => {
+  it('send_payment: sats + recipient, grouped thousands', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'bob', amount_sats: 4800 } }))
+      .toBe('Send 4,800 sats to bob. Confirm?');
+  });
+
+  it('send_payment: explicit layer is read back', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'bob', amount_sats: 1000000, layer: 'spark' } }))
+      .toBe('Send 1,000,000 sats to bob over Spark. Confirm?');
+  });
+
+  it('send_payment: asset amount when no sats (core router, no layer suffix)', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'alice', asset: 'USDT', amount: 10 } }))
+      .toBe('Send 10 USDT to alice. Confirm?');
+  });
+
+  it('spark_send: layer comes from the tool, address is shortened', () => {
+    const line = confirmReadback({
+      name: 'spark_send',
+      arguments: { amount_sats: 5000, to: 'bc1qabcdef0123456789xyzlongaddress' },
+    });
+    expect(line).toBe('Send 5,000 sats to bc1qab…ress over Spark. Confirm?');
+  });
+
+  it('rln_send_asset: asset + ticker + recipient over RLN', () => {
+    expect(confirmReadback({ name: 'rln_send_asset', arguments: { asset: 'USDT', amount: 10, to: 'bob' } }))
+      .toBe('Send 10 USDT to bob over RLN. Confirm?');
+  });
+
+  it('rln_pay_invoice: invoice shortened, over RLN', () => {
+    const line = confirmReadback({
+      name: 'rln_pay_invoice',
+      arguments: { invoice: 'lnbc1ptestinvoice0123456789abcd' },
+    });
+    expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over RLN. Confirm?');
+  });
+
+  it('execute_swap: from → to with amount', () => {
+    expect(confirmReadback({ name: 'execute_swap', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 0.01 } }))
+      .toBe('Swap 0.01 BTC for USDT. Confirm?');
+  });
+
+  it('returns null for non-spend tools', () => {
+    expect(confirmReadback({ name: 'get_balances', arguments: {} })).toBeNull();
+    expect(confirmReadback({ name: 'resolve_contact', arguments: { name: 'bob' } })).toBeNull();
+  });
+
+  it('short contact names are not truncated; long refs are', () => {
+    expect(confirmReadback({ name: 'arkade_send', arguments: { amount_sats: 100, to: 'mum' } }))
+      .toBe('Send 100 sats to mum over Arkade. Confirm?');
+  });
+});