@kaleidorg/mind 0.1.0 → 0.3.0

package/src/funnel.ts

@@ -0,0 +1,285 @@
+/**
+ * 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.',
+  '',
+  'CORE RULES (these override every skill instruction):',
+  "1. If a tool can answer the user's question, CALL IT. Never describe how a",
+  "   tool works (\"the pairs are listed using kaleidoswap_get_pairs\") — calling",
+  '   the tool IS the answer.',
+  '2. Never invent a balance, address, amount, price, quote, fee, pair, or any',
+  "   other value. Every number or identifier in your reply MUST come from a tool",
+  '   result returned in the CURRENT turn.',
+  '3. Never reuse a number, name, or detail from a previous turn unless the user',
+  '   is explicitly asking about that earlier result. Each new question gets a',
+  '   fresh tool call.',
+  '4. If a tool needs a required argument the user did not give (e.g. an amount',
+  "   for a quote), ASK for it. Do not invent values. Do not call the tool with",
+  '   the required field missing.',
+  '5. All BTC amounts are in satoshis. Asset codes are case-insensitive but the',
+  '   canonical forms are BTC, USDT, XAUT — do not silently shorten to USD, XAU.',
+  '',
+  'Keep replies short and friendly. When a tool returns multiple fields, surface',
+  "the ones that matter — never collapse a structured result to a single number",
+  'when other fields are non-zero or safety-relevant (e.g. pending balances,',
+  'fees, slippage).',
+].join('\n');
+
+/** 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;
+  /** A tool returned a result (agentic tier). Errors arrive as `{error}`. */
+  onToolResult?: (event: {
+    name: string;
+    arguments: Record<string, unknown>;
+    result: unknown;
+  }) => 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 }));
+      },
+      onToolResult: cbs.onToolResult,
+      onConfirm: cbs.onConfirm,
+    });
+    return { text: res.text ?? '', tier: 'agentic', toolCalls: res.toolCalls, turns: res.turns };
+  }
+}

package/src/index.ts

@@ -29,10 +29,138 @@ 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';
+export { confirmReadback } from './wallet/confirm.js';
+
+// ── KaleidoSwap maker tool contract (single source of truth) ────────────────
+export {
+  KALEIDOSWAP_TOOLS,
+  KALEIDOSWAP_SPEND_TOOLS,
+  isKaleidoswapSpendTool,
+  getKaleidoswapTool,
+  kaleidoswapTools,
+  bindKaleidoswapTools,
+} from './kaleidoswap/contract.js';
+export type {
+  KaleidoswapGroup,
+  KaleidoswapToolDef,
+  KaleidoswapHandler,
+  BindKaleidoswapOptions,
+} from './kaleidoswap/contract.js';
+
+// ── LSPS1 (Lightning Service Provider channel orders) ───────────────────────
+export {
+  LSPS1_TOOLS,
+  LSPS1_SPEND_TOOLS,
+  isLsps1SpendTool,
+  getLsps1Tool,
+  bindLsps1Tools,
+} from './lsps1/contract.js';
+export type {
+  Lsps1ToolDef,
+  Lsps1Handler,
+  BindLsps1Options,
+} from './lsps1/contract.js';
+
+// ── KaleidoSwap atomic-swap recipe (opt-in — register via Funnel.recipes) ──
+export { kaleidoswapAtomicRecipe } from './recipe/kaleidoswap-atomic.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,
+  MemoryConsolidation,
+  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 { createBtcMapToolSource, BTC_MAP_SAMPLE } from './knowledge/btc-map.js';
+export type {
+  BtcMapToolOptions,
+  BtcMapMerchant,
+  BtcMapFetch,
+  LocationProvider,
+  LatLng,
+} from './knowledge/btc-map.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,

package/src/kaleidoswap/contract.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest';
+import {
+  KALEIDOSWAP_TOOLS,
+  KALEIDOSWAP_SPEND_TOOLS,
+  isKaleidoswapSpendTool,
+  getKaleidoswapTool,
+  kaleidoswapTools,
+  bindKaleidoswapTools,
+  type KaleidoswapHandler,
+} from './contract.js';
+
+describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
+  it('exposes the expected tool names', () => {
+    const names = KALEIDOSWAP_TOOLS.map((t) => t.name);
+    expect(names).toEqual([
+      'kaleidoswap_get_assets',
+      'kaleidoswap_get_pairs',
+      'kaleidoswap_get_quote',
+      'kaleidoswap_get_nodeinfo',
+      'kaleidoswap_place_order',
+      'kaleidoswap_get_order_status',
+      'kaleidoswap_get_order_history',
+      'kaleidoswap_atomic_init',
+      'kaleidoswap_atomic_execute',
+      'kaleidoswap_atomic_status',
+    ]);
+  });
+
+  it('every tool has a group and a parameters object', () => {
+    for (const t of KALEIDOSWAP_TOOLS) {
+      expect(['market', 'orders', 'atomic']).toContain(t.group);
+      expect(t.parameters).toBeDefined();
+      expect((t.parameters as any).type).toBe('object');
+    }
+  });
+
+  it('marks every spend tool as requiresConfirmation', () => {
+    for (const t of KALEIDOSWAP_TOOLS) {
+      expect(!!t.spend).toBe(!!t.requiresConfirmation);
+    }
+  });
+
+  it('lists every spend tool exactly once in KALEIDOSWAP_SPEND_TOOLS', () => {
+    const expected = KALEIDOSWAP_TOOLS.filter((t) => t.spend).map((t) => t.name).sort();
+    expect([...KALEIDOSWAP_SPEND_TOOLS].sort()).toEqual(expected);
+    // Sanity: place_order, atomic_init, atomic_execute are spend; the rest aren't.
+    expect(expected).toEqual([
+      'kaleidoswap_atomic_execute',
+      'kaleidoswap_atomic_init',
+      'kaleidoswap_place_order',
+    ]);
+  });
+
+  it('isKaleidoswapSpendTool agrees with the set', () => {
+    expect(isKaleidoswapSpendTool('kaleidoswap_place_order')).toBe(true);
+    expect(isKaleidoswapSpendTool('kaleidoswap_get_pairs')).toBe(false);
+    expect(isKaleidoswapSpendTool('not_a_tool')).toBe(false);
+  });
+
+  it('getKaleidoswapTool returns by name', () => {
+    expect(getKaleidoswapTool('kaleidoswap_get_quote')?.group).toBe('market');
+    expect(getKaleidoswapTool('nope')).toBeUndefined();
+  });
+});
+
+describe('kaleidoswapTools(groups)', () => {
+  it('returns all tools when no group filter', () => {
+    expect(kaleidoswapTools().length).toBe(KALEIDOSWAP_TOOLS.length);
+  });
+
+  it('filters by group', () => {
+    const market = kaleidoswapTools({ groups: ['market'] });
+    expect(market.every((t) => t.group === 'market')).toBe(true);
+    expect(market.map((t) => t.name)).toContain('kaleidoswap_get_quote');
+    expect(market.map((t) => t.name)).not.toContain('kaleidoswap_place_order');
+  });
+
+  it('combines multiple groups', () => {
+    const readPlusOrders = kaleidoswapTools({ groups: ['market', 'orders'] });
+    expect(readPlusOrders.some((t) => t.name === 'kaleidoswap_atomic_init')).toBe(false);
+    expect(readPlusOrders.some((t) => t.name === 'kaleidoswap_place_order')).toBe(true);
+  });
+});
+
+describe('bindKaleidoswapTools', () => {
+  // Handlers that just echo their args so we can verify wiring.
+  const echoHandlers = (): Record<string, KaleidoswapHandler> => ({
+    kaleidoswap_get_assets:        async () => ({ ok: true, tool: 'get_assets' }),
+    kaleidoswap_get_pairs:         async () => ({ ok: true, tool: 'get_pairs' }),
+    kaleidoswap_get_quote:         async (a) => ({ ok: true, tool: 'get_quote', args: a }),
+    kaleidoswap_get_nodeinfo:      async () => ({ ok: true, tool: 'get_nodeinfo' }),
+    kaleidoswap_place_order:       async (a) => ({ ok: true, tool: 'place_order', args: a }),
+    kaleidoswap_get_order_status:  async (a) => ({ ok: true, tool: 'get_order_status', args: a }),
+    kaleidoswap_get_order_history: async (a) => ({ ok: true, tool: 'get_order_history', args: a }),
+    kaleidoswap_atomic_init:       async (a) => ({ ok: true, tool: 'atomic_init', args: a }),
+    kaleidoswap_atomic_execute:    async (a) => ({ ok: true, tool: 'atomic_execute', args: a }),
+    kaleidoswap_atomic_status:     async (a) => ({ ok: true, tool: 'atomic_status', args: a }),
+  });
+
+  it('binds every tool when all handlers are present', () => {
+    const src = bindKaleidoswapTools(echoHandlers());
+    const tools = src.listTools();
+    expect(tools.length).toBe(KALEIDOSWAP_TOOLS.length);
+  });
+
+  it('preserves descriptions and the spend gate (requiresConfirmation)', () => {
+    const src = bindKaleidoswapTools(echoHandlers());
+    const place = src.listTools().find((t) => t.name === 'kaleidoswap_place_order');
+    const pairs = src.listTools().find((t) => t.name === 'kaleidoswap_get_pairs');
+    expect(place?.requiresConfirmation).toBe(true);
+    expect(pairs?.requiresConfirmation).toBeFalsy();
+  });
+
+  it('dispatches execute() to the right handler with args', async () => {
+    const src = bindKaleidoswapTools(echoHandlers());
+    const r = await src.execute('kaleidoswap_get_quote', { from_asset: 'BTC', to_asset: 'USDT', amount: 100_000 });
+    expect(r).toMatchObject({ ok: true, tool: 'get_quote', args: { from_asset: 'BTC', amount: 100_000 } });
+  });
+
+  it('throws when a handler is missing and allowMissing is false', () => {
+    const handlers = { kaleidoswap_get_pairs: echoHandlers().kaleidoswap_get_pairs };
+    expect(() => bindKaleidoswapTools(handlers)).toThrow(/no handler/);
+  });
+
+  it('skips missing handlers when allowMissing is true', () => {
+    const handlers: Record<string, KaleidoswapHandler> = {
+      kaleidoswap_get_pairs: async () => ({ ok: true }),
+      kaleidoswap_get_quote: async () => ({ ok: true }),
+    };
+    const src = bindKaleidoswapTools(handlers, { allowMissing: true });
+    const names = src.listTools().map((t) => t.name);
+    expect(names).toEqual(['kaleidoswap_get_pairs', 'kaleidoswap_get_quote']);
+  });
+
+  it('respects the groups filter when binding', () => {
+    const src = bindKaleidoswapTools(echoHandlers(), { groups: ['market'] });
+    const names = src.listTools().map((t) => t.name);
+    expect(names).toContain('kaleidoswap_get_quote');
+    expect(names).not.toContain('kaleidoswap_place_order');
+    expect(names).not.toContain('kaleidoswap_atomic_init');
+  });
+
+  it('uses opts.id for the ToolSource id', () => {
+    const src = bindKaleidoswapTools(echoHandlers(), { id: 'maker-prod' });
+    expect(src.id).toBe('maker-prod');
+  });
+});