@kaleidorg/mind 0.2.0 → 0.4.0

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

package/src/kaleidoswap/contract.ts

@@ -0,0 +1,212 @@
+/**
+ * Canonical KaleidoSwap tool contract — the single source of truth for the
+ * agent-facing tools that drive the KaleidoSwap maker.
+ *
+ * Every surface implements THESE EXACT tools, only the transport differs:
+ *   - mobile  → in-process handlers over the WDK protocol package
+ *               (`@kaleidorg/wdk-protocol-swap-kaleidoswap`) via `bindKaleidoswapTools`
+ *   - desktop → HTTP / kaleido-mcp / kaleido-cli, also via `bindKaleidoswapTools`
+ *   - eval    → stub handlers, also via `bindKaleidoswapTools`
+ *
+ * Because the schemas are identical everywhere, skills are portable and the
+ * model comparison is honest. Tools are grouped (`market`, `orders`, `atomic`)
+ * so a host can expose a read-only subset for sandbox/eval modes.
+ *
+ * Spend tools (place an order, init/execute an atomic swap) carry
+ * `spend: true` → `requiresConfirmation: true`, so the Engine always pauses
+ * for the host's confirm gate before executing.
+ *
+ * Pure data — no deps, no fetch, RN-safe.
+ */
+
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { InProcessTool } from '../tools/in-process.js';
+
+/** Functional grouping for selective binding (e.g. read-only sandbox). */
+export type KaleidoswapGroup = 'market' | 'orders' | 'atomic';
+
+export interface KaleidoswapToolDef extends ToolDef {
+  /** Functional group — lets a host expose a subset. */
+  group: KaleidoswapGroup;
+  /** Moves funds → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<string, { type: string; description?: string; enum?: string[] }>;
+
+function t(
+  group: KaleidoswapGroup,
+  name: string,
+  description: string,
+  properties: Props = {},
+  required: string[] = [],
+  spend = false,
+): KaleidoswapToolDef {
+  return {
+    group,
+    name,
+    description,
+    spend,
+    requiresConfirmation: spend,
+    parameters: { type: 'object', properties, required },
+  };
+}
+
+/**
+ * The canonical KaleidoSwap tool list. Schema is intentionally agent-facing —
+ * each host's adapter translates these args into the underlying transport's
+ * request body (maker REST JSON, WDK protocol calls, MCP, etc.).
+ */
+export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
+  // ─── market (read) ─────────────────────────────────────────────────────
+  t('market',
+    'kaleidoswap_get_assets',
+    'List the assets KaleidoSwap supports — BTC plus the RGB assets the maker has inventory for (e.g. USDT, XAUT). Returns symbol, precision, and issuer/contract id. No args.'),
+
+  t('market',
+    'kaleidoswap_get_pairs',
+    'List the trading pairs currently quoted by the maker, with the latest bid/ask and the minimum/maximum executable size on each side. Use this before quoting to pick a valid pair. No args.'),
+
+  t('market',
+    'kaleidoswap_get_quote',
+    'Get an executable quote for swapping a specific amount on one pair. Returns a quote id (use it with place_order or atomic_init), the expected receive amount, fees, slippage, and how long the quote is valid for. Re-quote rather than reusing a stale id.',
+    {
+      from_asset: { type: 'string', description: 'Asset to spend, e.g. "BTC" or "USDT".' },
+      to_asset:   { type: 'string', description: 'Asset to receive, e.g. "USDT" or "BTC".' },
+      amount:     { type: 'number', description: 'Amount of from_asset to swap. BTC is in satoshis; RGB assets use their asset-defined precision.' },
+      side:       { type: 'string', enum: ['buy', 'sell'], description: 'Default "sell" (you sell from_asset). Use "buy" only when from_asset is the quote currency you spend to acquire to_asset.' },
+    },
+    ['from_asset', 'to_asset', 'amount']),
+
+  t('market',
+    'kaleidoswap_get_nodeinfo',
+    "Get info about the maker's Lightning node — pubkey, host, port, connect URI. Useful before opening a channel or when the user wants to see the counterparty. No args."),
+
+  // ─── orders (orderbook / market-order flow) ─────────────────────────────
+  t('orders',
+    'kaleidoswap_place_order',
+    'Place an order using an executable quote. Returns an order id. SPEND: the host pauses for user confirmation before the maker is called. Use only after kaleidoswap_get_quote and only when the user has explicitly approved the amount + destination.',
+    {
+      quote_id: { type: 'string', description: 'The quote id returned by kaleidoswap_get_quote (must still be valid).' },
+    },
+    ['quote_id'],
+    /* spend */ true),
+
+  t('orders',
+    'kaleidoswap_get_order_status',
+    'Check the status of an order by id — pending / settling / completed / failed. Poll this after place_order until the order settles.',
+    {
+      order_id: { type: 'string', description: 'The order id returned by kaleidoswap_place_order.' },
+    },
+    ['order_id']),
+
+  t('orders',
+    'kaleidoswap_get_order_history',
+    "Get the user's recent KaleidoSwap orders for context (last N, paginated). Read-only.",
+    {
+      limit:  { type: 'number', description: 'Max rows (default 20, max 100).' },
+      cursor: { type: 'string', description: 'Pagination cursor from a previous call.' },
+    }),
+
+  // ─── atomic (the trust-minimised swap chain — used by the recipe) ───────
+  t('atomic',
+    'kaleidoswap_atomic_init',
+    "Initialise an atomic swap from a quote. Requires the receiver's RGB/LN invoice so the maker can lock the outgoing leg. SPEND: confirmation-gated. Returns the maker's invoice for the user to pay and an atomic id to track.",
+    {
+      quote_id:        { type: 'string', description: 'The quote id from kaleidoswap_get_quote.' },
+      receive_invoice: { type: 'string', description: "The user's RGB or Lightning invoice for to_asset, created on the user's own node." },
+    },
+    ['quote_id', 'receive_invoice'],
+    /* spend */ true),
+
+  t('atomic',
+    'kaleidoswap_atomic_execute',
+    "Tell the maker to release the receive leg now that the user has paid the maker's invoice. SPEND: confirmation-gated (committing the swap). Returns an updated atomic status.",
+    {
+      atomic_id: { type: 'string', description: 'The atomic id from kaleidoswap_atomic_init.' },
+    },
+    ['atomic_id'],
+    /* spend */ true),
+
+  t('atomic',
+    'kaleidoswap_atomic_status',
+    'Poll the status of an atomic swap — pending_payment / paid / settling / completed / failed / expired. Use this in a loop after execute until it terminates.',
+    {
+      atomic_id: { type: 'string', description: 'The atomic id from kaleidoswap_atomic_init.' },
+    },
+    ['atomic_id']),
+];
+
+/** All tool names that move funds (confirmation-gated). */
+export const KALEIDOSWAP_SPEND_TOOLS: Set<string> = new Set(
+  KALEIDOSWAP_TOOLS.filter((t) => t.spend).map((t) => t.name),
+);
+
+/** Quick lookup. */
+export function isKaleidoswapSpendTool(name: string): boolean {
+  return KALEIDOSWAP_SPEND_TOOLS.has(name);
+}
+
+/** Quick lookup. */
+export function getKaleidoswapTool(name: string): KaleidoswapToolDef | undefined {
+  return KALEIDOSWAP_TOOLS.find((t) => t.name === name);
+}
+
+/** Pick the contract tools for the given groups (all by default). */
+export function kaleidoswapTools(
+  opts: { groups?: KaleidoswapGroup[] } = {},
+): KaleidoswapToolDef[] {
+  if (!opts.groups) return [...KALEIDOSWAP_TOOLS];
+  const groups = new Set(opts.groups);
+  return KALEIDOSWAP_TOOLS.filter((x) => groups.has(x.group));
+}
+
+/** A handler bound to one contract tool. Args validated by JSON schema upstream. */
+export type KaleidoswapHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindKaleidoswapOptions {
+  /** Restrict the surface to a subset (e.g. read-only on eval). */
+  groups?: KaleidoswapGroup[];
+  /** Skip tools that have no handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  /** ToolSource id for the registry (default 'kaleidoswap'). */
+  id?: string;
+}
+
+/**
+ * Bind contract tools to in-process handlers → an InProcessToolSource.
+ *
+ * The host is responsible for the actual transport (HTTP/WDK/CLI/MCP) — this
+ * function is a pure shape adapter that preserves names, descriptions,
+ * parameter schemas, and the spend gate.
+ *
+ *   const source = bindKaleidoswapTools({
+ *     kaleidoswap_get_quote: async (args) => makerSdk.quote(args),
+ *     kaleidoswap_place_order: async ({ quote_id }) => makerSdk.placeOrder({ quoteId: quote_id }),
+ *     // …
+ *   });
+ *   tools.register(source);
+ */
+export function bindKaleidoswapTools(
+  handlers: Record<string, KaleidoswapHandler>,
+  opts: BindKaleidoswapOptions = {},
+): InProcessToolSource {
+  const defs = kaleidoswapTools(opts);
+  const bound: InProcessTool[] = [];
+  for (const def of defs) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindKaleidoswapTools: no handler for "${def.name}"`);
+    }
+    bound.push({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+      requiresConfirmation: def.requiresConfirmation,
+      handler,
+    });
+  }
+  return new InProcessToolSource(opts.id ?? 'kaleidoswap', bound);
+}

package/src/knowledge/btc-map.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createBtcMapToolSource,
+  BTC_MAP_SAMPLE,
+  type BtcMapFetch,
+  type LocationProvider,
+  type BtcMapMerchant,
+} from './btc-map.js';
+import type { Merchant } from './merchants.js';
+
+const exec = async (
+  src: ReturnType<typeof createBtcMapToolSource>,
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<any> => src.execute(name, args);
+
+describe('createBtcMapToolSource — tool surface', () => {
+  it('exposes find_merchant_locations and get_merchant_info', () => {
+    const src = createBtcMapToolSource();
+    const names = src.listTools().map((t) => t.name);
+    expect(names).toEqual(['find_merchant_locations', 'get_merchant_info']);
+    expect(src.has('find_merchant_locations')).toBe(true);
+    expect(src.has('get_merchant_info')).toBe(true);
+    expect(src.has('find_merchants')).toBe(false); // legacy name is gone
+  });
+
+  it('throws on unknown tool', async () => {
+    const src = createBtcMapToolSource();
+    await expect(exec(src, 'no_such_tool')).rejects.toThrow(/unknown tool/);
+  });
+});
+
+describe('find_merchant_locations — offline fallback', () => {
+  it('returns offline rows when no location and no fetch are injected', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'find_merchant_locations', {});
+    expect(r.success).toBe(true);
+    expect(r.source).toBe('offline');
+    expect(r.precise_location).toBe(false);
+    expect(r.merchants.length).toBeGreaterThan(0);
+    expect(r.merchants.length).toBeLessThanOrEqual(10); // default limit
+  });
+
+  it('honours category filter on offline data', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'find_merchant_locations', { category: 'bar' });
+    expect(r.merchants.every((m: any) => m.category === 'bar')).toBe(true);
+    // Sample has at least one bar (PubKey).
+    expect(r.merchants.length).toBeGreaterThan(0);
+  });
+
+  it('honours query filter on offline data', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'find_merchant_locations', { query: 'PubKey' });
+    expect(r.merchants.some((m: any) => m.name === 'PubKey')).toBe(true);
+  });
+
+  it('clamps limit to 1–20 with a default of 10', async () => {
+    const src = createBtcMapToolSource();
+    const big = await exec(src, 'find_merchant_locations', { limit: 9999 });
+    expect(big.merchants.length).toBeLessThanOrEqual(20);
+    const tiny = await exec(src, 'find_merchant_locations', { limit: -5 });
+    expect(tiny.merchants.length).toBeGreaterThanOrEqual(1); // clamped to ≥1
+  });
+
+  it('caller can override the offline dataset', async () => {
+    const custom: Merchant[] = [
+      { id: 'only', name: 'Only Café', category: 'cafe', acceptedAssets: ['lightning'] },
+    ];
+    const src = createBtcMapToolSource({ offlineMerchants: custom });
+    const r = await exec(src, 'find_merchant_locations', {});
+    expect(r.merchants).toHaveLength(1);
+    expect(r.merchants[0].name).toBe('Only Café');
+  });
+});
+
+describe('find_merchant_locations — live path (host-injected fetch)', () => {
+  const point = { lat: 46.0, lng: 8.95 };
+  const locationOnly: LocationProvider = {
+    getCurrent: async () => ({ ...point, label: 'Lugano', precise: true }),
+  };
+
+  it('uses live fetch when location resolves', async () => {
+    const captured: any[] = [];
+    const fetchImpl: BtcMapFetch = async (q) => {
+      captured.push(q);
+      return [
+        { id: 1, name: 'Live Café', category: 'cafe', lat: 46.0, lng: 8.95, distance_m: 42,
+          acceptedAssets: ['lightning'] } satisfies BtcMapMerchant,
+      ];
+    };
+    const src = createBtcMapToolSource({ location: locationOnly, fetch: fetchImpl });
+    const r = await exec(src, 'find_merchant_locations', { query: 'café', radius_km: 3 });
+    expect(r.source).toBe('btcmap');
+    expect(r.precise_location).toBe(true);
+    expect(r.merchants[0].name).toBe('Live Café');
+    expect(r.merchants[0].distance_m).toBe(42);
+    expect(captured[0]).toMatchObject({
+      center: { lat: 46.0, lng: 8.95 },
+      radiusMeters: 3000,
+      query: 'café',
+      limit: 10,
+    });
+  });
+
+  it('geocodes near_address when provided', async () => {
+    const geocoded = { lat: 38.71, lng: -9.143 };
+    const seen: string[] = [];
+    const location: LocationProvider = {
+      getCurrent: async () => ({ lat: 46.0, lng: 8.95, precise: true }), // should NOT be used
+      geocode: async (addr) => {
+        seen.push(addr);
+        return geocoded;
+      },
+    };
+    const fetchImpl: BtcMapFetch = async (q) => [
+      { id: 'lis', name: 'Lisbon Place', lat: q.center.lat, lng: q.center.lng,
+        acceptedAssets: ['lightning'] } satisfies BtcMapMerchant,
+    ];
+    const src = createBtcMapToolSource({ location, fetch: fetchImpl });
+    const r = await exec(src, 'find_merchant_locations', { near_address: 'Lisbon' });
+    expect(seen).toEqual(['Lisbon']);
+    expect(r.merchants[0].lat).toBeCloseTo(geocoded.lat);
+    expect(r.merchants[0].lng).toBeCloseTo(geocoded.lng);
+    expect(r.precise_location).toBe(false); // came from geocode, not GPS
+  });
+
+  it('falls back to offline when live fetch throws', async () => {
+    const src = createBtcMapToolSource({
+      location: locationOnly,
+      fetch: async () => { throw new Error('btcmap is down'); },
+    });
+    const r = await exec(src, 'find_merchant_locations', {});
+    expect(r.source).toBe('offline');
+    expect(r.merchants.length).toBeGreaterThan(0);
+  });
+
+  it('falls back to offline when location resolves but fetch is missing', async () => {
+    const src = createBtcMapToolSource({ location: locationOnly });
+    const r = await exec(src, 'find_merchant_locations', {});
+    expect(r.source).toBe('offline'); // no fetch injected → no live path
+  });
+});
+
+describe('get_merchant_info', () => {
+  it('finds a merchant by id', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'get_merchant_info', { merchant_id: 'nyc-pubkey' });
+    expect(r.success).toBe(true);
+    expect(r.merchant.name).toBe('PubKey');
+    expect(r.merchant.accepts_lightning).toBe(true);
+  });
+
+  it('finds a merchant by exact name', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'get_merchant_info', { merchant_name: 'Bistro Libertine' });
+    expect(r.success).toBe(true);
+    expect(r.merchant.city).toBe('Lugano');
+  });
+
+  it('returns an error and possible suggestions when the name does not match', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'get_merchant_info', { merchant_name: 'Nonexistent Merchant Name' });
+    expect(r.success).toBe(false);
+    expect(typeof r.error).toBe('string');
+  });
+
+  it('treats a fuzzy-close name as a hit (not an error)', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'get_merchant_info', { merchant_name: 'Pubkey' }); // PubKey
+    expect(r.success).toBe(true);
+    expect(r.merchant.name).toBe('PubKey');
+  });
+
+  it('returns an error (no throw) when given nothing', async () => {
+    const src = createBtcMapToolSource();
+    const r = await exec(src, 'get_merchant_info', {});
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('BTC_MAP_SAMPLE', () => {
+  it('has a row in Lugano with Lightning support (sanity)', () => {
+    const lugano = BTC_MAP_SAMPLE.filter((m) => m.city === 'Lugano');
+    expect(lugano.length).toBeGreaterThan(0);
+    expect(lugano.every((m) => m.acceptedAssets?.includes('lightning'))).toBe(true);
+  });
+});