@kaleidorg/mind 0.5.1 → 0.6.0

package/src/qvac/stream.ts

@@ -27,10 +27,31 @@ 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;
 }
 
 export interface ConsumedTurn extends ParsedTurn {
   requestId: string;
+  /** True when the run was stopped because `<think>` hit `maxThinkingTokens`. */
+  thinkingBudgetExceeded?: boolean;
+}
+
+/** Rough token estimate (~4 chars/token) — same heuristic the context budget uses. */
+function approxTokens(chars: number): number {
+  return Math.ceil(chars / 4);
 }
 
 /**
@@ -43,14 +64,30 @@ export async function consumeRun(
   handlers: StreamHandlers = {},
 ): Promise<ConsumedTurn> {
   let streamed = '';
+  let thinkingChars = 0;
+  let budgetExceeded = false;
   for await (const event of run.events) {
     if (event.type === 'contentDelta' && typeof event.text === 'string') {
       streamed += event.text;
       handlers.onToken?.(event.text);
     } else if (event.type === 'thinkingDelta' && typeof event.text === 'string') {
       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 };
+  return {
+    ...finalToTurn(final, streamed),
+    requestId: run.requestId,
+    thinkingBudgetExceeded: budgetExceeded,
+  };
 }

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/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),
     ]),
   ]);
 }
@@ -130,7 +130,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 +157,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
@@ -122,10 +122,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;

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

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,
@@ -187,6 +224,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 +234,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/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> {