@kaleidorg/mind 0.5.1 → 0.6.1

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

@@ -72,6 +72,22 @@ describe('runRecipe — pay a contact', () => {
     expect(sent).toHaveLength(0);
   });
 
+  it('never reports a failed wallet result as sent', async () => {
+    const tools = new ToolRegistry([new InProcessToolSource('wallet', [
+      { name: 'resolve_contact', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ name }) => ({ name, ln_address: `${name}@kaleidoswap.com` }) },
+      { name: 'fiat_to_sats', description: '', parameters: { type: 'object', properties: {} }, handler: async ({ amount }) => ({ sats: Math.round(Number(amount) * 1000) }) },
+      { name: 'send_payment', description: '', parameters: { type: 'object', properties: {} }, requiresConfirmation: true, handler: async () => ({ success: false, message: 'insufficient balance' }) },
+    ])]);
+    const res = await runRecipe(paymentsRecipe, 'pay bob 3 eur', {
+      provider: approve,
+      tools,
+      onConfirm: async () => ({ approved: true }),
+    });
+    expect(res.status).toBe('error');
+    expect(res.text).toContain('insufficient balance');
+    expect(res.text).not.toContain('Sent');
+  });
+
   it('falls back to ONE LLM extraction when regex misses', async () => {
     const sent: any[] = [];
     const tools = stubTools({ send: (a) => sent.push(a) });
@@ -142,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

@@ -29,6 +29,43 @@ export interface RunRecipeOptions {
   signal?: AbortSignal;
 }
 
+function toolFailure(result: unknown): string | null {
+  // A plain-string result (non-JSON MCP text, or a tool that returns prose):
+  // flag obvious error text so a failed action isn't reported as success.
+  if (typeof result === 'string') {
+    const s = result.trim();
+    return /^(error|failed|failure|exception)\b\s*[:\-]?/i.test(s) ? s : null;
+  }
+  if (!result || typeof result !== 'object') return null;
+  const r = result as Record<string, unknown>;
+  if (typeof r.error === 'string' && r.error.trim()) return r.error;
+  if (r.success === false || r.ok === false) {
+    return String(r.message ?? r.reason ?? 'The wallet action failed.');
+  }
+  const status = String(r.status ?? r.state ?? '').toLowerCase();
+  if (['error', 'failed', 'failure', 'rejected'].includes(status)) {
+    return String(r.message ?? r.reason ?? `The wallet returned status "${status}".`);
+  }
+  return null;
+}
+
+function failedResult(
+  recipe: Recipe,
+  ctx: RecipeContext,
+  inferences: number,
+  message: string,
+): RecipeResult {
+  return {
+    recipe: recipe.name,
+    slots: ctx.slots,
+    results: ctx.results,
+    text: `Couldn't complete that: ${message}`,
+    status: 'error',
+    error: message,
+    inferences,
+  };
+}
+
 /** Extract the recipe's slots — deterministic regex first, else ONE LLM call. */
 export async function extractSlots(
   provider: LLMProvider,
@@ -58,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(' ');
 
@@ -138,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 };
     }
@@ -187,6 +226,8 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
       const result = await opts.tools.execute(step.tool, args);
       ctx.results[step.as ?? step.tool] = result;
       opts.onStep?.(step.tool, args, result);
+      const failure = toolFailure(result);
+      if (failure) return failedResult(recipe, ctx, inferences, failure);
     }
 
     // Final action.
@@ -195,6 +236,8 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
     const finalResult = await opts.tools.execute(recipe.final.tool, finalArgs);
     ctx.results[recipe.final.as ?? recipe.final.tool] = finalResult;
     opts.onStep?.(recipe.final.tool, finalArgs, finalResult);
+    const failure = toolFailure(finalResult);
+    if (failure) return failedResult(recipe, ctx, inferences, failure);
 
     const out = recipe.summary?.(ctx, finalResult) ?? 'Done.';
     return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, final: finalResult, text: out, status: 'done', 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/tools/mcp.live.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Live MCP integration — regression guard for the "tool-less desktop chat" bug.
+ *
+ * The desktop agent (desktop-app/src-tauri/src/mind.rs → apps/provider
+ * connectMcpIfConfigured) wires tools EXACTLY the way this test does: spawn
+ * `node <kaleido-mcp>/dist/index.js` over stdio with RLN_NODE_URL pointing at
+ * the user's RGB-Lightning node, then listTools()/execute(). When that wiring
+ * breaks, the registry is empty, the model goes "tool-less", and it NARRATES
+ * tool calls it can never run ("Could you use the kaleidoswap_get_quote tool?")
+ * instead of returning real data — the exact 2026-06 symptom.
+ *
+ * This drives that chain end-to-end against a REAL running node and asserts the
+ * tools both EXIST (not tool-less) and EXECUTE (return live node data). A unit
+ * test can't catch this: the bug is in process/env wiring, not pure logic.
+ *
+ * Auto-skips unless (a) kaleido-mcp/dist is built and (b) an RLN node answers,
+ * so it's a no-op in CI and a real check on a dev box with a node up. Run it
+ * explicitly against a node with:
+ *   RLN_NODE_URL=http://localhost:3001 pnpm --filter @kaleidorg/mind test:live
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpToolSource } from './mcp.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// $KALEIDO_MCP_PATH override (what mind.rs sets), else the sibling repo's build.
+const MCP_ENTRY =
+  process.env.KALEIDO_MCP_PATH ??
+  resolve(here, '../../../../../kaleido-mcp/dist/index.js');
+const NODE_URL = (process.env.RLN_NODE_URL ?? 'http://localhost:3001').replace(/\/+$/, '');
+
+/** Probe the RLN node directly so we can (a) gate the suite and (b) compare the
+ *  MCP tool's output to ground truth pulled straight from the node. */
+async function fetchNodePubkey(): Promise<string | null> {
+  try {
+    const r = await fetch(`${NODE_URL}/nodeinfo`, { signal: AbortSignal.timeout(4000) });
+    if (!r.ok) return null;
+    const j = (await r.json()) as { pubkey?: string };
+    return typeof j.pubkey === 'string' && j.pubkey.length > 0 ? j.pubkey : null;
+  } catch {
+    return null;
+  }
+}
+
+const hasDist = existsSync(MCP_ENTRY);
+const livePubkey = hasDist ? await fetchNodePubkey() : null;
+const RUN = hasDist && !!livePubkey;
+
+if (!RUN) {
+  const why = !hasDist ? `no built MCP at ${MCP_ENTRY}` : `no RLN node at ${NODE_URL}`;
+  // eslint-disable-next-line no-console
+  console.warn(`[mcp.live] skipping live MCP integration — ${why}`);
+}
+
+describe.skipIf(!RUN)('MCP live integration (real RLN node)', () => {
+  let src: McpToolSource;
+
+  beforeAll(async () => {
+    src = new McpToolSource({
+      id: 'kaleido-test',
+      transport: {
+        kind: 'stdio',
+        command: 'node',
+        args: [MCP_ENTRY],
+        // Mirror the provider: inherit env, force the node URL, allow no WDK seed
+        // (rln_*/kaleidoswap_* register regardless; only spark_*/wdk_* need it).
+        env: {
+          ...process.env,
+          RLN_NODE_URL: NODE_URL,
+          WDK_SEED: process.env.WDK_SEED ?? '',
+        } as Record<string, string>,
+      },
+      timeoutMs: 30_000,
+    });
+    await src.connect();
+  }, 45_000);
+
+  afterAll(async () => {
+    await src?.close();
+  });
+
+  it('exposes a non-empty tool registry (the model is NOT tool-less)', () => {
+    const tools = src.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+    // The exact tools the agent narrated when it couldn't call them.
+    expect(src.has('rln_get_node_info')).toBe(true);
+    expect(src.has('rln_get_balances')).toBe(true);
+    expect(src.has('kaleidoswap_get_quote')).toBe(true);
+  });
+
+  it('preserves the confirmation gate on known spend tools', () => {
+    const spend = src.listTools().find((tool) => tool.name === 'rln_pay_invoice');
+    if (spend) expect(spend.requiresConfirmation).toBe(true);
+  });
+
+  it('rln_get_node_info EXECUTES against the node (returns the live pubkey)', async () => {
+    const out = await src.execute('rln_get_node_info', {});
+    const text = typeof out === 'string' ? out : JSON.stringify(out);
+    // Real execution returns the node's actual identity — not a narrated promise.
+    expect(text).toContain(livePubkey!);
+  }, 30_000);
+
+  it('rln_get_balances EXECUTES against the node (returns live balance fields)', async () => {
+    const out = await src.execute('rln_get_balances', {});
+    const text = typeof out === 'string' ? out : JSON.stringify(out);
+    const parsed = JSON.parse(text) as {
+      lightning_balance_sat?: number;
+      btc_onchain?: Record<string, number>;
+    };
+    expect(parsed).toHaveProperty('lightning_balance_sat');
+    expect(typeof parsed.lightning_balance_sat).toBe('number');
+    expect(parsed).toHaveProperty('btc_onchain');
+  }, 30_000);
+});

package/src/tools/mcp.parse.test.ts

@@ -0,0 +1,37 @@
+/** parseMcpResult — JSON parsing + isError handling for MCP tool results. */
+
+import { describe, it, expect } from 'vitest';
+import { parseMcpResult } from './mcp.js';
+
+describe('parseMcpResult', () => {
+  it('parses JSON text content into an object (so recipes thread real fields)', () => {
+    const res = { content: [{ type: 'text', text: '{"rfq_id":"abc","total_sat":1500}' }] };
+    expect(parseMcpResult(res)).toEqual({ rfq_id: 'abc', total_sat: 1500 });
+  });
+
+  it('surfaces isError as an {error} object (so a failed spend is not "success")', () => {
+    const res = { isError: true, content: [{ type: 'text', text: 'insufficient funds' }] };
+    expect(parseMcpResult(res)).toEqual({ error: 'insufficient funds' });
+  });
+
+  it('errors with no text still produce an {error} object', () => {
+    expect(parseMcpResult({ isError: true, content: [] })).toEqual({
+      error: 'The tool reported an error.',
+    });
+  });
+
+  it('passes non-JSON prose through unchanged', () => {
+    const res = { content: [{ type: 'text', text: 'Bitcoin is digital cash.' }] };
+    expect(parseMcpResult(res)).toBe('Bitcoin is digital cash.');
+  });
+
+  it('returns the content array when there is no text block', () => {
+    const res = { content: [{ type: 'image', data: 'x' }] };
+    expect(parseMcpResult(res)).toEqual([{ type: 'image', data: 'x' }]);
+  });
+
+  it('joins multiple text blocks before parsing', () => {
+    const res = { content: [{ type: 'text', text: '{"a":1,' }, { type: 'text', text: '"b":2}' }] };
+    expect(parseMcpResult(res)).toEqual({ a: 1, b: 2 });
+  });
+});

package/src/tools/mcp.ts

@@ -20,6 +20,18 @@
 
 import type { ToolDef } from '../types.js';
 import type { ToolSource } from './source.js';
+import { isKaleidoswapSpendTool } from '../kaleidoswap/contract.js';
+import { isLsps1SpendTool } from '../lsps1/contract.js';
+import { isSpendTool } from '../wallet/contract.js';
+
+function toolRequiresConfirmation(name: string, description: string): boolean {
+  return (
+    isSpendTool(name) ||
+    isKaleidoswapSpendTool(name) ||
+    isLsps1SpendTool(name) ||
+    /\bSPEND\b.*\bconfirm/i.test(description)
+  );
+}
 
 export type McpTransport =
   | { kind: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
@@ -30,10 +42,47 @@ export interface McpToolSourceOptions {
   transport: McpTransport;
   /** Optional allowlist — only expose these tool names if provided. */
   allow?: string[];
+  /** Optional prefix denylist applied after discovery (for host-specific rails). */
+  denyPrefixes?: string[];
   /** Per-call timeout (ms). Default 60_000. */
   timeoutMs?: number;
 }
 
+/**
+ * Normalize an MCP `callTool` result into a structured value.
+ *
+ * Two fixes vs. returning the raw text content:
+ *  - `isError` (the MCP failure signal) becomes an `{ error }` object, so callers
+ *    — the recipe runner's `toolFailure`, the agent — treat it as a FAILURE
+ *    instead of a successful result. Without this the agent claimed a spend had
+ *    succeeded when the wallet actually rejected it.
+ *  - JSON text is PARSED, so recipes thread real fields (rfq_id, total_sat,
+ *    order_id) and any failure fields (error/status) are visible. A raw string
+ *    hid both — the quote's rfq_id never reached the create call, and the canned
+ *    success summary fired regardless. Non-JSON text passes through unchanged;
+ *    the engine re-stringifies objects when feeding the model.
+ *
+ * Exported for unit testing.
+ */
+export function parseMcpResult(res: unknown): unknown {
+  const r = res as { content?: Array<{ type?: string; text?: string }>; isError?: boolean } | null;
+  const text = Array.isArray(r?.content)
+    ? r!.content
+        .filter((c) => c?.type === 'text')
+        .map((c) => c?.text ?? '')
+        .join('\n')
+    : '';
+  if (r?.isError) return { error: text || 'The tool reported an error.' };
+  if (text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return Array.isArray(r?.content) ? r!.content : res;
+}
+
 export class McpToolSource implements ToolSource {
   readonly id: string;
   private readonly opts: McpToolSourceOptions;
@@ -71,12 +120,15 @@ export class McpToolSource implements ToolSource {
 
     const listed = await this.client.listTools();
     const allow = this.opts.allow ? new Set(this.opts.allow) : null;
+    const denied = this.opts.denyPrefixes ?? [];
     this.tools = (listed.tools ?? [])
       .filter((t: any) => !allow || allow.has(t.name))
+      .filter((t: any) => !denied.some((prefix) => t.name.startsWith(prefix)))
       .map((t: any) => ({
         name: t.name,
         description: t.description ?? '',
         parameters: t.inputSchema ?? { type: 'object', properties: {} },
+        requiresConfirmation: toolRequiresConfirmation(t.name, t.description ?? ''),
       }));
   }
 
@@ -95,15 +147,9 @@ export class McpToolSource implements ToolSource {
       undefined,
       { timeout: this.opts.timeoutMs ?? 60_000 },
     );
-    // MCP returns content blocks; surface text content as the tool result.
-    if (Array.isArray(res?.content)) {
-      const text = res.content
-        .filter((c: any) => c.type === 'text')
-        .map((c: any) => c.text)
-        .join('\n');
-      return text || res.content;
-    }
-    return res;
+    // Parse JSON + surface isError so recipes/agent get structured results and
+    // real failures (not an opaque string that hid both). See parseMcpResult.
+    return parseMcpResult(res);
   }
 
   async close(): Promise<void> {

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).'),