@kaleidorg/mind 0.1.0 → 0.2.0

package/dist/wallet/contract.js

@@ -0,0 +1,113 @@
+/**
+ * Canonical multi-L2 wallet tool contract — the single source of truth for
+ * KaleidoMind's wallet tools (names + JSON schemas + spend flags).
+ *
+ * Every surface implements THESE EXACT tools, only the transport differs:
+ *   - mobile  → in-process handlers over the WDK adapters (`bindWalletTools`)
+ *   - desktop → kaleido-mcp (tools namespaced per layer) + a `kaleido` CLI
+ *   - eval    → stub handlers
+ *
+ * Because the schemas are identical everywhere, skills are portable and the
+ * model comparison is honest. Tools are namespaced per layer (`spark_*`,
+ * `rln_*`, `arkade_*`, `liquid_*`); cross-cutting router/helpers are unprefixed.
+ *
+ * Spend tools (move funds) carry `spend: true` → `requiresConfirmation: true`,
+ * so the Engine always pauses for the host's confirm gate before executing.
+ *
+ * Pure data — no deps, RN-safe.
+ */
+import { InProcessToolSource } from '../tools/in-process.js';
+function t(layer, name, description, properties = {}, required = [], spend = false) {
+    return {
+        layer,
+        name,
+        description,
+        spend,
+        requiresConfirmation: spend,
+        parameters: { type: 'object', properties, required },
+    };
+}
+const sats = { type: 'number', description: 'Amount in satoshis' };
+const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT', 'BTC'" };
+/** The full contract. Keep descriptions terse — small models read every word. */
+export const WALLET_TOOLS = [
+    // ── Spark ──────────────────────────────────────────────────────────────
+    t('spark', 'spark_get_balance', 'Get the Spark wallet BTC balance.'),
+    t('spark', 'spark_get_address', 'Get a Spark deposit address to receive BTC.'),
+    t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice to receive BTC.', { amount_sats: sats }),
+    t('spark', 'spark_send', 'Send BTC from Spark to an address or invoice.', { amount_sats: sats, to: { type: 'string', description: 'Address or invoice' } }, ['amount_sats', 'to'], true),
+    // ── RLN / RGB ──────────────────────────────────────────────────────────
+    t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),
+    t('rln', 'rln_get_node_info', 'Get RLN node status and sync state.'),
+    t('rln', 'rln_list_channels', 'List the RLN node Lightning channels.'),
+    t('rln', 'rln_create_ln_invoice', 'Create a Lightning (BTC) invoice on the RLN node.', { amount_sats: sats }),
+    t('rln', 'rln_create_rgb_invoice', 'Create an RGB asset invoice to receive an asset (e.g. USDT).', { asset, amount: { type: 'number', description: 'Asset amount' } }, ['asset', 'amount']),
+    t('rln', 'rln_pay_invoice', 'Pay a Lightning invoice from the RLN node.', { invoice: { type: 'string' } }, ['invoice'], true),
+    t('rln', 'rln_send_asset', 'Send an RGB asset (e.g. USDT) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+    // ── Arkade ─────────────────────────────────────────────────────────────
+    t('arkade', 'arkade_get_balance', 'Get the Arkade wallet balance.'),
+    t('arkade', 'arkade_get_address', 'Get an Arkade address to receive funds.'),
+    t('arkade', 'arkade_send', 'Send BTC from Arkade to a recipient.', { amount_sats: sats, to: { type: 'string' } }, ['amount_sats', 'to'], true),
+    // ── Liquid (later) ─────────────────────────────────────────────────────
+    t('liquid', 'liquid_get_balance', 'Get the Liquid wallet balance (L-BTC + assets).'),
+    t('liquid', 'liquid_create_invoice', 'Create a Liquid invoice/address to receive (L-BTC or L-USDt).', { asset, amount: { type: 'number' } }),
+    t('liquid', 'liquid_send', 'Send a Liquid asset (L-BTC or L-USDt) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+    // ── Core: router + helpers ─────────────────────────────────────────────
+    t('core', 'get_balances', 'Get balances across all layers (or one layer).', { layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'], description: 'Optional: a single layer' } }),
+    t('core', 'resolve_contact', 'Resolve a contact name to a Lightning address / Nostr / preferred rail.', { name: { type: 'string', description: 'Contact name, e.g. "bob"' } }, ['name']),
+    t('core', 'get_price', 'Get the current price of an asset, optionally in a fiat currency.', { asset, fiat: { type: 'string', description: "Fiat code, e.g. 'EUR', 'USD'" } }),
+    t('core', 'fiat_to_sats', 'Convert a fiat amount to satoshis at the current rate.', { amount: { type: 'number' }, currency: { type: 'string', description: "Fiat code, e.g. 'EUR'" } }, ['amount', 'currency']),
+    t('core', 'get_swap_quote', 'Quote a swap between two assets.', { from_asset: asset, to_asset: asset, amount: { type: 'number' } }, ['from_asset', 'to_asset', 'amount']),
+    t('core', 'execute_swap', 'Execute a previously quoted swap.', { quote_id: { type: 'string' }, from_asset: asset, to_asset: asset, amount: { type: 'number' } }, [], true),
+    // The high-level entry a skill prefers — picks the rail for the asset, or uses `layer`.
+    t('core', 'send_payment', 'Send a payment, automatically choosing the best layer for the asset (or use `layer`).', { asset, amount_sats: sats, to: { type: 'string', description: 'Contact, address, or invoice' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }, ['to'], true),
+    // High-level receive — picks the right invoice/address tool for the asset/layer.
+    t('core', 'create_invoice', 'Create an invoice or address to receive funds, choosing the rail for the asset (or use `layer`). Omit amount for an any-amount invoice.', { asset, amount: { type: 'number', description: 'Amount (sats for BTC, asset units otherwise) — optional' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }),
+];
+// ── Selectors ───────────────────────────────────────────────────────────────
+export const WALLET_LAYERS = ['spark', 'rln', 'arkade', 'liquid', 'core'];
+/** Names of all spend (fund-moving) tools — these are confirmation-gated. */
+export const SPEND_TOOLS = new Set(WALLET_TOOLS.filter((x) => x.spend).map((x) => x.name));
+export function isSpendTool(name) {
+    return SPEND_TOOLS.has(name);
+}
+export function getWalletTool(name) {
+    return WALLET_TOOLS.find((x) => x.name === name);
+}
+/** Pick the contract tools for the given layers (core helpers included by default). */
+export function walletTools(opts = {}) {
+    const layers = new Set(opts.layers ?? ['spark', 'rln', 'arkade', 'liquid']);
+    if (opts.includeCore !== false)
+        layers.add('core');
+    return WALLET_TOOLS.filter((x) => layers.has(x.layer));
+}
+/** Strip to plain ToolDefs (drop the layer/spend metadata). */
+export function toToolDefs(tools) {
+    return tools.map(({ name, description, parameters, requiresConfirmation }) => ({ name, description, parameters, requiresConfirmation }));
+}
+/**
+ * Bind contract tools to in-process handlers → an InProcessToolSource. The
+ * mobile (and eval) binding: pass a map of `{ toolName: handler }` and you get a
+ * ToolSource implementing the canonical schemas with spend flags preserved.
+ */
+export function bindWalletTools(handlers, opts = {}) {
+    const tools = walletTools(opts);
+    const bound = [];
+    for (const def of tools) {
+        const handler = handlers[def.name];
+        if (!handler) {
+            if (opts.allowMissing)
+                continue;
+            throw new Error(`bindWalletTools: 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 ?? 'wallet', bound);
+}
+//# sourceMappingURL=contract.js.map

package/dist/wallet/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/wallet/contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaleidorg/mind",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local-first reasoning + function-calling engine for KaleidoSwap. QVAC-powered.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,20 +16,24 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     },
     "./mcp": {
+      "types": "./dist/tools/mcp.d.ts",
       "import": "./dist/tools/mcp.js",
-      "types": "./dist/tools/mcp.d.ts"
+      "default": "./dist/tools/mcp.js"
     },
     "./skills": {
+      "types": "./dist/skills/loader.d.ts",
       "import": "./dist/skills/loader.js",
-      "types": "./dist/skills/loader.d.ts"
+      "default": "./dist/skills/loader.js"
     },
     "./logger": {
+      "types": "./dist/logger.d.ts",
       "import": "./dist/logger.js",
-      "types": "./dist/logger.d.ts"
+      "default": "./dist/logger.js"
     }
   },
   "files": [

package/src/capabilities.ts

@@ -0,0 +1,67 @@
+/**
+ * Capability profiling — decide which features to turn on for a given device +
+ * model, so a 2 GB phone running a 0.6B model doesn't try to do everything.
+ *
+ * Pure heuristic. Hosts call this once (with device RAM + the model's context
+ * size + whether an embedder is available) and get back feature flags + sane
+ * retrieval defaults to feed the ContextBuilder.
+ */
+
+import { contextBudgetTokens } from './context/budget.js';
+
+export interface CapabilityInput {
+  /** Total device RAM in bytes (e.g. react-native-device-info getTotalMemory). */
+  ramBytes?: number;
+  /** The loaded model's context window in tokens (modelConfig.ctx_size). */
+  modelCtxTokens: number;
+  /** Whether an EmbeddingProvider is wired (QVAC embed, etc.). */
+  hasEmbeddings?: boolean;
+  /** Running inference on a remote provider (desktop/server) — relaxes limits. */
+  delegated?: boolean;
+}
+
+export interface MindCapabilities {
+  /** Long-term memory (cheap — on unless the window is tiny). */
+  memory: boolean;
+  /** Semantic recall for memory (needs embeddings). */
+  semanticMemory: boolean;
+  /** Retrieval-augmented generation (needs embeddings + enough RAM/context). */
+  rag: boolean;
+  /** Token budget for injected system context. */
+  contextBudgetTokens: number;
+  /** Memories to auto-recall into context. */
+  topKMemory: number;
+  /** Knowledge chunks the search_knowledge tool returns. */
+  topKRag: number;
+}
+
+const GiB = 1024 * 1024 * 1024;
+
+export function capabilityProfile(input: CapabilityInput): MindCapabilities {
+  const ramGb = input.delegated ? Infinity : (input.ramBytes ?? 0) / GiB;
+  const ctx = input.modelCtxTokens;
+  const hasEmb = !!input.hasEmbeddings;
+
+  const budget = contextBudgetTokens(ctx);
+
+  // Memory: on whenever there's room for a few lines. Semantic needs embeddings.
+  const memory = budget >= 256;
+  const semanticMemory = memory && hasEmb;
+
+  // RAG is the expensive one: needs embeddings, a non-tiny context window, and
+  // (on-device) enough RAM to hold an embedding model + index.
+  const rag = hasEmb && ctx >= 4096 && (input.delegated || ramGb >= 3);
+
+  // Scale how much we pull in with the available window.
+  const topKMemory = budget >= 1500 ? 4 : budget >= 700 ? 3 : 2;
+  const topKRag = rag ? (budget >= 2500 ? 5 : 3) : 0;
+
+  return {
+    memory,
+    semanticMemory,
+    rag,
+    contextBudgetTokens: budget,
+    topKMemory,
+    topKRag,
+  };
+}

package/src/context/budget.ts

@@ -0,0 +1,46 @@
+/**
+ * Context budgeting — the hardware-aware part.
+ *
+ * Small on-device models have small context windows (a 0.6B may run at 2k, a
+ * desktop 8B at 8k+). Memory, skills, RAG and tool schemas all compete for that
+ * window. These helpers turn a model's `ctx_size` into a token budget for the
+ * injected context, so we never overflow a tiny model.
+ *
+ * Token estimation is deliberately rough (≈ 4 chars/token) — no tokenizer dep.
+ */
+
+/** Rough token count for a string (no tokenizer — ~4 chars/token). */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Trim text to at most `maxTokens` (on a word boundary where possible). */
+export function clampToTokens(text: string, maxTokens: number): string {
+  const maxChars = maxTokens * 4;
+  if (text.length <= maxChars) return text;
+  const cut = text.slice(0, maxChars);
+  const sp = cut.lastIndexOf(' ');
+  return (sp > maxChars * 0.6 ? cut.slice(0, sp) : cut).trimEnd() + '…';
+}
+
+export interface BudgetReserves {
+  /** Tokens to leave for the model's reply. Default 512. */
+  output?: number;
+  /** Tokens to budget for tool schemas the engine sends. Default 600. */
+  tools?: number;
+  /** Tokens to budget for the running conversation (user + history). Default 768. */
+  conversation?: number;
+}
+
+/**
+ * Tokens available for the *injected system context* (soul + instructions +
+ * skill + memory + RAG), given the model's context window and what else must
+ * fit. Never negative; clamped to a sane floor so something always gets in.
+ */
+export function contextBudgetTokens(ctxSize: number, reserves: BudgetReserves = {}): number {
+  const output = reserves.output ?? 512;
+  const tools = reserves.tools ?? 600;
+  const conversation = reserves.conversation ?? 768;
+  const available = ctxSize - output - tools - conversation;
+  return Math.max(256, available);
+}

package/src/context/builder.ts

@@ -0,0 +1,100 @@
+/**
+ * ContextBuilder — assembles the system prompt for a turn from, in priority
+ * order: the agent's identity (soul) → operating instructions → the active
+ * skill playbook → auto-recalled memories → auto-retrieved knowledge, trimmed
+ * to a token budget so it never overflows a small model.
+ *
+ * Memory and RAG can ALSO be tools (the model pulls them in itself). Use this
+ * for the always-on slice (identity + the most relevant memory/snippet); use
+ * the tools (`recall`, `search_knowledge`) for deeper, on-demand lookups.
+ */
+
+import type { AgentProfile, MemoryStore } from '../memory/types.js';
+import type { Retriever } from '../rag/retriever.js';
+import { clampToTokens, estimateTokens } from './budget.js';
+
+export interface ContextBuilderOptions {
+  profile: AgentProfile;
+  /** Auto-recall relevant memories into context. */
+  memory?: MemoryStore;
+  /** Auto-retrieve relevant knowledge into context. */
+  retriever?: Retriever;
+  /** Max tokens for the whole assembled system prompt (see contextBudgetTokens). */
+  budgetTokens?: number;
+  /** Memories to recall (default 3). */
+  topKMemory?: number;
+  /** Knowledge chunks to retrieve (default 0 — prefer the search_knowledge tool). */
+  topKRag?: number;
+}
+
+export interface BuildInput {
+  /** The user's message — drives memory recall + retrieval. */
+  query: string;
+  /** A composed skill playbook to splice in (from SkillRegistry.compose). */
+  skillSystem?: string;
+}
+
+export class ContextBuilder {
+  constructor(private readonly opts: ContextBuilderOptions) {}
+
+  async build(input: BuildInput): Promise<{ system: string }> {
+    const { profile } = this.opts;
+    const budget = this.opts.budgetTokens ?? 1024;
+    const sections: string[] = [];
+    let used = 0;
+
+    const add = (text: string, { force = false } = {}): void => {
+      const t = text.trim();
+      if (!t) return;
+      const cost = estimateTokens(t) + 1;
+      if (!force && used + cost > budget) {
+        // Try to fit a trimmed version of optional sections.
+        const room = budget - used - 1;
+        if (room < 40) return;
+        const trimmed = clampToTokens(t, room);
+        sections.push(trimmed);
+        used += estimateTokens(trimmed) + 1;
+        return;
+      }
+      sections.push(t);
+      used += cost;
+    };
+
+    // 1. Identity (always) — name + soul.
+    add(`# ${profile.name}\n${profile.soul}`, { force: true });
+
+    // 2. Operating instructions (always, if any).
+    if (profile.instructions) add(`## Instructions\n${profile.instructions}`, { force: true });
+
+    // 3. Active skill playbook.
+    if (input.skillSystem) add(input.skillSystem);
+
+    // 4. Auto-recalled memory.
+    const kMem = this.opts.topKMemory ?? 3;
+    if (this.opts.memory && kMem > 0) {
+      try {
+        const mems = await this.opts.memory.search({ text: input.query, limit: kMem });
+        if (mems.length) {
+          add(`## What you remember\n${mems.map((m) => `- (${m.kind}) ${m.text}`).join('\n')}`);
+        }
+      } catch {
+        /* memory is best-effort */
+      }
+    }
+
+    // 5. Auto-retrieved knowledge (opt-in; default prefers the tool).
+    const kRag = this.opts.topKRag ?? 0;
+    if (this.opts.retriever && kRag > 0) {
+      try {
+        const hits = await this.opts.retriever.search(input.query, kRag);
+        if (hits.length) {
+          add(`## Relevant context\n${hits.map((h) => h.text).join('\n\n')}`);
+        }
+      } catch {
+        /* retrieval is best-effort */
+      }
+    }
+
+    return { system: sections.join('\n\n') };
+  }
+}

package/src/context/context.test.ts

@@ -0,0 +1,83 @@
+/** Context budget + builder + capability tests. */
+
+import { describe, it, expect } from 'vitest';
+import { estimateTokens, clampToTokens, contextBudgetTokens } from './budget.js';
+import { ContextBuilder } from './builder.js';
+import { capabilityProfile } from '../capabilities.js';
+import { InMemoryMemoryStore } from '../memory/store.js';
+import type { AgentProfile } from '../memory/types.js';
+
+const profile: AgentProfile = {
+  name: 'KaleidoMind',
+  soul: 'You are a sovereign, local-first Bitcoin assistant. Calm, precise, private.',
+  instructions: 'Never reveal seeds. Confirm spends.',
+};
+
+describe('budget helpers', () => {
+  it('estimates + clamps by ~4 chars/token', () => {
+    expect(estimateTokens('a'.repeat(40))).toBe(10);
+    const clamped = clampToTokens('word '.repeat(100), 10);
+    expect(clamped.length).toBeLessThanOrEqual(10 * 4 + 1);
+    expect(clamped.endsWith('…')).toBe(true);
+  });
+
+  it('reserves output/tools/conversation from the window', () => {
+    expect(contextBudgetTokens(8192)).toBe(8192 - 512 - 600 - 768);
+    expect(contextBudgetTokens(2048)).toBeGreaterThanOrEqual(256); // floor
+    expect(contextBudgetTokens(512)).toBe(256); // clamped to floor
+  });
+});
+
+describe('ContextBuilder', () => {
+  it('always includes identity + instructions, then memory', async () => {
+    const memory = new InMemoryMemoryStore({ now: () => 1 });
+    await memory.add({ text: 'user prefers sats over USD', kind: 'preference' });
+    const builder = new ContextBuilder({ profile, memory, topKMemory: 3, budgetTokens: 1024 });
+
+    const { system } = await builder.build({ query: 'show my balance in sats' });
+    expect(system).toMatch(/# KaleidoMind/);
+    expect(system).toMatch(/Never reveal seeds/);
+    expect(system).toMatch(/What you remember/);
+    expect(system).toMatch(/prefers sats/);
+  });
+
+  it('keeps identity even under a tiny budget (drops optional sections)', async () => {
+    const memory = new InMemoryMemoryStore({ now: () => 1 });
+    await memory.add({ text: 'a'.repeat(400), kind: 'note' });
+    const builder = new ContextBuilder({ profile, memory, topKMemory: 3, budgetTokens: 40 });
+    const { system } = await builder.build({ query: 'x' });
+    expect(system).toMatch(/# KaleidoMind/); // identity survives
+  });
+
+  it('splices in a composed skill playbook', async () => {
+    const builder = new ContextBuilder({ profile, budgetTokens: 2048 });
+    const { system } = await builder.build({
+      query: 'buy a gift card',
+      skillSystem: '## Active skill: bitrefill\nRoute the purchase.',
+    });
+    expect(system).toMatch(/Active skill: bitrefill/);
+  });
+});
+
+describe('capabilityProfile', () => {
+  it('low-end phone: memory yes, RAG no', () => {
+    const c = capabilityProfile({ ramBytes: 2 * 1024 ** 3, modelCtxTokens: 2048, hasEmbeddings: true });
+    expect(c.memory).toBe(true);
+    expect(c.rag).toBe(false); // ctx too small + low RAM
+    expect(c.topKRag).toBe(0);
+  });
+
+  it('desktop / delegated: RAG on', () => {
+    const c = capabilityProfile({ modelCtxTokens: 8192, hasEmbeddings: true, delegated: true });
+    expect(c.rag).toBe(true);
+    expect(c.topKRag).toBeGreaterThan(0);
+    expect(c.semanticMemory).toBe(true);
+  });
+
+  it('no embeddings → no RAG, no semantic memory', () => {
+    const c = capabilityProfile({ ramBytes: 16 * 1024 ** 3, modelCtxTokens: 8192, hasEmbeddings: false });
+    expect(c.rag).toBe(false);
+    expect(c.semanticMemory).toBe(false);
+    expect(c.memory).toBe(true);
+  });
+});

package/src/fastpath/fastpath.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { FastPath, WALLET_FAST_INTENTS } from './fastpath.js';
+
+const fp = new FastPath(WALLET_FAST_INTENTS);
+
+describe('FastPath (Tier-0)', () => {
+  it('routes balance asks → get_balances', () => {
+    expect(fp.select("what's my balance")?.tool).toBe('get_balances');
+    expect(fp.select('how much do i have')?.tool).toBe('get_balances');
+    expect(fp.select('show my funds')?.tool).toBe('get_balances');
+  });
+
+  it('routes receive-address asks → spark_get_address', () => {
+    expect(fp.select('give me a receive address')?.tool).toBe('spark_get_address');
+    expect(fp.select('what is my address')?.tool).toBe('spark_get_address');
+  });
+
+  it('routes price asks → get_price', () => {
+    expect(fp.select('btc price')?.tool).toBe('get_price');
+    expect(fp.select('how much is bitcoin')?.tool).toBe('get_price');
+  });
+
+  it('does NOT fire on spend / compound requests', () => {
+    expect(fp.select('pay bob 3 eur')).toBeNull();
+    expect(fp.select('send 5000 sats to alice')).toBeNull();
+    expect(fp.select('check my balance and then send 1000 to bob')).toBeNull(); // compound → LLM
+    expect(fp.select('swap 10 usdt for btc')).toBeNull();
+  });
+
+  it('does NOT fire on unrelated chatter', () => {
+    expect(fp.select('hello there')).toBeNull();
+    expect(fp.select('what can you do')).toBeNull();
+  });
+});

package/src/fastpath/fastpath.ts

@@ -0,0 +1,70 @@
+/**
+ * Tier-0 deterministic fast-path — answer the common, unambiguous wallet asks
+ * with NO LLM at all. "balance", "receive address", "btc price" map straight to
+ * a single tool call. The model is reserved for genuine ambiguity.
+ *
+ * This is the biggest mobile UX lever: ~60-80% of wallet requests are simple,
+ * and our eval showed tiny models are slow + weak at args — so skip them here.
+ *
+ * Matchers are intentionally CONSERVATIVE: when in doubt, return null and let
+ * the recipe / agentic loop handle it. Under-firing is fine; mis-firing is not.
+ *
+ * Pure data — no deps. The host executes the returned tool + renders the result.
+ */
+
+export interface FastIntent {
+  name: string;
+  /** Contract tool to call when this intent matches. */
+  tool: string;
+  /** True only when this intent UNAMBIGUOUSLY matches the text. */
+  match: (text: string) => boolean;
+  /** Optional args derived from the text (default: none). */
+  args?: (text: string) => Record<string, unknown>;
+}
+
+export interface FastHit {
+  intent: FastIntent;
+  tool: string;
+  args: Record<string, unknown>;
+}
+
+export class FastPath {
+  private intents: FastIntent[];
+  constructor(intents: FastIntent[] = []) {
+    this.intents = [...intents];
+  }
+  add(intent: FastIntent): void {
+    this.intents.push(intent);
+  }
+  list(): FastIntent[] {
+    return [...this.intents];
+  }
+  /** 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;
+  }
+}
+
+// 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;
+
+/** Default wallet read intents (balance / receive address / price). */
+export const WALLET_FAST_INTENTS: FastIntent[] = [
+  {
+    name: 'balance',
+    tool: '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: 'address',
+    tool: 'spark_get_address',
+    match: (t) => !ACTIONY.test(t) && /\b(receive address|deposit address|my address|an address|get .*address|where.* receive)\b/i.test(t),
+  },
+  {
+    name: 'price',
+    tool: 'get_price',
+    match: (t) => !ACTIONY.test(t) && /\b(btc price|bitcoin price|price of (btc|bitcoin)|how much is (a |one )?(btc|bitcoin))\b/i.test(t),
+  },
+];