@kaleidorg/mind 0.1.0 → 0.2.0

package/src/funnel.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ToolRegistry } from './tools/registry.js';
+import { InProcessToolSource } from './tools/in-process.js';
+import type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+import { Funnel, DEFAULT_WALLET_SYSTEM } from './funnel.js';
+import { parseSkill } from './skills/registry.js';
+
+// ── Fixtures ──────────────────────────────────────────────────────────
+
+/** Stub contract tools across all three tiers + ambient memory/RAG. */
+function stubTools(spy?: { send?: (a: any) => void }) {
+  const wallet = new InProcessToolSource('wallet', [
+    { name: 'get_balances', description: 'balances', parameters: {}, handler: async () => ({ total_sats: 4000, layers: [{ layer: 'spark' }, { layer: 'rln' }] }) },
+    { name: 'get_price', description: 'price', parameters: {}, handler: async () => ({ price_usd: 100000 }) },
+    { name: 'resolve_contact', description: '', parameters: {}, handler: async ({ name }) => ({ name, ln_address: `${name}@kaleidoswap.com` }) },
+    { name: 'fiat_to_sats', description: '', parameters: {}, handler: async ({ amount }) => ({ sats: Math.round(Number(amount) * 1000) }) },
+    { name: 'send_payment', description: '', parameters: {}, requiresConfirmation: true, handler: async (a) => { spy?.send?.(a); return { status: 'SUCCESS' }; } },
+    { name: 'list_channels', description: 'channels', parameters: {}, handler: async () => ({ channels: [] }) },
+  ]);
+  const ambient = new InProcessToolSource('ambient', [
+    { name: 'remember', description: '', parameters: {}, handler: async () => ({ ok: true }) },
+    { name: 'recall', description: '', parameters: {}, handler: async () => ({ items: [] }) },
+    { name: 'search_knowledge', description: '', parameters: {}, handler: async () => ({ chunks: [] }) },
+  ]);
+  return new ToolRegistry([wallet, ambient]);
+}
+
+/** Provider that replays scripted turns and records every TurnInput. */
+function scriptedProvider(turns: Array<Partial<TurnOutput>>): LLMProvider & { inputs: TurnInput[] } {
+  const inputs: TurnInput[] = [];
+  let i = 0;
+  return {
+    name: 'scripted',
+    inputs,
+    async runTurn(input: TurnInput): Promise<TurnOutput> {
+      // Snapshot — the Engine mutates its messages array across turns.
+      inputs.push({ ...input, messages: [...input.messages] });
+      const t = turns[Math.min(i++, turns.length - 1)] ?? {};
+      return { text: t.text ?? '', rawContent: t.rawContent ?? t.text ?? '', toolCalls: t.toolCalls ?? [] };
+    },
+  };
+}
+
+const TEST_SKILL = parseSkill(
+  [
+    '---',
+    'name: channels',
+    'description: Inspect Lightning channels.',
+    'triggers: channels, channel, liquidity',
+    'tools: list_channels',
+    '---',
+    'When asked about channels, call list_channels and summarise.',
+  ].join('\n'),
+);
+
+// ── T0: fast-path ─────────────────────────────────────────────────────
+
+describe('Funnel — T0 fast-path', () => {
+  it('answers balance with zero inferences and returns the card data', async () => {
+    const provider = scriptedProvider([]);
+    const funnel = new Funnel({ provider, tools: stubTools() });
+
+    const res = await funnel.runTurn("what's my balance?");
+
+    expect(res.tier).toBe('fast');
+    expect(res.intent).toBe('balance');
+    expect(res.text).toContain('4,000 sats');
+    expect(res.data).toMatchObject({ total_sats: 4000 });
+    expect(provider.inputs).toHaveLength(0); // no LLM
+  });
+});
+
+// ── T2: recipes ───────────────────────────────────────────────────────
+
+describe('Funnel — T2 recipes', () => {
+  it('runs a confident payment deterministically, confirm-gated', async () => {
+    const sent: any[] = [];
+    const provider = scriptedProvider([]);
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const onStep = vi.fn();
+    const funnel = new Funnel({ provider, tools: stubTools({ send: (a) => sent.push(a) }) });
+
+    const res = await funnel.runTurn('pay bob 3 eur', { onConfirm, onStep });
+
+    expect(res.tier).toBe('recipe');
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(sent[0]).toEqual({ to: 'bob@kaleidoswap.com', amount_sats: 3000 });
+    expect(onStep).toHaveBeenCalled();
+    expect(provider.inputs).toHaveLength(0); // deterministic extraction
+  });
+
+  it('fails closed: a recipe spend with no onConfirm sends nothing', async () => {
+    const sent: any[] = [];
+    const funnel = new Funnel({ provider: scriptedProvider([]), tools: stubTools({ send: (a) => sent.push(a) }) });
+
+    const res = await funnel.runTurn('pay bob 3 eur');
+
+    expect(res.tier).toBe('recipe');
+    expect(sent).toHaveLength(0);
+  });
+});
+
+describe('Funnel — partial tool surfaces fall through to agentic', () => {
+  it('skips T0 and T2 when the registry lacks their tools', async () => {
+    // A host (e.g. desktop MCP) that implements none of the contract helpers.
+    const bare = new ToolRegistry([
+      new InProcessToolSource('other', [
+        { name: 'unrelated_tool', description: '', parameters: {}, handler: async () => ({}) },
+      ]),
+    ]);
+    const provider = scriptedProvider([{ text: 'answered by the model' }]);
+    const funnel = new Funnel({ provider, tools: bare });
+
+    const fast = await funnel.runTurn("what's my balance?");
+    expect(fast.tier).toBe('agentic'); // no get_balances → no T0
+
+    const pay = await funnel.runTurn('pay bob 3 eur');
+    expect(pay.tier).toBe('agentic'); // no send_payment → no T2
+  });
+});
+
+// ── T1: agentic ───────────────────────────────────────────────────────
+
+describe('Funnel — T1 agentic', () => {
+  it('routes unmatched queries to the engine and returns tool calls', async () => {
+    const provider = scriptedProvider([
+      { toolCalls: [{ name: 'get_price', arguments: {} }] },
+      { text: 'BTC is at $100,000.' },
+    ]);
+    const onToolCall = vi.fn();
+    const funnel = new Funnel({ provider, tools: stubTools() });
+
+    const res = await funnel.runTurn('should I buy more sats this week?', { onToolCall });
+
+    expect(res.tier).toBe('agentic');
+    expect(res.text).toBe('BTC is at $100,000.');
+    expect(res.toolCalls).toHaveLength(1);
+    expect(res.toolCalls?.[0]).toMatchObject({ name: 'get_price', result: { price_usd: 100000 } });
+    // requiresConfirmation enrichment is async (getDef) — let it flush.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(onToolCall).toHaveBeenCalledWith({ name: 'get_price', arguments: {} }, { requiresConfirmation: false });
+  });
+
+  it('appends the persona and trims history per settings', async () => {
+    const provider = scriptedProvider([{ text: 'ok' }]);
+    const funnel = new Funnel({
+      provider,
+      tools: stubTools(),
+      getSettings: () => ({ persona: 'Speak like a pirate.', historyLength: 2 }),
+    });
+
+    const history = Array.from({ length: 6 }, (_, i) => ({ role: 'user' as const, content: `m${i}` }));
+    await funnel.runTurn('tell me something', { history });
+
+    const messages = provider.inputs[0].messages;
+    expect(messages[0].content).toContain(DEFAULT_WALLET_SYSTEM);
+    expect(messages[0].content).toContain('Speak like a pirate.');
+    // system + 2 kept history + the new user message
+    expect(messages).toHaveLength(4);
+    expect(messages[1].content).toBe('m4');
+    expect(messages[2].content).toBe('m5');
+  });
+
+  it('scopes tools to the matched skill plus ambient tools', async () => {
+    const provider = scriptedProvider([{ text: 'ok' }]);
+    const funnel = new Funnel({ provider, tools: stubTools(), skills: [TEST_SKILL] });
+
+    await funnel.runTurn('how are my channels doing?');
+
+    const names = provider.inputs[0].tools.map((t) => t.name);
+    expect(names).toContain('list_channels');
+    expect(names).toContain('remember');
+    expect(names).toContain('search_knowledge');
+    expect(names).not.toContain('send_payment'); // narrowed out by the skill
+  });
+
+  it('hides ambient tools when their toggles are off (no skill matched)', async () => {
+    const provider = scriptedProvider([{ text: 'ok' }]);
+    const funnel = new Funnel({
+      provider,
+      tools: stubTools(),
+      getSettings: () => ({ memoryEnabled: false, ragEnabled: false }),
+    });
+
+    await funnel.runTurn('tell me something interesting');
+
+    const names = provider.inputs[0].tools.map((t) => t.name);
+    expect(names).not.toContain('remember');
+    expect(names).not.toContain('recall');
+    expect(names).not.toContain('search_knowledge');
+    expect(names).toContain('get_balances'); // everything else stays
+  });
+
+  it('listSkills honors disabledSkills and tracks settings changes', () => {
+    let disabled: string[] = [];
+    const funnel = new Funnel({
+      provider: scriptedProvider([]),
+      tools: stubTools(),
+      skills: [TEST_SKILL],
+      getSettings: () => ({ disabledSkills: disabled }),
+    });
+
+    expect(funnel.listSkills().map((s) => s.name)).toEqual(['channels']);
+    disabled = ['channels'];
+    expect(funnel.listSkills()).toHaveLength(0);
+  });
+});

package/src/funnel.ts

@@ -0,0 +1,260 @@
+/**
+ * Funnel — the tiered agent loop (T0 fast-path → T2 recipe → T1 agentic).
+ *
+ * This is the mobile-optimized funnel from the roadmap, lifted out of the
+ * hosts so every surface (rate chat + voice, desktop provider, agent) runs
+ * the SAME routing:
+ *
+ *   request
+ *     ├─ T0  deterministic fast-path  (no LLM)        balance / address / price
+ *     ├─ T2  recipe multi-step        (~1 inference)  "pay bob 3 EUR"
+ *     └─ T1  skill-scoped agentic loop                everything else
+ *
+ * Hosts inject the provider, the tool registry, and a `getSettings` closure
+ * read fresh each turn — so user-tunable settings (persona, history length,
+ * memory/RAG toggles, disabled skills) never require rebuilding the funnel
+ * or dropping host state like an embedded RAG index.
+ *
+ * Safety is unchanged from the Engine: spend tools are confirmation-gated by
+ * the contract; with no `onConfirm` the gate fails closed.
+ */
+
+import { Engine } from './engine.js';
+import type { ToolRegistry } from './tools/registry.js';
+import { FastPath, WALLET_FAST_INTENTS } from './fastpath/fastpath.js';
+import type { FastIntent } from './fastpath/fastpath.js';
+import { RecipeRegistry, runRecipe } from './recipe/runner.js';
+import { paymentsRecipe } from './recipe/payments.js';
+import { receiveRecipe } from './recipe/receive.js';
+import { assetSendRecipe } from './recipe/asset-send.js';
+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 { ConfirmDecision, Message, ToolResult } from './types.js';
+
+/** Base system prompt for the wallet assistant. Hosts may override. */
+export const DEFAULT_WALLET_SYSTEM =
+  'You are KaleidoSwap, a concise, privacy-first assistant running inside a ' +
+  'non-custodial Bitcoin, Lightning and RGB wallet. Use the provided tools to ' +
+  'take actions: pay invoices and contacts, create invoices, check balances. ' +
+  'Never invent a balance, address, amount or result — always call the ' +
+  'relevant tool and report what it returns. All BTC amounts are in satoshis. ' +
+  'Keep replies short and friendly.';
+
+/** Tools that stay available even when a skill narrows the set. */
+const AMBIENT_MEMORY = ['remember', 'recall'];
+const AMBIENT_RAG = ['search_knowledge'];
+
+const DEFAULT_HISTORY = 8;
+
+/** Per-user agent settings, read fresh each turn via `getSettings`. */
+export interface FunnelSettings {
+  /** Extra instructions appended to the system prompt. */
+  persona?: string;
+  /** Most recent history messages to keep in the prompt (default 8). */
+  historyLength?: number;
+  /** Expose the remember/recall tools (default true). */
+  memoryEnabled?: boolean;
+  /** Expose the search_knowledge tool (default true). */
+  ragEnabled?: boolean;
+  /** Skill names the user turned off. */
+  disabledSkills?: string[];
+}
+
+export interface FunnelCallbacks {
+  history?: Message[];
+  /** The live requestId of the agentic run (so a stop button can cancel it). */
+  onStart?: (requestId: string) => void;
+  onToken?: (token: string, turn: number) => void;
+  /** A recipe step is executing (deterministic tier). */
+  onStep?: (name: string) => void;
+  /** The model requested a tool (agentic tier), before it executes. */
+  onToolCall?: (
+    call: { name: string; arguments: Record<string, unknown> },
+    info: { requiresConfirmation: boolean },
+  ) => void;
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+}
+
+export interface FunnelResult {
+  text: string;
+  tier: 'fast' | 'recipe' | 'agentic';
+  /** Fast tier only: the matched intent + raw tool result (e.g. for a balance card). */
+  intent?: string;
+  data?: unknown;
+  /** Agentic tier only: executed tool calls + reasoning turns. */
+  toolCalls?: ToolResult[];
+  turns?: number;
+}
+
+export interface FunnelOptions {
+  provider: LLMProvider;
+  /** ALL tool sources merged — wallet, memory, RAG, merchant, L402, … */
+  tools: ToolRegistry;
+  /** Skills available to the agentic tier (disabled ones filtered per turn). */
+  skills?: Skill[];
+  /** Recipes for the T2 tier. Default: asset-send, payments, receive. */
+  recipes?: Recipe[];
+  /** Fast-path intents for the T0 tier. Default: WALLET_FAST_INTENTS. */
+  fastIntents?: FastIntent[];
+  /** Base system prompt (persona is appended). Default: DEFAULT_WALLET_SYSTEM. */
+  system?: string;
+  /** Max reasoning↔tool rounds in the agentic tier. Default 5. */
+  maxTurns?: number;
+  /** User settings, read fresh each turn. */
+  getSettings?: () => FunnelSettings;
+  /** Render a fast-path tool result as user-facing text. Default: built-in. */
+  renderFast?: (intent: string, result: unknown) => string;
+  /** Diagnostics sink (tier routing, tool calls). Default: silent. */
+  log?: (message: string) => void;
+}
+
+function defaultRenderFast(intent: string, r: any): string {
+  if (intent === 'balance') {
+    const sats = Number(r?.total_sats ?? 0);
+    const n = r?.layers?.length ?? 0;
+    return `You have ${sats.toLocaleString()} sats${n > 1 ? ` across ${n} layers` : ''}.`;
+  }
+  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()}.`;
+}
+
+export class Funnel {
+  private readonly provider: LLMProvider;
+  private readonly registry: ToolRegistry;
+  private readonly engine: Engine;
+  private readonly fastPath: FastPath;
+  private readonly recipes: RecipeRegistry;
+  private readonly allSkills: Skill[];
+  private readonly system: string;
+  private readonly getSettings: () => FunnelSettings;
+  private readonly renderFast: (intent: string, result: unknown) => string;
+  private readonly log: (message: string) => void;
+
+  /** Skill registry, rebuilt only when the disabled-skills set changes. */
+  private skillsCache: { key: string; reg: SkillRegistry } | null = null;
+
+  constructor(opts: FunnelOptions) {
+    this.provider = opts.provider;
+    this.registry = opts.tools;
+    this.engine = new Engine({
+      provider: opts.provider,
+      tools: opts.tools,
+      defaultMaxTurns: opts.maxTurns ?? 5,
+    });
+    this.fastPath = new FastPath(opts.fastIntents ?? WALLET_FAST_INTENTS);
+    this.recipes = new RecipeRegistry(opts.recipes ?? [assetSendRecipe, paymentsRecipe, receiveRecipe]);
+    this.allSkills = opts.skills ?? [];
+    this.system = opts.system ?? DEFAULT_WALLET_SYSTEM;
+    this.getSettings = opts.getSettings ?? (() => ({}));
+    this.renderFast = opts.renderFast ?? defaultRenderFast;
+    this.log = opts.log ?? (() => {});
+  }
+
+  /** Skills currently enabled (e.g. for a skills sheet). */
+  listSkills(): Skill[] {
+    return this.skillsFor(this.getSettings().disabledSkills).list();
+  }
+
+  private skillsFor(disabled: string[] = []): SkillRegistry {
+    const key = [...disabled].sort().join(',');
+    if (this.skillsCache?.key !== key) {
+      this.skillsCache = {
+        key,
+        reg: new SkillRegistry(this.allSkills.filter((s) => !disabled.includes(s.name))),
+      };
+    }
+    return this.skillsCache.reg;
+  }
+
+  async runTurn(text: string, cbs: FunnelCallbacks = {}): Promise<FunnelResult> {
+    const settings = this.getSettings();
+
+    // ── T0: deterministic fast-path (no LLM) ──
+    // Only fires when the host's registry actually implements the intent's
+    // tool — a partial tool surface (e.g. desktop without the core aggregate
+    // helpers) falls through to the agentic tier instead of erroring.
+    const fast = this.fastPath.select(text);
+    if (fast && (await this.registry.getDef(fast.tool))) {
+      this.log(`tier=fast-path → ${fast.tool}`);
+      const r = await this.registry.execute(fast.tool, fast.args);
+      return { text: this.renderFast(fast.intent.name, r), tier: 'fast', intent: fast.intent.name, data: r };
+    }
+
+    // ── T2: recipe multi-step — fires only when the recipe is confident given
+    // its extracted slots (payments need a recipient; receive always fires),
+    // and the registry implements the recipe's final action.
+    const recipe = this.recipes.select(text);
+    const slots = recipe?.extract?.(text) ?? null;
+    const fires =
+      !!recipe &&
+      !!slots &&
+      (recipe.confident ? recipe.confident(slots) : Object.keys(slots).length > 0) &&
+      !!(await this.registry.getDef(recipe.final.tool));
+    if (recipe && fires) {
+      this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slots)}`);
+      const res = await runRecipe(recipe, text, {
+        provider: this.provider,
+        tools: this.registry,
+        onConfirm: cbs.onConfirm,
+        onStep: (name) => {
+          this.log(`step ${name}`);
+          cbs.onStep?.(name);
+        },
+      });
+      return { text: res.text, tier: 'recipe' };
+    }
+
+    // ── T1: skill-scoped agentic loop ──
+    const skills = this.skillsFor(settings.disabledSkills);
+    const skill = skills.select(text);
+    const base = settings.persona ? `${this.system}\n\n## Your persona\n${settings.persona}` : this.system;
+    const { system, allowedTools } = skills.compose(base, skill);
+
+    // 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 ragOn = settings.ragEnabled !== false;
+    const ambient = [...(memoryOn ? AMBIENT_MEMORY : []), ...(ragOn ? AMBIENT_RAG : [])];
+    const disabledAmbient = [...(memoryOn ? [] : AMBIENT_MEMORY), ...(ragOn ? [] : AMBIENT_RAG)];
+    let scoped: string[] | undefined;
+    if (allowedTools) {
+      scoped = [...new Set([...allowedTools, ...ambient])];
+    } else if (disabledAmbient.length) {
+      // No skill matched but a toggle is off: expose everything except the
+      // disabled ambient tools (the sources stay mounted — no rebuild).
+      const all = (await this.registry.listTools()).map((t) => t.name);
+      scoped = all.filter((n) => !disabledAmbient.includes(n));
+    }
+
+    // Trim history so the prompt (system + skill + tools + history) stays
+    // within the small on-device model's context window.
+    const keep = settings.historyLength ?? DEFAULT_HISTORY;
+    const history = (cbs.history ?? []).slice(-keep);
+    const messages: Message[] = [
+      { role: 'system', content: system },
+      ...history,
+      { role: 'user', content: text },
+    ];
+
+    this.log(`tier=agentic skill=${skill?.name ?? 'none'} tools=[${(scoped ?? ['all']).join(',')}]`);
+    const res = await this.engine.runAgentic(messages, {
+      allowedTools: scoped,
+      onStart: (requestId) => cbs.onStart?.(requestId),
+      onToken: cbs.onToken,
+      onToolCall: (call) => {
+        this.log(`tool ${call.name} ${JSON.stringify(call.arguments)}`);
+        // getDef is async; fire-and-forget so the loop is never blocked on UI.
+        void this.registry
+          .getDef(call.name)
+          .then((def) => cbs.onToolCall?.(call, { requiresConfirmation: !!def?.requiresConfirmation }))
+          .catch(() => cbs.onToolCall?.(call, { requiresConfirmation: false }));
+      },
+      onConfirm: cbs.onConfirm,
+    });
+    return { text: res.text ?? '', tier: 'agentic', toolCalls: res.toolCalls, turns: res.turns };
+  }
+}

package/src/index.ts

@@ -29,10 +29,95 @@ export {
   bolt11AmountSats,
 } from './tools/l402.js';
 export type { L402Options, L402PayResult } from './tools/l402.js';
+export { createCliToolSource, isAllowed } from './tools/cli.js';
+export type { CliToolOptions, CommandRunner, CommandResult } from './tools/cli.js';
+
+// ── Multi-L2 wallet tool contract (single source of truth) ─────────────────
+export {
+  WALLET_TOOLS,
+  WALLET_LAYERS,
+  SPEND_TOOLS,
+  isSpendTool,
+  getWalletTool,
+  walletTools,
+  toToolDefs,
+  bindWalletTools,
+} from './wallet/contract.js';
+export type {
+  WalletLayer,
+  WalletToolDef,
+  WalletHandler,
+  BindWalletOptions,
+} from './wallet/contract.js';
+
+// ── Recipes (mobile multi-step: "recipes, not planning") ───────────────────
+export { runRecipe, extractSlots, RecipeRegistry } from './recipe/runner.js';
+export type { RunRecipeOptions } from './recipe/runner.js';
+export { paymentsRecipe, extractPayment } from './recipe/payments.js';
+export { swapRecipe, extractSwap } from './recipe/swap.js';
+export { receiveRecipe, extractReceive } from './recipe/receive.js';
+export { assetSendRecipe, extractAssetSend } from './recipe/asset-send.js';
+export type { Recipe, RecipeStep, RecipeSlot, RecipeContext, RecipeResult, RecipeStatus } from './recipe/types.js';
+
+// ── Tier-0 deterministic fast-path (no LLM) ────────────────────────────────
+export { FastPath, WALLET_FAST_INTENTS } from './fastpath/fastpath.js';
+export type { FastIntent, FastHit } from './fastpath/fastpath.js';
+
+// ── Memory (soul + recall) ───────────────────────────────────────────────
+export { InMemoryMemoryStore } from './memory/store.js';
+export type { MemoryStoreOptions } from './memory/store.js';
+export { createMemoryToolSource } from './memory/tool.js';
+export type {
+  AgentProfile,
+  MemoryItem,
+  MemoryKind,
+  MemoryQuery,
+  MemoryStore,
+  MemoryIO,
+  NewMemory,
+} from './memory/types.js';
+
+// ── RAG ──────────────────────────────────────────────────────────────────
+export { Retriever, chunkText } from './rag/retriever.js';
+export type { RetrieverOptions } from './rag/retriever.js';
+export { InMemoryVectorStore, cosineSimilarity } from './rag/vector-store.js';
+export { createRagToolSource } from './rag/tool.js';
+export type { RagToolOptions } from './rag/tool.js';
+export type {
+  EmbeddingProvider,
+  Chunk,
+  RetrievedChunk,
+  RagDocument,
+  VectorStore,
+  VectorStoreIO,
+} from './rag/types.js';
+
+// ── Context assembly + hardware budget ─────────────────────────────────────
+export { ContextBuilder } from './context/builder.js';
+export type { ContextBuilderOptions, BuildInput } from './context/builder.js';
+export {
+  estimateTokens,
+  clampToTokens,
+  contextBudgetTokens,
+} from './context/budget.js';
+export type { BudgetReserves } from './context/budget.js';
+export { capabilityProfile } from './capabilities.js';
+export type { CapabilityInput, MindCapabilities } from './capabilities.js';
+
+// ── Knowledge packs + corpus adapters (for RAG) ────────────────────────────
+export { BITCOIN_COPILOT_DOCS } from './knowledge/bitcoin-copilot.js';
+export { walletHistoryToDocuments, contactsToDocuments } from './knowledge/wallet.js';
+export type { WalletTx, Contact } from './knowledge/wallet.js';
+export { merchantsToDocuments } from './knowledge/merchants.js';
+export type { Merchant } from './knowledge/merchants.js';
 
 export { Engine } from './engine.js';
 export type { EngineOptions, AgenticOptions, AgenticResult } from './engine.js';
 
+// ── Funnel (T0 fast-path → T2 recipe → T1 agentic — the tiered agent) ───────
+export { Funnel, DEFAULT_WALLET_SYSTEM } from './funnel.js';
+export type { FunnelOptions, FunnelSettings, FunnelCallbacks, FunnelResult } from './funnel.js';
+
 export {
   SkillRegistry,
   parseSkill,