@kaleidorg/mind 0.5.1 → 0.6.1

package/src/context/compress.ts

@@ -0,0 +1,230 @@
+/**
+ * Tool-output compression — the "fit more into a tiny window" part.
+ *
+ * Tool results are the single biggest, most repetitive thing the engine pushes
+ * into a small on-device model's context. A merchant search returns 40 near
+ * identical rows; a tx history returns hundreds; a swap quote nests config the
+ * model never reads. Every round, the *raw* `JSON.stringify(result)` is fed back
+ * into history — so on a 2k-window 0.6B model the conversation drowns in JSON
+ * the model didn't need, crowding out the system prompt, the skill, and the
+ * actual question.
+ *
+ * `compressToolResult` is a structural crusher (the idea behind Headroom's
+ * SmartCrusher/ToolCrusher, reimplemented natively — no dependency, no network,
+ * no proxy, so it stays on-device and private). It walks the JSON and:
+ *
+ *   • dedupes identical array items, then keeps the first/last few and replaces
+ *     the middle with an honest `{ "__elided__": N }` marker,
+ *   • caps nesting depth (deep config → a one-line summary),
+ *   • truncates long *prose* strings (logs, descriptions),
+ *
+ * and never regresses: if crushing doesn't actually save tokens, the original
+ * is returned untouched.
+ *
+ * SAFETY: it never touches numbers, never elides whole objects, never truncates
+ * whitespace-free strings (addresses, BOLT11 invoices, txids, pubkeys), and
+ * never touches a value under a money/identity key (see DEFAULT_PRESERVE_KEYS).
+ * Amounts and recipients reach the model intact — the confirm readback is built
+ * deterministically from the resolved call anyway, but this keeps the model's
+ * own view honest too. Small results (below `minTokens`) are passed through
+ * verbatim so nothing changes for the common case.
+ */
+
+import { estimateTokens } from './budget.js';
+
+/** Keys whose values are never elided or truncated — amounts, ids, recipients. */
+export const DEFAULT_PRESERVE_KEYS: readonly string[] = [
+  'amount',
+  'amount_sat',
+  'amount_sats',
+  'amount_msat',
+  'sat',
+  'sats',
+  'msat',
+  'value',
+  'fee',
+  'fee_sat',
+  'fee_sats',
+  'total',
+  'total_sats',
+  'balance',
+  'balance_sat',
+  'address',
+  'invoice',
+  'bolt11',
+  'payment_request',
+  'payment_hash',
+  'preimage',
+  'txid',
+  'tx_id',
+  'pubkey',
+  'node_id',
+  'recipient',
+  'destination',
+  'asset_id',
+  'contract_id',
+  'rate',
+  'price',
+  'price_usd',
+];
+
+export interface ToolCrushOptions {
+  /** Don't compress results estimated below this many tokens. Default 200. */
+  minTokens?: number;
+  /** Max items kept in any array before the middle is elided. Default 8. */
+  maxArrayItems?: number;
+  /** Max nesting depth kept verbatim; deeper is summarized. Default 6. */
+  maxDepth?: number;
+  /** Max chars for a single prose string before truncation (0 disables). Default 600. */
+  maxStringLength?: number;
+  /** Dedupe identical array items before eliding. Default true. */
+  dedupe?: boolean;
+  /** Keys whose values are never elided/truncated (defaults to DEFAULT_PRESERVE_KEYS). */
+  preserveKeys?: readonly string[];
+}
+
+export interface CrushResult {
+  /** Serialized, compressed content — ready to push into history. */
+  content: string;
+  /** Estimated tokens of the original serialization. */
+  originalTokens: number;
+  /** Estimated tokens after crushing. */
+  compressedTokens: number;
+  /** Total array items dropped across the whole structure. */
+  elided: number;
+  /** False when the original was returned untouched (too small, or no win). */
+  changed: boolean;
+}
+
+interface Resolved {
+  minTokens: number;
+  maxArrayItems: number;
+  maxDepth: number;
+  maxStringLength: number;
+  dedupe: boolean;
+  preserve: Set<string>;
+}
+
+/** A string with no whitespace is treated as an identifier (address/invoice/hash) and never truncated. */
+function isIdentifierLike(s: string): boolean {
+  return !/\s/.test(s);
+}
+
+function serialize(value: unknown): string {
+  return typeof value === 'string' ? value : safeStringify(value);
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Crush a tool result for inclusion in model context. Returns the original,
+ * verbatim, when it's small or when crushing wouldn't save tokens.
+ */
+export function compressToolResult(value: unknown, opts: ToolCrushOptions = {}): CrushResult {
+  const cfg: Resolved = {
+    minTokens: opts.minTokens ?? 200,
+    maxArrayItems: Math.max(2, opts.maxArrayItems ?? 8),
+    maxDepth: Math.max(1, opts.maxDepth ?? 6),
+    maxStringLength: opts.maxStringLength ?? 600,
+    dedupe: opts.dedupe ?? true,
+    preserve: new Set((opts.preserveKeys ?? DEFAULT_PRESERVE_KEYS).map((k) => k.toLowerCase())),
+  };
+
+  const original = serialize(value);
+  const originalTokens = estimateTokens(original);
+
+  // Below the floor, never touch it — correctness over savings for small results.
+  if (originalTokens < cfg.minTokens) {
+    return { content: original, originalTokens, compressedTokens: originalTokens, elided: 0, changed: false };
+  }
+
+  let elided = 0;
+  const crushed = crush(value, cfg, 0, false, () => {
+    elided += 1;
+  });
+  const content = serialize(crushed);
+  const compressedTokens = estimateTokens(content);
+
+  // Never regress: if crushing didn't actually shrink it, keep the original.
+  if (compressedTokens >= originalTokens) {
+    return { content: original, originalTokens, compressedTokens: originalTokens, elided: 0, changed: false };
+  }
+
+  return { content, originalTokens, compressedTokens, elided, changed: true };
+}
+
+/**
+ * Recursively crush a JSON-ish value.
+ *
+ * @param preserved when true, the value sits under a preserve key — kept verbatim.
+ * @param onElide   called once per array item dropped (for stats).
+ */
+function crush(value: unknown, cfg: Resolved, depth: number, preserved: boolean, onElide: () => void): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === 'string') {
+    if (preserved || isIdentifierLike(value)) return value;
+    if (cfg.maxStringLength > 0 && value.length > cfg.maxStringLength) {
+      const omitted = value.length - cfg.maxStringLength;
+      return `${value.slice(0, cfg.maxStringLength)}… (+${omitted} chars)`;
+    }
+    return value;
+  }
+
+  if (typeof value !== 'object') return value; // number, boolean — never touched
+
+  // Beyond max depth, collapse to a one-line shape summary instead of the subtree.
+  if (depth >= cfg.maxDepth) {
+    if (Array.isArray(value)) return `[array: ${value.length} items]`;
+    return `[object: ${Object.keys(value as object).length} keys]`;
+  }
+
+  if (Array.isArray(value)) {
+    let items = value;
+
+    if (cfg.dedupe && items.length > cfg.maxArrayItems) {
+      const seen = new Set<string>();
+      const unique: unknown[] = [];
+      for (const item of items) {
+        const key = safeStringify(item);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        unique.push(item);
+      }
+      items = unique;
+    }
+
+    if (items.length <= cfg.maxArrayItems) {
+      return items.map((v) => crush(v, cfg, depth + 1, preserved, onElide));
+    }
+
+    // Keep the front and a little of the tail (Headroom's "anchors"); elide the
+    // middle with an honest marker so the model knows data was omitted and can
+    // ask a more specific question / call a narrower tool.
+    const keepFirst = Math.max(1, Math.ceil(cfg.maxArrayItems * 0.6));
+    const keepLast = Math.max(0, cfg.maxArrayItems - keepFirst);
+    const head = items.slice(0, keepFirst);
+    const tail = keepLast > 0 ? items.slice(items.length - keepLast) : [];
+    const droppedCount = items.length - head.length - tail.length;
+    for (let i = 0; i < droppedCount; i++) onElide();
+
+    const out: unknown[] = head.map((v) => crush(v, cfg, depth + 1, preserved, onElide));
+    out.push({ __elided__: droppedCount, note: 'items omitted to fit context' });
+    for (const v of tail) out.push(crush(v, cfg, depth + 1, preserved, onElide));
+    return out;
+  }
+
+  const obj = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(obj)) {
+    const keep = preserved || cfg.preserve.has(key.toLowerCase());
+    result[key] = crush(v, cfg, depth + 1, keep, onElide);
+  }
+  return result;
+}

package/src/engine.test.ts

@@ -150,6 +150,40 @@ describe('Engine agentic loop', () => {
     expect(balanceTool.handler).toHaveBeenCalledTimes(3);
   });
 
+  it('crushes verbose tool output in history but keeps the raw result for callbacks', async () => {
+    const bulky = {
+      name: 'list_merchants',
+      description: 'returns many rows',
+      parameters: {},
+      handler: vi.fn(async () => ({
+        results: Array.from({ length: 50 }, (_, i) => ({
+          name: `Shop ${i}`,
+          blurb: 'Accepts Bitcoin and Lightning, open daily, friendly staff and good wifi.',
+          amount_sats: 1000 + i,
+        })),
+      })),
+    };
+    const onToolResult = vi.fn();
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'list_merchants', arguments: {} }] },
+        { text: 'Found some merchants.' },
+      ]),
+      tools: new ToolRegistry([new InProcessToolSource('m', [bulky])]),
+      compressToolOutput: { maxArrayItems: 6 },
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'find cafes' }], { onToolResult });
+
+    // The history frame the model sees is crushed (elision marker present)...
+    const toolFrame = res.messages.find((m) => m.role === 'tool');
+    expect(toolFrame?.content).toContain('__elided__');
+    // ...but amounts survive and the callback/result still carry the full data.
+    expect(toolFrame?.content).toContain('amount_sats');
+    expect(onToolResult.mock.calls[0][0].result).toEqual(await bulky.handler.mock.results[0].value);
+    expect((res.toolCalls[0].result as { results: unknown[] }).results).toHaveLength(50);
+  });
+
   it('surfaces a tool error as a result instead of throwing', async () => {
     const boom = {
       name: 'boom',

package/src/engine.ts

@@ -16,7 +16,9 @@
 
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 import type { LLMProvider } from './providers/types.js';
+import type { InferenceMetrics } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
+import { compressToolResult, type ToolCrushOptions } from './context/compress.js';
 
 export interface EngineOptions {
   provider: LLMProvider;
@@ -25,6 +27,15 @@ export interface EngineOptions {
   defaultSystem?: string;
   /** Max reasoning↔tool rounds before forcing a stop. Default 5. */
   defaultMaxTurns?: number;
+  /**
+   * Crush verbose tool results before they're fed back into history, so a
+   * tiny on-device model's context window isn't drowned in repetitive JSON
+   * (merchant lists, tx history, nested quotes). `true` uses safe defaults;
+   * pass options to tune. Off by default — small results are never touched and
+   * amounts/addresses/invoices are always preserved (see compressToolResult).
+   * The `onToolResult` callback and `toolCalls` still carry the raw result.
+   */
+  compressToolOutput?: boolean | ToolCrushOptions;
 }
 
 export interface AgenticOptions {
@@ -59,6 +70,8 @@ export interface AgenticResult {
   messages: Message[];
   /** Wall-clock duration of the whole agentic run, ms. */
   latencyMs: number;
+  /** One receipt per model call in this agentic run. */
+  inference: InferenceMetrics[];
 }
 
 export class Engine {
@@ -66,12 +79,18 @@ export class Engine {
   private readonly registry: ToolRegistry;
   private readonly defaultSystem?: string;
   private readonly defaultMaxTurns: number;
+  private readonly compressOpts?: ToolCrushOptions;
 
   constructor(opts: EngineOptions) {
     this.provider = opts.provider;
     this.registry = opts.tools;
     this.defaultSystem = opts.defaultSystem;
     this.defaultMaxTurns = opts.defaultMaxTurns ?? 5;
+    this.compressOpts = opts.compressToolOutput
+      ? opts.compressToolOutput === true
+        ? {}
+        : opts.compressToolOutput
+      : undefined;
   }
 
   async runAgentic(messages: Message[], opts: AgenticOptions = {}): Promise<AgenticResult> {
@@ -90,6 +109,7 @@ export class Engine {
     let lastRequestId: string | undefined;
     let finalText = '';
     let turns = 0;
+    const inference: InferenceMetrics[] = [];
 
     for (let turn = 1; turn <= maxTurns; turn++) {
       turns = turn;
@@ -104,6 +124,7 @@ export class Engine {
       });
 
       lastRequestId = out.requestId;
+      if (out.inference) inference.push(out.inference);
       if (out.requestId) opts.onStart?.(out.requestId, turn);
       finalText = (out.text || '').trim();
 
@@ -133,10 +154,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),
-        });
+        history.push({ role: 'tool', content: this.toHistoryContent(result) });
       }
 
       if (turn === maxTurns && !finalText) {
@@ -155,6 +173,7 @@ export class Engine {
       requestId: lastRequestId,
       messages: history,
       latencyMs: Date.now() - startedAt,
+      inference,
     };
   }
 
@@ -162,6 +181,18 @@ export class Engine {
     await this.provider.cancel?.(requestId);
   }
 
+  /**
+   * Serialize a tool result for history, optionally crushing verbose JSON so
+   * it doesn't swamp a small context window. The raw result is unchanged for
+   * callbacks/logs — only the model-facing history copy is compressed.
+   */
+  private toHistoryContent(result: unknown): string {
+    if (!this.compressOpts) {
+      return typeof result === 'string' ? result : JSON.stringify(result);
+    }
+    return compressToolResult(result, this.compressOpts).content;
+  }
+
   private async safeExecute(name: string, args: Record<string, unknown>): Promise<unknown> {
     try {
       return await this.registry.execute(name, args);

package/src/evidence.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import {
+  EVIDENCE_SCHEMA,
+  EvidenceRecorder,
+  sanitizeEvidenceEvent,
+  type EvidenceEvent,
+} from './evidence.js';
+
+function memoryRecorder(lines: string[]) {
+  return new EvidenceRecorder({
+    io: {
+      appendLine: async (line) => {
+        lines.push(line);
+      },
+      now: () => new Date('2026-06-20T12:00:00.000Z'),
+    },
+  });
+}
+
+describe('EvidenceRecorder', () => {
+  it('writes a completed inference receipt', async () => {
+    const lines: string[] = [];
+    const event = await memoryRecorder(lines).record({
+      event: 'inference',
+      runId: 'desktop-demo',
+      surface: 'desktop',
+      prompt: 'show my balance',
+      response: 'You have 42 sats.',
+      inference: [{ durationMs: 220, ttftMs: 40, totalTokens: 18, status: 'completed' }],
+    });
+    expect(event.schema).toBe(EVIDENCE_SCHEMA);
+    expect(JSON.parse(lines[0]).inference[0].ttftMs).toBe(40);
+  });
+
+  it('records a failed inference without inventing token metrics', async () => {
+    const lines: string[] = [];
+    await memoryRecorder(lines).record({
+      event: 'error',
+      runId: 'failed-demo',
+      surface: 'test',
+      error: { name: 'ModelError', message: 'model failed to load' },
+    });
+    expect(JSON.parse(lines[0]).error.name).toBe('ModelError');
+  });
+
+  it('records tool calls and confirmation decisions', async () => {
+    const lines: string[] = [];
+    const recorder = memoryRecorder(lines);
+    await recorder.record({
+      event: 'tool_call',
+      runId: 'tools-demo',
+      surface: 'mobile',
+      tool: { name: 'rln_send_btc', arguments: { amount_sat: 100 } },
+    });
+    await recorder.record({
+      event: 'confirmation',
+      runId: 'tools-demo',
+      surface: 'mobile',
+      confirmation: { tool: 'rln_send_btc', approved: false, reason: 'demo stop' },
+    });
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[1]).confirmation.approved).toBe(false);
+  });
+
+  it('sanitizes payment material in interrupted runs', () => {
+    const event: EvidenceEvent = {
+      schema: EVIDENCE_SCHEMA,
+      event: 'inference',
+      ts: '2026-06-20T12:00:00.000Z',
+      runId: 'cancelled-demo',
+      surface: 'mobile',
+      prompt: 'pay lnbc123456789012345678901234567890',
+      tool: { name: 'rln_pay_invoice', arguments: { invoice: 'lnbc-secret' } },
+      inference: { durationMs: 50, status: 'cancelled' },
+    };
+    const clean = sanitizeEvidenceEvent(event);
+    expect(clean.prompt).toContain('[payment-data-redacted]');
+    expect(clean.tool?.arguments?.invoice).toBe('[redacted]');
+  });
+});

package/src/evidence.ts

@@ -0,0 +1,114 @@
+/**
+ * Hackathon evidence JSONL.
+ *
+ * This is deliberately transport-neutral: Node writes it to disk, React Native
+ * writes it to the app documents directory, and tests keep it in memory.
+ */
+import type { InferenceMetrics } from './providers/types.js';
+
+export const EVIDENCE_SCHEMA = 'kaleidomind.evidence.v1' as const;
+
+export type EvidenceSurface = 'desktop' | 'mobile' | 'cli' | 'test';
+export type EvidenceEventType =
+  | 'model_load'
+  | 'model_unload'
+  | 'inference'
+  | 'tool_call'
+  | 'tool_result'
+  | 'confirmation'
+  | 'error';
+
+export interface EvidenceEvent {
+  schema: typeof EVIDENCE_SCHEMA;
+  event: EvidenceEventType;
+  ts: string;
+  runId: string;
+  surface: EvidenceSurface;
+  model?: {
+    name: string;
+    version?: string;
+    source?: 'local' | 'delegated';
+  };
+  hardware?: {
+    device: string;
+    os?: string;
+    memoryGb?: number;
+  };
+  prompt?: string;
+  response?: string;
+  inference?: InferenceMetrics | InferenceMetrics[];
+  tool?: {
+    name: string;
+    arguments?: Record<string, unknown>;
+    result?: unknown;
+  };
+  confirmation?: {
+    tool: string;
+    approved: boolean;
+    reason?: string;
+  };
+  error?: {
+    name: string;
+    message: string;
+  };
+  meta?: Record<string, unknown>;
+}
+
+export type EvidenceInput = Omit<EvidenceEvent, 'schema' | 'ts'>;
+
+export interface EvidenceIO {
+  appendLine(line: string): Promise<void>;
+  now(): Date;
+}
+
+export interface EvidenceRecorderOptions {
+  io: EvidenceIO;
+  sanitize?: (event: EvidenceEvent) => EvidenceEvent;
+}
+
+export class EvidenceRecorder {
+  constructor(private readonly opts: EvidenceRecorderOptions) {}
+
+  async record(input: EvidenceInput): Promise<EvidenceEvent> {
+    let event: EvidenceEvent = {
+      ...input,
+      schema: EVIDENCE_SCHEMA,
+      ts: this.opts.io.now().toISOString(),
+    };
+    event = (this.opts.sanitize ?? sanitizeEvidenceEvent)(event);
+    await this.opts.io.appendLine(JSON.stringify(event));
+    return event;
+  }
+}
+
+const SENSITIVE_KEYS = new Set([
+  'address',
+  'invoice',
+  'bolt11',
+  'seed',
+  'mnemonic',
+  'private_key',
+  'privateKey',
+  'access_token',
+  'accessToken',
+  'preimage',
+]);
+
+const PAYMENT_TOKEN =
+  /\b(?:ln(?:bc|tb|bcrt)[0-9a-z]{20,}|(?:bc1|tb1|bcrt1)[0-9a-z]{20,})\b/gi;
+
+/** Mask wallet secrets while preserving prompts, model output and benchmark value. */
+export function sanitizeEvidenceEvent(event: EvidenceEvent): EvidenceEvent {
+  const walk = (value: unknown, key?: string): unknown => {
+    if (key && SENSITIVE_KEYS.has(key)) return '[redacted]';
+    if (typeof value === 'string') return value.replace(PAYMENT_TOKEN, '[payment-data-redacted]');
+    if (Array.isArray(value)) return value.map((item) => walk(item));
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, walk(v, k)]),
+      );
+    }
+    return value;
+  };
+  return walk(event) as EvidenceEvent;
+}

package/src/flashnet/contract.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FLASHNET_TOOLS,
+  FLASHNET_SPEND_TOOLS,
+  isFlashnetSpendTool,
+  getFlashnetTool,
+  bindFlashnetTools,
+  type FlashnetHandler,
+} from './contract.js';
+
+describe('FLASHNET_TOOLS — shape invariants', () => {
+  it('exposes the expected tool names in order', () => {
+    expect(FLASHNET_TOOLS.map((t) => t.name)).toEqual([
+      'flashnet_list_pools',
+      'flashnet_get_pool',
+      'flashnet_simulate_swap',
+      'flashnet_execute_swap',
+      'flashnet_get_balance',
+    ]);
+  });
+
+  it('every tool has an object parameters schema', () => {
+    for (const t of FLASHNET_TOOLS) {
+      expect((t.parameters as any)?.type).toBe('object');
+    }
+  });
+
+  it('aligns spend ↔ requiresConfirmation', () => {
+    for (const t of FLASHNET_TOOLS) {
+      expect(!!t.spend).toBe(!!t.requiresConfirmation);
+    }
+  });
+
+  it('marks only flashnet_execute_swap as spend', () => {
+    expect([...FLASHNET_SPEND_TOOLS]).toEqual(['flashnet_execute_swap']);
+    expect(isFlashnetSpendTool('flashnet_execute_swap')).toBe(true);
+    expect(isFlashnetSpendTool('flashnet_simulate_swap')).toBe(false);
+    expect(isFlashnetSpendTool('flashnet_list_pools')).toBe(false);
+  });
+
+  it('getFlashnetTool returns by name', () => {
+    expect(getFlashnetTool('flashnet_simulate_swap')?.name).toBe('flashnet_simulate_swap');
+    expect(getFlashnetTool('nope')).toBeUndefined();
+  });
+
+  it('execute_swap requires the canonical 5 fields', () => {
+    const def = getFlashnetTool('flashnet_execute_swap')!;
+    expect((def.parameters as any).required).toEqual([
+      'pool_id', 'asset_in_address', 'asset_out_address', 'amount_in', 'min_amount_out',
+    ]);
+  });
+
+  it('simulate_swap requires pool + assets + amount but no slippage', () => {
+    const def = getFlashnetTool('flashnet_simulate_swap')!;
+    expect((def.parameters as any).required).toEqual([
+      'pool_id', 'asset_in_address', 'asset_out_address', 'amount_in',
+    ]);
+  });
+});
+
+describe('bindFlashnetTools', () => {
+  const echoHandlers = (): Record<string, FlashnetHandler> => ({
+    flashnet_list_pools:    async (a) => ({ ok: true, t: 'list_pools', args: a }),
+    flashnet_get_pool:      async (a) => ({ ok: true, t: 'get_pool', args: a }),
+    flashnet_simulate_swap: async (a) => ({ ok: true, t: 'simulate_swap', args: a }),
+    flashnet_execute_swap:  async (a) => ({ ok: true, t: 'execute_swap', args: a }),
+    flashnet_get_balance:   async () => ({ btc_sats: 100000, tokens: [] }),
+  });
+
+  it('binds every tool and preserves the spend gate', () => {
+    const src = bindFlashnetTools(echoHandlers());
+    expect(src.listTools().length).toBe(5);
+    const exec = src.listTools().find((t) => t.name === 'flashnet_execute_swap');
+    expect(exec?.requiresConfirmation).toBe(true);
+    const sim = src.listTools().find((t) => t.name === 'flashnet_simulate_swap');
+    expect(sim?.requiresConfirmation).toBeFalsy();
+  });
+
+  it('dispatches with args', async () => {
+    const src = bindFlashnetTools(echoHandlers());
+    const r = await src.execute('flashnet_simulate_swap', {
+      pool_id: 'p1',
+      asset_in_address: 'btc',
+      asset_out_address: 'usdb',
+      amount_in: '100000',
+    });
+    expect(r).toMatchObject({ ok: true, t: 'simulate_swap' });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    const partial = { flashnet_list_pools: echoHandlers().flashnet_list_pools };
+    expect(() => bindFlashnetTools(partial)).toThrow(/no handler/);
+    const src = bindFlashnetTools(partial, { allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['flashnet_list_pools']);
+  });
+
+  it('uses opts.id for the ToolSource id', () => {
+    const src = bindFlashnetTools(echoHandlers(), { id: 'flashnet-regtest' });
+    expect(src.id).toBe('flashnet-regtest');
+  });
+});