@kaleidorg/mind 0.1.0 → 0.3.0

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,87 @@
+/** 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, dedup yes but no LLM merge', () => {
+    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);
+    expect(c.dedupeMemory).toBe(true); // embedding-only dedup is mobile-safe
+    expect(c.mergeMemory).toBe(false); // never run merge inference on a tiny phone
+  });
+
+  it('desktop / delegated: RAG on, memory merge 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);
+    expect(c.dedupeMemory).toBe(true);
+    expect(c.mergeMemory).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/engine.ts

@@ -35,6 +35,11 @@ export interface AgenticOptions {
   onStart?: (requestId: string, turn: number) => void;
   /** Fired when the model requests a tool, before it executes. */
   onToolCall?: (call: { name: string; arguments: Record<string, unknown> }, turn: number) => void;
+  /**
+   * Fired after a tool returns (success OR error — errors arrive as `{error}`).
+   * Useful for surfacing the raw response back to the user in a debug UI.
+   */
+  onToolResult?: (event: { name: string; arguments: Record<string, unknown>; result: unknown }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
   onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
   /**
@@ -127,6 +132,7 @@ export class Engine {
         }
 
         executed.push({ name: call.name, arguments: call.arguments, result });
+        opts.onToolResult?.({ name: call.name, arguments: call.arguments, result }, turn);
         history.push({
           role: 'tool',
           content: typeof result === 'string' ? result : JSON.stringify(result),

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),
+  },
+];

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