@kaleidorg/mind 0.7.0 → 0.8.1

package/src/engine.ts

@@ -16,9 +16,25 @@
 
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 import type { LLMProvider } from './providers/types.js';
-import type { InferenceMetrics } from './providers/types.js';
+import type { InferenceMetrics, ToolCallError, ToolChoice } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { compressToolResult, type ToolCrushOptions } from './context/compress.js';
+import {
+  callKey,
+  declinedToolResult,
+  detectWalletAction,
+  hasCapableTool,
+  noToolReply,
+  findUngroundedPaymentData,
+  fixSatsBtcConversions,
+  ungroundedReply,
+  validateToolArgs,
+} from './guards.js';
+import { confirmReadback } from './wallet/confirm.js';
+import { annotateRgbBalances, fixRgbBalanceUnits } from './context/rgb-units.js';
+import type { SkillRegistry } from './skills/registry.js';
+import type { Skill } from './skills/types.js';
+import { selectAvailableSkill } from './skills/select.js';
 
 export interface EngineOptions {
   provider: LLMProvider;
@@ -36,6 +52,33 @@ export interface EngineOptions {
    * The `onToolResult` callback and `toolCalls` still carry the raw result.
    */
   compressToolOutput?: boolean | ToolCrushOptions;
+  /**
+   * Replace a final answer that contains an invoice/address/payment request no
+   * tool returned and the user never typed. Default true.
+   */
+  guardUngroundedPaymentData?: boolean;
+  /**
+   * Keep amounts honest: recompute BTC figures paired with a sats amount, add
+   * `balance_display` to RGB asset balances the model sees, and relabel an
+   * asset balance the answer calls sats. Default true.
+   */
+  fixAmountConversions?: boolean;
+  /** Let the model reason on a forced first tool call. Default false (thinking off). */
+  thinkOnForcedCalls?: boolean;
+  /**
+   * Answer a wallet action (create an invoice, get an address, pay, send) with
+   * a fixed "no tool" reply, without inference, when no exposed tool can do it.
+   * Default true.
+   */
+  guardMissingTools?: boolean;
+  /** End the run with a fixed "Cancelled" reply when the user declines every call in a turn. Default true. */
+  endTurnOnDecline?: boolean;
+}
+
+export interface ComposedSkill {
+  skill: Skill | null;
+  system: string;
+  allowedTools?: string[];
 }
 
 export interface AgenticOptions {
@@ -52,12 +95,20 @@ export interface AgenticOptions {
    */
   onToolResult?: (event: { name: string; arguments: Record<string, unknown>; result: unknown }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
-  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown>; summary?: string }) => Promise<ConfirmDecision>;
   /**
    * Restrict the tools exposed to the model this run (progressive disclosure).
    * Typically the active skill's tool list — see SkillRegistry.compose().
    */
   allowedTools?: string[];
+  /**
+   * Tool choice for the FIRST model call only — e.g. `'required'` when the
+   * request is a wallet action, so the model can't answer in prose with
+   * made-up data. Later rounds are left to the model.
+   */
+  firstTurnToolChoice?: ToolChoice;
+  /** Session key passed to every model call of this run. Default: a fresh key per run. */
+  sessionKey?: string;
   signal?: AbortSignal;
 }
 
@@ -74,18 +125,41 @@ export interface AgenticResult {
   inference: InferenceMetrics[];
 }
 
+const STOPPED_MESSAGE = 'I had to stop after several steps — please try a more specific request.';
+
+const TOOL_CALL_FAILED_MESSAGE =
+  "I couldn't put together a valid request for that. Please rephrase it with the exact values (asset, amount, recipient).";
+
+function toolErrorMessage(errors: ToolCallError[], cutOff: boolean): string {
+  if (cutOff) {
+    return 'Your tool call was cut off because the output got too long. Make ONE tool call at a time with only the required arguments, or answer from the results you already have.';
+  }
+  const detail = errors.map((e) => e.message).join('; ');
+  return `Your tool call could not be read (${detail}). Call the tool again with valid JSON arguments that match its schema, or ask the user for the missing values.`;
+}
+
 export class Engine {
   private readonly provider: LLMProvider;
   private readonly registry: ToolRegistry;
   private readonly defaultSystem?: string;
   private readonly defaultMaxTurns: number;
   private readonly compressOpts?: ToolCrushOptions;
+  private readonly guardPaymentData: boolean;
+  private readonly fixAmounts: boolean;
+  private readonly thinkOnForcedCalls: boolean;
+  private readonly guardMissingTools: boolean;
+  private readonly endTurnOnDecline: boolean;
 
   constructor(opts: EngineOptions) {
     this.provider = opts.provider;
     this.registry = opts.tools;
     this.defaultSystem = opts.defaultSystem;
     this.defaultMaxTurns = opts.defaultMaxTurns ?? 5;
+    this.guardPaymentData = opts.guardUngroundedPaymentData ?? true;
+    this.fixAmounts = opts.fixAmountConversions ?? true;
+    this.thinkOnForcedCalls = opts.thinkOnForcedCalls ?? false;
+    this.guardMissingTools = opts.guardMissingTools ?? true;
+    this.endTurnOnDecline = opts.endTurnOnDecline ?? true;
     this.compressOpts = opts.compressToolOutput
       ? opts.compressToolOutput === true
         ? {}
@@ -93,7 +167,29 @@ export class Engine {
       : undefined;
   }
 
+  /**
+   * Select the skill for `query` among those that can act with this engine's
+   * tools (skills whose `requires-tools` are missing are skipped), then
+   * compose its system prompt. Pass the result to runAgentic:
+   *
+   *   const { system, allowedTools } = await engine.composeSkill(skills, question, base);
+   *   await engine.runAgentic([{ role: 'system', content: system }, { role: 'user', content: question }], { allowedTools });
+   */
+  async composeSkill(skills: SkillRegistry, query: string, base: string): Promise<ComposedSkill> {
+    const skill = selectAvailableSkill(skills, query, await this.registry.listTools());
+    return { skill, ...skills.compose(base, skill) };
+  }
+
   async runAgentic(messages: Message[], opts: AgenticOptions = {}): Promise<AgenticResult> {
+    const sessionKey = opts.sessionKey ?? `mind-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+      return await this.runAgenticSession(messages, { ...opts, sessionKey });
+    } finally {
+      if (!opts.sessionKey) await this.provider.endSession?.(sessionKey).catch(() => {});
+    }
+  }
+
+  private async runAgenticSession(messages: Message[], opts: AgenticOptions): Promise<AgenticResult> {
     const maxTurns = opts.maxTurns ?? this.defaultMaxTurns;
     const hasSystem = messages.some((m) => m.role === 'system');
     const system = hasSystem ? undefined : this.defaultSystem;
@@ -108,17 +204,37 @@ export class Engine {
     const executed: ToolResult[] = [];
     let lastRequestId: string | undefined;
     let finalText = '';
+    // Set when finalText is one of the engine's own fixed replies, which the
+    // answer guards below must not rewrite.
+    let engineReply = false;
     let turns = 0;
     const inference: InferenceMetrics[] = [];
+    const seen = new Map<string, { result: unknown; count: number }>();
+    let toolErrorRetries = 0;
+
+    const lastUser = [...messages].reverse().find((m) => m.role === 'user')?.content ?? '';
+    const action = this.guardMissingTools ? detectWalletAction(lastUser) : null;
+    if (action && !hasCapableTool(action, allTools.map((t) => t.name))) {
+      const text = noToolReply(action);
+      history.push({ role: 'assistant', content: text });
+      return { text, turns: 0, toolCalls: [], messages: history, latencyMs: Date.now() - startedAt, inference };
+    }
 
-    for (let turn = 1; turn <= maxTurns; turn++) {
+    // A retry after an unreadable tool call does not count against maxTurns.
+    for (let turn = 1; turn <= maxTurns + toolErrorRetries; turn++) {
       turns = turn;
       if (opts.signal?.aborted) break;
 
       const out = await this.provider.runTurn({
+      sessionKey: opts.sessionKey,
         messages: history,
         tools: allTools,
         system,
+        // A forced first call only picks the tool and its arguments; reasoning
+        // there costs most of the turn's time on small models.
+        ...(turn === 1 && opts.firstTurnToolChoice && allTools.length
+          ? { toolChoice: opts.firstTurnToolChoice, ...(this.thinkOnForcedCalls ? {} : { thinking: 'off' as const }) }
+          : {}),
         onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
         signal: opts.signal,
       });
@@ -126,40 +242,126 @@ export class Engine {
       lastRequestId = out.requestId;
       if (out.inference) inference.push(out.inference);
       if (out.requestId) opts.onStart?.(out.requestId, turn);
-      finalText = (out.text || '').trim();
+      finalText = out.incomplete ? '' : (out.text || '').trim();
+
+      // The model tried to call a tool but the call didn't parse: tell it what
+      // went wrong and let it try again (once) instead of showing the broken
+      // frame as the answer.
+      if ((!out.toolCalls || out.toolCalls.length === 0) && out.toolErrors?.length) {
+        if (toolErrorRetries < 1) {
+          toolErrorRetries += 1;
+          const cutOff = out.inference?.status === 'truncated';
+          history.push({ role: 'assistant', content: out.rawContent || finalText });
+          history.push({ role: 'tool', content: JSON.stringify({ error: toolErrorMessage(out.toolErrors, cutOff) }) });
+          continue;
+        }
+        finalText = TOOL_CALL_FAILED_MESSAGE;
+        engineReply = true;
+        break;
+      }
 
       // No tool calls ⇒ the model produced its final answer.
-      if (!out.toolCalls || out.toolCalls.length === 0) break;
+      if (!out.toolCalls || out.toolCalls.length === 0) {
+        if (!finalText && executed.length) finalText = await this.recoverAnswer(history, system, executed, inference, opts, turn);
+        else if (!finalText && out.incomplete) finalText = (out.text || '').trim();
+        break;
+      }
 
       // Anchor the next turn with the raw assistant frame.
       history.push({ role: 'assistant', content: out.rawContent || finalText });
 
+      let repeatedAgain = false;
+      const declinedThisTurn: string[] = [];
       for (const call of out.toolCalls) {
         opts.onToolCall?.({ name: call.name, arguments: call.arguments }, turn);
         const def = await this.registry.getDef(call.name);
+        const key = callKey(call.name, call.arguments);
+        const previous = seen.get(key);
 
+        let args = call.arguments;
         let result: unknown;
-        if (def?.requiresConfirmation) {
-          const decision = opts.onConfirm
-            ? await opts.onConfirm({ name: call.name, arguments: call.arguments })
-            : { approved: false, reason: 'no confirmation handler available' };
-          if (decision.approved) {
-            result = await this.safeExecute(call.name, call.arguments);
+        if (previous) {
+          previous.count += 1;
+          if (previous.count > 2) repeatedAgain = true;
+          result = {
+            error:
+              `You already called ${call.name} with these arguments; the result was: ` +
+              `${this.toHistoryContent(previous.result)}. Do not call it again — answer the user now.`,
+          };
+        } else if (!def) {
+          result = { error: `Unknown tool "${call.name}".` };
+        } else {
+          const check = validateToolArgs(def, call.arguments);
+          if (!check.ok) {
+            result = {
+              error: `Invalid arguments for ${call.name}: ${check.errors.join('; ')}. Fix them or ask the user for the missing values.`,
+            };
+          } else if (def.requiresConfirmation) {
+            args = check.args;
+            const summary = confirmReadback({ name: call.name, arguments: args }) ?? undefined;
+            const decision = opts.onConfirm
+              ? await opts.onConfirm({ name: call.name, arguments: args, ...(summary ? { summary } : {}) })
+              : { approved: false, reason: 'no confirmation handler available' };
+            if (decision.approved) {
+              result = await this.safeExecute(call.name, args);
+            } else {
+              result = declinedToolResult(call.name, decision.reason);
+              declinedThisTurn.push(summary ? summary.replace(/\.?\s*Confirm\?$/, '') : call.name.replace(/_/g, ' '));
+            }
           } else {
-            result = { declined: true, reason: decision.reason ?? 'user declined' };
+            args = check.args;
+            result = await this.safeExecute(call.name, args);
           }
-        } else {
-          result = await this.safeExecute(call.name, call.arguments);
         }
 
-        executed.push({ name: call.name, arguments: call.arguments, result });
-        opts.onToolResult?.({ name: call.name, arguments: call.arguments, result }, turn);
-        history.push({ role: 'tool', content: this.toHistoryContent(result) });
+        if (!previous) {
+          // A mutating (confirm-gated) call can change what reads return.
+          if (def?.requiresConfirmation) seen.clear();
+          seen.set(key, { result, count: 1 });
+        }
+        executed.push({ name: call.name, arguments: args, result });
+        opts.onToolResult?.({ name: call.name, arguments: args, result }, turn);
+        history.push({ role: 'tool', content: this.toHistoryContent(this.fixAmounts ? annotateRgbBalances(result) : result) });
+      }
+
+      if (this.endTurnOnDecline && declinedThisTurn.length && declinedThisTurn.length === out.toolCalls.length) {
+        finalText = `Cancelled — you declined: ${declinedThisTurn.join('; ')}. Nothing was sent or changed.`;
+        engineReply = true;
+        break;
       }
 
-      if (turn === maxTurns && !finalText) {
-        finalText = 'I had to stop after several steps — please try a more specific request.';
+      if (repeatedAgain) {
+        const forced = await this.provider.runTurn({
+      sessionKey: opts.sessionKey,
+          messages: history,
+          tools: [],
+          system,
+          onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+          signal: opts.signal,
+        });
+        if (forced.inference) inference.push(forced.inference);
+        finalText = (forced.text || '').trim() || 'I could not get a different result from the wallet — please try a more specific request.';
+        break;
       }
+
+    }
+
+    // Never return an empty answer (e.g. the last turn ran out of tokens).
+    if (!finalText && !opts.signal?.aborted) {
+      finalText = STOPPED_MESSAGE;
+      engineReply = true;
+    }
+
+    if (this.fixAmounts && finalText && !engineReply) {
+      finalText = fixRgbBalanceUnits(fixSatsBtcConversions(finalText), executed.map((e) => e.result));
+    }
+
+    if (this.guardPaymentData && finalText && !engineReply) {
+      const ungrounded = findUngroundedPaymentData(finalText, [
+        ...messages.map((m) => m.content),
+        ...executed.map((e) => e.result),
+      ]);
+      if (ungrounded.length) finalText = ungroundedReply(ungrounded);
     }
 
     // Append the final answer so the returned conversation is complete (the
@@ -177,6 +379,39 @@ export class Engine {
     };
   }
 
+  /**
+   * The model ran tools but produced no visible answer (e.g. reasoning used the
+   * whole output budget). Ask once more without tools; if that is empty too,
+   * show the last tool result instead of an empty reply.
+   */
+  private async recoverAnswer(
+    history: Message[],
+    system: string | undefined,
+    executed: ToolResult[],
+    inference: InferenceMetrics[],
+    opts: AgenticOptions,
+    turn: number,
+  ): Promise<string> {
+    if (opts.signal?.aborted) return '';
+    const retry = await this.provider.runTurn({
+      sessionKey: opts.sessionKey,
+      messages: [
+        ...history,
+        { role: 'user', content: 'Answer my question now from the tool results above, in a few short sentences.' },
+      ],
+      tools: [],
+      system,
+      onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+      signal: opts.signal,
+    });
+    if (retry.inference) inference.push(retry.inference);
+    const text = retry.incomplete ? '' : (retry.text || '').trim();
+    if (text) return text;
+    const last = executed[executed.length - 1]!;
+    const body = compressToolResult(last.result, this.compressOpts ?? {}).content;
+    return `I couldn't phrase an answer in time. Here is what ${last.name.replace(/_/g, ' ')} returned:\n\n${body.length > 2000 ? `${body.slice(0, 2000)}…` : body}`;
+  }
+
   async cancel(requestId: string): Promise<void> {
     await this.provider.cancel?.(requestId);
   }

package/src/fastpath/fastpath.ts

@@ -16,6 +16,8 @@ export interface FastIntent {
   name: string;
   /** Contract tool to call when this intent matches. */
   tool: string;
+  /** Equivalent tools to try, in order, when the host doesn't expose `tool`. */
+  fallbackTools?: string[];
   /** True only when this intent UNAMBIGUOUSLY matches the text. */
   match: (text: string) => boolean;
   /** Optional args derived from the text (default: none). */
@@ -24,7 +26,10 @@ export interface FastIntent {
 
 export interface FastHit {
   intent: FastIntent;
+  /** The intent's primary tool. */
   tool: string;
+  /** Primary tool first, then the fallbacks. */
+  tools: string[];
   args: Record<string, unknown>;
 }
 
@@ -42,24 +47,39 @@ export class FastPath {
   /** The first unambiguously-matching intent, or null. */
   select(text: string): FastHit | null {
     const intent = this.intents.find((i) => i.match(text));
-    return intent ? { intent, tool: intent.tool, args: intent.args?.(text) ?? {} } : null;
+    return intent
+      ? { intent, tool: intent.tool, tools: [intent.tool, ...(intent.fallbackTools ?? [])], args: intent.args?.(text) ?? {} }
+      : null;
   }
 }
 
 // A "spend or compound" guard — never fast-path anything that moves money or
 // chains another action ("send", "pay", "and then", "swap").
 const ACTIONY = /\b(send|pay|transfer|swap|buy|sell|then|after that)\b/i;
+// Asks that create something are not reads, even when they mention assets.
+const CREATEY = /\b(issue|mint|create|make|new|generate|invoice|receive|request)\b/i;
 
-/** Default wallet read intents (balance / receive address / price). */
+/** Default wallet read intents (balance / RGB assets / receive address / price). */
 export const WALLET_FAST_INTENTS: FastIntent[] = [
   {
     name: 'balance',
     tool: 'get_balances',
+    fallbackTools: ['rln_get_balances', 'wdk_get_balances'],
     match: (t) => !ACTIONY.test(t) && /\b(balance|funds|how much (do i|have i|i have)|how much.* (do i have|in my wallet))\b/i.test(t),
   },
+  {
+    name: 'assets',
+    tool: 'rln_list_assets',
+    fallbackTools: ['wdk_list_assets'],
+    match: (t) =>
+      !ACTIONY.test(t) &&
+      !CREATEY.test(t) &&
+      /\b(which|what|list|show|my)\b[^.?!]*\b(rgb assets?|assets?|tokens?)\b|\b(rgb assets?|tokens?) (do i|i) (have|hold|own)\b/i.test(t),
+  },
   {
     name: 'address',
     tool: 'spark_get_address',
+    fallbackTools: ['rln_get_address', 'wdk_get_address'],
     match: (t) => !ACTIONY.test(t) && /\b(receive address|deposit address|my address|an address|get .*address|where.* receive)\b/i.test(t),
   },
   {

package/src/fastpath/render.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { defaultRenderFast } from './render.js';
+import { FastPath, WALLET_FAST_INTENTS } from './fastpath.js';
+
+const fp = new FastPath(WALLET_FAST_INTENTS);
+
+describe('fast path: RLN tools and RGB assets', () => {
+  it('lists fallback tools after the primary one', () => {
+    expect(fp.select('What is my on-chain BTC balance?')?.tools).toEqual(['get_balances', 'rln_get_balances', 'wdk_get_balances']);
+  });
+
+  it('routes asset questions, not asset actions', () => {
+    expect(fp.select('Which RGB assets do I hold, and what are the balances?')?.intent.name).toBe('assets');
+    expect(fp.select('list my tokens')?.intent.name).toBe('assets');
+    expect(fp.select('Issue a new RGB asset named FOO')).toBeNull();
+    expect(fp.select('Create an RGB invoice so I can receive 10 USDT')).toBeNull();
+    expect(fp.select('Send 1 USDT to rgb:abc')).toBeNull();
+  });
+
+  it('renders the kaleido-mcp, aggregate and MockWallet balance shapes', () => {
+    expect(
+      defaultRenderFast(
+        'balance',
+        JSON.stringify({ btc_onchain: { vanilla_spendable_sats: 4277, colored_spendable_sats: 195000 }, lightning_balance_sat: 0 }),
+      ),
+    ).toBe('On-chain: 4,277 sats spendable.\nRGB UTXOs: 195,000 sats (holding RGB assets, not for spending).\nLightning: 0 sats.');
+    expect(defaultRenderFast('balance', { total_sats: 1000, layers: [{}, {}] })).toBe('You have 1,000 sats across 2 layers.');
+    expect(defaultRenderFast('balance', { btc_sats: 300000 })).toBe('You have 300,000 sats.');
+  });
+
+  it('renders RGB assets with their ticker and precision', () => {
+    const mcp = [
+      { ticker: 'Q35A', name: 'Bench Q35A', precision: 0, balance: { spendable: 1_000_000 } },
+      { ticker: 'USDT', name: 'Tether USD', precision: 6, balance: { spendable: 2_500_000 } },
+    ];
+    expect(defaultRenderFast('assets', mcp)).toBe('Your RGB assets:\n- Q35A (Bench Q35A): 1,000,000 Q35A\n- USDT (Tether USD): 2.5 USDT');
+    expect(defaultRenderFast('assets', { assets: [] })).toBe("You don't hold any RGB assets yet.");
+  });
+});

package/src/fastpath/render.ts

@@ -0,0 +1,56 @@
+/**
+ * Text for a fast-path result. Tools that answer the same intent return
+ * different shapes (aggregate wallet, kaleido-mcp, MockWallet), so each shape
+ * is read here instead of asking a model to describe it.
+ */
+import { formatRgbAmount } from '../context/rgb-units.js';
+
+type Obj = Record<string, any>;
+
+const sats = (n: unknown) => `${Number(n ?? 0).toLocaleString('en-US')} sats`;
+
+function parse(r: unknown): unknown {
+  if (typeof r !== 'string') return r;
+  try {
+    return JSON.parse(r);
+  } catch {
+    return r;
+  }
+}
+
+function renderBalance(r: Obj): string {
+  if (r.total_sats !== undefined) {
+    const n = r.layers?.length ?? 0;
+    return `You have ${sats(r.total_sats)}${n > 1 ? ` across ${n} layers` : ''}.`;
+  }
+  if (r.btc_onchain) {
+    const b = r.btc_onchain;
+    const lines = [`On-chain: ${sats(b.vanilla_spendable_sats)} spendable.`];
+    if (Number(b.colored_spendable_sats)) lines.push(`RGB UTXOs: ${sats(b.colored_spendable_sats)} (holding RGB assets, not for spending).`);
+    if (r.lightning_balance_sat !== undefined) lines.push(`Lightning: ${sats(r.lightning_balance_sat)}.`);
+    return lines.join('\n');
+  }
+  if (r.btc_sats !== undefined) return `You have ${sats(r.btc_sats)}.`;
+  return `Balances:\n${JSON.stringify(r, null, 2)}`;
+}
+
+function renderAssets(r: unknown): string {
+  const list: Obj[] = Array.isArray(r) ? r : Array.isArray((r as Obj)?.assets) ? (r as Obj).assets : [];
+  if (!list.length) return "You don't hold any RGB assets yet.";
+  const rows = list.map((a) => {
+    const raw = a.balance?.spendable ?? a.balance?.settled;
+    const amount = typeof raw === 'number' ? `${formatRgbAmount(raw, Number(a.precision) || 0)} ${a.ticker}` : 'balance unknown';
+    return `- ${a.ticker}${a.name && a.name !== a.ticker ? ` (${a.name})` : ''}: ${amount}`;
+  });
+  return `Your RGB assets:\n${rows.join('\n')}`;
+}
+
+export function defaultRenderFast(intent: string, result: unknown): string {
+  const r = parse(result) as Obj;
+  if (intent === 'balance') return renderBalance(r ?? {});
+  if (intent === 'assets') return renderAssets(r);
+  if (intent === 'address') {
+    return r?.address ? `Here's your receive address:\n\n\`${r.address}\`` : 'No address available right now.';
+  }
+  return `Bitcoin is $${Number(r?.price_usd ?? 0).toLocaleString('en-US')}.`;
+}

package/src/funnel.mind.test.ts

@@ -17,6 +17,7 @@
  * Fully deterministic (no node/model/maker), so it runs in CI. Live tool
  * execution against a real node is the separate mcp.live.test.ts.
  */
+import type { FastIntent } from './fastpath/fastpath.js';
 import { describe, expect, it } from 'vitest';
 import { Funnel } from './funnel.js';
 import { ToolRegistry } from './tools/registry.js';
@@ -83,7 +84,7 @@ function searchMerchants(query: string): string {
  */
 function buildMind(
   provider: LLMProvider,
-  opts: { skills?: Skill[]; log?: (m: string) => void } = {},
+  opts: { skills?: Skill[]; log?: (m: string) => void; fastIntents?: FastIntent[] } = {},
 ): { funnel: Funnel; calls: Array<{ name: string; args: any }> } {
   const calls: Array<{ name: string; args: any }> = [];
   const tool = (name: string, response: any, spend = false) => ({
@@ -140,27 +141,21 @@ function buildMind(
   ]);
 
   return {
-    funnel: new Funnel({ provider, tools, recipes: DESKTOP_RECIPES, maxTurns: 8, skills: opts.skills, log: opts.log }),
+    funnel: new Funnel({ provider, tools, recipes: DESKTOP_RECIPES, maxTurns: 8, skills: opts.skills, log: opts.log, ...(opts.fastIntents ? { fastIntents: opts.fastIntents } : {}) }),
     calls,
   };
 }
 
 describe('desktop mind — balance', () => {
-  it('routes "what\'s my balance?" to the agentic tier and calls rln_get_balances', async () => {
-    const { funnel, calls } = buildMind(
-      scripted([
-        { text: '', toolCalls: [{ name: 'rln_get_balances', arguments: {} }] },
-        { text: 'You have 1,949,753 sats in Lightning.' },
-      ]),
-    );
+  it('answers "what\'s my balance?" on the fast path with rln_get_balances, no model', async () => {
+    const { funnel, calls } = buildMind(scripted([]));
 
     const res = await funnel.runTurn("what's my balance?");
 
-    expect(res.tier).toBe('agentic');
-    expect(calls.map((c) => c.name)).toContain('rln_get_balances');
-    const exec = res.toolCalls?.find((c) => c.name === 'rln_get_balances');
-    expect((exec?.result as { lightning_balance_sat?: number })?.lightning_balance_sat).toBe(1_949_753);
-    expect(res.text).toBeTruthy();
+    expect(res.tier).toBe('fast');
+    expect(calls.map((c) => c.name)).toEqual(['rln_get_balances']);
+    expect((res.data as { lightning_balance_sat?: number })?.lightning_balance_sat).toBe(1_949_753);
+    expect(res.text).toBe('On-chain: 100,000 sats spendable.\nLightning: 1,949,753 sats.');
   });
 });
 
@@ -335,11 +330,13 @@ describe('desktop mind — skill scoping (real skills)', () => {
     expect(node.tools?.every((tool) => tool.startsWith('rln_'))).toBe(true);
   });
 
-  it('kaleido-trading drops the phantom kaleidoswap_get_nodeinfo / get_order_history names', () => {
+  it('kaleido-trading drops the phantom kaleidoswap_get_nodeinfo / removed order-flow names', () => {
     const trading = SKILLS.find((s) => s.name === 'kaleido-trading')!;
     expect(trading.tools).not.toContain('kaleidoswap_get_nodeinfo');
     expect(trading.tools).not.toContain('kaleidoswap_get_order_history');
-    expect(trading.tools).toEqual(expect.arrayContaining(['kaleidoswap_get_quote', 'kaleidoswap_place_order']));
+    expect(trading.tools).not.toContain('kaleidoswap_place_order');
+    expect(trading.tools).not.toContain('kaleidoswap_get_order_status');
+    expect(trading.tools).toEqual(expect.arrayContaining(['kaleidoswap_get_quote', 'kaleidoswap_atomic_init']));
     expect(trading.tools).not.toEqual(
       expect.arrayContaining([
         'kaleidoswap_get_spreads',
@@ -357,7 +354,8 @@ describe('desktop mind — skill scoping (real skills)', () => {
         { text: '', toolCalls: [{ name: 'rln_get_balances', arguments: {} }] },
         { text: 'You have 1,949,753 sats.' },
       ]),
-      { skills: SKILLS, log: (m) => logs.push(m) },
+      // Fast path off, so the balance ask exercises skill scoping.
+      { skills: SKILLS, log: (m) => logs.push(m), fastIntents: [] },
     );
 
     const res = await funnel.runTurn("what's my balance?");