@kaleidorg/mind 0.1.0 → 0.3.0

package/src/recipe/swap.ts

@@ -0,0 +1,74 @@
+/**
+ * Built-in "swap" recipe — quote → (confirm) → execute, over the contract tools.
+ *
+ *   "buy 0.001 btc with usdt"   → from USDT, to BTC
+ *   "swap 10 usdt for btc"      → from USDT, to BTC
+ *   "sell 100 usdt for sats"    → from USDT, to BTC
+ *
+ * The deterministic extractor handles the common phrasings; the runner falls
+ * back to one LLM extraction otherwise. execute_swap is a spend → the engine's
+ * confirmation gate fires before it runs.
+ */
+
+import type { Recipe } from './types.js';
+
+const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+
+function normAsset(a?: string): string | undefined {
+  if (!a) return undefined;
+  const x = a.toLowerCase();
+  if (/btc|bitcoin|sat/.test(x)) return 'BTC';
+  if (/usdt|tether/.test(x)) return 'USDT';
+  if (/xaut|gold/.test(x)) return 'XAUT';
+  return a.toUpperCase();
+}
+const num = (s?: string) => (s ? Number(s.replace(/,/g, '')) : undefined);
+
+/** "buy 0.001 btc with usdt" / "swap 10 usdt for btc" / "sell 100 usdt for sats". */
+export function extractSwap(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  let m: RegExpMatchArray | null;
+  // buy <amt> <to> with/using <from>  (amount is of the asset being bought)
+  if ((m = t.match(/buy\s+([\d.,]+)\s*([a-z]+)\s+(?:with|using|for)\s+([a-z]+)/i))) {
+    return { amount: num(m[1]), to_asset: normAsset(m[2]), from_asset: normAsset(m[3]) };
+  }
+  // swap/sell/convert/exchange/trade <amt> <from> for/to/into <to>
+  if ((m = t.match(/(?:swap|sell|convert|exchange|trade)\s+([\d.,]+)\s*([a-z]+)\s+(?:for|to|into)\s+([a-z]+)/i))) {
+    return { amount: num(m[1]), from_asset: normAsset(m[2]), to_asset: normAsset(m[3]) };
+  }
+  return null;
+}
+
+export const swapRecipe: Recipe = {
+  name: 'swap',
+  description: 'Swap between BTC and an RGB asset — quote, then execute (with confirmation).',
+  // A crypto swap intent — but NOT buying a gift card (that's commerce) or an invoice.
+  match: (t) => /\b(swap|exchange|convert|trade)\b/i.test(t) || (/\b(buy|sell)\b/i.test(t) && ASSET.test(t) && !/\b(gift\s?card|top-?up|esim|voucher|invoice|address)\b/i.test(t)),
+  triggers: ['swap', 'exchange', 'convert', 'trade'],
+  slots: [
+    { name: 'from_asset', type: 'string', description: 'Asset to spend (e.g. USDT, BTC)', required: true },
+    { name: 'to_asset', type: 'string', description: 'Asset to receive (e.g. BTC, USDT)', required: true },
+    { name: 'amount', type: 'number', description: 'Amount to swap' },
+  ],
+  extract: extractSwap,
+  confident: (s) => !!s.from_asset && !!s.to_asset,
+  steps: [
+    {
+      tool: 'get_swap_quote',
+      as: 'quote',
+      args: (ctx) => ({ from_asset: ctx.slots.from_asset, to_asset: ctx.slots.to_asset, amount: ctx.slots.amount }),
+    },
+  ],
+  final: {
+    tool: 'execute_swap',
+    args: (ctx) => {
+      const q = ctx.results.quote as { quote_id?: string } | undefined;
+      return { quote_id: q?.quote_id, from_asset: ctx.slots.from_asset, to_asset: ctx.slots.to_asset, amount: ctx.slots.amount };
+    },
+  },
+  summary: (ctx) => {
+    const q = ctx.results.quote as { receive_amount?: number } | undefined;
+    const tail = q?.receive_amount ? ` (~${q.receive_amount} ${ctx.slots.to_asset})` : '';
+    return `Swapped ${ctx.slots.amount} ${ctx.slots.from_asset} → ${ctx.slots.to_asset}${tail}.`;
+  },
+};

package/src/recipe/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Recipes — multi-step that works on a tiny model. "Recipes, not planning."
+ *
+ * A small model can't reliably PLAN a chain ("pay bob 3 EUR" = resolve → price
+ * → convert → send) from scratch. So a Recipe carries the plan; the model is
+ * used for ONE thing — extracting the request's slots (recipient, amount, …).
+ * The engine then runs the deterministic steps and the (confirmation-gated)
+ * final action. ~1 inference instead of 5; reliable on 0.6–4B.
+ *
+ * Pure data + interfaces — no deps. The provider + tools are injected.
+ */
+
+export interface RecipeSlot {
+  name: string;
+  type?: 'string' | 'number' | 'boolean';
+  description: string;
+  required?: boolean;
+}
+
+export interface RecipeContext {
+  /** The original user text. */
+  text: string;
+  /** Extracted slots (deterministic regex, else one LLM call). */
+  slots: Record<string, unknown>;
+  /** Results of completed steps, keyed by `as` (or tool name). */
+  results: Record<string, unknown>;
+}
+
+export interface RecipeStep {
+  /** Tool to call. */
+  tool: string;
+  /** Build the tool args from the accumulated context. */
+  args: (ctx: RecipeContext) => Record<string, unknown>;
+  /** Store the result under this key (default: the tool name). */
+  as?: string;
+  /** Skip this step when true (e.g. recipient is already an address). */
+  skipIf?: (ctx: RecipeContext) => boolean;
+}
+
+export interface Recipe {
+  name: string;
+  description?: string;
+  /** Selection: a predicate or trigger phrases. */
+  match?: (text: string) => boolean;
+  triggers?: string[];
+  /** Fields the model (or regex) extracts from the request. */
+  slots: RecipeSlot[];
+  /** Optional deterministic extractor tried BEFORE the LLM (Tier-0 fast-path). */
+  extract?: (text: string) => Record<string, unknown> | null;
+  /**
+   * Whether the recipe is confident enough to RUN deterministically given the
+   * extracted slots (vs falling back to the agentic loop). e.g. payments needs a
+   * recipient; receive needs an amount or asset. Default: any slot extracted.
+   */
+  confident?: (slots: Record<string, unknown>) => boolean;
+  /** Deterministic steps, run in order, results threaded into `ctx`. */
+  steps: RecipeStep[];
+  /** The terminal action (usually a spend → confirmation-gated by its tool). */
+  final: RecipeStep;
+  /** Render the outcome for the user. */
+  summary?: (ctx: RecipeContext, finalResult: unknown) => string;
+}
+
+export type RecipeStatus = 'done' | 'cancelled' | 'error';
+
+export interface RecipeResult {
+  recipe: string;
+  slots: Record<string, unknown>;
+  results: Record<string, unknown>;
+  final?: unknown;
+  text: string;
+  status: RecipeStatus;
+  error?: string;
+  /** Number of LLM inferences used (0 if extraction was deterministic). */
+  inferences: number;
+}

package/src/skills/registry.ts

@@ -75,6 +75,23 @@ const STOPWORDS = new Set([
   'show', 'tell', 'how', 'much', 'many', 'about', 'into', 'over',
 ]);
 
+/** Escape a string for safe inclusion in a regex. */
+function reEscape(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Match a trigger phrase in the query with WORD BOUNDARIES — so the
+ * `usd` trigger on a wallet skill doesn't fire on `usdt`/`usdc`, and
+ * `cafe` doesn't fire on `cafeteria`. Multi-word triggers ("near me")
+ * still work because spaces are already word boundaries.
+ */
+function triggerMatches(query: string, trigger: string): boolean {
+  const t = trigger.toLowerCase().trim();
+  if (!t) return false;
+  return new RegExp(`\\b${reEscape(t)}\\b`).test(query);
+}
+
 /** Default selector: score by meaningful keyword overlap; triggers weigh most. */
 export const keywordSelector: SkillSelector = {
   select(query, skills) {
@@ -89,8 +106,10 @@ export const keywordSelector: SkillSelector = {
       const hayWords = haystack.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
       let score = 0;
       for (const w of hayWords) if (words.has(w)) score += 1;
-      // Strong boost for an explicit trigger appearing in the query.
-      for (const t of skill.triggers ?? []) if (q.includes(t.toLowerCase())) score += 3;
+      // Strong boost for an explicit trigger appearing in the query — at a
+      // word boundary, so short triggers (`usd`, `eur`, `cafe`) don't leak
+      // into longer words (`usdt`, `europe`, `cafeteria`).
+      for (const t of skill.triggers ?? []) if (triggerMatches(q, t)) score += 3;
       if (score > bestScore) {
         bestScore = score;
         best = skill;

package/src/skills/skills.test.ts

@@ -75,6 +75,48 @@ Manage Lightning channels via LSPS1.`);
   });
 });
 
+describe('SkillRegistry selection — trigger word boundaries', () => {
+  // Regression: short triggers must NOT match inside longer words.
+  // Bug observed in the CLI: a wallet skill with `usd` as a trigger was
+  // picked for "what is the quote of usdt to btc" because the old
+  // q.includes("usd") was true for "usdt", outranking the trading skill.
+  const reg = new SkillRegistry();
+  reg.addMarkdown(`---
+name: wallet-fiat
+description: Check the BTC price and convert fiat to sats. Fiat support: usd, eur, gbp.
+triggers: price, eur, usd, gbp
+---
+Wallet — fiat conversion.`);
+  reg.addMarkdown(`---
+name: trading
+description: Quote and execute swaps between BTC, USDT and XAUT on KaleidoSwap.
+triggers: quote, swap, trade, usdt, xaut
+---
+Trading on the maker.`);
+
+  it("doesn't fire the `usd` trigger inside `usdt`", () => {
+    const sel = reg.select('what is the quote of usdt to btc')?.name;
+    expect(sel).toBe('trading'); // not wallet-fiat
+  });
+
+  it('still fires the `usd` trigger when the user actually said `usd`', () => {
+    const sel = reg.select('how many sats is 30 usd')?.name;
+    expect(sel).toBe('wallet-fiat');
+  });
+
+  it("doesn't fire a short trigger inside a longer word — `cafe` not in `cafeteria`", () => {
+    const r2 = new SkillRegistry();
+    r2.addMarkdown(`---
+name: merchants
+description: Find merchants that accept Bitcoin.
+triggers: cafe, restaurant, bar
+---
+Merchant finder.`);
+    expect(r2.select('the cafeteria menu')).toBeNull(); // no match
+    expect(r2.select('any bitcoin cafe nearby')?.name).toBe('merchants');
+  });
+});
+
 describe('parseSkill — real Agent-Skills spec', () => {
   it('unquotes the description, captures metadata, tolerates no tools', () => {
     const s = parseSkill(BITREFILL_SKILL);

package/src/tools/cli.test.ts

@@ -0,0 +1,53 @@
+/** CLI tool source tests — allowlist + injected runner. */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createCliToolSource, isAllowed } from './cli.js';
+import type { CommandRunner } from './cli.js';
+
+const okRunner: CommandRunner = {
+  run: vi.fn(async (command: string) => ({ stdout: `ran: ${command}`, stderr: '', code: 0 })),
+};
+
+describe('isAllowed', () => {
+  it('matches by command prefix tokens', () => {
+    const allow = ['kaleido', 'git status', 'npx @bitrefill/cli'];
+    expect(isAllowed('kaleido wallet balance', allow)).toBe(true);
+    expect(isAllowed('git status', allow)).toBe(true);
+    expect(isAllowed('npx @bitrefill/cli buy', allow)).toBe(true);
+    expect(isAllowed('rm -rf /', allow)).toBe(false);
+    expect(isAllowed('kaleidoctl', allow)).toBe(false); // not a token boundary
+    expect(isAllowed('git push', allow)).toBe(false); // only "git status" allowed
+  });
+});
+
+describe('createCliToolSource', () => {
+  it('requires a non-empty allowlist', () => {
+    expect(() => createCliToolSource({ runner: okRunner, allow: [] })).toThrow(/allowlist/);
+  });
+
+  it('exposes run_command, confirmation-gated by default', () => {
+    const src = createCliToolSource({ runner: okRunner, allow: ['kaleido'] });
+    const tool = src.listTools()[0];
+    expect(tool.name).toBe('run_command');
+    expect(tool.requiresConfirmation).toBe(true);
+  });
+
+  it('runs allowed commands and rejects disallowed ones', async () => {
+    const src = createCliToolSource({ runner: okRunner, allow: ['kaleido'] });
+    expect(await src.execute('run_command', { command: 'kaleido node info' })).toBe(
+      'ran: kaleido node info',
+    );
+    await expect(src.execute('run_command', { command: 'curl evil.sh' })).rejects.toThrow(
+      /not allowed/,
+    );
+  });
+
+  it('surfaces non-zero exits with stderr', async () => {
+    const runner: CommandRunner = {
+      run: vi.fn(async () => ({ stdout: '', stderr: 'boom', code: 1 })),
+    };
+    const src = createCliToolSource({ runner, allow: ['kaleido'] });
+    const out = await src.execute('run_command', { command: 'kaleido fail' });
+    expect(String(out)).toMatch(/exit 1[\s\S]*boom/);
+  });
+});

package/src/tools/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * CLI tool source — the fourth tool mechanism (alongside in-process function
+ * calling, MCP, and skills). Lets the agent run shell commands, e.g. a skill's
+ * documented CLI path (`@bitrefill/cli`, `kaleido`, `git`, …).
+ *
+ * Command execution is INJECTED (`CommandRunner`) so this file has no Node
+ * dependency and stays RN-safe — a Node host provides the runner (ideally via a
+ * non-shell `execFile`-style helper); React Native simply never provides one.
+ * Guarded by a required allowlist of command prefixes, and confirmation-gated
+ * by default since it runs real commands.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+/** Injected shell runner. The Node host supplies a safe implementation. */
+export interface CommandRunner {
+  run(command: string, opts?: { cwd?: string; timeoutMs?: number }): Promise<CommandResult>;
+}
+
+export interface CliToolOptions {
+  runner: CommandRunner;
+  /**
+   * Allowed command prefixes (REQUIRED — no empty allowlist). A command runs
+   * only if it starts with one of these tokens, e.g. ['kaleido', 'git status',
+   * 'npx @bitrefill/cli'].
+   */
+  allow: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  /** Confirmation gate (default true — it executes real commands). */
+  requiresConfirmation?: boolean;
+  /** Tool description override (e.g. name the specific CLI). */
+  description?: string;
+}
+
+const RUN = 'run_command';
+
+/** True if `command` is permitted by the allowlist (prefix match on tokens). */
+export function isAllowed(command: string, allow: string[]): boolean {
+  const cmd = command.trim();
+  return allow.some((prefix) => {
+    const p = prefix.trim();
+    return p.length > 0 && (cmd === p || cmd.startsWith(p + ' '));
+  });
+}
+
+export function createCliToolSource(opts: CliToolOptions): ToolSource {
+  if (!opts.allow || opts.allow.length === 0) {
+    throw new Error('createCliToolSource: a non-empty `allow` allowlist is required');
+  }
+
+  const tool: ToolDef = {
+    name: RUN,
+    description:
+      opts.description ??
+      `Run an allowed shell command and return its output. Allowed commands start ` +
+        `with: ${opts.allow.join(', ')}. Use for documented CLI tools.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The full command line to run' },
+      },
+      required: ['command'],
+    },
+    requiresConfirmation: opts.requiresConfirmation ?? true,
+  };
+
+  async function execute(_name: string, args: Record<string, unknown>): Promise<unknown> {
+    const command = String(args.command ?? '').trim();
+    if (!command) throw new Error('run_command: command is required');
+    if (!isAllowed(command, opts.allow)) {
+      throw new Error(
+        `run_command: "${command.split(' ')[0]}" is not allowed. Allowed: ${opts.allow.join(', ')}`,
+      );
+    }
+    const res = await opts.runner.run(command, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+    const out = (res.stdout || '').trim();
+    const err = (res.stderr || '').trim();
+    if (res.code !== 0) {
+      return `exit ${res.code}${err ? `\n${err}` : ''}${out ? `\n${out}` : ''}`.trim();
+    }
+    return out || '(no output)';
+  }
+
+  return {
+    id: 'cli',
+    listTools: () => [tool],
+    has: (name) => name === RUN,
+    execute,
+  };
+}

package/src/tools/mcp.ts

@@ -13,8 +13,9 @@
  * 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.
+ * Wired end-to-end: connect() (stdio + HTTP transports), listTools() and
+ * execute() are implemented. Used by the desktop sidecar (kaleido-mcp +
+ * Bitrefill MCP) and verified against the remote Bitrefill MCP.
  */
 
 import type { ToolDef } from '../types.js';

package/src/wallet/confirm.test.ts

@@ -0,0 +1,57 @@
+/** Confirm-sheet readback — deterministic, voice-first spend summaries. */
+
+import { describe, it, expect } from 'vitest';
+import { confirmReadback } from './confirm.js';
+
+describe('confirmReadback', () => {
+  it('send_payment: sats + recipient, grouped thousands', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'bob', amount_sats: 4800 } }))
+      .toBe('Send 4,800 sats to bob. Confirm?');
+  });
+
+  it('send_payment: explicit layer is read back', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'bob', amount_sats: 1000000, layer: 'spark' } }))
+      .toBe('Send 1,000,000 sats to bob over Spark. Confirm?');
+  });
+
+  it('send_payment: asset amount when no sats (core router, no layer suffix)', () => {
+    expect(confirmReadback({ name: 'send_payment', arguments: { to: 'alice', asset: 'USDT', amount: 10 } }))
+      .toBe('Send 10 USDT to alice. Confirm?');
+  });
+
+  it('spark_send: layer comes from the tool, address is shortened', () => {
+    const line = confirmReadback({
+      name: 'spark_send',
+      arguments: { amount_sats: 5000, to: 'bc1qabcdef0123456789xyzlongaddress' },
+    });
+    expect(line).toBe('Send 5,000 sats to bc1qab…ress over Spark. Confirm?');
+  });
+
+  it('rln_send_asset: asset + ticker + recipient over RLN', () => {
+    expect(confirmReadback({ name: 'rln_send_asset', arguments: { asset: 'USDT', amount: 10, to: 'bob' } }))
+      .toBe('Send 10 USDT to bob over RLN. Confirm?');
+  });
+
+  it('rln_pay_invoice: invoice shortened, over RLN', () => {
+    const line = confirmReadback({
+      name: 'rln_pay_invoice',
+      arguments: { invoice: 'lnbc1ptestinvoice0123456789abcd' },
+    });
+    expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over RLN. Confirm?');
+  });
+
+  it('execute_swap: from → to with amount', () => {
+    expect(confirmReadback({ name: 'execute_swap', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 0.01 } }))
+      .toBe('Swap 0.01 BTC for USDT. Confirm?');
+  });
+
+  it('returns null for non-spend tools', () => {
+    expect(confirmReadback({ name: 'get_balances', arguments: {} })).toBeNull();
+    expect(confirmReadback({ name: 'resolve_contact', arguments: { name: 'bob' } })).toBeNull();
+  });
+
+  it('short contact names are not truncated; long refs are', () => {
+    expect(confirmReadback({ name: 'arkade_send', arguments: { amount_sats: 100, to: 'mum' } }))
+      .toBe('Send 100 sats to mum over Arkade. Confirm?');
+  });
+});

package/src/wallet/confirm.ts

@@ -0,0 +1,74 @@
+/**
+ * Confirm-sheet readback — a deterministic, voice-first summary of a spend that
+ * the host speaks before executing it ("Send 4,800 sats to bob over Spark.
+ * Confirm?"). Built from the resolved tool call, not the model: zero inference,
+ * identical on every surface, and impossible for the model to phrase around.
+ */
+
+import { getWalletTool } from './contract.js';
+
+const LAYER_LABEL: Record<string, string> = {
+  spark: 'Spark',
+  rln: 'RLN',
+  arkade: 'Arkade',
+  liquid: 'Liquid',
+};
+
+/** Group an integer with thousands separators, locale-independently (test-stable). */
+function fmtNum(n: number): string {
+  if (!Number.isFinite(n)) return String(n);
+  const neg = n < 0;
+  const [int, frac] = Math.abs(n).toString().split('.');
+  const grouped = int!.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return (neg ? '-' : '') + (frac ? `${grouped}.${frac}` : grouped);
+}
+
+/** Looks like an address/invoice/lnurl (vs a human contact name). */
+function isRef(s: string): boolean {
+  return /^(ln(bc|tb|bcrt)|bc1|tb1|lq1|lnurl)/i.test(s) || (s.length > 20 && !/\s/.test(s));
+}
+
+/** Shorten an address/invoice for speech; leave contact names intact. */
+function shortRef(s: string): string {
+  const v = s.trim();
+  return isRef(v) ? `${v.slice(0, 6)}…${v.slice(-4)}` : v;
+}
+
+/** " over Spark" suffix for the call's layer (explicit arg wins, else the tool's). */
+function over(name: string, args: Record<string, unknown>): string {
+  const layer = typeof args.layer === 'string' ? args.layer : getWalletTool(name)?.layer;
+  const label = layer ? LAYER_LABEL[layer] : undefined;
+  return label ? ` over ${label}` : '';
+}
+
+const sats = (v: unknown) => `${fmtNum(Number(v))} sats`;
+const asset = (amount: unknown, ticker: unknown) => `${fmtNum(Number(amount))} ${String(ticker)}`;
+
+/** A spoken confirmation ending in "Confirm?", or null for non-spend tools. */
+export function confirmReadback(call: { name: string; arguments: Record<string, unknown> }): string | null {
+  const { name, arguments: a } = call;
+  const to = (k = 'to') => shortRef(String(a[k] ?? ''));
+  const ask = (s: string) => `${s}. Confirm?`;
+
+  switch (name) {
+    case 'send_payment': {
+      const amt = a.amount_sats != null ? sats(a.amount_sats)
+        : a.asset != null && a.amount != null ? asset(a.amount, a.asset)
+        : undefined;
+      return ask(amt ? `Send ${amt} to ${to()}${over(name, a)}` : `Send a payment to ${to()}${over(name, a)}`);
+    }
+    case 'spark_send':
+    case 'arkade_send':
+      return ask(`Send ${sats(a.amount_sats)} to ${to()}${over(name, a)}`);
+    case 'rln_send_asset':
+    case 'liquid_send':
+      return ask(`Send ${asset(a.amount, a.asset)} to ${to()}${over(name, a)}`);
+    case 'rln_pay_invoice':
+      return ask(`Pay Lightning invoice ${shortRef(String(a.invoice ?? ''))}${over(name, a)}`);
+    case 'execute_swap':
+      return ask(`Swap ${fmtNum(Number(a.amount))} ${String(a.from_asset)} for ${String(a.to_asset)}`);
+    default:
+      // Unknown but spend-flagged tool → a generic, still-honest readback.
+      return getWalletTool(name)?.spend ? ask(`Confirm ${name.replace(/_/g, ' ')}`) : null;
+  }
+}

package/src/wallet/contract.test.ts

@@ -0,0 +1,89 @@
+/** Wallet contract tests — integrity of the single source of truth. */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  WALLET_TOOLS,
+  SPEND_TOOLS,
+  isSpendTool,
+  walletTools,
+  toToolDefs,
+  bindWalletTools,
+  getWalletTool,
+} from './contract.js';
+
+describe('WALLET_TOOLS contract', () => {
+  it('has unique names and object schemas', () => {
+    const names = WALLET_TOOLS.map((t) => t.name);
+    expect(new Set(names).size).toBe(names.length);
+    for (const t of WALLET_TOOLS) {
+      expect(t.name).toMatch(/^[a-z][a-z0-9_]+$/);
+      expect((t.parameters as any).type).toBe('object');
+    }
+  });
+
+  it('namespaces per-layer tools and keeps core helpers unprefixed', () => {
+    for (const t of WALLET_TOOLS) {
+      if (t.layer === 'core') continue;
+      expect(t.name.startsWith(`${t.layer}_`)).toBe(true);
+    }
+    expect(getWalletTool('send_payment')!.layer).toBe('core');
+    expect(getWalletTool('resolve_contact')!.layer).toBe('core');
+  });
+
+  it('spend tools are confirmation-gated; reads do not move funds', () => {
+    for (const t of WALLET_TOOLS) {
+      expect(!!t.requiresConfirmation).toBe(!!t.spend);
+    }
+    // every fund-moving tool is flagged
+    expect(isSpendTool('send_payment')).toBe(true);
+    expect(isSpendTool('rln_send_asset')).toBe(true);
+    expect(isSpendTool('execute_swap')).toBe(true);
+    expect(isSpendTool('spark_send')).toBe(true);
+    // reads are not
+    expect(isSpendTool('get_balances')).toBe(false);
+    expect(isSpendTool('get_price')).toBe(false);
+    expect([...SPEND_TOOLS].length).toBeGreaterThanOrEqual(5);
+  });
+
+  it('required args declared on the actionable tools', () => {
+    expect((getWalletTool('send_payment')!.parameters as any).required).toContain('to');
+    expect((getWalletTool('fiat_to_sats')!.parameters as any).required).toEqual(['amount', 'currency']);
+    expect((getWalletTool('rln_create_rgb_invoice')!.parameters as any).required).toEqual(['asset', 'amount']);
+  });
+});
+
+describe('selectors', () => {
+  it('walletTools filters by layer + always includes core unless disabled', () => {
+    const spark = walletTools({ layers: ['spark'] });
+    expect(spark.some((t) => t.name === 'spark_send')).toBe(true);
+    expect(spark.some((t) => t.layer === 'core')).toBe(true); // core included by default
+    expect(spark.some((t) => t.layer === 'rln')).toBe(false);
+
+    const noCore = walletTools({ layers: ['spark'], includeCore: false });
+    expect(noCore.every((t) => t.layer === 'spark')).toBe(true);
+  });
+
+  it('toToolDefs strips metadata but keeps requiresConfirmation', () => {
+    const defs = toToolDefs(walletTools({ layers: ['spark'] }));
+    const send = defs.find((d) => d.name === 'spark_send')!;
+    expect(send.requiresConfirmation).toBe(true);
+    expect('layer' in (send as any)).toBe(false);
+  });
+});
+
+describe('bindWalletTools', () => {
+  it('binds handlers → an InProcessToolSource with spend flags preserved', async () => {
+    const handler = vi.fn(async () => ({ ok: true }));
+    const src = bindWalletTools({ spark_get_balance: handler, spark_send: handler }, { layers: ['spark'], includeCore: false, allowMissing: true });
+    const tools = src.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual(['spark_get_balance', 'spark_send']);
+    expect(tools.find((t) => t.name === 'spark_send')!.requiresConfirmation).toBe(true);
+    expect(await src.execute('spark_get_balance', {})).toEqual({ ok: true });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    expect(() => bindWalletTools({}, { layers: ['spark'], includeCore: false })).toThrow(/no handler/);
+    const src = bindWalletTools({ spark_get_balance: async () => 1 }, { layers: ['spark'], includeCore: false, allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['spark_get_balance']);
+  });
+});