@kaleidorg/mind 0.6.0 → 0.6.2

package/src/qvac/provider.ts

@@ -17,7 +17,7 @@
  * delegated to a desktop peer.
  */
 import type * as QvacSdk from '@qvac/sdk';
-import type { LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
+import type { InferenceMetrics, LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
 import type { QvacTurnStats } from './parse.js';
 import { consumeRun } from './stream.js';
 
@@ -138,12 +138,36 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
       // instead of an empty bubble so the agentic loop ends cleanly.
       const text =
         result.text || (result.thinkingBudgetExceeded ? THINKING_BUDGET_FALLBACK : result.text);
+      const totalTokens = result.stats?.totalTokens;
+      const promptTokens = result.stats?.promptTokens;
+      const inference: InferenceMetrics = {
+        requestId: result.requestId,
+        durationMs: result.timing.durationMs,
+        status:
+          result.stopReason === 'cancelled'
+            ? 'cancelled'
+            : result.truncated
+              ? 'truncated'
+              : 'completed',
+        ...(result.stats?.backendDevice ? { backendDevice: result.stats.backendDevice } : {}),
+        ...(typeof promptTokens === 'number' ? { promptTokens } : {}),
+        ...(typeof totalTokens === 'number' ? { totalTokens } : {}),
+        ...(typeof totalTokens === 'number' && typeof promptTokens === 'number'
+          ? { completionTokens: Math.max(0, totalTokens - promptTokens) }
+          : {}),
+        ...(typeof result.timing.ttftMs === 'number' ? { ttftMs: result.timing.ttftMs } : {}),
+        ...(typeof result.stats?.tokensPerSecond === 'number'
+          ? { tokensPerSecond: result.stats.tokensPerSecond }
+          : {}),
+        ...(result.stopReason ? { stopReason: result.stopReason } : {}),
+      };
 
       return {
         text,
         rawContent: result.rawContent,
         toolCalls: result.toolCalls,
         requestId: result.requestId,
+        inference,
       };
     },
 

package/src/qvac/stream.test.ts

@@ -101,4 +101,15 @@ describe('consumeRun', () => {
     await consumeRun(run, { onToken: (t) => tokens.push(t) });
     expect(tokens).toEqual(['hi']);
   });
+
+  it('measures first-token and total completion timing', async () => {
+    const ticks = [100, 145, 190];
+    const out = await consumeRun(
+      fakeRun([{ type: 'thinkingDelta', text: 'plan' }, { type: 'contentDelta', text: 'answer' }], {
+        contentText: 'answer',
+      }),
+      { now: () => ticks.shift() ?? 190 },
+    );
+    expect(out.timing).toEqual({ ttftMs: 45, durationMs: 90 });
+  });
 });

package/src/qvac/stream.ts

@@ -41,12 +41,18 @@ export interface StreamHandlers {
    * 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. */
@@ -63,14 +69,19 @@ 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;
@@ -85,9 +96,14 @@ export async function consumeRun(
     }
   }
   const final = await run.final;
+  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/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

@@ -31,12 +31,12 @@ function buildStubs(captured: { name: string; args: any }[]) {
   });
   return new ToolRegistry([
     new InProcessToolSource('kaleidoswap', [
+      // Mirror the REAL kaleido-mcp `kaleidoswap_get_quote` response: each leg
+      // echoes asset_id + ticker + layer + amount_raw (integer) + amount_display.
       tool('kaleidoswap_get_quote', {
         rfq_id: 'rfq-1',
-        from_asset: { asset_id: 'USDT', ticker: 'USDT', amount: 10_000_000 },
-        to_asset: { asset_id: 'BTC', ticker: 'BTC', amount: 15_250_000 },
-        from_amount_display: '10 USDT',
-        to_amount_display: '15,250 sats',
+        from_asset: { asset_id: 'USDT', ticker: 'USDT', layer: 'RGB_LN', amount_raw: 10_000_000, amount_display: '10' },
+        to_asset: { asset_id: 'BTC', ticker: 'BTC', layer: 'BTC_LN', amount_raw: 15_250_000, amount_display: '15,250 sats' },
         fee_display: '154 sats',
       }),
       tool('kaleidoswap_atomic_init', { swapstring: 'SWAP/abc/def', payment_hash: 'ph-1' }, /* 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)', () => {
@@ -145,8 +166,33 @@ describe('kaleidoswapAtomicRecipe — full chain', () => {
     const init = captured.find((c) => c.name === 'kaleidoswap_atomic_init')!;
     expect(init.args).toEqual({
       rfq_id: 'rfq-1',
-      from_asset: 'USDT', from_amount: 10_000_000,
-      to_asset: 'BTC', to_amount: 15_250_000,
+      from_asset_id: 'USDT', from_amount_raw: 10_000_000,
+      to_asset_id: 'BTC', to_amount_raw: 15_250_000,
+    });
+  });
+
+  it('builds get_quote args matching the kaleido-mcp schema (sell vs buy leg)', async () => {
+    // The reported bug: the recipe must emit the MCP tool's field names
+    // (from_asset_id/to_asset_id/from_layer/to_layer) and put the amount on the
+    // correct leg — to_amount for "buy 1 usdt", from_amount for a sell/swap.
+    const sell: { name: string; args: any }[] = [];
+    await runRecipe(kaleidoswapAtomicRecipe, 'swap 10 usdt to btc', {
+      provider: refusingProvider, tools: buildStubs(sell), onConfirm: async () => ({ approved: true }),
+      slots: { from_asset: 'USDT', to_asset: 'BTC', amount: 10, amount_side: 'from' },
+    });
+    expect(sell.find((c) => c.name === 'kaleidoswap_get_quote')!.args).toEqual({
+      from_asset_id: 'USDT', to_asset_id: 'BTC',
+      from_layer: 'RGB_LN', to_layer: 'BTC_LN', from_amount: 10,
+    });
+
+    const buy: { name: string; args: any }[] = [];
+    await runRecipe(kaleidoswapAtomicRecipe, 'buy 1 usdt', {
+      provider: refusingProvider, tools: buildStubs(buy), onConfirm: async () => ({ approved: true }),
+      slots: { from_asset: 'BTC', to_asset: 'USDT', amount: 1, amount_side: 'to' },
+    });
+    expect(buy.find((c) => c.name === 'kaleidoswap_get_quote')!.args).toEqual({
+      from_asset_id: 'BTC', to_asset_id: 'USDT',
+      from_layer: 'BTC_LN', to_layer: 'RGB_LN', to_amount: 1,
     });
   });