@kaleidorg/mind 0.2.0 → 0.3.0

package/skills/kaleido-trading/SKILL.md

@@ -1,31 +1,98 @@
 ---
 name: kaleido-trading
-description: "Trade and manage a portfolio on KaleidoSwap: get live prices and market data, quote and place atomic swaps between BTC and RGB assets (USDT, XAUT), acquire inbound liquidity from the LSP, and check positions. Triggers when the user wants a price, a quote, to swap or trade assets, to rebalance a portfolio, or to acquire a Lightning channel from the LSP."
-tools: get_price, get_market_data, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_get_position, kaleidoswap_lsp_get_info, kaleidoswap_lsp_create_order
-triggers: price, quote, swap, trade, rebalance, portfolio, market, slippage, liquidity, channel order
+description: "Trade on KaleidoSwap — quote and execute swaps between BTC and RGB assets (USDT, XAUT). Get assets and pairs, pull an executable quote, place a market order, or track an atomic swap end-to-end. Triggers when the user wants a price, a quote, to swap or trade assets, or to rebalance between BTC and stablecoins."
+tools: get_price, fiat_to_sats, kaleidoswap_get_assets, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_get_nodeinfo, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_get_order_history
+triggers: quote, swap, trade, rebalance, slippage, pair, pairs, usdt, xaut, kaleidoswap, rfq
 metadata:
   author: kaleidoswap
-  version: "0.1.0"
-  surface: "kaleido-mcp (KaleidoSwap maker + market data)"
+  version: "0.3.0"
 ---
 
 # KaleidoSwap trading
 
-Quote, swap, and manage a portfolio through the KaleidoSwap maker and market
-data MCP tools.
+Quote and execute swaps on the KaleidoSwap maker. The model picks tools by
+name; the host binds them through whichever transport it runs over (WDK on
+mobile, HTTP/MCP/CLI on desktop).
+
+## Critical rules — these override everything else
+
+You have **no knowledge** of any price, quote, fee, pair, or order. Every
+number, pair, or quote id in your reply MUST come from a tool result returned
+in the CURRENT turn:
+
+- "What's the BTC price?" → call `get_price` and state the number it returns.
+- "What pairs are listed?" → call `kaleidoswap_get_pairs` and list them.
+- "Quote 100k sats to USDT" → call `kaleidoswap_get_quote(BTC, USDT, 100000)`,
+  then state the receive amount + fees from the result.
+
+**Calling the tool IS the answer.** Never write "the pairs are listed using
+kaleidoswap_get_pairs" or "the function returns the quote" — just call it.
+
+**Never reuse a number across turns.** If the user asks a new question, the
+previous turn's quote, price, or fee is irrelevant — fetch fresh.
+
+**Never invent a quote.** Without a `quote_id` and `receive_amount` returned
+this turn, you do not have a quote. Say so and re-quote.
+
+## Asset codes (canonical)
+
+Only these codes are accepted:
+
+- `BTC` (Bitcoin, amounts always in satoshis)
+- `USDT` (Tether) — **not** `USD`, **not** `tether`
+- `XAUT` (Tether Gold) — **not** `XAU`, **not** `gold`
+
+When the user types `USD` they almost always mean `USDT` — confirm before
+quoting. Same for `gold` → `XAUT`. Don't silently substitute.
+
+## Tools
+
+### `kaleidoswap_get_pairs` — no args
+Use when the user asks "what can I trade", "list pairs", "what's available",
+or before quoting an unfamiliar pair.
+
+### `kaleidoswap_get_quote` — REQUIRES `amount`
+Required args: `from_asset` AND `to_asset` AND `amount`. The maker rejects
+calls missing any of these.
+
+**If the user didn't give an amount, ASK for it. Do not call the tool with
+from/to alone.**
+
+Examples:
+- "Quote 100k sats to USDT" → `{from_asset: "BTC", to_asset: "USDT", amount: 100000}`
+- "What's the USDT/BTC rate?" → ask: "How many USDT do you want to swap?"
+  (no amount → no quote possible).
+- "Buy 50 USDT of BTC" → `{from_asset: "USDT", to_asset: "BTC", amount: 50}`
+  (USDT is what's being spent).
+
+### `kaleidoswap_place_order(quote_id)` 🔒 spend
+Only after `kaleidoswap_get_quote` returned a `quote_id` THIS turn, and only
+when the user has explicitly approved the amount + direction.
+
+### `kaleidoswap_get_order_status(order_id)`
+Poll after placing an order. Report status plainly — pending, settling,
+completed, failed.
 
 ## Flow
 
-1. **Price first.** Use `get_price` / `get_market_data` for context and
-   `kaleidoswap_get_quote` for an executable price before proposing a trade.
-2. **Confirm the trade.** Show pair, direction, amount in, expected amount out,
-   and fees. Wait for explicit approval before `kaleidoswap_place_order`.
-3. **Track it.** After placing, poll `kaleidoswap_get_order_status` until the
-   swap settles, then report the result and the new `kaleidoswap_get_position`.
-4. **Need inbound liquidity?** If a swap can't route for lack of a channel, use
-   `kaleidoswap_lsp_get_info` then `kaleidoswap_lsp_create_order` to buy one.
+1. **Pick a pair** — skip when obvious (`BTC/USDT`, `BTC/XAUT`).
+2. **Quote** — `kaleidoswap_get_quote`. REQUIRES amount.
+3. **Show + confirm** — surface pair, direction, amount in, expected out,
+   fees, slippage. **Never hide cost** — a small model must not abbreviate
+   fees out of the message.
+4. **Place** — spend-gated by the engine. The host pauses for the user.
+5. **Track** — poll `kaleidoswap_get_order_status` until it terminates.
+
+## Don'ts
 
-## Rules
+- Don't invent prices, quotes, quote_ids, or order_ids.
+- Don't reuse a number from a previous turn.
+- Don't describe how a tool works — call it.
+- Don't call `kaleidoswap_get_quote` with from/to only — ask for the amount.
+- Don't accept `XAU` as `XAUT` or `USD` as `USDT` silently — confirm.
+- Don't retry the same failing tool call in a loop. If a call fails, read the
+  error and either ask the user, fix the args, or stop.
 
-- Never trade on a stale quote — re-quote if the user hesitates.
-- Surface slippage and fees explicitly; small local models must not hide cost.
+For the atomic-swap flow (trust-minimised cross-asset swap that the maker
+can't settle from balance), use the `kaleido-trading` atomic recipe — the
+agentic chain is not safe to plan on a 0.6B model.

package/skills/merchant-finder/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: merchant-finder
+description: "Find Bitcoin-accepting merchants near the user using live BTC Map data and the device's real location. Triggers when the user asks where to spend Bitcoin, for a shop, store, restaurant, cafe, bar, or ATM that accepts Bitcoin, or for merchants nearby."
+tools: find_merchant_locations, get_merchant_info
+triggers: merchant, merchants, shop, shops, store, stores, restaurant, restaurants, cafe, cafes, bar, bars, atm, atms, accept, accepts, accepting, nearby, near me, around, place, places, spend, find, pizza, food, coffee, bitcoin map, btcmap
+metadata:
+  author: kaleidoswap
+  version: "0.2.0"
+  homepage: "https://btcmap.org"
+---
+
+# Merchant finder
+
+Discover places that accept Bitcoin payments — cafés, restaurants, bars, shops,
+and ATMs. Live BTC Map data when the host injects a fetcher + location;
+otherwise a small offline list keeps the skill answerable.
+
+## Critical rule — never answer from memory
+
+You have **no knowledge of any merchant**. Every place, name, address and
+distance in your reply MUST come from a `find_merchant_locations` result
+returned in the CURRENT turn. **Call `find_merchant_locations` for every
+place question**, even if a similar question was answered earlier — do NOT
+reuse or adapt a previous answer. Never invent a merchant.
+
+## How to call the tools
+
+1. **Start with `find_merchant_locations`.** Pass ONLY the fields the user
+   actually named — do not invent constraints:
+
+   - `query` — a specific thing the user named (e.g. `"tapas"`, `"coffee"`,
+     `"pizza"`). Omit when they only said "near me" or only named a place.
+
+   - `category` — must be EXACTLY one of: `restaurant`, `cafe`, `bar`, `shop`,
+     `grocery`, `lodging`, `atm`. **Anything else is invalid — leave it empty.**
+     The words "merchant", "merchants", "place", "places", "store", "stores"
+     are NOT categories — they're the generic noun for what you're searching
+     for, so they belong in `query` at best, never in `category`.
+
+   - `near_address` — a city, neighbourhood, or address (e.g. `"Milan"`,
+     `"Bitcoin Beach, El Salvador"`). Use this any time the user names a
+     location instead of "near me".
+
+   - `radius_km` — **omit unless the user names a specific number.** The
+     default (5 km) is a sensible search radius for a city. Don't pick a
+     small radius (1, 2, 3) yourself — city-wide searches need 5+.
+
+   - `limit` — 1–20, default 10. Omit unless the user names a count.
+
+   Examples (positive):
+   - "where can I spend btc near me" → `find_merchant_locations({})`
+   - "find merchants in Milan" → `find_merchant_locations({ near_address: "Milan" })`
+     ↑ no `category` — "merchants" is NOT a category.
+   - "cafes in Lisbon" → `find_merchant_locations({ category: "cafe", near_address: "Lisbon" })`
+   - "pizza places in Switzerland that take bitcoin" →
+     `find_merchant_locations({ query: "pizza", near_address: "Switzerland" })`
+     ↑ "places" is NOT a category — pizza goes in `query`.
+   - "lightning bars in NYC, within 2 km" →
+     `find_merchant_locations({ category: "bar", near_address: "New York", radius_km: 2 })`
+     ↑ user explicitly said "2 km" → set radius_km.
+
+   Examples (anti — do NOT do these):
+   - ❌ `category: "merchant"` (not a category)
+   - ❌ `category: "place"` (not a category)
+   - ❌ `radius_km: 2` when the user didn't say "2 km" — you're picking a
+     too-small radius and the result will be empty.
+
+2. **Present the results.** Each row carries:
+   - `name`, `category`, `address`
+   - `distance_m` when present — show in metres or km
+   - `accepts_bitcoin` / `accepts_lightning` — relevant because Lightning is
+     fastest for small payments
+   - `phone`, `website`, `opening_hours` when present — surface if asked
+
+3. **Use `get_merchant_info` only when** the user asks for more detail on one
+   specific result. Pass `merchant_id` (preferred) or `merchant_name`.
+
+## Reply style
+
+- Be concise. One line per merchant works:
+  `Name — category, address (X m away, accepts: lightning, onchain)`.
+- If the result `source` is `offline`, say so plainly — it means the live
+  BTC Map fetch wasn't available, so the list is limited.
+- If `find_merchant_locations` returns zero merchants, say so — don't invent
+  places. Suggest widening `radius_km` or trying `near_address`.
+- When the user says "near me" and `precise_location` is false, mention which
+  fallback location was used so they know it's not their actual GPS.

package/skills/paid-data/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: paid-data
+description: Fetch premium or paywalled data that requires a small Lightning (L402) payment — paid feeds, gated APIs, unlockable resources. Triggers when the user wants premium, paid, or unlockable data behind an L402 paywall.
+tools: fetch_paid_resource
+triggers: premium, paid, l402, feed, subscription, unlock, paywall
+---
+
+# Paid data
+
+Fetch L402-paywalled resources, paying small Lightning invoices automatically
+with `fetch_paid_resource`. Small amounts pay without prompting (capped);
+anything larger is declined. Tell the user what was paid and what was returned.

package/skills/wallet-assistant/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: wallet-assistant
+description: Everyday wallet tasks on this phone — check the BTC/asset balance, create an invoice to receive, send a payment, look up a contact, get the BTC price, or convert a fiat amount to sats. Triggers when the user asks about their balance, wants to receive or send money, pay an invoice, or pay a contact.
+tools: get_balances, get_price, fiat_to_sats, resolve_contact, send_payment, rln_pay_invoice, rln_create_ln_invoice, spark_create_invoice
+triggers: balance, pay, send, receive, address, invoice, transactions, contact, funds, money, price, sats, eur, gbp
+---
+
+# Wallet assistant
+
+You operate the user's on-device multi-L2 Bitcoin wallet. ALWAYS use a tool to
+get real data — NEVER invent a balance, address, amount, price, or result.
+
+## Critical rules
+
+You have no knowledge of balances, prices, addresses, or invoices. Every value
+in your reply MUST come from a tool result returned in the CURRENT turn — do
+not reuse a number from a previous turn.
+
+When a tool returns multiple fields, **report all the load-bearing ones**:
+- `get_balances` may return `{confirmed, pending, total}` — when `pending`
+  is non-zero, report BOTH. `confirmed` is spendable; `pending` is settling
+  and is NOT spendable yet. The user needs to know the difference.
+- `fiat_to_sats` returns `{sats}` plus a `note` when the currency was an
+  approximation — surface the note.
+
+## Rules
+
+- Balance / "how much do I have" → call `get_balances`, then state the number.
+- Receive / "an invoice for N sats" → call `rln_create_ln_invoice` (or
+  `spark_create_invoice`) with the amount.
+- Price → `get_price`. "How many sats is 3 EUR" → `fiat_to_sats`.
+- Pay a Lightning invoice → `rln_pay_invoice`.
+- Send to a person/amount → first `resolve_contact` (and `fiat_to_sats` if the
+  amount is in fiat), then `send_payment` with the amount in sats and the
+  recipient. State the amount and destination; the app asks the user to confirm
+  before it sends.
+
+Keep replies short, but never drop a balance component or a fee.

package/src/capabilities.ts

@@ -25,6 +25,10 @@ export interface MindCapabilities {
   memory: boolean;
   /** Semantic recall for memory (needs embeddings). */
   semanticMemory: boolean;
+  /** Embedding-only dedup of near-duplicate memories (zero inference — mobile-safe). */
+  dedupeMemory: boolean;
+  /** LLM merge of near-duplicate memories (an extra inference — capable/delegated only). */
+  mergeMemory: boolean;
   /** Retrieval-augmented generation (needs embeddings + enough RAM/context). */
   rag: boolean;
   /** Token budget for injected system context. */
@@ -48,6 +52,12 @@ export function capabilityProfile(input: CapabilityInput): MindCapabilities {
   const memory = budget >= 256;
   const semanticMemory = memory && hasEmb;
 
+  // Consolidation: embedding-only dedup is cheap (no inference) — on wherever
+  // semantic memory is. The LLM merge costs an extra inference, so reserve it
+  // for delegated or roomy on-device setups; never run it on a tiny phone model.
+  const dedupeMemory = semanticMemory;
+  const mergeMemory = dedupeMemory && (input.delegated || (ramGb >= 4 && ctx >= 4096));
+
   // RAG is the expensive one: needs embeddings, a non-tiny context window, and
   // (on-device) enough RAM to hold an embedding model + index.
   const rag = hasEmb && ctx >= 4096 && (input.delegated || ramGb >= 3);
@@ -59,6 +69,8 @@ export function capabilityProfile(input: CapabilityInput): MindCapabilities {
   return {
     memory,
     semanticMemory,
+    dedupeMemory,
+    mergeMemory,
     rag,
     contextBudgetTokens: budget,
     topKMemory,

package/src/context/context.test.ts

@@ -60,18 +60,22 @@ describe('ContextBuilder', () => {
 });
 
 describe('capabilityProfile', () => {
-  it('low-end phone: memory yes, RAG no', () => {
+  it('low-end phone: memory yes, RAG no, dedup yes but no LLM merge', () => {
     const c = capabilityProfile({ ramBytes: 2 * 1024 ** 3, modelCtxTokens: 2048, hasEmbeddings: true });
     expect(c.memory).toBe(true);
     expect(c.rag).toBe(false); // ctx too small + low RAM
     expect(c.topKRag).toBe(0);
+    expect(c.dedupeMemory).toBe(true); // embedding-only dedup is mobile-safe
+    expect(c.mergeMemory).toBe(false); // never run merge inference on a tiny phone
   });
 
-  it('desktop / delegated: RAG on', () => {
+  it('desktop / delegated: RAG on, memory merge on', () => {
     const c = capabilityProfile({ modelCtxTokens: 8192, hasEmbeddings: true, delegated: true });
     expect(c.rag).toBe(true);
     expect(c.topKRag).toBeGreaterThan(0);
     expect(c.semanticMemory).toBe(true);
+    expect(c.dedupeMemory).toBe(true);
+    expect(c.mergeMemory).toBe(true);
   });
 
   it('no embeddings → no RAG, no semantic memory', () => {

package/src/engine.ts

@@ -35,6 +35,11 @@ export interface AgenticOptions {
   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;
+  /**
+   * Fired after a tool returns (success OR error — errors arrive as `{error}`).
+   * Useful for surfacing the raw response back to the user in a debug UI.
+   */
+  onToolResult?: (event: { name: string; arguments: Record<string, unknown>; result: unknown }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
   onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
   /**
@@ -127,6 +132,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),

package/src/funnel.ts

@@ -34,13 +34,31 @@ 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. Use the provided tools to ' +
-  'take actions: pay invoices and contacts, create invoices, check balances. ' +
-  'Never invent a balance, address, amount or result — always call the ' +
-  'relevant tool and report what it returns. All BTC amounts are in satoshis. ' +
-  'Keep replies short and friendly.';
+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'];
@@ -74,6 +92,12 @@ export interface FunnelCallbacks {
     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>;
 }
 
@@ -253,6 +277,7 @@ export class Funnel {
           .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

@@ -49,6 +49,40 @@ export type {
   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';
@@ -69,6 +103,7 @@ export type { MemoryStoreOptions } from './memory/store.js';
 export { createMemoryToolSource } from './memory/tool.js';
 export type {
   AgentProfile,
+  MemoryConsolidation,
   MemoryItem,
   MemoryKind,
   MemoryQuery,
@@ -110,6 +145,14 @@ export { walletHistoryToDocuments, contactsToDocuments } from './knowledge/walle
 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';

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