@kaleidorg/mind 0.0.1 → 0.2.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,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/engine.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Engine + tool-calling tests.
+ *
+ * These exercise the full agentic loop deterministically — no model, no
+ * device — using a scripted mock provider and mock tool sources. This is the
+ * fastest way to verify tools are selected, executed, fed back, and gated by
+ * confirmation, exactly as they would be with a real QVAC model.
+ *
+ *   pnpm --filter @kaleidorg/mind test
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { Engine } from './engine.js';
+import { ToolRegistry } from './tools/registry.js';
+import { InProcessToolSource } from './tools/in-process.js';
+import type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+import type { ToolCall } from './types.js';
+
+/**
+ * A scripted provider: each entry in `script` is one turn's output. When it
+ * returns tool calls, the engine executes them and calls the provider again
+ * for the next scripted turn.
+ */
+function scriptedProvider(script: Array<{ text: string; toolCalls?: ToolCall[] }>): LLMProvider {
+  let turn = 0;
+  return {
+    name: 'scripted',
+    async runTurn(input: TurnInput): Promise<TurnOutput> {
+      const step = script[Math.min(turn, script.length - 1)];
+      turn += 1;
+      // stream the text so onToken paths are exercised
+      input.onToken?.(step.text);
+      return {
+        text: step.text,
+        rawContent: step.text,
+        toolCalls: step.toolCalls ?? [],
+        requestId: `req-${turn}`,
+      };
+    },
+  };
+}
+
+const balanceTool = {
+  name: 'get_balance',
+  description: 'Get the wallet balance in sats',
+  parameters: {},
+  handler: vi.fn(async () => ({ sats: 50_000 })),
+};
+
+const payTool = {
+  name: 'pay_invoice',
+  description: 'Pay a Lightning invoice',
+  parameters: {},
+  requiresConfirmation: true,
+  handler: vi.fn(async (args: Record<string, unknown>) => ({ paid: true, to: args.invoice })),
+};
+
+function freshTools() {
+  balanceTool.handler.mockClear();
+  payTool.handler.mockClear();
+  return new ToolRegistry([new InProcessToolSource('wallet', [balanceTool, payTool])]);
+}
+
+describe('Engine agentic loop', () => {
+  it('calls a read tool, feeds the result back, and returns a final answer', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // turn 1: call tool
+        { text: 'You have 50,000 sats.' }, // turn 2: final answer (sees the result)
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: "what's my balance?" }]);
+
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('You have 50,000 sats.');
+    expect(res.turns).toBe(2);
+    expect(res.toolCalls).toHaveLength(1);
+    expect(res.toolCalls[0].result).toEqual({ sats: 50_000 });
+  });
+
+  it('pauses money tools for confirmation and executes on approval', async () => {
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc1' } }] },
+        { text: 'Sent ✅' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
+
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(payTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('Sent ✅');
+    expect(res.toolCalls[0].result).toEqual({ paid: true, to: 'lnbc1' });
+  });
+
+  it('does NOT execute a money tool when the user declines', async () => {
+    const onConfirm = vi.fn(async () => ({ approved: false, reason: 'cancelled' }));
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc1' } }] },
+        { text: 'Okay, cancelled.' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
+
+    expect(payTool.handler).not.toHaveBeenCalled();
+    expect(res.toolCalls[0].result).toMatchObject({ declined: true, reason: 'cancelled' });
+    expect(res.text).toBe('Okay, cancelled.');
+  });
+
+  it('chains multiple tool calls across turns', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'get_balance', arguments: {} }] },
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc2' } }] },
+        { text: 'Checked balance, then paid.' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'check then pay' }], {
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(payTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.turns).toBe(3);
+    expect(res.toolCalls.map((c) => c.name)).toEqual(['get_balance', 'pay_invoice']);
+  });
+
+  it('stops at maxTurns if the model never stops calling tools', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // always calls a tool
+      ]),
+      tools: freshTools(),
+      defaultMaxTurns: 3,
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'go' }]);
+
+    expect(res.turns).toBe(3);
+    expect(balanceTool.handler).toHaveBeenCalledTimes(3);
+  });
+
+  it('surfaces a tool error as a result instead of throwing', async () => {
+    const boom = {
+      name: 'boom',
+      description: 'throws',
+      parameters: {},
+      handler: vi.fn(async () => {
+        throw new Error('kaboom');
+      }),
+    };
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'boom', arguments: {} }] },
+        { text: 'handled the error' },
+      ]),
+      tools: new ToolRegistry([new InProcessToolSource('x', [boom])]),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'go' }]);
+    expect(res.toolCalls[0].result).toMatchObject({ error: 'kaboom' });
+    expect(res.text).toBe('handled the error');
+  });
+});
+
+describe('ToolRegistry', () => {
+  it('merges tools from multiple sources and routes calls to the owner', async () => {
+    const a = new InProcessToolSource('a', [
+      { name: 'one', description: '', parameters: {}, handler: async () => 'from-a' },
+    ]);
+    const b = new InProcessToolSource('b', [
+      { name: 'two', description: '', parameters: {}, handler: async () => 'from-b' },
+    ]);
+    const reg = new ToolRegistry([a, b]);
+
+    const tools = await reg.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual(['one', 'two']);
+    expect(await reg.execute('one', {})).toBe('from-a');
+    expect(await reg.execute('two', {})).toBe('from-b');
+  });
+
+  it('first source wins on a name clash', async () => {
+    const a = new InProcessToolSource('a', [
+      { name: 'dup', description: 'A', parameters: {}, handler: async () => 'a' },
+    ]);
+    const b = new InProcessToolSource('b', [
+      { name: 'dup', description: 'B', parameters: {}, handler: async () => 'b' },
+    ]);
+    const reg = new ToolRegistry([a, b]);
+    const tools = await reg.listTools();
+    expect(tools).toHaveLength(1);
+    expect(await reg.execute('dup', {})).toBe('a');
+  });
+});

package/src/engine.ts

@@ -37,6 +37,11 @@ export interface AgenticOptions {
   onToolCall?: (call: { name: string; arguments: Record<string, unknown> }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
   onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  /**
+   * Restrict the tools exposed to the model this run (progressive disclosure).
+   * Typically the active skill's tool list — see SkillRegistry.compose().
+   */
+  allowedTools?: string[];
   signal?: AbortSignal;
 }
 
@@ -45,6 +50,10 @@ export interface AgenticResult {
   turns: number;
   toolCalls: ToolResult[];
   requestId?: string;
+  /** Full conversation incl. assistant/tool frames — for logging / datasets. */
+  messages: Message[];
+  /** Wall-clock duration of the whole agentic run, ms. */
+  latencyMs: number;
 }
 
 export class Engine {
@@ -65,8 +74,13 @@ export class Engine {
     const hasSystem = messages.some((m) => m.role === 'system');
     const system = hasSystem ? undefined : this.defaultSystem;
 
+    const startedAt = Date.now();
     const history: Message[] = [...messages];
-    const allTools = await this.registry.listTools();
+    const registryTools = await this.registry.listTools();
+    // Progressive disclosure: expose only the active skill's tools when set.
+    const allTools = opts.allowedTools
+      ? registryTools.filter((t) => opts.allowedTools!.includes(t.name))
+      : registryTools;
     const executed: ToolResult[] = [];
     let lastRequestId: string | undefined;
     let finalText = '';
@@ -124,7 +138,18 @@ export class Engine {
       }
     }
 
-    return { text: finalText, turns, toolCalls: executed, requestId: lastRequestId };
+    // Append the final answer so the returned conversation is complete (the
+    // loop breaks before pushing the no-tool-call turn).
+    if (finalText) history.push({ role: 'assistant', content: finalText });
+
+    return {
+      text: finalText,
+      turns,
+      toolCalls: executed,
+      requestId: lastRequestId,
+      messages: history,
+      latencyMs: Date.now() - startedAt,
+    };
   }
 
   async cancel(requestId: string): Promise<void> {

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