@kaleidorg/mind 0.0.1

package/src/engine.ts

@@ -0,0 +1,141 @@
+/**
+ * Engine — the agentic loop, provider- and tool-source-agnostic.
+ *
+ * This is the shared "brain" logic, lifted out of rate's QVACService so the
+ * mobile app, the desktop app and the agent all run the SAME loop:
+ *
+ *   reason → (tool calls?) → execute / confirm → feed results back → repeat
+ *   → natural-language answer.
+ *
+ * Follows the QVAC multi-turn pattern: push the raw assistant frame plus
+ * `{role:'tool'}` results into history each round, loop until the model stops
+ * calling tools. Money tools pause for an `onConfirm` gate; their handlers run
+ * wherever the ToolSource lives (on the phone for the wallet), even when
+ * inference is delegated to a remote provider.
+ */
+
+import type { ConfirmDecision, Message, ToolResult } from './types.js';
+import type { LLMProvider } from './providers/types.js';
+import type { ToolRegistry } from './tools/registry.js';
+
+export interface EngineOptions {
+  provider: LLMProvider;
+  tools: ToolRegistry;
+  /** Prepended as a system message when the caller didn't supply one. */
+  defaultSystem?: string;
+  /** Max reasoning↔tool rounds before forcing a stop. Default 5. */
+  defaultMaxTurns?: number;
+}
+
+export interface AgenticOptions {
+  maxTurns?: number;
+  /** Visible content tokens as they stream, tagged with the current turn. */
+  onToken?: (token: string, turn: number) => void;
+  /** The live requestId for the current turn (so a stop button can cancel it). */
+  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;
+  /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  signal?: AbortSignal;
+}
+
+export interface AgenticResult {
+  text: string;
+  turns: number;
+  toolCalls: ToolResult[];
+  requestId?: string;
+}
+
+export class Engine {
+  private readonly provider: LLMProvider;
+  private readonly registry: ToolRegistry;
+  private readonly defaultSystem?: string;
+  private readonly defaultMaxTurns: number;
+
+  constructor(opts: EngineOptions) {
+    this.provider = opts.provider;
+    this.registry = opts.tools;
+    this.defaultSystem = opts.defaultSystem;
+    this.defaultMaxTurns = opts.defaultMaxTurns ?? 5;
+  }
+
+  async runAgentic(messages: Message[], opts: AgenticOptions = {}): Promise<AgenticResult> {
+    const maxTurns = opts.maxTurns ?? this.defaultMaxTurns;
+    const hasSystem = messages.some((m) => m.role === 'system');
+    const system = hasSystem ? undefined : this.defaultSystem;
+
+    const history: Message[] = [...messages];
+    const allTools = await this.registry.listTools();
+    const executed: ToolResult[] = [];
+    let lastRequestId: string | undefined;
+    let finalText = '';
+    let turns = 0;
+
+    for (let turn = 1; turn <= maxTurns; turn++) {
+      turns = turn;
+      if (opts.signal?.aborted) break;
+
+      const out = await this.provider.runTurn({
+        messages: history,
+        tools: allTools,
+        system,
+        onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+        signal: opts.signal,
+      });
+
+      lastRequestId = out.requestId;
+      if (out.requestId) opts.onStart?.(out.requestId, turn);
+      finalText = (out.text || '').trim();
+
+      // No tool calls ⇒ the model produced its final answer.
+      if (!out.toolCalls || out.toolCalls.length === 0) break;
+
+      // Anchor the next turn with the raw assistant frame.
+      history.push({ role: 'assistant', content: out.rawContent || finalText });
+
+      for (const call of out.toolCalls) {
+        opts.onToolCall?.({ name: call.name, arguments: call.arguments }, turn);
+        const def = await this.registry.getDef(call.name);
+
+        let result: unknown;
+        if (def?.requiresConfirmation) {
+          const decision = opts.onConfirm
+            ? await opts.onConfirm({ name: call.name, arguments: call.arguments })
+            : { approved: false, reason: 'no confirmation handler available' };
+          if (decision.approved) {
+            result = await this.safeExecute(call.name, call.arguments);
+          } else {
+            result = { declined: true, reason: decision.reason ?? 'user declined' };
+          }
+        } else {
+          result = await this.safeExecute(call.name, call.arguments);
+        }
+
+        executed.push({ name: call.name, arguments: call.arguments, result });
+        history.push({
+          role: 'tool',
+          content: typeof result === 'string' ? result : JSON.stringify(result),
+        });
+      }
+
+      if (turn === maxTurns && !finalText) {
+        finalText = 'I had to stop after several steps — please try a more specific request.';
+      }
+    }
+
+    return { text: finalText, turns, toolCalls: executed, requestId: lastRequestId };
+  }
+
+  async cancel(requestId: string): Promise<void> {
+    await this.provider.cancel?.(requestId);
+  }
+
+  private async safeExecute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    try {
+      return await this.registry.execute(name, args);
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @kaleido/mind — shared local-AI reasoning engine for KaleidoSwap.
+ *
+ * Pure TypeScript, zero runtime dependencies. Hosts inject:
+ *   - an LLMProvider (wrapping @qvac/sdk, Anthropic, …)
+ *   - one or more ToolSources (in-process wallet tools, MCP servers, …)
+ *
+ * and get the shared agentic loop, identical on mobile / desktop / agent.
+ */
+
+export type {
+  Role,
+  Message,
+  ToolDef,
+  ToolCall,
+  ToolResult,
+  ConfirmDecision,
+} from './types.js';
+
+export type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+
+export type { ToolSource } from './tools/source.js';
+export { InProcessToolSource } from './tools/in-process.js';
+export type { InProcessTool } from './tools/in-process.js';
+export { ToolRegistry } from './tools/registry.js';
+
+export { Engine } from './engine.js';
+export type { EngineOptions, AgenticOptions, AgenticResult } from './engine.js';
+
+export { TurnLogger, defaultMask } from './logger.js';
+export type { TurnLog, Device, LoggerIO, LoggerOptions } from './logger.js';

package/src/logger.ts

@@ -0,0 +1,127 @@
+/**
+ * Structured turn logger — JSONL output, designed for future fine-tuning
+ * datasets. Format is compatible with Salesforce/APIGen-MT-5k so KaleidoMind
+ * records can be concatenated with public data and fed to SFT pipelines.
+ *
+ * Privacy posture: amounts/addresses/contacts are HASHED at log time.
+ * Raw values are kept in a separate local store and only re-attached at
+ * export with explicit --include-pii.
+ */
+
+import type { Message, ToolCall, ToolResult } from './types.js';
+
+export type Device =
+  | 'rate-ios'
+  | 'rate-android'
+  | 'kaleido-agent'
+  | 'rate-extension'
+  | 'kaleido-cli'
+  | 'playground';
+
+export interface TurnLog {
+  id: string;
+  ts: string;
+  session_id: string;
+  device: Device;
+  model: {
+    provider: string;
+    name: string;
+    version?: string;
+  };
+  /** Hash-based identifier for the system prompt — same hash = same prompt. */
+  system_hash: string;
+  /** Names + schema hashes only, never raw schemas with semantic data. */
+  tools: { name: string; schema_hash: string }[];
+  messages: Message[];
+  decision: {
+    tool_calls: ToolCall[];
+    final_text: string | null;
+    reasoning_tokens?: number;
+  };
+  results: ToolResult[];
+  feedback?: {
+    thumbs?: 'up' | 'down';
+    edited_args?: Record<string, unknown>;
+    retry_count?: number;
+  };
+  latency_ms: {
+    transcribe?: number;
+    reason: number;
+    tools?: number;
+    total: number;
+  };
+  meta?: Record<string, unknown>;
+}
+
+export interface LoggerOptions {
+  /** Absolute path where YYYY-MM-DD/session-<id>.jsonl files are written. */
+  dir: string;
+  device: Device;
+  /** Pluggable IO so the same logger works in Node + RN + tests. */
+  io: LoggerIO;
+  /** PII masker — defaults to hashing common fields. */
+  mask?: (log: TurnLog) => TurnLog;
+}
+
+export interface LoggerIO {
+  ensureDir(path: string): Promise<void>;
+  appendLine(filePath: string, line: string): Promise<void>;
+  hash(value: unknown): string;
+  now(): Date;
+}
+
+export class TurnLogger {
+  constructor(private readonly opts: LoggerOptions) {}
+
+  async log(input: Omit<TurnLog, 'id' | 'ts' | 'device'>): Promise<void> {
+    const ts = this.opts.io.now().toISOString();
+    const id = `${input.session_id}-${this.opts.io.hash({ ts, n: Math.random() }).slice(0, 8)}`;
+    let entry: TurnLog = { ...input, id, ts, device: this.opts.device };
+    if (this.opts.mask) entry = this.opts.mask(entry);
+
+    const day = ts.slice(0, 10);
+    const dir = `${this.opts.dir}/${day}`;
+    await this.opts.io.ensureDir(dir);
+    await this.opts.io.appendLine(
+      `${dir}/session-${input.session_id}.jsonl`,
+      JSON.stringify(entry),
+    );
+  }
+}
+
+/**
+ * Default masking — hashes amounts, addresses, invoices, contact names.
+ * Tools without these fields pass through unchanged.
+ */
+export function defaultMask(io: LoggerIO): (log: TurnLog) => TurnLog {
+  const FIELDS_TO_HASH = new Set([
+    'amount', 'amount_msat', 'amount_sat',
+    'address', 'invoice', 'bolt11', 'pubkey', 'node_id',
+    'contact', 'contact_name', 'recipient',
+  ]);
+
+  const walk = (v: unknown): unknown => {
+    if (v === null || v === undefined) return v;
+    if (Array.isArray(v)) return v.map(walk);
+    if (typeof v === 'object') {
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = FIELDS_TO_HASH.has(k) ? `h:${io.hash(val).slice(0, 8)}` : walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+
+  return (log) => ({
+    ...log,
+    decision: {
+      ...log.decision,
+      tool_calls: log.decision.tool_calls.map((c) => ({
+        ...c,
+        arguments: walk(c.arguments) as Record<string, unknown>,
+      })),
+    },
+    results: log.results.map((r) => ({ ...r, result: walk(r.result) })),
+  });
+}

package/src/providers/types.ts

@@ -0,0 +1,47 @@
+/**
+ * LLMProvider — the only thing the Engine talks to for inference.
+ *
+ * Each host implements this over its own LLM transport:
+ *   - rate (mobile): wraps @qvac/sdk completion() (local or P2P-delegated)
+ *   - desktop-app:   wraps @qvac/sdk completion() in Node
+ *   - kaleidoagent:  could wrap Anthropic/OpenAI
+ *
+ * The core package never imports any LLM SDK — it only depends on this
+ * interface, so it stays pure TS and bundles anywhere.
+ */
+
+import type { Message, ToolCall, ToolDef } from '../types.js';
+
+export interface TurnInput {
+  messages: Message[];
+  tools: ToolDef[];
+  /** System prompt, when not already present as a message. */
+  system?: string;
+  /** Visible content tokens as they stream. */
+  onToken?: (token: string) => void;
+  signal?: AbortSignal;
+}
+
+export interface TurnOutput {
+  /** Cleaned assistant content for display. */
+  text: string;
+  /**
+   * Raw assistant frame to push back into history for the next turn. For
+   * tool-calling models this includes the tool-call framing the model needs
+   * to anchor continuation (e.g. QVAC's `final.raw.fullText`). Falls back to
+   * `text` when a provider has no separate raw form.
+   */
+  rawContent: string;
+  /** Tool calls the model requested this turn (empty ⇒ final answer). */
+  toolCalls: ToolCall[];
+  /** Provider request id, for cancellation. */
+  requestId?: string;
+}
+
+export interface LLMProvider {
+  readonly name: string;
+  /** Run one completion turn. */
+  runTurn(input: TurnInput): Promise<TurnOutput>;
+  /** Cancel an in-flight turn by request id, if the provider supports it. */
+  cancel?(requestId: string): Promise<void>;
+}

package/src/tools/in-process.ts

@@ -0,0 +1,49 @@
+/**
+ * InProcessToolSource — tools whose handlers run in the same process.
+ *
+ * Used by the mobile wallet: the handlers call the device's wallet adapters
+ * (Spark / Arkade / RGB) directly, so signing happens on the phone even when
+ * the model's inference is delegated to a desktop over P2P.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export interface InProcessTool<Args = Record<string, unknown>> {
+  name: string;
+  description: string;
+  /** Zod schema (or any shape the provider understands). */
+  parameters: unknown;
+  /** When true, the engine pauses for confirmation before executing. */
+  requiresConfirmation?: boolean;
+  handler: (args: Args) => Promise<unknown>;
+}
+
+export class InProcessToolSource implements ToolSource {
+  readonly id: string;
+  private readonly tools = new Map<string, InProcessTool>();
+
+  constructor(id: string, tools: InProcessTool[]) {
+    this.id = id;
+    for (const t of tools) this.tools.set(t.name, t as InProcessTool);
+  }
+
+  listTools(): ToolDef[] {
+    return Array.from(this.tools.values()).map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+      requiresConfirmation: t.requiresConfirmation,
+    }));
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  async execute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Tool "${name}" not found in source "${this.id}"`);
+    return tool.handler(args);
+  }
+}

package/src/tools/mcp.ts

@@ -0,0 +1,112 @@
+/**
+ * McpToolSource — exposes an MCP server's tools to the engine. NODE ONLY.
+ *
+ * Not exported from the package's main entry (`@kaleido/mind`) — import it
+ * explicitly from `@kaleido/mind/mcp` on Node hosts (desktop-app, kaleidoagent)
+ * so React Native never bundles the MCP SDK or any subprocess machinery.
+ *
+ * Connects to a server like `kaleido-mcp` (Spark + RLN + KaleidoSwap DEX +
+ * MPP/L402 + market data, ~64 tools) over stdio or HTTP, lists its tools, and
+ * routes execute() calls through the MCP client.
+ *
+ * The `@modelcontextprotocol/sdk` dependency is imported dynamically so this
+ * file type-checks and ships even where the SDK isn't installed; constructing
+ * an McpToolSource without it throws a clear error.
+ *
+ * STATUS: skeleton for the desktop pass. The shape is final; the connect()
+ * body is wired when we integrate desktop-app.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export type McpTransport =
+  | { kind: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | { kind: 'http'; url: string; headers?: Record<string, string> };
+
+export interface McpToolSourceOptions {
+  id: string;
+  transport: McpTransport;
+  /** Optional allowlist — only expose these tool names if provided. */
+  allow?: string[];
+  /** Per-call timeout (ms). Default 60_000. */
+  timeoutMs?: number;
+}
+
+export class McpToolSource implements ToolSource {
+  readonly id: string;
+  private readonly opts: McpToolSourceOptions;
+  private client: any | null = null;
+  private tools: ToolDef[] = [];
+
+  constructor(opts: McpToolSourceOptions) {
+    this.id = opts.id;
+    this.opts = opts;
+  }
+
+  /** Connect to the MCP server and cache its tool list. Call once at startup. */
+  async connect(): Promise<void> {
+    // Dynamic import keeps the MCP SDK out of bundles that never call connect().
+    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+    const t = this.opts.transport;
+
+    let transport: any;
+    if (t.kind === 'stdio') {
+      const { StdioClientTransport } = await import(
+        '@modelcontextprotocol/sdk/client/stdio.js'
+      );
+      transport = new StdioClientTransport({ command: t.command, args: t.args ?? [], env: t.env });
+    } else {
+      const { StreamableHTTPClientTransport } = await import(
+        '@modelcontextprotocol/sdk/client/streamableHttp.js'
+      );
+      transport = new StreamableHTTPClientTransport(new URL(t.url), {
+        requestInit: t.headers ? { headers: t.headers } : undefined,
+      });
+    }
+
+    this.client = new Client({ name: `kaleido-mind:${this.id}`, version: '0.0.1' }, { capabilities: {} });
+    await this.client.connect(transport);
+
+    const listed = await this.client.listTools();
+    const allow = this.opts.allow ? new Set(this.opts.allow) : null;
+    this.tools = (listed.tools ?? [])
+      .filter((t: any) => !allow || allow.has(t.name))
+      .map((t: any) => ({
+        name: t.name,
+        description: t.description ?? '',
+        parameters: t.inputSchema ?? { type: 'object', properties: {} },
+      }));
+  }
+
+  listTools(): ToolDef[] {
+    return this.tools;
+  }
+
+  has(name: string): boolean {
+    return this.tools.some((t) => t.name === name);
+  }
+
+  async execute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    if (!this.client) throw new Error(`McpToolSource "${this.id}" not connected — call connect() first`);
+    const res = await this.client.callTool(
+      { name, arguments: args },
+      undefined,
+      { timeout: this.opts.timeoutMs ?? 60_000 },
+    );
+    // MCP returns content blocks; surface text content as the tool result.
+    if (Array.isArray(res?.content)) {
+      const text = res.content
+        .filter((c: any) => c.type === 'text')
+        .map((c: any) => c.text)
+        .join('\n');
+      return text || res.content;
+    }
+    return res;
+  }
+
+  async close(): Promise<void> {
+    await this.client?.close?.();
+    this.client = null;
+  }
+}

package/src/tools/registry.ts

@@ -0,0 +1,56 @@
+/**
+ * ToolRegistry — merges multiple ToolSources into one tool list for the model
+ * and routes each tool call back to the source that owns it.
+ *
+ * Name-clash policy: first source wins (sources are consulted in registration
+ * order), so a host can layer a high-priority source over a broader one.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export class ToolRegistry {
+  private readonly sources: ToolSource[] = [];
+
+  constructor(sources: ToolSource[] = []) {
+    this.sources = [...sources];
+  }
+
+  add(source: ToolSource): this {
+    this.sources.push(source);
+    return this;
+  }
+
+  /** Merged, de-duplicated tool list across all sources. */
+  async listTools(): Promise<ToolDef[]> {
+    const out: ToolDef[] = [];
+    const seen = new Set<string>();
+    for (const source of this.sources) {
+      const tools = await source.listTools();
+      for (const t of tools) {
+        if (seen.has(t.name)) continue; // first source wins
+        seen.add(t.name);
+        out.push(t);
+      }
+    }
+    return out;
+  }
+
+  /** The first source that owns a tool by name. */
+  private ownerOf(name: string): ToolSource | undefined {
+    return this.sources.find((s) => s.has(name));
+  }
+
+  /** Execute a tool, routing to its owning source. */
+  async execute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const owner = this.ownerOf(name);
+    if (!owner) throw new Error(`No tool source owns "${name}"`);
+    return owner.execute(name, args);
+  }
+
+  /** Look up a tool definition (e.g. to check requiresConfirmation). */
+  async getDef(name: string): Promise<ToolDef | undefined> {
+    const tools = await this.listTools();
+    return tools.find((t) => t.name === name);
+  }
+}

package/src/tools/source.ts

@@ -0,0 +1,26 @@
+/**
+ * ToolSource — anything that exposes a set of tools and can execute them.
+ *
+ * This is the seam that makes the engine modular. Two implementations cover
+ * every surface:
+ *   - InProcessToolSource — Zod tools + local handlers (works on React Native;
+ *     used by the mobile wallet — handlers run on-device so keys never leave)
+ *   - McpToolSource       — connects an MCP server over stdio/HTTP (Node only;
+ *     used on desktop for the full kaleido-mcp toolset)
+ *
+ * The engine merges N sources into one tool list for the model and routes each
+ * tool call back to the source that owns it.
+ */
+
+import type { ToolDef } from '../types.js';
+
+export interface ToolSource {
+  /** Stable identifier (for logging / debugging). */
+  readonly id: string;
+  /** The tools this source exposes. May be async (e.g. MCP listTools). */
+  listTools(): ToolDef[] | Promise<ToolDef[]>;
+  /** Whether this source owns a tool by name. */
+  has(name: string): boolean;
+  /** Execute a tool this source owns. */
+  execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Core types for the kaleido-mind engine.
+ *
+ * Pure data shapes — no runtime dependencies. The engine, tool sources and
+ * providers are all defined in terms of these, so the core package bundles
+ * cleanly on any host (React Native / Node / browser) without dragging in
+ * @qvac/sdk or any native code.
+ */
+
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface Message {
+  role: Role;
+  content: string;
+}
+
+/**
+ * A tool the model can call. `parameters` is intentionally `unknown` — it may
+ * be a Zod schema (in-process tools) or a JSON Schema (MCP tools). Each
+ * provider converts it to whatever its SDK expects.
+ */
+export interface ToolDef {
+  name: string;
+  description: string;
+  parameters: unknown;
+  /** When true, the engine pauses for `onConfirm` before executing (e.g. payments). */
+  requiresConfirmation?: boolean;
+}
+
+export interface ToolCall {
+  /** Provider-assigned id, when available. */
+  id?: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface ToolResult {
+  name: string;
+  arguments: Record<string, unknown>;
+  result: unknown;
+}
+
+export interface ConfirmDecision {
+  approved: boolean;
+  reason?: string;
+}