@kaleidorg/mind 0.8.0 → 0.9.0

package/src/engine.ts

@@ -11,27 +11,26 @@
  * `{role:'tool'}` results into history each round, loop until the model stops
  * calling tools. Money tools pause for an `onConfirm` gate; their handlers run
  * wherever the ToolSource lives (on the phone for the wallet), even when
- * inference is delegated to a remote provider.
+ * inference runs on a remote server.
  */
 
-import type { ConfirmDecision, Message, ToolResult } from './types.js';
-import type { LLMProvider } from './providers/types.js';
-import type { InferenceMetrics, ToolCallError, ToolChoice } from './providers/types.js';
+import type { ConfirmDecision, Message, ToolCall, ToolDef, ToolResult } from './types.js';
+import type { InferenceMetrics, LLMProvider, 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 { callKey, declinedToolResult, detectWalletAction, hasCapableTool, noToolReply, validateToolArgs } from './guards.js';
 import { confirmReadback } from './wallet/confirm.js';
-import { annotateRgbBalances, fixRgbBalanceUnits } from './context/rgb-units.js';
+import { annotateRgbBalances } from './context/rgb-units.js';
+import {
+  REPEATED_CALL_REPLY,
+  TOOL_CALL_FAILED_REPLY,
+  cancelledReply,
+  engine,
+  finalizeAnswer,
+  model,
+  toolErrorFeedback,
+  type Answer,
+} from './engine/answer.js';
 import type { SkillRegistry } from './skills/registry.js';
 import type { Skill } from './skills/types.js';
 import { selectAvailableSkill } from './skills/select.js';
@@ -63,6 +62,8 @@ export interface EngineOptions {
    * 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.
@@ -105,6 +106,8 @@ export interface AgenticOptions {
    * 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;
 }
 
@@ -121,17 +124,16 @@ 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.`;
+/** State of one agentic run. */
+interface RunState {
+  history: Message[];
+  system?: string;
+  tools: ToolDef[];
+  executed: ToolResult[];
+  inference: InferenceMetrics[];
+  /** Calls made this run, by name + arguments, with their first result. */
+  seen: Map<string, { result: unknown; count: number }>;
+  lastRequestId?: string;
 }
 
 export class Engine {
@@ -142,6 +144,7 @@ export class Engine {
   private readonly compressOpts?: ToolCrushOptions;
   private readonly guardPaymentData: boolean;
   private readonly fixAmounts: boolean;
+  private readonly thinkOnForcedCalls: boolean;
   private readonly guardMissingTools: boolean;
   private readonly endTurnOnDecline: boolean;
 
@@ -152,6 +155,7 @@ export class Engine {
     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
@@ -175,221 +179,228 @@ export class Engine {
   }
 
   async runAgentic(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;
+    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 startedAt = Date.now();
-    const history: Message[] = [...messages];
+    const maxTurns = opts.maxTurns ?? this.defaultMaxTurns;
     const registryTools = await this.registry.listTools();
-    // Progressive disclosure: expose only the active skill's tools when set.
-    const allTools = opts.allowedTools
-      ? registryTools.filter((t) => opts.allowedTools!.includes(t.name))
-      : registryTools;
-    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 state: RunState = {
+      history: [...messages],
+      system: messages.some((m) => m.role === 'system') ? undefined : this.defaultSystem,
+      // Progressive disclosure: expose only the active skill's tools when set.
+      tools: opts.allowedTools ? registryTools.filter((t) => opts.allowedTools!.includes(t.name)) : registryTools,
+      executed: [],
+      inference: [],
+      seen: new Map(),
+    };
 
     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))) {
+    if (action && !hasCapableTool(action, state.tools.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 };
+      state.history.push({ role: 'assistant', content: text });
+      return { text, turns: 0, toolCalls: [], messages: state.history, latencyMs: Date.now() - startedAt, inference: state.inference };
     }
 
+    let answer: Answer = model('');
+    let turns = 0;
+    let toolErrorRetries = 0;
     // 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({
-        messages: history,
-        tools: allTools,
-        system,
-        ...(turn === 1 && opts.firstTurnToolChoice && allTools.length
-          ? { toolChoice: opts.firstTurnToolChoice }
-          : {}),
-        onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
-        signal: opts.signal,
+      // A forced first call only picks the tool and its arguments; reasoning
+      // there costs most of the turn's time on small models.
+      const forced = turn === 1 && opts.firstTurnToolChoice && state.tools.length;
+      const out = await this.callModel(state, opts, turn, {
+        tools: state.tools,
+        ...(forced ? { toolChoice: opts.firstTurnToolChoice, ...(this.thinkOnForcedCalls ? {} : { thinking: 'off' as const }) } : {}),
       });
-
-      lastRequestId = out.requestId;
-      if (out.inference) inference.push(out.inference);
       if (out.requestId) opts.onStart?.(out.requestId, turn);
-      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;
+      answer = model(out.incomplete ? '' : (out.text || '').trim());
+
+      if (!out.toolCalls?.length) {
+        // The model tried to call a tool but the call didn't parse: tell it
+        // what went wrong and let it try once more instead of showing the
+        // broken frame as the answer.
+        if (out.toolErrors?.length) {
+          if (toolErrorRetries < 1) {
+            toolErrorRetries += 1;
+            state.history.push({ role: 'assistant', content: out.rawContent || answer.text });
+            state.history.push({
+              role: 'tool',
+              content: JSON.stringify({ error: toolErrorFeedback(out.toolErrors, out.inference?.status === 'truncated') }),
+            });
+            continue;
+          }
+          answer = engine(TOOL_CALL_FAILED_REPLY);
+          break;
         }
-        finalText = TOOL_CALL_FAILED_MESSAGE;
-        engineReply = true;
-        break;
-      }
-
-      // No tool calls ⇒ the model produced its final answer.
-      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();
+        // No tool calls ⇒ the model produced its final answer.
+        if (!answer.text && state.executed.length) answer = await this.recoverAnswer(state, opts, turn);
+        else if (!answer.text && out.incomplete) answer = model((out.text || '').trim());
         break;
       }
 
       // Anchor the next turn with the raw assistant frame.
-      history.push({ role: 'assistant', content: out.rawContent || finalText });
+      state.history.push({ role: 'assistant', content: out.rawContent || answer.text });
 
       let repeatedAgain = false;
-      const declinedThisTurn: string[] = [];
+      const declined: 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 (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 {
-            args = check.args;
-            result = await this.safeExecute(call.name, args);
-          }
-        }
-
-        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) });
+        const step = await this.executeCall(state, call, opts, turn);
+        repeatedAgain ||= step.repeatedAgain;
+        if (step.declined) declined.push(step.declined);
       }
 
-      if (this.endTurnOnDecline && declinedThisTurn.length && declinedThisTurn.length === out.toolCalls.length) {
-        finalText = `Cancelled — you declined: ${declinedThisTurn.join('; ')}. Nothing was sent or changed.`;
-        engineReply = true;
+      if (this.endTurnOnDecline && declined.length && declined.length === out.toolCalls.length) {
+        answer = engine(cancelledReply(declined));
         break;
       }
 
       if (repeatedAgain) {
-        const forced = await this.provider.runTurn({
-          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.';
+        const last = await this.callModel(state, opts, turn, { tools: [] });
+        const text = (last.text || '').trim();
+        answer = text ? model(text) : engine(REPEATED_CALL_REPLY);
         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);
     }
 
+    const text = finalizeAnswer(answer, {
+      fixAmounts: this.fixAmounts,
+      guardPaymentData: this.guardPaymentData,
+      sources: [...messages.map((m) => m.content), ...state.executed.map((e) => e.result)],
+      toolResults: state.executed.map((e) => e.result),
+      aborted: !!opts.signal?.aborted,
+    });
     // Append the final answer so the returned conversation is complete (the
     // loop breaks before pushing the no-tool-call turn).
-    if (finalText) history.push({ role: 'assistant', content: finalText });
+    if (text) state.history.push({ role: 'assistant', content: text });
 
     return {
-      text: finalText,
+      text,
       turns,
-      toolCalls: executed,
-      requestId: lastRequestId,
-      messages: history,
+      toolCalls: state.executed,
+      requestId: state.lastRequestId,
+      messages: state.history,
       latencyMs: Date.now() - startedAt,
-      inference,
+      inference: state.inference,
     };
   }
 
+  /** One model call within the run's session; records its receipt. */
+  private async callModel(
+    state: RunState,
+    opts: AgenticOptions,
+    turn: number,
+    extra: { tools: ToolDef[]; messages?: Message[]; toolChoice?: ToolChoice; thinking?: 'off' },
+  ) {
+    const out = await this.provider.runTurn({
+      messages: extra.messages ?? state.history,
+      system: state.system,
+      sessionKey: opts.sessionKey,
+      ...extra,
+      onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+      signal: opts.signal,
+    });
+    if (out.inference) state.inference.push(out.inference);
+    if (out.requestId) state.lastRequestId = out.requestId;
+    return out;
+  }
+
+  /**
+   * Validate, confirm (for spends) and execute one tool call, and add its
+   * result to the history. Returns the readback when the user declined it.
+   */
+  private async executeCall(
+    state: RunState,
+    call: ToolCall,
+    opts: AgenticOptions,
+    turn: number,
+  ): Promise<{ repeatedAgain: boolean; declined?: string }> {
+    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 = state.seen.get(key);
+    let repeatedAgain = false;
+    let declined: string | undefined;
+
+    let args = call.arguments;
+    let result: unknown;
+    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);
+          declined = summary ? summary.replace(/\.?\s*Confirm\?$/, '') : call.name.replace(/_/g, ' ');
+        }
+      } else {
+        args = check.args;
+        result = await this.safeExecute(call.name, args);
+      }
+    }
+
+    if (!previous) {
+      // A mutating (confirm-gated) call can change what reads return.
+      if (def?.requiresConfirmation) state.seen.clear();
+      state.seen.set(key, { result, count: 1 });
+    }
+    state.executed.push({ name: call.name, arguments: args, result });
+    opts.onToolResult?.({ name: call.name, arguments: args, result }, turn);
+    state.history.push({ role: 'tool', content: this.toHistoryContent(this.fixAmounts ? annotateRgbBalances(result) : result) });
+    return { repeatedAgain, ...(declined ? { declined } : {}) };
+  }
+
   /**
    * 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({
+  private async recoverAnswer(state: RunState, opts: AgenticOptions, turn: number): Promise<Answer> {
+    if (opts.signal?.aborted) return model('');
+    const retry = await this.callModel(state, opts, turn, {
+      tools: [],
       messages: [
-        ...history,
+        ...state.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]!;
+    if (text) return model(text);
+    const last = state.executed[state.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}`;
+    return engine(
+      `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> {

package/src/evidence.ts

@@ -27,7 +27,7 @@ export interface EvidenceEvent {
   model?: {
     name: string;
     version?: string;
-    source?: 'local' | 'delegated';
+    source?: 'local' | 'remote';
   };
   hardware?: {
     device: string;

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')}.`;
+}