@kaleidorg/mind 0.2.0 → 0.4.0

package/src/qvac/text.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { cleanAssistantVisibleText, sanitizeForSupertonic } from './text.js';
+
+describe('cleanAssistantVisibleText', () => {
+  it('strips a closed <think> block', () => {
+    expect(cleanAssistantVisibleText('<think>plan the answer</think>Your balance is 5k sats.'))
+      .toBe('Your balance is 5k sats.');
+  });
+
+  it('strips an unclosed <think> tail', () => {
+    expect(cleanAssistantVisibleText('Done.<think>still reasoning'))
+      .toBe('Done.');
+  });
+
+  it('drops a leading tool-call prefix and keeps the sentence after it', () => {
+    // The heuristic strips up to `"arguments":` then one `{`. Cleanly recovers
+    // the tail when the model emits the framing without real JSON args.
+    const raw = '{"name":"get_balance","arguments": You have 5,000 sats.';
+    expect(cleanAssistantVisibleText(raw)).toBe('You have 5,000 sats.');
+  });
+
+  it('is lossy when real JSON args follow (known heuristic limit, stray braces remain)', () => {
+    // Documents current behaviour verbatim from rate; a candidate for a future
+    // balanced-brace fix once it can be re-verified on device.
+    const raw = '{"name":"get_balance","arguments":{}} You have 5,000 sats.';
+    expect(cleanAssistantVisibleText(raw)).toBe('}} You have 5,000 sats.');
+  });
+
+  it('collapses whitespace and trims', () => {
+    expect(cleanAssistantVisibleText('  hello   world  ')).toBe('hello world');
+  });
+
+  it('leaves plain text untouched', () => {
+    expect(cleanAssistantVisibleText('Sent 3 EUR to bob.')).toBe('Sent 3 EUR to bob.');
+  });
+});
+
+describe('sanitizeForSupertonic', () => {
+  it('redacts a bolt11 lightning invoice', () => {
+    const out = sanitizeForSupertonic('Pay lnbc1' + 'q'.repeat(60) + ' now');
+    expect(out).toContain('Lightning invoice');
+    expect(out).not.toMatch(/lnbc1q/i);
+  });
+
+  it('redacts an lnurl string', () => {
+    const out = sanitizeForSupertonic('Use lnurl1' + 'a'.repeat(50));
+    expect(out).toContain('Lightning payment link');
+    expect(out).not.toMatch(/lnurl1a/i);
+  });
+
+  it('strips fenced code blocks and inline backticks', () => {
+    const out = sanitizeForSupertonic('Run ```rm -rf``` or `ls` here');
+    expect(out).not.toContain('`');
+    expect(out).toContain('ls');
+  });
+
+  it('removes the backtick character (U+0060) entirely', () => {
+    const out = sanitizeForSupertonic('a`b`c');
+    expect(Array.from(out).some((ch) => ch.charCodeAt(0) === 0x60)).toBe(false);
+  });
+
+  it('normalizes smart quotes to ASCII', () => {
+    const out = sanitizeForSupertonic('“hello” ‘world’');
+    expect(out).toBe('"hello" \'world\'');
+  });
+
+  it('drops non-ASCII and collapses whitespace', () => {
+    expect(sanitizeForSupertonic('café   ✨ ok')).toBe('caf ok');
+  });
+});

package/src/qvac/text.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure text helpers for QVAC output. No SDK, no platform — safe to run and test
+ * anywhere. Lifted verbatim from rate's QVACService so every host shares one
+ * implementation instead of drifting copies.
+ */
+
+/**
+ * Clean a raw assistant completion into user-visible text:
+ *  - drop `<think>…</think>` reasoning (small models leak it into content),
+ *  - drop a leading `{"name":…,"arguments":…}` tool-call object some tiny models
+ *    emit as plain text, keeping any natural-language sentence that follows.
+ */
+export function cleanAssistantVisibleText(text: string): string {
+  let cleaned = text
+    // Qwen-style reasoning sometimes arrives in contentText. Never show/speak it.
+    .replace(/<think\b[\s\S]*?<\/think>/gi, ' ')
+    .replace(/<think\b[\s\S]*$/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // Some small local models emit a tool-call object as plain text. Drop the
+  // leading fragment and keep any natural-language sentence that follows.
+  const toolPrefix = cleaned.match(/^\s*\{?\s*"name"\s*:\s*"[^"]+"\s*,\s*"arguments"\s*:\s*/i);
+  if (toolPrefix) {
+    cleaned = cleaned.slice(toolPrefix[0].length).replace(/^\s*\{?\s*/, '').trim();
+  }
+
+  return cleaned
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Make text safe for the SUPERTONIC TTS model: redact payment strings (so they
+ * are never read aloud), strip markdown/code, normalize smart punctuation, and
+ * drop any non-ASCII or backtick (U+0060) the model can't synthesize.
+ */
+export function sanitizeForSupertonic(text: string): string {
+  const normalized = text
+    .replace(/\b(?:lightning:)?ln(?:bc|tb|bcrt)[a-z0-9]{40,}\b/gi, 'Lightning invoice')
+    .replace(/\blnurl[0-9a-z]{40,}\b/gi, 'Lightning payment link')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/[`´ˋ′*_~#<>|[\]{}]/g, ' ')
+    .replace(/[“”]/g, '"')
+    .replace(/[‘’]/g, "'")
+    .replace(/[•·]/g, '. ')
+    .replace(/[^\x09\x0A\x0D\x20-\x7E]/g, ' ')
+    .replace(/\s+/g, ' ');
+
+  return Array.from(normalized)
+    .filter((ch) => {
+      const code = ch.charCodeAt(0);
+      return (code === 0x09 || code === 0x0A || code === 0x0D || (code >= 0x20 && code <= 0x7E)) &&
+        code !== 0x60;
+    })
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+}

package/src/qvac/voice.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createQvacVoice } from './voice.js';
+
+describe('createQvacVoice.transcribeAudio', () => {
+  it('strips the file:// prefix and passes a plain path to the SDK', async () => {
+    const transcribe = vi.fn(async () => 'hello world');
+    const voice = createQvacVoice({
+      transcribe: transcribe as any,
+      textToSpeech: (() => {}) as any,
+      getWhisperModelId: () => 'whisper-1',
+      getTtsModelId: () => null,
+    });
+    const text = await voice.transcribeAudio('file:///tmp/clip.wav');
+    expect(text).toBe('hello world');
+    expect(transcribe).toHaveBeenCalledWith({ modelId: 'whisper-1', audioChunk: '/tmp/clip.wav' });
+  });
+
+  it('throws when no Whisper model is loaded', async () => {
+    const voice = createQvacVoice({
+      transcribe: (() => { throw new Error('nope'); }) as any,
+      textToSpeech: (() => {}) as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => null,
+    });
+    await expect(voice.transcribeAudio('/tmp/clip.wav')).rejects.toThrow(/not loaded/);
+  });
+});
+
+describe('createQvacVoice.synthesizeSpeech', () => {
+  function ttsReturning(pcm: number[]) {
+    const calls: any[] = [];
+    const fn = (params: any) => {
+      calls.push(params);
+      return { buffer: Promise.resolve(pcm) };
+    };
+    return { fn, calls };
+  }
+
+  it('returns null when no TTS model is loaded', async () => {
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: (() => { throw new Error('should not run'); }) as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => null,
+    });
+    expect(await voice.synthesizeSpeech('hi')).toBeNull();
+  });
+
+  it('returns null when the text is empty after sanitization', async () => {
+    const tts = ttsReturning([1, 2, 3]);
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: tts.fn as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => 'tts-1',
+    });
+    // Only non-ASCII / markup ⇒ sanitizes to empty ⇒ no synthesis attempted.
+    expect(await voice.synthesizeSpeech('✨🎉')).toBeNull();
+    expect(tts.calls).toHaveLength(0);
+  });
+
+  it('redacts payment strings before synthesis and returns PCM + sample rate', async () => {
+    const tts = ttsReturning([10, 20, 30]);
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: tts.fn as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => 'tts-1',
+      ttsSampleRate: 22050,
+    });
+    const out = await voice.synthesizeSpeech('Pay lnbc1' + 'q'.repeat(60) + ' now');
+    expect(out).toEqual({ pcm: [10, 20, 30], sampleRate: 22050 });
+    expect(tts.calls[0].text).toContain('Lightning invoice');
+    expect(tts.calls[0].text).not.toMatch(/lnbc1q/i);
+    expect(tts.calls[0]).toMatchObject({ modelId: 'tts-1', inputType: 'text', stream: false });
+  });
+
+  it('defaults to the SUPERTONIC 44.1 kHz sample rate', async () => {
+    const tts = ttsReturning([1]);
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: tts.fn as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => 'tts-1',
+    });
+    const out = await voice.synthesizeSpeech('Your balance is five thousand sats');
+    expect(out?.sampleRate).toBe(44100);
+  });
+});
+
+describe('createQvacVoice.openVoiceSession', () => {
+  const fakeSession = {
+    write() {},
+    end() {},
+    destroy() {},
+    async *[Symbol.asyncIterator]() {},
+  };
+
+  it('opens a VAD stream with the whisper model + default params', async () => {
+    const calls: any[] = [];
+    const transcribeStream = (p: any) => {
+      calls.push(p);
+      return Promise.resolve(fakeSession);
+    };
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: (() => {}) as any,
+      transcribeStream: transcribeStream as any,
+      getWhisperModelId: () => 'w1',
+      getTtsModelId: () => null,
+    });
+    const session = await voice.openVoiceSession();
+    expect(session).toBe(fakeSession);
+    expect(calls[0]).toMatchObject({ modelId: 'w1', emitVadEvents: true, endOfTurnSilenceMs: 700 });
+  });
+
+  it('merges param overrides over the defaults', async () => {
+    const calls: any[] = [];
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: (() => {}) as any,
+      transcribeStream: ((p: any) => { calls.push(p); return Promise.resolve(fakeSession); }) as any,
+      getWhisperModelId: () => 'w1',
+      getTtsModelId: () => null,
+    });
+    await voice.openVoiceSession({ endOfTurnSilenceMs: 1200 });
+    expect(calls[0].endOfTurnSilenceMs).toBe(1200);
+    expect(calls[0].emitVadEvents).toBe(true);
+  });
+
+  it('throws when transcribeStream was not provided', async () => {
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: (() => {}) as any,
+      getWhisperModelId: () => 'w1',
+      getTtsModelId: () => null,
+    });
+    await expect(voice.openVoiceSession()).rejects.toThrow(/transcribeStream not provided/);
+  });
+
+  it('throws when no Whisper model is loaded', async () => {
+    const voice = createQvacVoice({
+      transcribe: (() => {}) as any,
+      textToSpeech: (() => {}) as any,
+      transcribeStream: (() => Promise.resolve(fakeSession)) as any,
+      getWhisperModelId: () => null,
+      getTtsModelId: () => null,
+    });
+    await expect(voice.openVoiceSession()).rejects.toThrow(/not loaded/);
+  });
+});

package/src/qvac/voice.ts

@@ -0,0 +1,122 @@
+/**
+ * Voice runtime ops shared across hosts: one-shot transcription (Whisper) and
+ * speech synthesis (SUPERTONIC TTS). Like the provider, the SDK functions are
+ * injected (type-only `@qvac/sdk` import, erased at build) so this carries no
+ * runtime SDK dependency and is unit-testable with fakes.
+ *
+ * The host still owns model lifecycle (download, load, local-vs-delegated) and
+ * audio I/O (mic capture, playback). It passes the loaded model-id resolvers;
+ * this module does the SDK calls + the text gating that must be identical
+ * everywhere (payment-string redaction, U+0060 refusal, file:// stripping).
+ *
+ * The streaming voice-assistant loop (transcribeStream + VAD) builds on top of
+ * these in a later pass.
+ */
+import type * as QvacSdk from '@qvac/sdk';
+import { sanitizeForSupertonic } from './text.js';
+import { TTS_SAMPLE_RATE, DEFAULT_VOICE_STREAM_PARAMS } from './config.js';
+import type { VoiceTranscriptEvent } from './assistant.js';
+
+type TranscribeFn = typeof QvacSdk.transcribe;
+type TextToSpeechFn = typeof QvacSdk.textToSpeech;
+type TranscribeStreamFn = typeof QvacSdk.transcribeStream;
+
+/** 16-bit PCM samples plus their sample rate, ready for the host to play. */
+export interface PcmAudio {
+  pcm: number[];
+  sampleRate: number;
+}
+
+/**
+ * A live VAD transcription session: feed mic audio with `write()`, iterate to
+ * receive `text`/`vad`/`endOfTurn` events, `end()` when audio stops. Pass it
+ * straight to `runVoiceAssistant`.
+ */
+export interface VoiceSession {
+  write(audioChunk: Uint8Array): void;
+  end(): void;
+  destroy(): void;
+  [Symbol.asyncIterator](): AsyncIterator<VoiceTranscriptEvent>;
+}
+
+export interface QvacVoiceOptions {
+  /** The SDK's `transcribe` (injected). */
+  transcribe: TranscribeFn;
+  /** The SDK's `textToSpeech` (injected). */
+  textToSpeech: TextToSpeechFn;
+  /** The SDK's `transcribeStream` (injected) — only needed for `openVoiceSession`. */
+  transcribeStream?: TranscribeStreamFn;
+  /** Resolve the loaded Whisper model id (null ⇒ not loaded → throws). */
+  getWhisperModelId: () => string | null;
+  /** Resolve the loaded TTS model id (null ⇒ not loaded → returns null). */
+  getTtsModelId: () => string | null;
+  /** TTS output sample rate; defaults to SUPERTONIC-2's 44.1 kHz. */
+  ttsSampleRate?: number;
+}
+
+export interface QvacVoice {
+  /** Transcribe an audio file (path or `file://` URI) to text. */
+  transcribeAudio(audioUri: string): Promise<string>;
+  /**
+   * Synthesize speech for `text`. Returns PCM + sample rate, or `null` when TTS
+   * is unavailable or the text is empty after sanitization (host falls back to
+   * the system voice). Payment strings are redacted so they're never read aloud.
+   */
+  synthesizeSpeech(text: string): Promise<PcmAudio | null>;
+  /**
+   * Open a hands-free VAD transcription session (continuous voice). Requires
+   * `transcribeStream` to have been provided. Merge in `paramsOverride` to tune
+   * the defaults ({@link DEFAULT_VOICE_STREAM_PARAMS}). Feed the returned session
+   * to `runVoiceAssistant`.
+   */
+  openVoiceSession(paramsOverride?: Record<string, unknown>): Promise<VoiceSession>;
+}
+
+export function createQvacVoice(options: QvacVoiceOptions): QvacVoice {
+  const sampleRate = options.ttsSampleRate ?? TTS_SAMPLE_RATE;
+
+  return {
+    async transcribeAudio(audioUri: string): Promise<string> {
+      const modelId = options.getWhisperModelId();
+      if (!modelId) throw new Error('Whisper model not loaded');
+      // The SDK's native file reader wants a plain filesystem path, not a
+      // `file://` URI — the URI raises AUDIO_FILE_NOT_FOUND even when present.
+      const audioChunk = audioUri.replace('file://', '');
+      return await options.transcribe({ modelId, audioChunk } as Parameters<TranscribeFn>[0]);
+    },
+
+    async synthesizeSpeech(text: string): Promise<PcmAudio | null> {
+      const modelId = options.getTtsModelId();
+      if (!modelId) return null;
+
+      const trimmed = sanitizeForSupertonic(text);
+      if (!trimmed) return null;
+      // Belt-and-suspenders: SUPERTONIC chokes on U+0060; sanitize already
+      // strips it, so refuse if any slipped through rather than crash the voice.
+      if (Array.from(trimmed).some((ch) => ch.charCodeAt(0) === 0x60)) return null;
+
+      const result = options.textToSpeech({
+        modelId,
+        text: trimmed,
+        inputType: 'text',
+        stream: false,
+      } as Parameters<TextToSpeechFn>[0]);
+      const pcm = await result.buffer;
+      return { pcm, sampleRate };
+    },
+
+    async openVoiceSession(paramsOverride: Record<string, unknown> = {}): Promise<VoiceSession> {
+      if (!options.transcribeStream) {
+        throw new Error('transcribeStream not provided — pass it in QvacVoiceOptions for voice sessions');
+      }
+      const modelId = options.getWhisperModelId();
+      if (!modelId) throw new Error('Whisper model not loaded');
+      const session = await options.transcribeStream({
+        modelId,
+        ...DEFAULT_VOICE_STREAM_PARAMS,
+        ...paramsOverride,
+      } as Parameters<TranscribeStreamFn>[0]);
+      return session as unknown as VoiceSession;
+    },
+  };
+}

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);