@kaleidorg/mind 0.6.0 → 0.6.2

package/src/recipe/kaleidoswap-atomic.ts

@@ -34,35 +34,62 @@
 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;
 };
 
 interface QuoteResult {
   rfq_id?: string;
-  from_asset?: { asset_id?: string; ticker?: string; amount?: number };
-  to_asset?: { asset_id?: string; ticker?: string; amount?: number };
+  // kaleido-mcp `kaleidoswap_get_quote` echoes each leg with the resolved
+  // asset_id, ticker, layer, the raw integer amount (amount_raw) and a display string.
+  from_asset?: { asset_id?: string; ticker?: string; amount_raw?: number; amount_display?: string };
+  to_asset?: { asset_id?: string; ticker?: string; amount_raw?: number; amount_display?: string };
   from_amount_display?: string;
   to_amount_display?: string;
   fee_display?: string;
 }
-interface InitResult { swapstring?: string; payment_hash?: string }
+
+// KaleidoSwap atomic is a BTC ↔ RGB venue: BTC settles on Lightning, RGB
+// assets on RGB-over-Lightning. The maker/MCP layer is derived from the asset.
+const layerFor = (asset: unknown): string =>
+  /^btc$/i.test(String(asset)) ? 'BTC_LN' : 'RGB_LN';
+
+// Render a quote leg as "<amount> <TICKER>" from the MCP quote echo, or undefined
+// if the leg is missing (callers fall back to the user's slot values).
+const quoteLeg = (leg?: { ticker?: string; amount_display?: string }): string | undefined =>
+  leg?.amount_display != null ? `${leg.amount_display}${leg.ticker ? ` ${leg.ticker}` : ''}` : undefined;
+interface InitResult { swapstring?: string; payment_hash?: string; atomic_id?: string }
 interface NodeInfo { pubkey?: string }
 
 export const kaleidoswapAtomicRecipe: Recipe = {
@@ -72,10 +99,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).
@@ -90,14 +117,21 @@ export const kaleidoswapAtomicRecipe: Recipe = {
     {
       tool: 'kaleidoswap_get_quote',
       as: 'quote',
-      args: (ctx) => ({
-        from_asset: ctx.slots.from_asset,
-        to_asset: ctx.slots.to_asset,
-        amount: ctx.slots.amount,
-        // 'to' for buy ("buy 1 USDT" → amount is what you RECEIVE); default
-        // 'from' for sell/swap. The host puts the amount on the right leg.
-        amount_side: ctx.slots.amount_side ?? 'from',
-      }),
+      args: (ctx) => {
+        // 'to' for buy ("buy 1 USDT" → amount is what you RECEIVE) goes on the
+        // to_amount leg; 'from' (sell/swap) goes on from_amount. Layers are
+        // derived from the asset. Exactly one amount leg is set.
+        const side = ctx.slots.amount_side ?? 'from';
+        const base = {
+          from_asset_id: ctx.slots.from_asset,
+          to_asset_id: ctx.slots.to_asset,
+          from_layer: layerFor(ctx.slots.from_asset),
+          to_layer: layerFor(ctx.slots.to_asset),
+        };
+        return side === 'to'
+          ? { ...base, to_amount: ctx.slots.amount }
+          : { ...base, from_amount: ctx.slots.amount };
+      },
     },
     // 2. MAKER locks the swap. SwapRequest is flat (asset ids + maker-unit
     //    amounts) — sourced straight from the quote result, no re-scaling.
@@ -109,10 +143,10 @@ export const kaleidoswapAtomicRecipe: Recipe = {
         const q = ctx.results.quote as QuoteResult | undefined;
         return {
           rfq_id: q?.rfq_id,
-          from_asset: q?.from_asset?.asset_id,
-          from_amount: q?.from_asset?.amount,
-          to_asset: q?.to_asset?.asset_id,
-          to_amount: q?.to_asset?.amount,
+          from_asset_id: q?.from_asset?.asset_id,
+          from_amount_raw: q?.from_asset?.amount_raw,
+          to_asset_id: q?.to_asset?.asset_id,
+          to_amount_raw: q?.to_asset?.amount_raw,
         };
       },
     },
@@ -150,15 +184,18 @@ export const kaleidoswapAtomicRecipe: Recipe = {
   // ONE confirmation, fired after the quote / before init, with the real numbers.
   confirm: (ctx: RecipeContext) => {
     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);
+    const from = quoteLeg(q?.from_asset) ?? `${ctx.slots.amount} ${ctx.slots.from_asset}`;
+    const to = quoteLeg(q?.to_asset) ?? String(ctx.slots.to_asset);
     const fee = q?.fee_display ? ` · fee ${q.fee_display}` : '';
     return `Swap ${from} → ${to}${fee} on KaleidoSwap. Proceed?`;
   },
   summary: (ctx) => {
     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 from = quoteLeg(q?.from_asset) ?? `${ctx.slots.amount} ${ctx.slots.from_asset}`;
+    const to = quoteLeg(q?.to_asset) ?? String(ctx.slots.to_asset);
+    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.`;
   },
 };

package/src/recipe/kaleidoswap-channel-order.test.ts

@@ -166,6 +166,21 @@ describe('extractChannelOrder — deterministic prefilter', () => {
     expect(extractChannelOrder('what is my balance')).toBeNull();
     expect(extractChannelOrder('swap 1000 sats to usdt')).toBeNull();
   });
+
+  it('catches "on the other" after "my side" (user-reported variation)', () => {
+    const r = extractChannelOrder('get a channel with 30000 on my side and 80000 on the other');
+    expect(r).toMatchObject({ client_balance_sat: 30_000, lsp_balance_sat: 80_000 });
+  });
+
+  it('catches "with X on my side and Y on the other side"', () => {
+    const r = extractChannelOrder('buy a channel with 20000 on my side and 100000 on the other side');
+    expect(r).toMatchObject({ client_balance_sat: 20_000, lsp_balance_sat: 100_000 });
+  });
+
+  it('catches "on lsps" variant with "on the other"', () => {
+    const r = extractChannelOrder('get a channel for me with 100000 on lsps and 20000 on the other');
+    expect(r).toMatchObject({ client_balance_sat: 20_000, lsp_balance_sat: 100_000 });
+  });
 });
 
 describe('kaleidoswapChannelOrderRecipe — selection', () => {
@@ -193,6 +208,29 @@ describe('kaleidoswapChannelOrderRecipe — selection', () => {
     expect(m('do I need a channel to receive lightning payments?')).toBe(false);
     expect(m('can I receive without an inbound channel?')).toBe(false);
   });
+
+  it('does NOT trigger on read/verify questions about EXISTING channels', () => {
+    const m = kaleidoswapChannelOrderRecipe.match!;
+    // A spend must never fire from a question about channels the user has.
+    // These route to rgb-lightning-node (rln_list_channels).
+    expect(m('list my channels')).toBe(false);
+    expect(m('list my channels and their capacities')).toBe(false);
+    expect(m('do I have a channel with about 60000 inbound and 15000 on my side?')).toBe(false);
+    expect(m('show my channels')).toBe(false);
+    expect(m('check my channel status')).toBe(false);
+    expect(m('which channels do I have')).toBe(false);
+    expect(m('what is the status of my channel order')).toBe(false);
+  });
+
+  it('STILL triggers on genuine acquire intents (regression guard)', () => {
+    const m = kaleidoswapChannelOrderRecipe.match!;
+    expect(m('buy me a channel: 60000 sats inbound and 15000 on my side')).toBe(true);
+    expect(m('buy a 500k inbound channel')).toBe(true);
+    expect(m('open a channel from the LSP, 200k inbound')).toBe(true);
+    expect(m('I need 1M inbound liquidity')).toBe(true);
+    expect(m("I can't receive payments")).toBe(true);
+    expect(m('order a lsps1 channel')).toBe(true);
+  });
 });
 
 describe('kaleidoswapChannelOrderRecipe — full chain', () => {

package/src/recipe/kaleidoswap-channel-order.ts

@@ -37,16 +37,27 @@ const DEFAULT_EXPIRY_BLOCKS = 4320;
  *   - the trading skill's territory.
  */
 function CHANNEL_INTENT(t: string): boolean {
-  // Explanatory/question phrasing → not an order, let the agentic path handle it.
+  // Explanatory phrasing → not an order; let RAG / agentic answer.
   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;
-  // Explicit LSPS1 keywords always match.
+  // Read / verify phrasing → route to rgb-lightning-node (rln_list_channels),
+  // NEVER to a spend. "list my channels", "do I have a channel", "show/check
+  // my channels", "channel status".
+  if (/\b(list|show|view|check|which)\b/i.test(t)) return false;
+  if (/\bdo\s+I\s+(already\s+)?have\b/i.test(t)) return false;
+  if (/\bmy\s+channels?\b/i.test(t)) return false;
+  if (/\b(channel|order|lsp)\s+status\b/i.test(t) || /\bstatus\s+of\b/i.test(t)) return false;
+
+  // Explicit LSPS1 order keywords → acquire.
   if (/\b(lsps1|lsp\s+order|channel\s+order)\b/i.test(t)) return true;
-  // Inbound liquidity asks.
-  if (/\binbound(\s+(liquidity|capacity|channel))?\b/i.test(t)) return true;
+  // "I can't receive" → wants inbound liquidity.
   if (/\bcan('?t| not)\s+receive\b/i.test(t)) return true;
-  // "Buy / open / get a channel from the LSP" (or just "from KaleidoSwap"
-  // when the keyword "channel" is present).
-  if (/\b(buy|open|get|order)\b.*\bchannel\b/i.test(t)) return true;
+
+  // Otherwise require an explicit ACQUIRE verb so a bare mention of "channel"
+  // or "inbound" in a question doesn't trigger a spend.
+  const acquire = /\b(buy|open|get|order|purchase|acquire|need|want|add|create)\b/i.test(t);
+  if (!acquire) return false;
+  if (/\bchannel\b/i.test(t)) return true;
+  if (/\binbound(\s+(liquidity|capacity))?\b/i.test(t)) return true;
   return false;
 }
 
@@ -114,6 +125,12 @@ export function extractChannelOrder(text: string): Record<string, unknown> | nul
     if (otherNum && otherNum[1]) lsp_balance_sat = parseAmountWord(otherNum[1], otherNum[2]);
   }
 
+  // "on the other" when lsp side tagged first (e.g. "100k on lsps and 20k on the other") -> client side
+  if (lsp_balance_sat != null && client_balance_sat == null) {
+    const otherNum = t.match(/\b(\d[\d,.]*)\s*(k|m)?\s+(?:sats?\s+)?(?:on\s+the\s+other|the\s+other\s+side)\b/i);
+    if (otherNum && otherNum[1]) client_balance_sat = parseAmountWord(otherNum[1], otherNum[2]);
+  }
+
   // Specific anchored pattern for "on my side X and Y on the other" or similar structures
   if (client_balance_sat != null && lsp_balance_sat == null) {
     const otherAfterMy = t.match(/on\s+my\s+side.*?\b(\d[\d,.]*)\s*(k|m)?\s+(?:sats?\s+)?on\s+the\s+other\b/i);
@@ -531,7 +548,7 @@ export const kaleidoswapChannelOrderRecipe: Recipe = {
     const beforeIds = new Set((before?.channels ?? []).map((c) => c.channel_id));
     const fresh = (channels?.channels ?? []).filter((c) => c.channel_id && !beforeIds.has(c.channel_id));
     const match = fresh[0];
-    let opened = ' The channel will open once the LSP confirms the payment — ask me to check its status (call lsp_get_order with the exact order_id and access_token above).';
+    let opened = ' The channel will open once the LSP confirms the payment — say "check my channel status" (or "lsp status") and I will recall the details + poll lsp_get_order automatically.';
     if (match) {
       const cap = match.capacity_sat != null ? `${match.capacity_sat.toLocaleString()}-sat` : 'new';
       const ready = match.ready ? 'ready' : (match.status ?? 'opening');
@@ -543,6 +560,7 @@ export const kaleidoswapChannelOrderRecipe: Recipe = {
     const lspAsset = Number(ctx.slots.lsp_asset_amount ?? 0);
     const assetPart = ticker ? ` (${lspAsset.toLocaleString()} ${ticker} inbound)` : '';
 
-    return `Channel order created. To check status use: lsp_get_order with${tokenNote} .${paid}${assetPart}.${adjusted}${opened}`;
+    return `remember: LSPS1 channel order ${id} access_token=${token || ''} (for later lsp_get_order status checks).
+Channel order created. ${tokenNote ? `order_id=${id} access_token=${token}. ` : ''}To check status later, call: lsp_get_order(order_id=${id}, access_token=${token || '...'}) .${paid}${assetPart}.${adjusted}${opened}`;
   },
 };

package/src/recipe/kaleidoswap-price.ts

@@ -21,8 +21,14 @@ import type { Recipe, RecipeContext } from './types.js';
 import { extractPriceQuery } from './swap.js';
 
 const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+// Flashnet (Spark AMM) cues — a price/rate question aimed at a Flashnet asset
+// or venue should NOT be quoted via the KaleidoSwap maker. Defer to the
+// agentic tier (flashnet-swaps simulate_swap is the read-only quote there).
+const FLASHNET_CUE = /\b(flashnet|usdb|spark)\b/i;
 const PRICE_INTENT = (t: string) =>
-  /\b(price|rate|cost|worth|how\s+(?:much|many))\b/i.test(t) && ASSET.test(t);
+  /\b(price|rate|cost|worth|how\s+(?:much|many))\b/i.test(t) &&
+  ASSET.test(t) &&
+  !FLASHNET_CUE.test(t);
 
 interface QuoteResult {
   rfq_id?: string;

package/src/recipe/recipe.test.ts

@@ -158,6 +158,11 @@ describe('extractPriceQuery', () => {
       amount: 1, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to',
     });
   });
+  it('parses a quantity quote with the amount on the priced asset', () => {
+    expect(extractPriceQuery('how many sats is 10 USDT worth?')).toEqual({
+      amount: 10, from_asset: 'BTC', to_asset: 'USDT', amount_side: 'to',
+    });
+  });
   it('handles "cost of xaut" and "how much does 1 btc cost"', () => {
     expect((extractPriceQuery('cost of xaut') as any)?.to_asset).toBe('XAUT');
     expect((extractPriceQuery('how much does 1 btc cost') as any)?.to_asset).toBe('BTC');

package/src/recipe/runner.ts

@@ -95,10 +95,12 @@ export async function extractSlots(
   const system = [
     `Call ${EXTRACT_TOOL} with the fields from the user's message.`,
     recipe.description ? `This extraction is for: ${recipe.description}.` : '',
-    'Only emit values that match the field descriptions.',
+    'Only emit values that match the field descriptions. Use the examples and phrasings listed in each field\'s description (including context like "on the other" when "my side" appears).',
     'Canonical assets: BTC, USDT, XAUT (pass as strings like "BTC" or "USDT").',
     'amount_side: "to" when the named amount is what you receive/buy (e.g. "buy 1 USDT" → to_asset=USDT, amount=1, from_asset=BTC); "from" for sell/swap (amount on from_asset).',
     'The host binding handles per-asset precision scaling (BTC in sats → maker units; USDT/XAUT whole units). Pass the user\'s number as-is for the correct side.',
+    'If a value is ambiguous from the message, prefer the mapping from the field descriptions rather than guessing.',
+    'For status-related follow-ups the history (or recall result) will contain explicit "order_id=... access_token=..." or "atomic_id=..." strings from prior summaries — when relevant extract them exactly.',
     'Do not call any other tool and do not add commentary.',
   ].filter(Boolean).join(' ');
 
@@ -175,10 +177,10 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
     if (recipe.confident && !recipe.confident(ctx.slots)) {
       const missing = recipe.slots
         .filter((s) => s.required && (ctx.slots[s.name] == null || ctx.slots[s.name] === ''))
-        .map((s) => `${s.name} (${s.description})`);
+        .map((s) => s.name);
       const ask =
         missing.length > 0
-          ? `I need a bit more info — please specify: ${missing.join('; ')}.`
+          ? `I need a bit more info — please specify the ${missing.join(' and ')} (rephrase with the numbers, or use recall if this is a follow-up status check).`
           : "I don't have enough info to do that — could you rephrase with the specifics?";
       return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: ask, status: 'needs-info', inferences };
     }

package/src/recipe/swap.ts

@@ -12,7 +12,7 @@
 
 import type { Recipe } from './types.js';
 
-const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold|usdb)\b/i;
 
 /** Strict: returns a canonical code only for a KNOWN crypto asset, else undefined
  *  (so "kaleido", "the", etc. are not mistaken for an asset). */
@@ -22,6 +22,7 @@ function knownAsset(a?: string): string | undefined {
   if (/^(btc|bitcoin|sat|sats|satoshi|satoshis)$/.test(x)) return 'BTC';
   if (/^(usdt|tether)$/.test(x)) return 'USDT';
   if (/^(xaut|gold)$/.test(x)) return 'XAUT';
+  if (/^usdb$/.test(x)) return 'USDB';
   return undefined;
 }
 
@@ -106,6 +107,20 @@ export function extractPriceQuery(text: string): Record<string, unknown> | null
   // Reject swap intent — those go to the atomic recipe, not the price recipe.
   if (/\b(swap|exchange|convert|trade|buy|sell|get|purchase|acquire)\b/i.test(t)) return null;
 
+  // Natural quantity quote: "how many sats is 10 USDT worth?" The amount is
+  // on the priced asset (TO leg); the requested denomination is the FROM leg.
+  const quantityWorth = t.match(
+    /\bhow\s+(?:many|much)\s+([a-z]+)\s+(?:is|are)\s+(\d[\d.,]*)\s+([a-z]+)\s+worth\b/i,
+  );
+  if (quantityWorth) {
+    const denom = knownAsset(quantityWorth[1]);
+    const amount = parseAmount(quantityWorth[2]);
+    const asset = knownAsset(quantityWorth[3]);
+    if (denom && asset && amount != null) {
+      return { amount, from_asset: denom, to_asset: asset, amount_side: 'to' };
+    }
+  }
+
   // ORDER MATTERS: "how much B for A" (first) must be checked BEFORE
   // "how much X (in Y)?" — otherwise the latter would gobble the first asset
   // and miss the "for/per" tail. Optional "the" article is tolerated

package/src/wallet/confirm.test.ts

@@ -40,6 +40,14 @@ describe('confirmReadback', () => {
     expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over RLN. Confirm?');
   });
 
+  it('spark_pay_invoice: same readback shape, over Spark', () => {
+    const line = confirmReadback({
+      name: 'spark_pay_invoice',
+      arguments: { invoice: 'lnbc1ptestinvoice0123456789abcd' },
+    });
+    expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over Spark. 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?');

package/src/wallet/confirm.ts

@@ -64,6 +64,7 @@ export function confirmReadback(call: { name: string; arguments: Record<string,
     case 'liquid_send':
       return ask(`Send ${asset(a.amount, a.asset)} to ${to()}${over(name, a)}`);
     case 'rln_pay_invoice':
+    case 'spark_pay_invoice':
       return ask(`Pay Lightning invoice ${shortRef(String(a.invoice ?? ''))}${over(name, a)}`);
     case 'execute_swap':
       return ask(`Swap ${fmtNum(Number(a.amount))} ${String(a.from_asset)} for ${String(a.to_asset)}`);

package/src/wallet/contract.test.ts

@@ -39,12 +39,22 @@ describe('WALLET_TOOLS contract', () => {
     expect(isSpendTool('rln_send_asset')).toBe(true);
     expect(isSpendTool('execute_swap')).toBe(true);
     expect(isSpendTool('spark_send')).toBe(true);
+    expect(isSpendTool('spark_pay_invoice')).toBe(true);
     // reads are not
     expect(isSpendTool('get_balances')).toBe(false);
     expect(isSpendTool('get_price')).toBe(false);
     expect([...SPEND_TOOLS].length).toBeGreaterThanOrEqual(5);
   });
 
+  it('spark_pay_invoice is its own tool — BOLT11-shaped, amount optional', () => {
+    const def = getWalletTool('spark_pay_invoice');
+    expect(def?.layer).toBe('spark');
+    expect(def?.spend).toBe(true);
+    expect((def!.parameters as any).required).toEqual(['invoice']);
+    expect((def!.parameters as any).properties.invoice.type).toBe('string');
+    expect((def!.parameters as any).properties.amount_sats.type).toBe('number');
+  });
+
   it('required args declared on the actionable tools', () => {
     expect((getWalletTool('send_payment')!.parameters as any).required).toContain('to');
     expect((getWalletTool('fiat_to_sats')!.parameters as any).required).toEqual(['amount', 'currency']);

package/src/wallet/contract.ts

@@ -56,10 +56,32 @@ const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT',
 /** The full contract. Keep descriptions terse — small models read every word. */
 export const WALLET_TOOLS: WalletToolDef[] = [
   // ── Spark ──────────────────────────────────────────────────────────────
-  t('spark', 'spark_get_balance', 'Get the Spark wallet BTC balance.'),
-  t('spark', 'spark_get_address', 'Get a Spark deposit address to receive BTC.'),
-  t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice to receive BTC.', { amount_sats: sats }),
-  t('spark', 'spark_send', 'Send BTC from Spark to an address or invoice.', { amount_sats: sats, to: { type: 'string', description: 'Address or invoice' } }, ['amount_sats', 'to'], true),
+  t('spark', 'spark_get_balance', 'Get the Spark wallet balances — BTC sats AND every Spark-native token (e.g. USDB). Returns `{ total: <sats>, tokens: [{ address, balance, symbol?, decimals?, available_to_send? }], connected, layer, network }`. Use for ANY "balance / how much / what do I have on Spark" question — call it fresh every time, balances change. The `tokens` array surfaces ALL Spark-native tokens the wallet holds, so you do NOT need to call flashnet_get_balance separately for that (flashnet_get_balance is the AMM-client view of the same wallet and returns the same numbers). For RGB asset balances (USDT, XAUT) use the RLN tools — RGB assets are NOT on Spark.'),
+  // The user-facing "Spark address" — an off-chain Spark identity (sparkrt1…/
+  // spark1…). For OFF-CHAIN peer transfers WITHIN Spark. NOT a Bitcoin
+  // on-chain address. Use spark_get_onchain_address for the on-chain deposit
+  // path; use spark_create_invoice for a Lightning invoice.
+  t('spark', 'spark_get_address', 'Get the user\'s Spark address (sparkrt1…/spark1…) — an OFF-CHAIN Spark identity for receiving Spark-to-Spark transfers. NOT a Bitcoin on-chain address (does not start with bc1/tb1/bcrt1) and NOT a Lightning invoice. For "an on-chain address to deposit BTC into Spark" use spark_get_onchain_address. For a Lightning invoice use spark_create_invoice.'),
+  // Real on-chain Bitcoin address used to deposit BTC FROM mainnet INTO the
+  // Spark wallet. The SDK calls this a "static deposit address" — bc1…/tb1…/
+  // bcrt1…. The opposite of spark_get_address.
+  t('spark', 'spark_get_onchain_address', 'Get a real Bitcoin ON-CHAIN address (bc1…/tb1…/bcrt1…) for depositing BTC from the Bitcoin L1 into the Spark wallet. Use ANY time the user asks for "an on-chain address", "deposit address", "Bitcoin address to fund Spark", "where do I send my on-chain BTC". This is NOT the Spark identity (spark_get_address) and NOT a Lightning invoice (spark_create_invoice).'),
+  t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice (BOLT11) to receive BTC over Lightning. Returns an invoice string the user can share. Use when the user asks for "an invoice", "a lightning invoice", "pay me", or names an amount they want received. NOT an address.', { amount_sats: sats }),
+  // Explicit Lightning-invoice payer. BOLT11 invoices encode the amount, so
+  // `amount_sats` is optional and only used for amount-less ("any-amount")
+  // invoices. Prefer this over `spark_send` when the destination is a BOLT11
+  // invoice — it removes ambiguity for small models and gives the cross-skill
+  // bitrefill flow a single, unambiguous target.
+  t('spark', 'spark_pay_invoice',
+    'Pay a Lightning (BOLT11) invoice from the Spark wallet. The invoice already encodes the amount; pass amount_sats ONLY for amount-less invoices. Use this for any BOLT11 destination (Bitrefill, contact, raw invoice).',
+    { invoice: { type: 'string', description: 'BOLT11 Lightning invoice (lnbc…/lntb…/lnbcrt…).' }, amount_sats: { type: 'number', description: 'Required ONLY when the invoice has no amount; omit otherwise.' } },
+    ['invoice'],
+    /* spend */ true),
+  t('spark', 'spark_send',
+    'Send BTC from Spark to an on-chain address (bc1…/tb1…). For BOLT11 invoices, prefer spark_pay_invoice.',
+    { amount_sats: sats, to: { type: 'string', description: 'On-chain Bitcoin address.' } },
+    ['amount_sats', 'to'],
+    /* spend */ true),
 
   // ── RLN / RGB ──────────────────────────────────────────────────────────
   t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),