@kaleidorg/mind 0.5.1 → 0.6.1

package/src/qvac/stream.ts

@@ -27,10 +27,37 @@ export interface StreamHandlers {
   onToken?: (token: string) => void;
   /** The model's `<think>` reasoning, streamed separately. */
   onThinking?: (token: string) => void;
+  /**
+   * Cap the `<think>` reasoning at this many tokens. The cap is on TOKENS, not
+   * wall-clock seconds — tok/s varies by model and hardware, so a time budget is
+   * unreliable; the SDK has no numeric reasoning budget (`reasoning_budget` is
+   * only on/off), so we count thinking tokens and stop the run once they exceed
+   * this. Omit for unlimited reasoning.
+   */
+  maxThinkingTokens?: number;
+  /**
+   * Fires once, the moment the thinking budget is exceeded, so the host can
+   * cancel the in-flight run (the SDK keeps generating otherwise). consumeRun
+   * stops forwarding deltas after this.
+   */
+  onThinkingBudgetExceeded?: () => void;
+  /** Injectable monotonic-ish wall clock for deterministic timing tests. */
+  now?: () => number;
 }
 
 export interface ConsumedTurn extends ParsedTurn {
   requestId: string;
+  /** True when the run was stopped because `<think>` hit `maxThinkingTokens`. */
+  thinkingBudgetExceeded?: boolean;
+  timing: {
+    ttftMs?: number;
+    durationMs: number;
+  };
+}
+
+/** Rough token estimate (~4 chars/token) — same heuristic the context budget uses. */
+function approxTokens(chars: number): number {
+  return Math.ceil(chars / 4);
 }
 
 /**
@@ -42,15 +69,41 @@ export async function consumeRun(
   run: CompletionRunLike,
   handlers: StreamHandlers = {},
 ): Promise<ConsumedTurn> {
+  const now = handlers.now ?? Date.now;
+  const startedAt = now();
+  let firstTokenAt: number | undefined;
   let streamed = '';
+  let thinkingChars = 0;
+  let budgetExceeded = false;
   for await (const event of run.events) {
     if (event.type === 'contentDelta' && typeof event.text === 'string') {
+      if (firstTokenAt === undefined && event.text.length > 0) firstTokenAt = now();
       streamed += event.text;
       handlers.onToken?.(event.text);
     } else if (event.type === 'thinkingDelta' && typeof event.text === 'string') {
+      if (firstTokenAt === undefined && event.text.length > 0) firstTokenAt = now();
       handlers.onThinking?.(event.text);
+      if (handlers.maxThinkingTokens !== undefined && !budgetExceeded) {
+        thinkingChars += event.text.length;
+        if (approxTokens(thinkingChars) >= handlers.maxThinkingTokens) {
+          budgetExceeded = true;
+          handlers.onThinkingBudgetExceeded?.();
+          // Stop forwarding; the host cancels the run, so `final` resolves
+          // (stopReason 'cancelled') with whatever was produced so far.
+          break;
+        }
+      }
     }
   }
   const final = await run.final;
-  return { ...finalToTurn(final, streamed), requestId: run.requestId };
+  const finishedAt = now();
+  return {
+    ...finalToTurn(final, streamed),
+    requestId: run.requestId,
+    thinkingBudgetExceeded: budgetExceeded,
+    timing: {
+      ...(firstTokenAt === undefined ? {} : { ttftMs: Math.max(0, firstTokenAt - startedAt) }),
+      durationMs: Math.max(0, finishedAt - startedAt),
+    },
+  };
 }

package/src/recipe/buy-asset-channel.test.ts

@@ -54,6 +54,11 @@ describe('extractBuyAsset (deterministic Tier-0)', () => {
   it('handles comma grouping in the amount', () => {
     expect(extractBuyAsset('buy 1,000 usdt')).toEqual({ asset: 'USDT', asset_amount: 1000 });
   });
+  it('parses an article/filler between the verb and amount ("buy a 100 usdt channel")', () => {
+    expect(extractBuyAsset('buy a 100 usdt channel')).toEqual({ asset: 'USDT', asset_amount: 100 });
+    expect(extractBuyAsset('get a 100 usdt inbound channel')).toEqual({ asset: 'USDT', asset_amount: 100 });
+    expect(extractBuyAsset('buy and sell 100 usdt')).toBeNull(); // "and" is not filler
+  });
   it('null for a swap (a named source asset ⇒ swap owns it)', () => {
     expect(extractBuyAsset('buy 0.001 btc with usdt')).toBeNull();
     expect(extractBuyAsset('swap 10 usdt for btc')).toBeNull();

package/src/recipe/buy-asset-channel.ts

@@ -48,13 +48,16 @@ const num = (s?: string): number | undefined => {
 /** Thousands separators, locale-independent (deterministic for tests). */
 const commas = (n: number): string => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
 
-/** "buy 100 usdt" / "get me 50 xaut" / "i want 200 usdt" / "purchase 10 xaut". */
+/** "buy 100 usdt" / "get me 50 xaut" / "buy a 100 usdt channel" / "purchase 10 xaut". */
 export function extractBuyAsset(text: string): Record<string, unknown> | null {
   const t = text.trim();
   if (NOT_BUY.test(t) || HAS_SOURCE.test(t)) return null;
   if (!RGB_ASSET.test(t)) return null;
-  // buy/get/want/acquire/purchase [me] <amount> <asset>
-  const m = t.match(/\b(?:buy|get|acquire|want|purchase|onboard|need)\b(?:\s+me)?\s+([\d.,]+)\s*([a-z]+)/i);
+  // buy/get/want/acquire/purchase [me|a|an|some|new]* <amount> <asset>
+  // Filler words (the article in "buy A 100 usdt channel") must not break extraction.
+  const m = t.match(
+    /\b(?:buy|get|acquire|want|purchase|onboard|need)\b(?:\s+(?:me|a|an|some|new)\b)*\s+([\d.,]+)\s*([a-z]+)/i,
+  );
   if (!m) return null;
   const asset = normAsset(m[2]);
   const amount = num(m[1]);

package/src/recipe/flashnet-swap.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { flashnetSwapRecipe } from './flashnet-swap.js';
+
+describe('flashnetSwapRecipe — selection', () => {
+  it('claims swap/buy/sell phrasings with a Flashnet/Spark cue', () => {
+    expect(flashnetSwapRecipe.match!('swap 10000 sats with usdb')).toBe(true);
+    expect(flashnetSwapRecipe.match!('swap 5000 sats to usdb on flashnet')).toBe(true);
+    expect(flashnetSwapRecipe.match!('buy usdb with 1000 sats')).toBe(true);
+    expect(flashnetSwapRecipe.match!('exchange btc for usdb on spark')).toBe(true);
+    expect(flashnetSwapRecipe.match!('sell 5 usdb')).toBe(true);
+  });
+
+  it('does NOT claim RGB swaps (USDT / XAUT belong to kaleidoswap-atomic)', () => {
+    expect(flashnetSwapRecipe.match!('swap 100k sats to usdt')).toBe(false);
+    expect(flashnetSwapRecipe.match!('convert btc to xaut')).toBe(false);
+    expect(flashnetSwapRecipe.match!('sell 10 usdt for sats')).toBe(false);
+  });
+
+  it('does NOT claim a bare swap without a Flashnet/Spark cue', () => {
+    expect(flashnetSwapRecipe.match!('swap 100000 sats')).toBe(false);
+    expect(flashnetSwapRecipe.match!('exchange some bitcoin')).toBe(false);
+  });
+
+  it('does NOT claim commerce / receive / channel phrasings', () => {
+    expect(flashnetSwapRecipe.match!('buy a gift card with btc')).toBe(false);
+    expect(flashnetSwapRecipe.match!('create an invoice for 1000 sats')).toBe(false);
+    expect(flashnetSwapRecipe.match!('buy a usdb channel on flashnet')).toBe(false);
+  });
+
+  it('does NOT claim educational questions', () => {
+    expect(flashnetSwapRecipe.match!('how does a flashnet swap work?')).toBe(false);
+    expect(flashnetSwapRecipe.match!('what is usdb?')).toBe(false);
+    expect(flashnetSwapRecipe.match!('explain flashnet')).toBe(false);
+  });
+});
+
+describe('flashnetSwapRecipe — shape', () => {
+  it('extracts the 4 swap slots', () => {
+    expect(flashnetSwapRecipe.slots.map((s) => s.name).sort()).toEqual([
+      'amount', 'amount_side', 'from_asset', 'to_asset',
+    ]);
+    const required = flashnetSwapRecipe.slots.filter((s) => s.required).map((s) => s.name).sort();
+    expect(required).toEqual(['from_asset', 'to_asset']);
+  });
+
+  it('forces the model to do slot extraction (not the deterministic regex)', () => {
+    expect(flashnetSwapRecipe.forceModelExtract).toBe(true);
+  });
+
+  it('runs the canonical 2-step + final chain (list_pools → simulate → execute)', () => {
+    expect(flashnetSwapRecipe.steps.map((s) => s.tool)).toEqual([
+      'flashnet_list_pools',
+      'flashnet_simulate_swap',
+    ]);
+    expect(flashnetSwapRecipe.final.tool).toBe('flashnet_execute_swap');
+  });
+
+  it('confident only when both assets + amount are extracted', () => {
+    expect(flashnetSwapRecipe.confident!({})).toBe(false);
+    expect(flashnetSwapRecipe.confident!({ from_asset: 'BTC' })).toBe(false);
+    expect(flashnetSwapRecipe.confident!({ from_asset: 'BTC', to_asset: 'USDB' })).toBeFalsy();
+    expect(flashnetSwapRecipe.confident!({ from_asset: 'BTC', to_asset: 'USDB', amount: 1000 })).toBe(true);
+  });
+
+  it('has a recipe-level confirm gate (single approval covers the chain)', () => {
+    expect(typeof flashnetSwapRecipe.confirm).toBe('function');
+  });
+});
+
+describe('flashnetSwapRecipe — direction is LITERAL', () => {
+  it('simulate step uses from_asset as asset_in (the spent leg) by construction', () => {
+    const simStep = flashnetSwapRecipe.steps.find((s) => s.tool === 'flashnet_simulate_swap')!;
+    // Build a minimal ctx as runRecipe would: pools result with a BTC/USDB
+    // pool, slots saying from=BTC, to=USDB, amount=10000. The args function
+    // must put BTC on asset_in and amount=10000 on amount_in — the previous
+    // model-driven inversion bug becomes impossible.
+    const ctx: any = {
+      slots: { from_asset: 'BTC', to_asset: 'USDB', amount: 10000 },
+      results: {
+        pools: {
+          pools: [{
+            pool_id: 'pool-xyz',
+            asset_a_address: '0e6354aaaa', asset_a_symbol: 'USDB',
+            asset_b_address: '020202bbbb', asset_b_symbol: 'BTC',
+          }],
+        },
+      },
+    };
+    const args = simStep.args(ctx) as any;
+    expect(args.pool_id).toBe('pool-xyz');
+    // The pool already stores BTC's address (the SDK constant `020202…`);
+    // the recipe passes it through directly so the adapter doesn't have to
+    // re-resolve the "BTC" ticker.
+    expect(args.asset_in_address).toBe('020202bbbb'); // BTC, from the pool
+    expect(args.asset_out_address).toBe('0e6354aaaa'); // USDB by symbol
+    expect(args.amount_in).toBe('10000');
+  });
+
+  it('execute step computes min_amount_out from the simulated value (not the raw value)', () => {
+    const ctx: any = {
+      slots: { from_asset: 'BTC', to_asset: 'USDB', amount: 10000 },
+      results: {
+        pools: { pools: [{ pool_id: 'p', asset_a_address: 'a', asset_a_symbol: 'USDB', asset_b_address: 'b', asset_b_symbol: 'BTC' }] },
+        sim:   { amount_out: '1472', execution_price: '0.1472' },
+      },
+    };
+    const args = flashnetSwapRecipe.final.args(ctx) as any;
+    // Default 50 bps = 0.5% slippage tolerance → floor(1472 * 0.995) = 1464.
+    expect(args.min_amount_out).toBe('1464');
+    expect(args.max_slippage_bps).toBe(50);
+    // BTC (from_asset) → pool's BTC-side address `b`.
+    expect(args.asset_in_address).toBe('b');
+  });
+});

package/src/recipe/flashnet-swap.ts

@@ -0,0 +1,266 @@
+/**
+ * Built-in "swap on Flashnet" recipe — Spark-native AMM, deterministic chain.
+ *
+ * A Flashnet swap on a small model was fragile when left to the agentic loop:
+ * the model had to discover the pool, get the asset addresses right, pick the
+ * correct simulate DIRECTION (asset_in = what the user spends), compute
+ * `min_amount_out` from slippage tolerance, and then thread all of that into
+ * execute. With Qwen3-1.7B that often produced an inverted simulate (token →
+ * BTC instead of BTC → token), and on the follow-up "yes" the skill context
+ * was lost and the model called `flashnet_simulate_swap({})` with no args.
+ *
+ *   "swap 10000 sats with usdb"
+ *     ↓ 1 model inference (slot extraction: from/to/amount/amount_side)
+ *   flashnet_list_pools           ← discover the right pool deterministically
+ *     ↓
+ *   flashnet_simulate_swap        ← quote (read-only)
+ *     ↓ [ONE confirmation gate — shows the real quote in plain English]
+ *   flashnet_execute_swap         ← settle (the spend)
+ *
+ * The whole chain runs with 1 LLM inference total (slot extraction), same
+ * pattern as `kaleidoswapAtomicRecipe`. The host's `flashnet_list_pools` is
+ * side-agnostic and labels symbols, so picking the right pool from the
+ * extracted asset pair is cheap and reliable.
+ *
+ * Slippage: default `max_slippage_bps = 50` (0.5%). The runner computes
+ * `min_amount_out = floor(amount_out × (1 − bps/10000))` from the simulate
+ * result before execute — never trusts the simulated value as-is.
+ *
+ * Asset taxonomy guard: matches ONLY when a Flashnet cue is present
+ * (flashnet/usdb/spark), so RGB swaps (USDT/XAUT) still go to the
+ * KaleidoSwap atomic recipe. The two recipes are disjoint.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+import { extractSwap } from './swap.js';
+
+// Flashnet cue — same set the kaleidoswap-atomic recipe defers ON, so the
+// two are disjoint by construction.
+const FLASHNET_CUE = /\b(flashnet|usdb|spark)\b/i;
+// Spark-token tickers that imply a Flashnet swap even without "flashnet" in
+// the text. Keep this list small and Spark-specific — never includes RGB
+// assets (USDT, XAUT, gold).
+const SPARK_TOKEN = /\b(usdb)\b/i;
+// Generic swap-intent verbs that pair with an asset name. "buy/sell/get" join
+// the swap intent only when an ASSET is named (so "buy a gift card" doesn't
+// route here — that's bitrefill territory).
+const SWAP_VERB = /\b(swap|exchange|convert|trade)\b/i;
+const BUY_VERB = /\b(buy|sell|get|purchase|acquire)\b/i;
+const ASSET = /\b(btc|bitcoin|sats?|usdb)\b/i;
+const NON_SWAP = /\b(gift\s?card|top-?up|esim|voucher|invoice|address|channel|inbound|liquidity|lsps?\b)\b/i;
+
+const FLASHNET_INTENT = (t: string) => {
+  // Educational questions go to the agentic skill (which can call list_pools
+  // for an honest read).
+  if (/\b(why|how|what|when|explain|tell\s+me|do\s+I\s+need|should\s+I|can\s+I)\b/i.test(t)) return false;
+  // Must have a Flashnet/Spark cue OR name a Spark-native token like USDB,
+  // so this never grabs an RGB swap (those go to kaleidoswap-atomic).
+  if (!FLASHNET_CUE.test(t) && !SPARK_TOKEN.test(t)) return false;
+  if (NON_SWAP.test(t)) return false;
+  if (SWAP_VERB.test(t)) return true;
+  if (BUY_VERB.test(t) && ASSET.test(t)) return true;
+  return false;
+};
+
+// ── Shape helpers (decoupled from the SDK's exact field names; the host
+//    adapter normalizes responses to these). ────────────────────────────────
+interface PoolRow {
+  pool_id: string;
+  asset_a_address: string;
+  asset_b_address: string;
+  asset_a_symbol?: string;
+  asset_b_symbol?: string;
+  curve_type?: string;
+  tvl_asset_b?: string;
+  fee_bps?: number;
+}
+interface ListPoolsResult { pools: PoolRow[]; total_count?: number }
+interface SimulateResult {
+  amount_out?: string;
+  execution_price?: string;
+  price_impact_pct?: string;
+  fee_paid_asset_in?: string;
+  warning?: string;
+}
+interface ExecuteResult {
+  accepted?: boolean;
+  request_id?: string;
+  amount_out?: string;
+  execution_price?: string;
+}
+
+/**
+ * Resolve the asset address pair from a pool row + the user's requested
+ * (from_asset, to_asset) symbols. The pool stores ONE order (typically the
+ * non-BTC token on side A, BTC on side B), but the user can phrase the swap
+ * either direction.
+ *
+ * Strategy — deduce the unknown side from the known one:
+ *   1. Match each leg to a pool side by symbol or by the BTC-ticker family.
+ *   2. If one leg resolves to a side, the other leg MUST be the opposite side
+ *      (a pool only has two assets). This is the case that prevented an
+ *      earlier "asset_in == asset_out" bug on regtest, where the non-BTC
+ *      side carries no symbol.
+ *   3. Only as a last resort fall back to the "BTC on side B, token on side
+ *      A" default — true for almost every regtest pool we've seen.
+ */
+function isBtcTicker(s: string): boolean {
+  return s === 'BTC' || s === 'SATS' || s === 'BITCOIN';
+}
+
+function resolveLegAddresses(pool: PoolRow, from: string, to: string): { fromAddr: string; toAddr: string } {
+  const f = (from ?? '').toUpperCase();
+  const t = (to ?? '').toUpperCase();
+  const aSym = (pool.asset_a_symbol ?? '').toUpperCase();
+  const bSym = (pool.asset_b_symbol ?? '').toUpperCase();
+
+  // Which side (if any) does each leg map to?
+  const sideOf = (sym: string): 'a' | 'b' | undefined => {
+    if (sym === aSym && aSym) return 'a';
+    if (sym === bSym && bSym) return 'b';
+    return undefined;
+  };
+
+  let fSide = sideOf(f);
+  let tSide = sideOf(t);
+
+  // 2. Deduce the unknown side from the known one.
+  if (!fSide && tSide) fSide = tSide === 'a' ? 'b' : 'a';
+  if (!tSide && fSide) tSide = fSide === 'a' ? 'b' : 'a';
+
+  // 3. Last-resort default — only when NEITHER side resolved. BTC on side B
+  //    is the canonical layout for the Spark/Flashnet pools we've observed.
+  if (!fSide && !tSide) {
+    fSide = isBtcTicker(f) ? 'b' : 'a';
+    tSide = fSide === 'a' ? 'b' : 'a';
+  }
+
+  const addr = (side: 'a' | 'b'): string => (side === 'a' ? pool.asset_a_address : pool.asset_b_address);
+  return { fromAddr: addr(fSide!), toAddr: addr(tSide!) };
+}
+
+/** Compute min_amount_out = floor(amount_out × (1 − bps/10000)). String-safe. */
+function computeMinAmountOut(amountOut: string | undefined, slippageBps: number): string {
+  if (!amountOut) return '0';
+  try {
+    const out = BigInt(String(amountOut).replace(/[^\d]/g, ''));
+    const num = BigInt(10_000 - Math.max(0, Math.min(5_000, slippageBps)));
+    const min = (out * num) / 10_000n;
+    return min.toString();
+  } catch {
+    return '0';
+  }
+}
+
+const DEFAULT_SLIPPAGE_BPS = 50;
+
+export const flashnetSwapRecipe: Recipe = {
+  name: 'flashnet-swap',
+  description:
+    "Swap on Flashnet (Spark-native AMM): list pool → simulate → confirm once → execute. The user's Spark wallet IS the swap account.",
+  match: (t) => FLASHNET_INTENT(t),
+  triggers: ['flashnet', 'usdb', 'swap', 'exchange', 'convert', 'trade'],
+  slots: [
+    { name: 'from_asset', type: 'string', description: 'Asset the user SPENDS (BTC / USDB). "swap 10000 sats with usdb" → from_asset=BTC. "sell 1 usdb" → from_asset=USDB.', required: true },
+    { name: 'to_asset',   type: 'string', description: 'Asset the user GETS (BTC / USDB). "swap 10000 sats with usdb" → to_asset=USDB. "buy USDB with sats" → to_asset=USDB.', required: true },
+    { name: 'amount',     type: 'number', description: 'The numeric amount the user named. e.g. "swap 10000 sats with usdb" → amount=10000. Always in the asset on `amount_side`.' },
+    { name: 'amount_side', type: 'string', description: "Which leg the amount is denominated in: 'from' (the spent asset) or 'to' (the received asset). Default 'from'. 'buy 10 usdb with sats' → 'to'." },
+  ],
+  // extractSwap is the same regex extractor the KaleidoSwap atomic recipe
+  // uses; it returns {from_asset, to_asset, amount, amount_side?}. With
+  // forceModelExtract=true the runner ignores the det result and always asks
+  // the model — but the det extraction still feeds the Funnel's pre-filter so
+  // bare "buy/sell" with a Spark asset routes here even before the model runs.
+  extract: extractSwap,
+  forceModelExtract: true,
+  confident: (s) => !!s.from_asset && !!s.to_asset && !!s.amount,
+  steps: [
+    // 1. Discover the pool. Side-agnostic on the host side; one row is enough.
+    {
+      tool: 'flashnet_list_pools',
+      as: 'pools',
+      args: (ctx) => ({
+        asset_a: String(ctx.slots.from_asset ?? '').toUpperCase(),
+        asset_b: String(ctx.slots.to_asset ?? '').toUpperCase(),
+        sort: 'TVL_DESC',
+        limit: 5,
+      }),
+    },
+    // 2. Quote the swap. Direction is LITERAL: asset_in = what the user
+    //    spends (`from_asset`), asset_out = what they get (`to_asset`). The
+    //    runner — not the model — assembles this, so the inverted-direction
+    //    bug is impossible by construction.
+    {
+      tool: 'flashnet_simulate_swap',
+      as: 'sim',
+      args: (ctx) => {
+        const r = ctx.results.pools as ListPoolsResult | undefined;
+        const pool = r?.pools?.[0];
+        if (!pool) throw new Error(`No Flashnet pool found for ${ctx.slots.from_asset} ↔ ${ctx.slots.to_asset}.`);
+        const { fromAddr, toAddr } = resolveLegAddresses(pool, String(ctx.slots.from_asset ?? ''), String(ctx.slots.to_asset ?? ''));
+        return {
+          pool_id: pool.pool_id,
+          asset_in_address: fromAddr,
+          asset_out_address: toAddr,
+          amount_in: String(ctx.slots.amount ?? ''),
+        };
+      },
+    },
+  ],
+  // 3. Settle. Confirmation-gated at the recipe level (see runner.ts).
+  //    min_amount_out is computed here — never the raw simulated value — so a
+  //    moving pool can't fill at a worse price than `slippage_bps` allows.
+  final: {
+    tool: 'flashnet_execute_swap',
+    as: 'exec',
+    args: (ctx) => {
+      const r = ctx.results.pools as ListPoolsResult | undefined;
+      const pool = r?.pools?.[0];
+      const sim = ctx.results.sim as SimulateResult | undefined;
+      if (!pool || !sim) throw new Error('Flashnet swap: missing pool or simulation result.');
+      const { fromAddr, toAddr } = resolveLegAddresses(pool, String(ctx.slots.from_asset ?? ''), String(ctx.slots.to_asset ?? ''));
+      return {
+        pool_id: pool.pool_id,
+        asset_in_address: fromAddr,
+        asset_out_address: toAddr,
+        amount_in: String(ctx.slots.amount ?? ''),
+        min_amount_out: computeMinAmountOut(sim.amount_out, DEFAULT_SLIPPAGE_BPS),
+        max_slippage_bps: DEFAULT_SLIPPAGE_BPS,
+      };
+    },
+  },
+  // ONE confirmation, fired after simulate / before execute, with real numbers.
+  confirm: (ctx: RecipeContext) => {
+    const sim = ctx.results.sim as SimulateResult | undefined;
+    const from = fmtAmount(ctx.slots.amount, String(ctx.slots.from_asset ?? ''));
+    const to = fmtAmount(sim?.amount_out, String(ctx.slots.to_asset ?? ''));
+    const impact = sim?.price_impact_pct ? ` · ${sim.price_impact_pct} price impact` : '';
+    const warn = sim?.warning ? ` · ${sim.warning}` : '';
+    return `Swap ${from} → ~${to} on Flashnet (slippage cap ${DEFAULT_SLIPPAGE_BPS / 100}%)${impact}${warn}. Proceed?`;
+  },
+  summary: (ctx) => {
+    const sim = ctx.results.sim as SimulateResult | undefined;
+    const exec = ctx.results.exec as ExecuteResult | undefined;
+    const from = fmtAmount(ctx.slots.amount, String(ctx.slots.from_asset ?? ''));
+    const got = fmtAmount(exec?.amount_out ?? sim?.amount_out, String(ctx.slots.to_asset ?? ''));
+    if (exec?.accepted === false) {
+      return `Flashnet swap rejected: ${(exec as any)?.error ?? 'unknown error'}.`;
+    }
+    return `Flashnet swap submitted: ${from} → ${got}. request_id=${exec?.request_id ?? '?'}.`;
+  },
+};
+
+/**
+ * Format an amount + asset for user display. BTC is rendered as "X,XXX sats"
+ * (BTC is the asset, sats is the unit; the on-the-wire amount is already in
+ * sats so no conversion is needed). Anything else is rendered as
+ * "N TICKER" with thousand-separators.
+ */
+function fmtAmount(amount: unknown, asset: string): string {
+  const t = (asset ?? '').toUpperCase();
+  const n = Number(amount);
+  if (!Number.isFinite(n)) return `${amount ?? '?'} ${t}`;
+  const sep = n.toLocaleString('en-US');
+  if (t === 'BTC' || t === 'SATS' || t === 'BITCOIN') return `${sep} sats`;
+  return `${sep} ${t}`;
+}

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

@@ -44,7 +44,7 @@ function buildStubs(captured: { name: string; args: any }[]) {
     ]),
     new InProcessToolSource('rln', [
       tool('rln_get_node_info', { pubkey: '03c31dae' }),
-      tool('rln_whitelist_swap', { ok: true }, /* spend */ true),
+      tool('rln_atomic_taker', { ok: true }, /* spend */ true),
     ]),
   ]);
 }
@@ -66,6 +66,27 @@ describe('kaleidoswapAtomicRecipe — selection', () => {
   it('does not trigger on a balance question', () => {
     expect(kaleidoswapAtomicRecipe.match!('what is my balance')).toBe(false);
   });
+  it('DEFERS to Flashnet when a Flashnet/Spark cue is present (venue split)', () => {
+    // These belong to the agentic flashnet-swaps skill, not the KaleidoSwap
+    // maker recipe — so the recipe must NOT claim them.
+    expect(kaleidoswapAtomicRecipe.match!('swap 10000 sats with asset of your choice in flashnet')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('swap 5000 sats to usdb')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('swap btc to usdb on spark')).toBe(false);
+  });
+  it('does NOT claim a bare swap with no venue/asset cue (falls to agentic)', () => {
+    // Ambiguous — a swap always needs a target asset; let the skill tier ask
+    // or pick the connected venue rather than grabbing it for the maker.
+    expect(kaleidoswapAtomicRecipe.match!('swap 100000 sats')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('exchange some bitcoin')).toBe(false);
+  });
+  it('still claims swaps that name an RGB/maker asset', () => {
+    expect(kaleidoswapAtomicRecipe.match!('swap 100000 sats to usdt')).toBe(true);
+    expect(kaleidoswapAtomicRecipe.match!('convert btc to xaut')).toBe(true);
+  });
+  it('does not turn portfolio review or explicit no-trade language into a swap', () => {
+    expect(kaleidoswapAtomicRecipe.match!('review my portfolio allocation but do not trade')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('analyze my holdings without trading')).toBe(false);
+  });
 });
 
 describe('kaleidoswapAtomicRecipe — forceModelExtract (less deterministic slot parsing)', () => {
@@ -130,7 +151,7 @@ describe('kaleidoswapAtomicRecipe — full chain', () => {
       'kaleidoswap_get_quote',
       'kaleidoswap_atomic_init',
       'rln_get_node_info',
-      'rln_whitelist_swap',
+      'rln_atomic_taker',
       'kaleidoswap_atomic_execute',
     ]);
   });
@@ -157,7 +178,7 @@ describe('kaleidoswapAtomicRecipe — full chain', () => {
       provider: refusingProvider, tools, onConfirm: async () => ({ approved: true }),
       slots: { from_asset: 'USDT', to_asset: 'BTC', amount: 10, amount_side: 'from' },
     });
-    const whitelist = captured.find((c) => c.name === 'rln_whitelist_swap')!;
+    const whitelist = captured.find((c) => c.name === 'rln_atomic_taker')!;
     expect(whitelist.args).toEqual({ swapstring: 'SWAP/abc/def' });
     const exe = captured.find((c) => c.name === 'kaleidoswap_atomic_execute')!;
     expect(exe.args).toEqual({

package/src/recipe/kaleidoswap-atomic.ts

@@ -12,7 +12,7 @@
  *     ↓ [ONE confirmation gate — shows the real quote numbers]
  *   kaleidoswap_atomic_init      ← MAKER  locks the swap → swapstring, payment_hash
  *   rln_get_node_info            ← NODE   read pubkey (= taker_pubkey)
- *   rln_whitelist_swap           ← NODE   accept the swapstring
+ *   rln_atomic_taker             ← NODE   whitelist the swapstring (taker accepts)
  *   kaleidoswap_atomic_execute   ← MAKER  settle (final)
  *
  * `forceModelExtract` ensures the model is always consulted for slot parsing
@@ -34,23 +34,38 @@
 import type { Recipe, RecipeContext } from './types.js';
 import { extractSwap } from './swap.js';
 
-// Fire on swap intent — "swap/exchange/convert/trade", or "buy/sell/get" when a
-// crypto asset is named (so "buy one usdt" routes here, but "buy a gift card"
-// does not). PRICE / rate / "how much" questions are read-only and go to
-// `kaleidoswapPriceRecipe` instead — keep them out of this match.
-const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+// KaleidoSwap is a BTC↔RGB ATOMIC swap venue (maker + RLN node). It is NOT the
+// only swap venue anymore — Flashnet (Spark-native AMM, BTC↔Spark tokens like
+// USDB) is a sibling, handled by the agentic `flashnet-swaps` skill. The Funnel
+// runs recipes BEFORE skills, so a greedy "any swap word" match here would
+// monopolize every swap and starve Flashnet. To let both coexist, this recipe
+// only claims swaps that point at ITS venue:
+//   - names an RGB/maker asset or the venue itself (RGB_CUE), AND
+//   - does NOT name a Flashnet/Spark cue (FLASHNET_CUE → defer to the skill).
+// A bare "swap" with no venue cue falls through to the agentic tier, where the
+// skill selector disambiguates (or the model asks).
+const RGB_CUE = /\b(usdt|tether|xaut|gold|rgb|kaleidoswap|kaleido|atomic)\b/i;
+const FLASHNET_CUE = /\b(flashnet|usdb|spark)\b/i;
 const SWAP_INTENT = (t: string) => {
   // Explanatory / educational questions → route to RAG-backed agentic answer,
   // not the deterministic spend chain.
   if (/\b(why|how|what|when|explain|tell\s+me|do\s+I\s+need|should\s+I|can\s+I)\b/i.test(t)) return false;
-  if (/\b(swap|exchange|convert|trade)\b/i.test(t)) return true;
-  if (
+  // Flashnet owns its venue — defer to the flashnet-swaps skill.
+  if (FLASHNET_CUE.test(t)) return false;
+  // Portfolio analysis belongs to the portfolio skill, which reads balances
+  // and targets before suggesting any action. A mention of "trade" in a review
+  // request—especially "do not trade"—must never become an immediate swap.
+  if (/\b(portfolio|allocation|holdings|rebalance|rebalancing)\b/i.test(t)) return false;
+  if (/\b(?:do\s+not|don't|without|no)\s+(?:place\s+(?:a\s+)?)?(?:trade|swap|buy|sell|trading)\b/i.test(t)) return false;
+  const swapVerb = /\b(swap|exchange|convert|trade)\b/i.test(t);
+  const buyVerb =
     /\b(buy|sell|get|purchase|acquire)\b/i.test(t) &&
-    ASSET.test(t) &&
     // Exclude commerce / receive / LSPS1 channel-order phrasings that share
     // the buy/get verb. "Buy a USDT channel" is a channel order, not a swap.
-    !/\b(gift\s?card|top-?up|esim|voucher|invoice|address|channel|inbound|liquidity|lsps?\b)\b/i.test(t)
-  ) return true;
+    !/\b(gift\s?card|top-?up|esim|voucher|invoice|address|channel|inbound|liquidity|lsps?\b)\b/i.test(t);
+  // Only claim the swap when an RGB/maker asset (or the venue) is named, so a
+  // bare/ambiguous "swap" or a Flashnet-asset swap doesn't get grabbed here.
+  if (swapVerb || buyVerb) return RGB_CUE.test(t);
   return false;
 };
 
@@ -62,7 +77,7 @@ interface QuoteResult {
   to_amount_display?: string;
   fee_display?: string;
 }
-interface InitResult { swapstring?: string; payment_hash?: string }
+interface InitResult { swapstring?: string; payment_hash?: string; atomic_id?: string }
 interface NodeInfo { pubkey?: string }
 
 export const kaleidoswapAtomicRecipe: Recipe = {
@@ -72,10 +87,10 @@ export const kaleidoswapAtomicRecipe: Recipe = {
   match: (t) => SWAP_INTENT(t),
   triggers: ['swap', 'exchange', 'convert', 'trade', 'buy', 'sell'],
   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: 'The amount the user named' },
-    { name: 'amount_side', type: 'string', description: "Which leg the amount is on: 'from' (sell/swap) or 'to' (buy)" },
+    { name: 'from_asset', type: 'string', description: 'Asset to spend (BTC / USDT / XAUT). Example: "swap 10 usdt to btc" → from_asset=USDT', required: true },
+    { name: 'to_asset', type: 'string', description: 'Asset to receive (BTC / USDT / XAUT). Example: "buy 1 usdt" → to_asset=USDT', required: true },
+    { name: 'amount', type: 'number', description: 'The amount the user named (in from_asset units for sell, to_asset for buy). E.g. "buy 1 usdt" amount=1; "swap 100000 sats" amount=100000' },
+    { name: 'amount_side', type: 'string', description: "Which leg the amount is on: 'from' (sell/swap) or 'to' (buy). Use examples in descriptions and 'buy X Y' means to_asset." },
   ],
   // Keep the fast `extract` for the Funnel's cheap pre-filter (so "buy 1 usdt"
   // reliably enters the recipe branch instead of falling to free agentic).
@@ -122,10 +137,11 @@ export const kaleidoswapAtomicRecipe: Recipe = {
       as: 'node',
       args: () => ({}),
     },
-    // 4. NODE: whitelist the maker's swapstring (accept the swap). Ungated —
-    //    covered by the single confirm above.
+    // 4. NODE: the taker whitelists the maker's swapstring (accept the swap).
+    //    Exposed by kaleido-mcp as `rln_atomic_taker` (calls rln.whitelistSwap).
+    //    Ungated — covered by the single confirm above.
     {
-      tool: 'rln_whitelist_swap',
+      tool: 'rln_atomic_taker',
       as: 'whitelist',
       args: (ctx) => {
         const init = ctx.results.init as InitResult | undefined;
@@ -158,6 +174,9 @@ export const kaleidoswapAtomicRecipe: Recipe = {
     const q = ctx.results.quote as QuoteResult | undefined;
     const from = q?.from_amount_display ?? `${ctx.slots.amount} ${ctx.slots.from_asset}`;
     const to = q?.to_amount_display ?? String(ctx.slots.to_asset);
-    return `Swap submitted: ${from} → ${to}. Settling now — ask me to check the status.`;
+    const init = ctx.results.init as InitResult | undefined;
+    const id = init?.atomic_id || init?.payment_hash || '?';
+    return `remember: atomic swap atomic_id=${id} (for later kaleidoswap_atomic_status checks).
+Swap submitted: ${from} → ${to}. To check status later, call: kaleidoswap_atomic_status(atomic_id=${id}). Say "check my swap status" and I will recall + poll automatically.`;
   },
 };