@kaleidorg/mind 0.6.0 → 0.6.2

package/src/flashnet/contract.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FLASHNET_TOOLS,
+  FLASHNET_SPEND_TOOLS,
+  isFlashnetSpendTool,
+  getFlashnetTool,
+  bindFlashnetTools,
+  type FlashnetHandler,
+} from './contract.js';
+
+describe('FLASHNET_TOOLS — shape invariants', () => {
+  it('exposes the expected tool names in order', () => {
+    expect(FLASHNET_TOOLS.map((t) => t.name)).toEqual([
+      'flashnet_list_pools',
+      'flashnet_get_pool',
+      'flashnet_simulate_swap',
+      'flashnet_execute_swap',
+      'flashnet_get_balance',
+    ]);
+  });
+
+  it('every tool has an object parameters schema', () => {
+    for (const t of FLASHNET_TOOLS) {
+      expect((t.parameters as any)?.type).toBe('object');
+    }
+  });
+
+  it('aligns spend ↔ requiresConfirmation', () => {
+    for (const t of FLASHNET_TOOLS) {
+      expect(!!t.spend).toBe(!!t.requiresConfirmation);
+    }
+  });
+
+  it('marks only flashnet_execute_swap as spend', () => {
+    expect([...FLASHNET_SPEND_TOOLS]).toEqual(['flashnet_execute_swap']);
+    expect(isFlashnetSpendTool('flashnet_execute_swap')).toBe(true);
+    expect(isFlashnetSpendTool('flashnet_simulate_swap')).toBe(false);
+    expect(isFlashnetSpendTool('flashnet_list_pools')).toBe(false);
+  });
+
+  it('getFlashnetTool returns by name', () => {
+    expect(getFlashnetTool('flashnet_simulate_swap')?.name).toBe('flashnet_simulate_swap');
+    expect(getFlashnetTool('nope')).toBeUndefined();
+  });
+
+  it('execute_swap requires the canonical 5 fields', () => {
+    const def = getFlashnetTool('flashnet_execute_swap')!;
+    expect((def.parameters as any).required).toEqual([
+      'pool_id', 'asset_in_address', 'asset_out_address', 'amount_in', 'min_amount_out',
+    ]);
+  });
+
+  it('simulate_swap requires pool + assets + amount but no slippage', () => {
+    const def = getFlashnetTool('flashnet_simulate_swap')!;
+    expect((def.parameters as any).required).toEqual([
+      'pool_id', 'asset_in_address', 'asset_out_address', 'amount_in',
+    ]);
+  });
+});
+
+describe('bindFlashnetTools', () => {
+  const echoHandlers = (): Record<string, FlashnetHandler> => ({
+    flashnet_list_pools:    async (a) => ({ ok: true, t: 'list_pools', args: a }),
+    flashnet_get_pool:      async (a) => ({ ok: true, t: 'get_pool', args: a }),
+    flashnet_simulate_swap: async (a) => ({ ok: true, t: 'simulate_swap', args: a }),
+    flashnet_execute_swap:  async (a) => ({ ok: true, t: 'execute_swap', args: a }),
+    flashnet_get_balance:   async () => ({ btc_sats: 100000, tokens: [] }),
+  });
+
+  it('binds every tool and preserves the spend gate', () => {
+    const src = bindFlashnetTools(echoHandlers());
+    expect(src.listTools().length).toBe(5);
+    const exec = src.listTools().find((t) => t.name === 'flashnet_execute_swap');
+    expect(exec?.requiresConfirmation).toBe(true);
+    const sim = src.listTools().find((t) => t.name === 'flashnet_simulate_swap');
+    expect(sim?.requiresConfirmation).toBeFalsy();
+  });
+
+  it('dispatches with args', async () => {
+    const src = bindFlashnetTools(echoHandlers());
+    const r = await src.execute('flashnet_simulate_swap', {
+      pool_id: 'p1',
+      asset_in_address: 'btc',
+      asset_out_address: 'usdb',
+      amount_in: '100000',
+    });
+    expect(r).toMatchObject({ ok: true, t: 'simulate_swap' });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    const partial = { flashnet_list_pools: echoHandlers().flashnet_list_pools };
+    expect(() => bindFlashnetTools(partial)).toThrow(/no handler/);
+    const src = bindFlashnetTools(partial, { allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['flashnet_list_pools']);
+  });
+
+  it('uses opts.id for the ToolSource id', () => {
+    const src = bindFlashnetTools(echoHandlers(), { id: 'flashnet-regtest' });
+    expect(src.id).toBe('flashnet-regtest');
+  });
+});

package/src/flashnet/contract.ts

@@ -0,0 +1,164 @@
+/**
+ * Canonical Flashnet tool contract — AMM swaps on Spark.
+ *
+ * Flashnet is a Spark-native AMM (constant-product + V3 concentrated-liquidity
+ * pools). The agent surface is small and intent-aligned:
+ *
+ *   flashnet_list_pools       — discover pools by asset pair (read)
+ *   flashnet_get_pool         — pool details + reserves (read)
+ *   flashnet_simulate_swap    — quote a swap, no funds move (read)
+ *   flashnet_execute_swap     — SPEND, confirmation-gated (the swap itself)
+ *   flashnet_get_balance      — Spark wallet balance (BTC + tokens) as the
+ *                               AMM client sees it
+ *
+ * The model picks a pool, simulates to see the rate/output, optionally shows
+ * the user the quote, and then executes. The host's `FlashnetClient` (built
+ * over a `SparkWallet`) does the actual signing.
+ *
+ * Asset addresses on Flashnet:
+ *   - BTC is a constant pubkey: `BTC_ASSET_PUBKEY` per network.
+ *   - Tokens are Spark Bech32m token identifiers (or hex; the client coerces).
+ *
+ * Pure data — no deps, RN-safe.
+ */
+
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { InProcessTool } from '../tools/in-process.js';
+
+export interface FlashnetToolDef extends ToolDef {
+  /** Moves funds → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<
+  string,
+  { type: string; description?: string; enum?: string[]; items?: unknown }
+>;
+
+function t(
+  name: string,
+  description: string,
+  properties: Props = {},
+  required: string[] = [],
+  spend = false,
+): FlashnetToolDef {
+  return {
+    name,
+    description,
+    spend,
+    requiresConfirmation: spend,
+    parameters: { type: 'object', properties, required },
+  };
+}
+
+/** Canonical Flashnet tools. */
+export const FLASHNET_TOOLS: FlashnetToolDef[] = [
+  t(
+    'flashnet_list_pools',
+    "List Flashnet AMM pools. Filter by asset pair to find a venue for a swap (e.g. asset_a=BTC, asset_b=<USDB address> → pools that swap between them). Returns pools sorted by TVL by default. Use this BEFORE simulate_swap to pick a `pool_id`.",
+    {
+      asset_a: { type: 'string', description: 'OPTIONAL — first asset address (BTC pubkey or Spark token id). Filters pools.' },
+      asset_b: { type: 'string', description: 'OPTIONAL — second asset address. Filters pools containing both assets.' },
+      sort: { type: 'string', description: 'OPTIONAL — sort order. Default TVL_DESC.', enum: ['TVL_DESC', 'TVL_ASC', 'VOLUME24H_DESC', 'VOLUME24H_ASC', 'CREATED_AT_DESC', 'CREATED_AT_ASC'] },
+      limit: { type: 'number', description: 'OPTIONAL — max pools (1–50, default 10).' },
+    },
+  ),
+
+  t(
+    'flashnet_get_pool',
+    "Get a single pool's details — reserves, fees, current price, TVL. Use after flashnet_list_pools when the user wants to inspect a pool before swapping.",
+    {
+      pool_id: { type: 'string', description: 'Pool id (LP pubkey) from flashnet_list_pools.' },
+    },
+    ['pool_id'],
+  ),
+
+  t(
+    'flashnet_simulate_swap',
+    "Simulate a swap WITHOUT executing — returns `amount_out`, `execution_price`, `price_impact_pct`, `fee_paid`. Read-only. Use this to quote the user before they confirm. The `amount_in` is in smallest units of `asset_in` (sats for BTC, smallest unit of the token).",
+    {
+      pool_id:           { type: 'string', description: 'Pool id from flashnet_list_pools.' },
+      asset_in_address:  { type: 'string', description: 'Address of the asset the user is selling (BTC pubkey or Spark token id).' },
+      asset_out_address: { type: 'string', description: 'Address of the asset the user is buying.' },
+      amount_in:         { type: 'string', description: 'Amount to swap, in smallest units of asset_in. Strings (BigInt-safe). e.g. "100000" for 100k sats.' },
+    },
+    ['pool_id', 'asset_in_address', 'asset_out_address', 'amount_in'],
+  ),
+
+  t(
+    'flashnet_execute_swap',
+    "SPEND: confirmation-gated. Execute a swap quoted by flashnet_simulate_swap. `min_amount_out` and `max_slippage_bps` cap the worst-case fill (basis points: 100 = 1%, 50 = 0.5%). Returns the swap request id and the amount actually received.",
+    {
+      pool_id:           { type: 'string', description: 'Pool id from flashnet_list_pools.' },
+      asset_in_address:  { type: 'string' },
+      asset_out_address: { type: 'string' },
+      amount_in:         { type: 'string', description: 'Amount to swap, smallest units.' },
+      min_amount_out:    { type: 'string', description: 'Minimum acceptable output, smallest units. Calculate from simulate_swap.amount_out × (1 − max_slippage_bps/10000) and pass that — never trust the simulated value as-is.' },
+      max_slippage_bps:  { type: 'number', description: 'Maximum slippage in basis points (default 50 = 0.5%). 100 = 1%, 500 = 5%.' },
+    },
+    ['pool_id', 'asset_in_address', 'asset_out_address', 'amount_in', 'min_amount_out'],
+    /* spend */ true,
+  ),
+
+  t(
+    'flashnet_get_balance',
+    "Get the Spark wallet's BTC + token balances as the Flashnet client sees them. Useful to verify the user has enough of asset_in before quoting or executing a swap. Returns `{ btc_sats, tokens: [{ address, balance, symbol?, decimals? }] }`.",
+  ),
+];
+
+/** All Flashnet tool names that move funds (confirmation-gated). */
+export const FLASHNET_SPEND_TOOLS: Set<string> = new Set(
+  FLASHNET_TOOLS.filter((t) => t.spend).map((t) => t.name),
+);
+
+export function isFlashnetSpendTool(name: string): boolean {
+  return FLASHNET_SPEND_TOOLS.has(name);
+}
+
+export function getFlashnetTool(name: string): FlashnetToolDef | undefined {
+  return FLASHNET_TOOLS.find((t) => t.name === name);
+}
+
+/** A handler bound to one Flashnet tool. */
+export type FlashnetHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindFlashnetOptions {
+  /** Skip tools without a handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  /** ToolSource id for the registry (default 'flashnet'). */
+  id?: string;
+}
+
+/**
+ * Bind Flashnet contract tools to in-process handlers → an InProcessToolSource.
+ *
+ *   const source = bindFlashnetTools({
+ *     flashnet_list_pools:     async (a) => client.listPools(a),
+ *     flashnet_get_pool:       async ({ pool_id }) => client.getPoolDetails(pool_id),
+ *     flashnet_simulate_swap:  async (a) => client.simulateSwap(a),
+ *     flashnet_execute_swap:   async (a) => client.executeSwap(a),
+ *     flashnet_get_balance:    async () => client.getBalance(),
+ *   });
+ */
+export function bindFlashnetTools(
+  handlers: Record<string, FlashnetHandler>,
+  opts: BindFlashnetOptions = {},
+): InProcessToolSource {
+  const bound: InProcessTool[] = [];
+  for (const def of FLASHNET_TOOLS) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindFlashnetTools: no handler for "${def.name}"`);
+    }
+    bound.push({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+      requiresConfirmation: def.requiresConfirmation,
+      handler,
+    });
+  }
+  return new InProcessToolSource(opts.id ?? 'flashnet', bound);
+}

package/src/funnel.mind.test.ts

@@ -110,10 +110,8 @@ function buildMind(
       // atomic-swap chain (quote read; init/whitelist/execute are spends)
       tool('kaleidoswap_get_quote', {
         rfq_id: 'rfq-1',
-        from_asset: { asset_id: 'BTC', ticker: 'BTC', amount: 100_000 },
-        to_asset: { asset_id: 'rgb:USDT', ticker: 'USDT', amount: 1_000_000 },
-        from_amount_display: '100,000 sats',
-        to_amount_display: '1 USDT',
+        from_asset: { asset_id: 'BTC', ticker: 'BTC', layer: 'BTC_LN', amount_raw: 100_000, amount_display: '100,000 sats' },
+        to_asset: { asset_id: 'rgb:USDT', ticker: 'USDT', layer: 'RGB_LN', amount_raw: 1_000_000, amount_display: '1 USDT' },
         fee_display: '154 sats',
       }),
       tool('kaleidoswap_atomic_init', { swapstring: 'SWAP/abc/def', payment_hash: 'ph-1' }, /* spend */ true),
@@ -226,7 +224,7 @@ describe('desktop mind — buy assets via atomic swap', () => {
     ]);
     // init sources the asset ids + maker-unit amounts straight from the quote.
     const init = calls.find((c) => c.name === 'kaleidoswap_atomic_init')!;
-    expect(init.args).toMatchObject({ rfq_id: 'rfq-1', from_asset: 'BTC', to_asset: 'rgb:USDT' });
+    expect(init.args).toMatchObject({ rfq_id: 'rfq-1', from_asset_id: 'BTC', to_asset_id: 'rgb:USDT' });
     // execute carries the node pubkey as taker_pubkey + the maker's payment_hash.
     const exec = calls.find((c) => c.name === 'kaleidoswap_atomic_execute')!;
     expect(exec.args).toMatchObject({ swapstring: 'SWAP/abc/def', taker_pubkey: '030637ec', payment_hash: 'ph-1' });

package/src/funnel.ts

@@ -20,6 +20,7 @@
  */
 
 import { Engine } from './engine.js';
+import type { ToolCrushOptions } from './context/compress.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { FastPath, WALLET_FAST_INTENTS } from './fastpath/fastpath.js';
 import type { FastIntent } from './fastpath/fastpath.js';
@@ -31,6 +32,7 @@ import type { Recipe } from './recipe/types.js';
 import { SkillRegistry } from './skills/registry.js';
 import type { Skill } from './skills/types.js';
 import type { LLMProvider } from './providers/types.js';
+import type { InferenceMetrics } from './providers/types.js';
 import type { Retriever } from './rag/retriever.js';
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 
@@ -123,6 +125,8 @@ export interface FunnelResult {
   /** Agentic tier only: executed tool calls + reasoning turns. */
   toolCalls?: ToolResult[];
   turns?: number;
+  /** Agentic tier only: one local-inference receipt per model call. */
+  inference?: InferenceMetrics[];
 }
 
 export interface FunnelOptions {
@@ -139,6 +143,13 @@ export interface FunnelOptions {
   system?: string;
   /** Max reasoning↔tool rounds in the agentic tier. Default 5. */
   maxTurns?: number;
+  /**
+   * Crush verbose tool results before they re-enter the agentic loop's history,
+   * so a tiny on-device model's window isn't drowned in repetitive JSON. `true`
+   * uses safe defaults (amounts/addresses/invoices preserved); pass options to
+   * tune. Off by default. See compressToolResult.
+   */
+  compressToolOutput?: boolean | ToolCrushOptions;
   /** User settings, read fresh each turn. */
   getSettings?: () => FunnelSettings;
   /** Render a fast-path tool result as user-facing text. Default: built-in. */
@@ -196,6 +207,7 @@ export class Funnel {
       provider: opts.provider,
       tools: opts.tools,
       defaultMaxTurns: opts.maxTurns ?? 5,
+      compressToolOutput: opts.compressToolOutput,
     });
     this.fastPath = new FastPath(opts.fastIntents ?? WALLET_FAST_INTENTS);
     this.recipes = new RecipeRegistry(opts.recipes ?? [assetSendRecipe, paymentsRecipe, receiveRecipe]);
@@ -226,6 +238,8 @@ export class Funnel {
 
   async runTurn(text: string, cbs: FunnelCallbacks = {}): Promise<FunnelResult> {
     const settings = this.getSettings();
+    const memoryOn = settings.memoryEnabled !== false;
+    const ragOn = settings.ragEnabled !== false;
 
     // ── T0: deterministic fast-path (no LLM) ──
     // Only fires when the host's registry actually implements the intent's
@@ -247,15 +261,27 @@ export class Funnel {
     //       running steps with bad data.
     // Either way the registry must implement the recipe's final action.
     const recipe = this.recipes.select(text);
-    const slots = recipe?.extract?.(text) ?? null;
-    const deterministicallyConfident =
-      !!slots && (recipe?.confident ? recipe.confident(slots) : Object.keys(slots).length > 0);
+    // For forceModelExtract recipes (channel-order, atomic) the det extractor is
+    // de-emphasized: only used inside runRecipe as a backfill safety net; firing
+    // decision + log do not depend on brittle regex for varied NL.
+    let slotsForLog: any = null;
+    let detConfident = false;
+    if (recipe) {
+      if (recipe.forceModelExtract === true) {
+        slotsForLog = { forceModelExtract: true };
+        detConfident = true; // force path handles via LLM inside; prefilter only needs tool presence
+      } else {
+        const d = recipe.extract?.(text) ?? null;
+        slotsForLog = d;
+        detConfident = !!d && (recipe.confident ? recipe.confident(d) : Object.keys(d).length > 0);
+      }
+    }
     const fires =
       !!recipe &&
-      (recipe.forceModelExtract === true || deterministicallyConfident) &&
+      (recipe.forceModelExtract === true || detConfident) &&
       !!(await this.registry.getDef(recipe.final.tool));
     if (recipe && fires) {
-      this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slots)}`);
+      this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slotsForLog)}`);
       const res = await runRecipe(recipe, text, {
         provider: this.provider,
         tools: this.registry,
@@ -265,6 +291,26 @@ export class Funnel {
           cbs.onStep?.(name);
         },
       });
+      // Auto-remember ids/tokens from recipe summaries (the "remember: ..." lines)
+      // via the tool so status follow-ups can reliably recall even cross-session.
+      if (res.status === 'done' && memoryOn) {
+        try {
+          const hasRemember = await this.registry.getDef('remember');
+          if (hasRemember) {
+            const text = res.text || '';
+            const lines = text.split(/\n+/).filter((l) => /^\s*remember:/i.test(l));
+            for (const line of lines) {
+              const clean = line.trim();
+              if (clean.length > 8) {
+                void this.registry
+                  .execute('remember', { text: clean, kind: 'event', tags: ['recipe', 'order', 'status'] })
+                  .catch(() => {});
+                this.log(`auto-remembered: ${clean.slice(0, 80)}`);
+              }
+            }
+          }
+        } catch {}
+      }
       return { text: res.text, tier: 'recipe', route: recipe.name };
     }
 
@@ -278,7 +324,6 @@ export class Funnel {
     // RAG block sits above history so the model treats it as authoritative).
     // Only fires for agentic turns and only when the host opts in via
     // `retriever` AND the user hasn't disabled RAG in settings.
-    const ragOn = settings.ragEnabled !== false;
     if (this.retriever && ragOn && this.topKRag > 0) {
       try {
         const hits = await this.retriever.search(text, this.topKRag);
@@ -296,7 +341,6 @@ export class Funnel {
 
     // Ambient tools stay available even when a skill narrows the set — gated
     // by the user's memory/knowledge toggles (default on).
-    const memoryOn = settings.memoryEnabled !== false;
     const ambient = [...(memoryOn ? AMBIENT_MEMORY : []), ...(ragOn ? AMBIENT_RAG : [])];
     const disabledAmbient = [...(memoryOn ? [] : AMBIENT_MEMORY), ...(ragOn ? [] : AMBIENT_RAG)];
     let scoped: string[] | undefined;
@@ -349,6 +393,13 @@ export class Funnel {
       onToolResult: cbs.onToolResult,
       onConfirm: cbs.onConfirm,
     });
-    return { text: res.text ?? '', tier: 'agentic', route: skill?.name, toolCalls: res.toolCalls, turns: res.turns };
+    return {
+      text: res.text ?? '',
+      tier: 'agentic',
+      route: skill?.name,
+      toolCalls: res.toolCalls,
+      turns: res.turns,
+      inference: res.inference,
+    };
   }
 }

package/src/index.ts

@@ -17,7 +17,12 @@ export type {
   ConfirmDecision,
 } from './types.js';
 
-export type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+export type {
+  InferenceMetrics,
+  LLMProvider,
+  TurnInput,
+  TurnOutput,
+} from './providers/types.js';
 
 export type { ToolSource } from './tools/source.js';
 export { InProcessToolSource } from './tools/in-process.js';
@@ -81,12 +86,41 @@ export type {
   BindLsps1Options,
 } from './lsps1/contract.js';
 
+// ── Bitrefill (gift cards / mobile top-ups / eSIMs) ─────────────────────────
+export {
+  BITREFILL_TOOLS,
+  BITREFILL_SPEND_TOOLS,
+  isBitrefillSpendTool,
+  getBitrefillTool,
+  bindBitrefillTools,
+} from './bitrefill/contract.js';
+export type {
+  BitrefillToolDef,
+  BitrefillHandler,
+  BindBitrefillOptions,
+} from './bitrefill/contract.js';
+
+// ── Flashnet (Spark-native AMM — swaps over Spark) ──────────────────────────
+export {
+  FLASHNET_TOOLS,
+  FLASHNET_SPEND_TOOLS,
+  isFlashnetSpendTool,
+  getFlashnetTool,
+  bindFlashnetTools,
+} from './flashnet/contract.js';
+export type {
+  FlashnetToolDef,
+  FlashnetHandler,
+  BindFlashnetOptions,
+} from './flashnet/contract.js';
+
 // ── KaleidoSwap recipes (opt-in — register via Funnel.recipes) ──
 // price recipe is read-only (quote-only); atomic recipe runs the full swap.
 // Register the price recipe FIRST so phrasings like "BTC price" are answered
 // without firing any spend.
 export { kaleidoswapPriceRecipe } from './recipe/kaleidoswap-price.js';
 export { kaleidoswapAtomicRecipe } from './recipe/kaleidoswap-atomic.js';
+export { flashnetSwapRecipe } from './recipe/flashnet-swap.js';
 export {
   kaleidoswapChannelOrderRecipe,
   extractChannelOrder,
@@ -147,6 +181,8 @@ export {
   contextBudgetTokens,
 } from './context/budget.js';
 export type { BudgetReserves } from './context/budget.js';
+export { compressToolResult, DEFAULT_PRESERVE_KEYS } from './context/compress.js';
+export type { ToolCrushOptions, CrushResult } from './context/compress.js';
 export { capabilityProfile } from './capabilities.js';
 export type { CapabilityInput, MindCapabilities } from './capabilities.js';
 
@@ -187,6 +223,20 @@ export type { Skill, SkillReference, SkillSelector } from './skills/types.js';
 export { TurnLogger, defaultMask } from './logger.js';
 export type { TurnLog, Device, LoggerIO, LoggerOptions } from './logger.js';
 
+export {
+  EVIDENCE_SCHEMA,
+  EvidenceRecorder,
+  sanitizeEvidenceEvent,
+} from './evidence.js';
+export type {
+  EvidenceEvent,
+  EvidenceEventType,
+  EvidenceInput,
+  EvidenceIO,
+  EvidenceRecorderOptions,
+  EvidenceSurface,
+} from './evidence.js';
+
 // ── Autonomy (the task brain: scheduled tasks + run history + spend guardrails)
 // The operational half of the agent's memory — the state nanobot kept in
 // tasks.json + cron + run history, lifted into core (storage/timers injected).

package/src/kaleidoswap/contract.ts

@@ -100,7 +100,7 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
       order_id: { type: 'string', description: 'The order id returned by kaleidoswap_place_order.' },
       access_token: { type: 'string', description: 'The per-order access token returned by kaleidoswap_place_order. Required for status checks on the order.' },
     },
-    ['order_id']),
+    ['order_id', 'access_token']),
 
   t('orders',
     'kaleidoswap_get_order_history',

package/src/knowledge/bitcoin-copilot.ts

@@ -285,4 +285,98 @@ export const BITCOIN_COPILOT_DOCS: RagDocument[] = [
       "(not just inbound capacity).",
     metadata: { topic: 'rgb-channels' },
   },
+
+  // ── Layer / protocol taxonomy ─────────────────────────────────────────
+  // The single biggest source of model confusion is mixing up which assets
+  // live on which layer. Small models pattern-match on "USDT" or "Bitcoin"
+  // and assume every L2 supports every asset — they don't. Each L2 has its
+  // OWN asset family, and assets do not move between them without an
+  // explicit cross-layer swap or bridge.
+
+  {
+    id: 'kaleidomind-layers-overview',
+    text:
+      'This wallet supports THREE distinct Bitcoin L2s, each with its own ' +
+      'asset family. They are NOT interchangeable: a balance on one layer ' +
+      'cannot be spent on another without an explicit swap. ' +
+      '(1) SPARK — an off-chain BTC scaling layer (Lightspark / buildonspark, ' +
+      'Statechains-based). Assets: BTC (sats) + Spark-native tokens like ' +
+      'USDB. Tools: spark_* (balance/address/invoice/pay). Swap venue: ' +
+      'Flashnet AMM (BTC ⇄ Spark tokens). ' +
+      '(2) RLN / RGB — a Lightning node that carries RGB assets over ' +
+      'BOLT11 channels (colored channels). Assets: BTC + RGB assets like ' +
+      'USDT, XAUT. Tools: rln_* (nodeinfo/invoice/pay/whitelist). Swap ' +
+      'venue: KaleidoSwap maker (BTC ⇄ RGB assets via atomic HTLC swap). ' +
+      '(3) ARKADE — an Ark-based off-chain BTC layer. Assets: BTC. Tools: ' +
+      'arkade_* (balance/address/send). No native non-BTC assets today.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'spark-layer-assets',
+    text:
+      'Spark is an off-chain BTC scaling layer (Lightspark / buildonspark). ' +
+      "It holds BTC (sats) and Spark-native tokens. USDB is a Spark token. " +
+      'Spark addresses look like spark1… (or sparkrt1… on regtest). ' +
+      'CRITICAL: Spark does NOT carry RGB assets. USDT and XAUT are RGB ' +
+      'assets that live on the RLN (RGB Lightning Node) layer — not on ' +
+      "Spark. A user's USDT balance, if they have one, is on RLN, NOT " +
+      'Spark. Conversely, USDB lives only on Spark (and trades on ' +
+      'Flashnet); it has no presence on RLN/RGB. When asked "what assets ' +
+      'are on Spark / what can I trade on Spark", answer with Spark-native ' +
+      'tokens (BTC + USDB and any other Spark tokens the AMM lists via ' +
+      'flashnet_list_pools), NOT USDT/XAUT/RGB.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'rln-layer-assets',
+    text:
+      'RLN (RGB Lightning Node) is a Lightning node that carries RGB ' +
+      'assets over BOLT11 channels (a.k.a. colored channels). It holds ' +
+      'BTC on standard Lightning channels and RGB assets — USDT, XAUT, ' +
+      'and any other client-side-validated asset issued via RGB — on ' +
+      'asset channels. Each asset needs its own channel. RGB assets do ' +
+      'NOT live on Spark or Arkade; they are RLN-only. Swap venue for ' +
+      'BTC ⇄ RGB asset is the KaleidoSwap maker (atomic HTLC: quote → ' +
+      'init → whitelist → execute). To receive an RGB asset over ' +
+      'Lightning, you first need an LSPS1-opened asset channel.',
+    metadata: { topic: 'layers' },
+  },
+
+  {
+    id: 'swap-venue-split',
+    text:
+      "Two swap venues, two asset families — DO NOT confuse them. " +
+      "FLASHNET is a Spark-native AMM. It trades between BTC and " +
+      "Spark-native tokens (e.g. USDB). It uses the same Spark wallet " +
+      "as the user's balance. Tools: flashnet_list_pools, " +
+      "flashnet_simulate_swap, flashnet_execute_swap. Skill: " +
+      "flashnet-swaps. ASSETS: BTC, USDB, and anything else " +
+      "flashnet_list_pools returns. NEVER offer USDT/XAUT on Flashnet. " +
+      "KALEIDOSWAP is an atomic HTLC maker. It trades between BTC and " +
+      "RGB assets (USDT, XAUT). It uses the RLN node. Tools: " +
+      "kaleidoswap_get_quote, kaleidoswap_atomic_init, " +
+      "kaleidoswap_atomic_execute. Skill: kaleido-trading. ASSETS: BTC, " +
+      "USDT, XAUT, and other RGB assets the maker prices. NEVER offer " +
+      "USDB on KaleidoSwap.",
+    metadata: { topic: 'venues' },
+  },
+
+  {
+    id: 'asset-to-layer-routing',
+    text:
+      "How to route by asset name. The asset names tell you which layer " +
+      "to use — don't guess: " +
+      "BTC / sats → all layers (Spark / RLN / Arkade / on-chain) carry " +
+      "BTC; pick by user context. " +
+      "USDB → Spark only, via Flashnet (flashnet-swaps). " +
+      "USDT → RLN/RGB only, via KaleidoSwap (kaleido-trading). " +
+      "XAUT (tether-gold) → RLN/RGB only, via KaleidoSwap. " +
+      "If a user names an asset you don't recognise, do NOT assume a " +
+      "layer — ask, or list pools/assets via the right tool first " +
+      "(flashnet_list_pools for Spark-side, kaleidoswap_get_pairs / " +
+      "kaleidoswap_get_assets for RGB-side).",
+    metadata: { topic: 'venues' },
+  },
 ];

package/src/providers/types.ts

@@ -22,6 +22,22 @@ export interface TurnInput {
   signal?: AbortSignal;
 }
 
+/** Judge-auditable metrics for one provider inference request. */
+export interface InferenceMetrics {
+  requestId?: string;
+  backendDevice?: 'cpu' | 'gpu';
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  /** Milliseconds from completion() start to the first generated delta. */
+  ttftMs?: number;
+  /** End-to-end completion duration measured by the host. */
+  durationMs: number;
+  tokensPerSecond?: number;
+  stopReason?: string;
+  status: 'completed' | 'cancelled' | 'truncated' | 'failed';
+}
+
 export interface TurnOutput {
   /** Cleaned assistant content for display. */
   text: string;
@@ -36,6 +52,8 @@ export interface TurnOutput {
   toolCalls: ToolCall[];
   /** Provider request id, for cancellation. */
   requestId?: string;
+  /** Optional local-inference receipt. Hosts may persist this as JSONL evidence. */
+  inference?: InferenceMetrics;
 }
 
 export interface LLMProvider {