@kaleidorg/mind 0.7.0 → 0.8.0

package/src/qvac/stream.ts

@@ -28,11 +28,9 @@ export interface StreamHandlers {
   /** The model's `<think>` reasoning, streamed separately. */
   onThinking?: (token: string) => void;
   /**
-   * Cap the `<think>` reasoning at this many tokens. The cap is on TOKENS, not
-   * wall-clock seconds — tok/s varies by model and hardware, so a time budget is
-   * unreliable; the SDK has no numeric reasoning budget (`reasoning_budget` is
-   * only on/off), so we count thinking tokens and stop the run once they exceed
-   * this. Omit for unlimited reasoning.
+   * Stop the run once `<think>` reasoning exceeds this many tokens (estimated
+   * from characters). A backstop for the SDK's own `reasoning_budget`. Omit for
+   * unlimited reasoning.
    */
   maxThinkingTokens?: number;
   /**

package/src/qvac/tools.ts

@@ -104,3 +104,13 @@ export function toQvacTools(
   }
   return tools.map(toQvacTool);
 }
+
+/**
+ * JSON Schema for a tool's parameters: a JSON-Schema def is returned as is
+ * (nested objects intact), a Zod schema is converted to a flat object schema.
+ */
+export function toolParametersSchema(t: Pick<ToolDef, 'name' | 'description' | 'parameters'>): Record<string, unknown> {
+  const p = t.parameters as Obj | null | undefined;
+  if (p && typeof p === 'object' && !isZodLike(p) && ('properties' in p || p.type === 'object')) return p;
+  return toQvacTool(t).parameters;
+}

package/src/recipe/issue-asset.test.ts

@@ -35,6 +35,45 @@ describe('extractIssueAsset (deterministic Tier-0)', () => {
   });
 });
 
+describe('extractIssueAsset — review regressions', () => {
+  it('reads thousands separators in both styles, and decimals with k/m', () => {
+    expect(extractIssueAsset('crea 1.000 token CAFE chiamati Caffè Club')).toMatchObject({ amount: 1000, ticker: 'CAFE', name: 'Caffè Club' });
+    expect(extractIssueAsset('issue 1,000 TICKET tokens')).toMatchObject({ amount: 1000 });
+    expect(extractIssueAsset('mint 1,5k PIZZA tokens')).toMatchObject({ amount: 1500 });
+    expect(extractIssueAsset('mint 1.5k PIZZA tokens')).toMatchObject({ amount: 1500 });
+  });
+  it('never takes the supply from a number inside the name', () => {
+    expect(extractIssueAsset('mint tokens named Web3 Summit 2026, supply 300')).toMatchObject({ name: 'Web3 Summit 2026', amount: 300 });
+    expect(extractIssueAsset('mint tokens named Web3 Summit 2026')).toMatchObject({ name: 'Web3 Summit 2026', amount: undefined });
+    expect(issueAssetRecipe.confident!(extractIssueAsset('mint tokens named Web3 Summit 2026')!)).toBe(false);
+    expect(extractIssueAsset('launch a token called Moon with ticker MOON and 1m supply')).toMatchObject({ name: 'Moon', ticker: 'MOON', amount: 1_000_000 });
+  });
+  it('only fires when the request opens with the verb', () => {
+    expect(issueAssetRecipe.match!('I have an issue with my USDT tokens')).toBe(false);
+    expect(issueAssetRecipe.match!('how do I create a token?')).toBe(false);
+    expect(extractIssueAsset('I have an issue with my USDT tokens')).toBeNull();
+    expect(issueAssetRecipe.match!('please mint 100 PIZZA tokens')).toBe(true);
+    expect(issueAssetRecipe.match!('puoi creare 100 token CAFE?')).toBe(true);
+  });
+  it('apostrophes inside a name are not quotes', () => {
+    expect(extractIssueAsset("mint 100 tokens called Joe's Pizza with ticker 'JOE'")).toEqual({ name: "Joe's Pizza", ticker: 'JOE', amount: 100, schema: 'NIA' });
+    expect(extractIssueAsset("crea 50 token chiamati Bottega dell'Arte con ticker ARTE")).toMatchObject({ name: "Bottega dell'Arte", ticker: 'ARTE', amount: 50 });
+    expect(extractIssueAsset('mint 10 tokens "Pizza Points" ticker PP')).toMatchObject({ name: 'Pizza Points', ticker: 'PP', amount: 10 });
+  });
+});
+
+describe('MockWallet.reset', () => {
+  it('restores the initial state, including issued assets and UTXOs', async () => {
+    const wallet = new MockWallet({ utxos: 1 });
+    await wallet.registry().execute('rln_issue_asset', { name: 'Ticket', ticker: 'TICKET', amount: 10 });
+    expect(wallet.utxos).toBe(0);
+    wallet.reset();
+    expect(wallet.utxos).toBe(1);
+    expect(wallet.assets.TICKET).toBeUndefined();
+    await expect(wallet.registry().execute('rln_issue_asset', { name: 'Ticket', ticker: 'TICKET', amount: 10 })).resolves.toMatchObject({ issued: true });
+  });
+});
+
 describe('issue-asset readback', () => {
   it('fungible: supply + ticker + name', () => {
     expect(confirmReadback({ name: 'rln_issue_asset', arguments: { name: 'Hackathon Ticket', ticker: 'TICKET', amount: 1000 } }))

package/src/recipe/issue-asset.ts

@@ -13,30 +13,58 @@
 
 import type { Recipe, RecipeContext } from './types.js';
 
-const VERB = /\b(issue|mint|create|launch|emetti|conia|crea)\b/i;
+// The request must OPEN with the verb ("issue …", "please mint …", "puoi creare …"),
+// so "I have an issue with my tokens" or "how do I create a token?" stay with the model.
+const VERB = /^(?:(?:please|pls|per favore|can you|could you|puoi|potresti)\s+)?(issue|mint|create|launch|emetti|conia|crea|creare|emettere|coniare)\b/i;
 const NOUN = /\b(tokens?|assets?|coins?|nfts?|tickets?|gettoni|badges?)\b/i;
 const NOT_ISSUE = /\b(invoice|fattura|channel|canale|swap|buy|sell|send|pay|compra|vendi|invia|paga)\b/i;
 const NFT = /\b(nfts?|unique|unico|unica)\b/i;
 // Words that look like tickers but are part of the request, not the asset.
 const STOPWORDS = new Set(['RGB', 'NFT', 'NFTS', 'NIA', 'CFA', 'UDA', 'BTC', 'LN', 'AN', 'A']);
 
-function parseAmount(t: string): number | undefined {
-  const m = t.match(/(?:^|\s)(\d[\d.,]*)\s*([km])?(?=\s|$)/i);
-  if (!m) return undefined;
-  let n = Number(m[1]!.replace(/,/g, ''));
-  if (m[2]) n *= m[2].toLowerCase() === 'k' ? 1_000 : 1_000_000;
-  return Number.isFinite(n) && n > 0 ? n : undefined;
+// "1000", "1,000", "1.000" (it), "1.5", "1,5" (it), optionally followed by k/m.
+const NUM = String.raw`(\d{1,3}(?:[.,]\d{3})+|\d+(?:[.,]\d+)?)\s*([km])?`;
+
+function toNumber(digits: string, suffix?: string): number | undefined {
+  // Groups of exactly three digits are thousands separators in both "1,000" and "1.000";
+  // a single separator followed by another digit count is a decimal point.
+  const n = /^\d{1,3}(?:[.,]\d{3})+$/.test(digits)
+    ? Number(digits.replace(/[.,]/g, ''))
+    : Number(digits.replace(',', '.'));
+  const scaled = suffix ? n * (suffix.toLowerCase() === 'k' ? 1_000 : 1_000_000) : n;
+  return Number.isFinite(scaled) && scaled > 0 ? scaled : undefined;
 }
 
+/**
+ * The supply: an explicit "supply 300" / "1m supply" wins, then a number right before the token
+ * noun / ticker ("1000 TICKET tokens", "500 token"). Numbers inside the asset name
+ * ("Web3 Summit 2026") are never the supply.
+ */
+function parseAmount(t: string, name?: string): number | undefined {
+  const rest = name ? t.replace(name, ' ') : t;
+  const labelled = rest.match(new RegExp(String.raw`\b(?:supply|amount|quantit[àa]|totale)\s*(?:of|di|[:=])?\s*` + NUM, 'i'));
+  if (labelled) return toNumber(labelled[1]!, labelled[2]);
+  const trailing = rest.match(new RegExp(String.raw`(?:^|\s)` + NUM + String.raw`\s+(?:supply|di supply)\b`, 'i'));
+  if (trailing) return toNumber(trailing[1]!, trailing[2]);
+  const beforeNoun = rest.match(new RegExp(String.raw`(?:^|\s)` + NUM + String.raw`\s+(?:[A-Z][A-Z0-9]{1,7}\s+)?(?:tokens?|coins?|tickets?|gettoni|badges?|assets?)\b`, 'i'));
+  if (beforeNoun) return toNumber(beforeNoun[1]!, beforeNoun[2]);
+  return undefined;
+}
+
+const unquote = (s: string) => s.replace(/^["“'‘]+|["”'’]+$/g, '').trim();
+
 function parseName(t: string): string | undefined {
-  const quoted = t.match(/["“'‘]([^"”'’]{1,40})["”'’]/)?.[1];
-  if (quoted) return quoted.trim();
-  const m = t.match(/\b(?:called|named|chiamat[oaie])\s+(.+?)(?=\s+(?:with|ticker|con)\b|[,.;]|$)/i);
-  return m?.[1]?.trim() || undefined;
+  // "called Joe's Pizza with ticker 'JOE'" → Joe's Pizza (apostrophes inside a name are fine).
+  const m = t.match(/\b(?:called|named|chiamat[oaie])\s+(.+?)(?=\s+(?:with|ticker|con|supply)\b|[,;]|\.(?:\s|$)|$)/i);
+  if (m?.[1]) return unquote(m[1]) || undefined;
+  // Otherwise only a properly paired quote: double quotes, or single quotes that open
+  // after a space and close before a space/punctuation (so "Joe's" never opens one).
+  const quoted = t.match(/["“]([^"”]{1,40})["”]/)?.[1] ?? t.match(/(?:^|\s)['‘]([^'’]{1,40})['’](?=\s|$|[,.;!?])/)?.[1];
+  return quoted?.trim() || undefined;
 }
 
 function parseTicker(t: string, name?: string): string | undefined {
-  const explicit = t.match(/\bticker\s+([A-Za-z0-9]{1,8})\b/i)?.[1];
+  const explicit = t.match(/\bticker\s*[:=]?\s*["'“‘]?([A-Za-z0-9]{1,8})\b/i)?.[1];
   if (explicit) return explicit.toUpperCase();
   // An all-caps word that isn't part of the name ("1000 TICKET tokens").
   const nameWords = new Set((name ?? '').split(/\s+/));
@@ -57,7 +85,7 @@ export function extractIssueAsset(text: string): Record<string, unknown> | null
   const schema = NFT.test(t) ? 'UDA' : 'NIA';
   const name = parseName(t);
   const ticker = parseTicker(t, name) ?? (name ? tickerFromName(name) : undefined);
-  const amount = schema === 'UDA' ? 1 : parseAmount(t);
+  const amount = schema === 'UDA' ? 1 : parseAmount(t, name);
   if (!ticker && !name) return null;
   return { name: name ?? ticker, ticker, amount, schema };
 }

package/src/recipe/runner.ts

@@ -111,6 +111,7 @@ export async function extractSlots(
       system,
       messages: [{ role: 'user', content: text }],
       tools: [extractTool],
+      toolChoice: EXTRACT_TOOL,
       signal,
     });
   } catch (err) {

package/src/recipe/submarine-pay.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi } from 'vitest';
+import { extractSubmarinePay, submarinePayRecipe } from './submarine-pay.js';
+import { runRecipe } from './runner.js';
+import { Funnel } from '../funnel.js';
+import { paymentsRecipe } from './payments.js';
+import { MockWallet, scriptedProvider } from '../testing/index.js';
+import { SUBMARINE_TOOLS, isSubmarineSpendTool, formatSubmarineAmount } from '../submarine/contract.js';
+
+// 10u = 1,000 sats on signet.
+const INVOICE = 'lntbs10u1pnmockinvoice0qqqqqqqqqqqqqqqqqqqqqqqqq';
+
+describe('submarine contract', () => {
+  it('only fund moves money, and it takes nothing but the swap id', () => {
+    expect(SUBMARINE_TOOLS.map((t) => t.name)).toEqual([
+      'kaleidoswap_submarine_pairs', 'kaleidoswap_submarine_create', 'kaleidoswap_submarine_fund', 'kaleidoswap_submarine_status',
+    ]);
+    expect(SUBMARINE_TOOLS.filter((t) => t.requiresConfirmation).map((t) => t.name)).toEqual(['kaleidoswap_submarine_fund']);
+    expect(isSubmarineSpendTool('kaleidoswap_submarine_create')).toBe(false);
+    const fund = SUBMARINE_TOOLS.find((t) => t.name === 'kaleidoswap_submarine_fund')!;
+    expect(Object.keys((fund.parameters as any).properties)).toEqual(['swap_id']);
+  });
+  it('formats source amounts for the readback', () => {
+    expect(formatSubmarineAmount('L-USDT', '87500000')).toBe('0.875 L-USDT');
+    expect(formatSubmarineAmount('L-BTC', 1005)).toBe('1,005 sats of L-BTC');
+  });
+});
+
+describe('extractSubmarinePay', () => {
+  it('needs an invoice and an explicit Liquid asset', () => {
+    expect(extractSubmarinePay(`pay ${INVOICE} with L-USDT`)).toEqual({ invoice: INVOICE, from_asset: 'L-USDT' });
+    expect(extractSubmarinePay(`paga ${INVOICE} con USDT su Liquid`)).toEqual({ invoice: INVOICE, from_asset: 'L-USDT' });
+    expect(extractSubmarinePay(`pay ${INVOICE} using liquid bitcoin`)).toEqual({ invoice: INVOICE, from_asset: 'L-BTC' });
+    // Bare USDT is RGB USDT — not this recipe.
+    expect(extractSubmarinePay(`pay ${INVOICE} with USDT`)).toBeNull();
+    expect(extractSubmarinePay('pay bob 10 L-USDT')).toBeNull();
+  });
+});
+
+describe('runRecipe — submarine pay against the mock /v2 maker', () => {
+  it('creates, confirms once with the maker amount, then funds', async () => {
+    const wallet = new MockWallet({ priceUsd: 80_000 });
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(submarinePayRecipe, `pay ${INVOICE} with L-USDT`, { provider: scriptedProvider(), tools: wallet.registry(), onConfirm });
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0);
+    expect(onConfirm).toHaveBeenCalledOnce();
+    // 1,000 sats + 0.5% at $80k = 0.804 USD → 80,400,000 units of L-USDT (8 dp).
+    expect((onConfirm.mock.calls[0] as any[])[0].summary).toBe(
+      'Pay Lightning invoice lntbs10u1p…qqqqqq with 0.804 L-USDT (fees included) through a KaleidoSwap submarine swap. Confirm?');
+    expect(wallet.liquid['L-USDT']).toBe(100 * 1e8 - 80_400_000);
+    expect(wallet.sends.map((s) => s.tool)).toEqual(['kaleidoswap_submarine_fund']);
+    expect(res.text).toMatch(/^Locked 0\.804 L-USDT in swap sub1/);
+  });
+
+  it('declining funds nothing, but the swap was opened (no money moved)', async () => {
+    const wallet = new MockWallet();
+    const res = await runRecipe(submarinePayRecipe, `pay ${INVOICE} with L-USDT`, {
+      provider: scriptedProvider(), tools: wallet.registry(), onConfirm: async () => ({ approved: false }),
+    });
+    expect(res.status).toBe('cancelled');
+    expect(wallet.sends).toEqual([]);
+    expect(wallet.submarineSwaps.sub1?.funded).toBe(false);
+  });
+
+  it('surfaces insufficient Liquid balance without locking anything', async () => {
+    const wallet = new MockWallet({ liquid: { 'L-USDT': 1000, 'L-BTC': 0 } });
+    const res = await runRecipe(submarinePayRecipe, `pay ${INVOICE} with L-USDT`, {
+      provider: scriptedProvider(), tools: wallet.registry(), onConfirm: async () => ({ approved: true }),
+    });
+    expect(res.status).toBe('error');
+    expect(res.error ?? res.text).toMatch(/Insufficient L-USDT/);
+    expect(wallet.sends).toEqual([]);
+  });
+});
+
+describe('Funnel — submarine-pay ahead of payments', () => {
+  it('routes "pay <invoice> with L-USDT" to the submarine recipe, plain invoices elsewhere', async () => {
+    const wallet = new MockWallet();
+    const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry(), recipes: [submarinePayRecipe, paymentsRecipe] });
+    const out = await funnel.runTurn(`pay ${INVOICE} with L-USDT`, { onConfirm: async () => ({ approved: true }) });
+    expect(out.tier).toBe('recipe');
+    expect(out.route).toBe('submarine-pay');
+    const status = await wallet.registry().execute('kaleidoswap_submarine_status', { swap_id: 'sub1' }) as { status: string };
+    expect(status.status).toBe('transaction.claimed');
+    expect(submarinePayRecipe.match!(`pay ${INVOICE}`)).toBe(false);
+  });
+});

package/src/recipe/submarine-pay.ts

@@ -0,0 +1,78 @@
+/**
+ * "Pay this Lightning invoice with my Liquid USDT" — a submarine swap on the
+ * KaleidoSwap /v2 maker:
+ *
+ *   "pay lntbs1… with L-USDT"           → kaleidoswap_submarine_create → 🔒 kaleidoswap_submarine_fund
+ *   "paga lntbs1… con USDT su Liquid"   → same
+ *
+ * One confirmation, shown after `create` so the user sees the exact amount the
+ * maker asked for (fees included) before anything is locked. Keys never reach
+ * the model; `fund` takes only the swap id. Opt-in: register via
+ * `Funnel.recipes` BEFORE the generic payments recipe on hosts that bind the
+ * submarine tools.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+import { formatSubmarineAmount } from '../submarine/contract.js';
+
+const INVOICE = /\b(ln(?:bcrt|tbs|bc|tb)[0-9a-z]{20,})\b/i;
+// Only an explicit Liquid asset: a bare "USDT" is RGB USDT (atomic recipe), not L-USDT.
+const L_USDT = /\b(l-?usdt|usdt[- ]?l|liquid[- ]usdt|usdt (?:on|su|in) liquid|usdt liquid)\b/i;
+const L_BTC = /\b(l-?btc|liquid[- ]btc|liquid bitcoin|btc (?:on|su|in) liquid|bitcoin (?:on|su|in) liquid)\b/i;
+
+/** Tool results may arrive as JSON text (MCP) or objects (in-process). */
+function obj(v: unknown): Record<string, unknown> {
+  if (typeof v === 'string') {
+    try { return JSON.parse(v) as Record<string, unknown>; } catch { return {}; }
+  }
+  return (v ?? {}) as Record<string, unknown>;
+}
+
+function shortInvoice(inv: string): string {
+  return `${inv.slice(0, 10)}…${inv.slice(-6)}`;
+}
+
+export function extractSubmarinePay(text: string): Record<string, unknown> | null {
+  const invoice = text.match(INVOICE)?.[1];
+  if (!invoice) return null;
+  const from_asset = L_USDT.test(text) ? 'L-USDT' : L_BTC.test(text) ? 'L-BTC' : undefined;
+  if (!from_asset) return null;
+  return { invoice, from_asset };
+}
+
+export const submarinePayRecipe: Recipe = {
+  name: 'submarine-pay',
+  description: 'Pay a Lightning invoice from Liquid funds (L-USDT or L-BTC) via a KaleidoSwap submarine swap — one confirmation.',
+  match: (t) => INVOICE.test(t) && (L_USDT.test(t) || L_BTC.test(t)),
+  triggers: ['l-usdt', 'liquid usdt', 'l-btc', 'submarine'],
+  slots: [
+    { name: 'invoice', type: 'string', description: 'BOLT11 Lightning invoice to pay', required: true },
+    { name: 'from_asset', type: 'string', description: 'L-USDT or L-BTC', required: true },
+  ],
+  extract: extractSubmarinePay,
+  confident: (s) => typeof s.invoice === 'string' && (s.from_asset === 'L-USDT' || s.from_asset === 'L-BTC'),
+  steps: [
+    {
+      tool: 'kaleidoswap_submarine_create',
+      as: 'swap',
+      args: (ctx) => ({ invoice: ctx.slots.invoice, from_asset: ctx.slots.from_asset }),
+    },
+  ],
+  confirm: (ctx: RecipeContext) => {
+    const swap = obj(ctx.results.swap);
+    const asset = String(swap.from_asset ?? ctx.slots.from_asset);
+    return `Pay Lightning invoice ${shortInvoice(String(ctx.slots.invoice))} with ${formatSubmarineAmount(asset, swap.expected_amount)} (fees included) through a KaleidoSwap submarine swap. Confirm?`;
+  },
+  final: {
+    tool: 'kaleidoswap_submarine_fund',
+    args: (ctx) => ({ swap_id: obj(ctx.results.swap).swap_id }),
+  },
+  summary: (ctx, final) => {
+    const swap = obj(ctx.results.swap);
+    const funded = obj(final);
+    const asset = String(swap.from_asset ?? ctx.slots.from_asset);
+    return `Locked ${formatSubmarineAmount(asset, swap.expected_amount)} in swap ${String(swap.swap_id)}` +
+      (funded.txid ? ` (tx ${String(funded.txid).slice(0, 12)}…)` : '') +
+      '. The maker pays the invoice once the lockup is seen — ask me for the swap status to follow it.';
+  },
+};

package/src/skills/registry.ts

@@ -20,7 +20,7 @@ export const READ_REFERENCE_TOOL = 'read_skill_reference';
  *   ---
  *   name: portfolio-manager
  *   description: Rebalance BTC/USDT/XAUT to target allocations.
- *   tools: get_balance, kaleidoswap_get_quote, kaleidoswap_place_order
+ *   tools: get_balance, kaleidoswap_get_quote, kaleidoswap_atomic_init
  *   triggers: rebalance, allocation, portfolio
  *   ---
  *   <instructions…>

package/src/skills/select.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool-aware skill selection: pick a skill that can actually act with the tools
+ * a host has, before any inference runs.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { Skill } from './types.js';
+import { READ_REFERENCE_TOOL, SkillRegistry } from './registry.js';
+
+/**
+ * Whether a skill can act given the live tool names. A `requires-tools`
+ * frontmatter list must be fully live; otherwise at least one of the skill's
+ * scoped tools must be.
+ */
+export function skillAvailable(skill: Skill, present: ReadonlySet<string>): boolean {
+  const required = skill.metadata?.['requires-tools'];
+  if (required) {
+    return required.split(',').map((t) => t.trim()).filter(Boolean).every((t) => present.has(t));
+  }
+  if (!skill.tools?.length) return true;
+  return skill.tools.some((t) => t !== READ_REFERENCE_TOOL && present.has(t));
+}
+
+/**
+ * Select the best skill for `query` among those that can act with `liveTools`.
+ * Skills whose `requires-tools` are missing are never picked; a skill with zero
+ * live tools is only a last resort.
+ */
+export function selectAvailableSkill(
+  skills: SkillRegistry | readonly Skill[],
+  query: string,
+  liveTools: Iterable<string | Pick<ToolDef, 'name'>>,
+): Skill | null {
+  const list = skills instanceof SkillRegistry ? skills.list() : [...skills];
+  const present = new Set([...liveTools].map((t) => (typeof t === 'string' ? t : t.name)));
+  const usable = list.filter((s) => skillAvailable(s, present));
+  return (
+    new SkillRegistry(usable).select(query) ??
+    new SkillRegistry(list.filter((s) => !s.metadata?.['requires-tools'] && !usable.includes(s))).select(query)
+  );
+}

package/src/submarine/contract.ts

@@ -0,0 +1,112 @@
+/**
+ * Canonical submarine-swap tool contract — pay a Lightning invoice from Liquid
+ * funds through the KaleidoSwap Boltz /v2 maker (kaleidoswap-maker-rs).
+ *
+ * The names match kaleido-mcp, which implements them over @kaleidorg/swap-sdk.
+ * Hosts with the SDK in-process (desktop sidecar, React Native) bind the same
+ * names with `bindSubmarineTools`.
+ *
+ * Keys and preimages never cross this contract: the host derives the refund key
+ * from its wallet mnemonic and persists the swap. `kaleidoswap_submarine_fund`
+ * — the only spend — takes nothing but the swap id, so the model cannot alter
+ * the amount, asset or lockup address it pays.
+ *
+ * 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';
+
+export interface SubmarineToolDef extends ToolDef {
+  /** Moves funds → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<string, { type: string; description?: string; enum?: string[] }>;
+
+function t(name: string, description: string, properties: Props = {}, required: string[] = [], spend = false): SubmarineToolDef {
+  return { name, description, spend, requiresConfirmation: spend, parameters: { type: 'object', properties, required } };
+}
+
+/** Assets a submarine swap can be paid from, as the maker names them. */
+export const SUBMARINE_FROM_ASSETS = ['L-USDT', 'L-BTC'] as const;
+export type SubmarineFromAsset = typeof SUBMARINE_FROM_ASSETS[number];
+
+/** Smallest-unit decimals of each source asset (L-USDT: 8, L-BTC: sats). */
+export const SUBMARINE_ASSET_DECIMALS: Record<SubmarineFromAsset, number> = { 'L-USDT': 8, 'L-BTC': 8 };
+
+const swapId = { type: 'string', description: 'Swap id returned by kaleidoswap_submarine_create' } as const;
+
+export const SUBMARINE_TOOLS: SubmarineToolDef[] = [
+  t('kaleidoswap_submarine_pairs',
+    'List what can pay a Lightning invoice through a submarine swap (e.g. L-USDT on Liquid → Lightning BTC): rate, min/max, fees. No args.'),
+
+  t('kaleidoswap_submarine_create',
+    'Open a submarine swap that pays a Lightning (BOLT11) invoice from Liquid funds. No funds move: returns swap_id and expected_amount (source asset smallest unit). Then confirm with the user and call kaleidoswap_submarine_fund.',
+    {
+      invoice:    { type: 'string', description: 'BOLT11 Lightning invoice to pay (must carry an amount)' },
+      from_asset: { type: 'string', enum: [...SUBMARINE_FROM_ASSETS], description: 'Asset to pay with (default L-USDT)' },
+    },
+    ['invoice']),
+
+  t('kaleidoswap_submarine_fund',
+    'SPEND: lock the funds for a swap from kaleidoswap_submarine_create. Takes only the swap id — amount, asset and address come from the stored swap. The maker then pays the invoice.',
+    { swap_id: swapId },
+    ['swap_id'],
+    /* spend */ true),
+
+  t('kaleidoswap_submarine_status',
+    'Status of a submarine swap. "transaction.claimed" = invoice paid, done. A failed funded swap needs a refund.',
+    { swap_id: swapId },
+    ['swap_id']),
+];
+
+export const SUBMARINE_SPEND_TOOLS: Set<string> = new Set(SUBMARINE_TOOLS.filter((d) => d.spend).map((d) => d.name));
+
+export function isSubmarineSpendTool(name: string): boolean {
+  return SUBMARINE_SPEND_TOOLS.has(name);
+}
+
+export function getSubmarineTool(name: string): SubmarineToolDef | undefined {
+  return SUBMARINE_TOOLS.find((d) => d.name === name);
+}
+
+/** Format a smallest-unit amount of a source asset for display ("52.3 L-USDT", "1,200 sats"). */
+export function formatSubmarineAmount(asset: string, smallestUnits: unknown): string {
+  const n = Number(smallestUnits);
+  if (!Number.isFinite(n)) return `${String(smallestUnits)} ${asset}`;
+  if (asset === 'L-BTC') return `${n.toLocaleString('en-US')} sats of L-BTC`;
+  const decimals = SUBMARINE_ASSET_DECIMALS[asset as SubmarineFromAsset] ?? 0;
+  const value = n / 10 ** decimals;
+  return `${value.toLocaleString('en-US', { maximumFractionDigits: decimals })} ${asset}`;
+}
+
+export type SubmarineHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindSubmarineOptions {
+  /** Skip tools without a handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  /** ToolSource id for the registry (default 'submarine'). */
+  id?: string;
+}
+
+/** Bind the submarine contract to in-process handlers → an InProcessToolSource. */
+export function bindSubmarineTools(handlers: Record<string, SubmarineHandler>, opts: BindSubmarineOptions = {}): InProcessToolSource {
+  const bound: InProcessTool[] = [];
+  for (const def of SUBMARINE_TOOLS) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindSubmarineTools: 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 ?? 'submarine', bound);
+}

package/src/testing/mock-wallet.ts

@@ -11,6 +11,7 @@
 
 import { bindWalletTools, type WalletHandler } from '../wallet/contract.js';
 import { ToolRegistry } from '../tools/registry.js';
+import { bindSubmarineTools, type SubmarineHandler } from '../submarine/contract.js';
 
 export interface SendRecord {
   tool: string;
@@ -28,6 +29,8 @@ export interface MockWalletOptions {
   assets?: Record<string, number>;
   /** Free colored UTXOs on the RLN node (issuance / RGB receive consume one). */
   utxos?: number;
+  /** Liquid balances in smallest units (L-USDT: 8 decimals, L-BTC: sats) for submarine swaps. */
+  liquid?: { 'L-USDT': number; 'L-BTC': number };
 }
 export interface MockRgbAsset {
   asset_id: string;
@@ -52,23 +55,31 @@ export class MockWallet {
   assets: Record<string, number>;
   contacts: MockContact[];
   utxos: number;
+  liquid: { 'L-USDT': number; 'L-BTC': number };
+  /** Submarine swaps opened against the mock /v2 maker, by id. */
+  submarineSwaps: Record<string, { from: 'L-USDT' | 'L-BTC'; invoice: string; expected: number; funded: boolean }> = {};
   /** RGB assets the node knows about (seeded USDT/XAUT + anything issued). */
   rgbAssets: MockRgbAsset[];
   transfers: MockTransfer[] = [];
   sends: SendRecord[] = [];
 
+  private readonly opts: MockWalletOptions;
+
   constructor(o: MockWalletOptions = {}) {
+    this.opts = o;
     this.priceUsd = o.priceUsd ?? 65_000;
     this.failRoute = o.failRoute ?? false;
-    this.balances = o.balances ?? { spark: 500_000, rln: 300_000, arkade: 200_000 };
-    this.assets = o.assets ?? { USDT: 25_000_000, XAUT: 0 };
-    this.contacts = o.contacts ?? [
+    // Copies: the wallet mutates its state, and reset() rebuilds from `o`.
+    this.balances = { ...(o.balances ?? { spark: 500_000, rln: 300_000, arkade: 200_000 }) };
+    this.assets = { ...(o.assets ?? { USDT: 25_000_000, XAUT: 0 }) };
+    this.contacts = o.contacts ? [...o.contacts] : [
       { name: 'bob', ln_address: 'bob@kaleidoswap.com' },
       { name: 'alice', ln_address: 'alice@kaleidoswap.com' },
       { name: 'john', ln_address: 'john.smith@kaleidoswap.com' },
       { name: 'john', ln_address: 'john.doe@kaleidoswap.com' }, // ambiguous on purpose
     ];
     this.utxos = o.utxos ?? 5;
+    this.liquid = { ...(o.liquid ?? { 'L-USDT': 100 * 1e8, 'L-BTC': 200_000 }) };
     this.rgbAssets = Object.keys(this.assets).map((ticker) => ({
       asset_id: mockAssetId(ticker),
       ticker,
@@ -112,9 +123,9 @@ export class MockWallet {
   totalSats(): number {
     return this.balances.spark + this.balances.rln + this.balances.arkade;
   }
+  /** Back to the constructor state: balances, contacts, UTXOs, issued assets, history. */
   reset(): void {
-    this.sends = [];
-    this.transfers = [];
+    Object.assign(this, new MockWallet(this.opts));
   }
 
   private send(tool: string, rec: { to: string; amount_sats?: number; asset?: string; amount?: number }) {
@@ -196,10 +207,56 @@ export class MockWallet {
     };
   }
 
+  /**
+   * The KaleidoSwap /v2 submarine contract against a toy maker: 0.5% fee, the
+   * invoice amount read from its BOLT11 human-readable part, L-USDT at `priceUsd`.
+   */
+  submarineHandlers(): Record<string, SubmarineHandler> {
+    return {
+      kaleidoswap_submarine_pairs: async () => ({
+        pairs: [
+          { from: 'L-USDT', to: 'BTC', fees: { percentage: 0.5 }, limits: { minimal: 10 * 1e8, maximal: 1_000 * 1e8 } },
+          { from: 'L-BTC', to: 'BTC', fees: { percentage: 0.5 }, limits: { minimal: 10_000, maximal: 1_000_000 } },
+        ],
+      }),
+      kaleidoswap_submarine_create: async ({ invoice, from_asset }) => {
+        const from = (from_asset ?? 'L-USDT') as 'L-USDT' | 'L-BTC';
+        if (from !== 'L-USDT' && from !== 'L-BTC') throw new Error(`Unsupported from_asset "${String(from_asset)}".`);
+        const sats = bolt11Sats(String(invoice));
+        if (sats == null) throw new Error('invalid_invoice: the invoice must be BOLT11 with an amount.');
+        const withFee = sats * 1.005;
+        const expected = Math.ceil(from === 'L-USDT' ? (withFee / 1e8) * this.priceUsd * 1e8 : withFee);
+        const id = `sub${Object.keys(this.submarineSwaps).length + 1}`;
+        this.submarineSwaps[id] = { from, invoice: String(invoice), expected, funded: false };
+        return { swap_id: id, from_asset: from, expected_amount: String(expected), lockup_address: `tlq1qmock${id}` };
+      },
+      kaleidoswap_submarine_fund: async ({ swap_id }) => {
+        const swap = this.submarineSwaps[String(swap_id)];
+        if (!swap) throw new Error(`No submarine swap "${String(swap_id)}" was created by this server.`);
+        if (swap.funded) throw new Error(`Swap ${String(swap_id)} is already funded.`);
+        if (this.liquid[swap.from] < swap.expected) throw new Error(`Insufficient ${swap.from} balance.`);
+        this.liquid[swap.from] -= swap.expected;
+        swap.funded = true;
+        this.sends.push({ tool: 'kaleidoswap_submarine_fund', to: swap.invoice, asset: swap.from, amount: swap.expected });
+        return { funded: true, swap_id, asset: swap.from, amount: String(swap.expected), txid: `mocktx${String(swap_id)}` };
+      },
+      kaleidoswap_submarine_status: async ({ swap_id }) => {
+        const swap = this.submarineSwaps[String(swap_id)];
+        if (!swap) throw new Error(`invalid_swap_id: "${String(swap_id)}" is not a swap id`);
+        const status = swap.funded ? 'transaction.claimed' : 'swap.created';
+        return { swap_id, status, done: swap.funded, failed: false, funded: swap.funded };
+      },
+    };
+  }
+
   /** Bind the contract tools to this wallet (optionally overriding some — e.g. to inject). */
   registry(overrides?: Partial<Record<string, WalletHandler>>): ToolRegistry {
     const h = { ...this.handlers(), ...(overrides ?? {}) } as Record<string, WalletHandler>;
-    return new ToolRegistry([bindWalletTools(h, { layers: ['spark', 'rln', 'arkade', 'core'], allowMissing: true })]);
+    const sub = { ...this.submarineHandlers(), ...(overrides ?? {}) } as Record<string, SubmarineHandler>;
+    return new ToolRegistry([
+      bindWalletTools(h, { layers: ['spark', 'rln', 'arkade', 'core'], allowMissing: true }),
+      bindSubmarineTools(sub, { allowMissing: true }),
+    ]);
   }
 }
 
@@ -209,3 +266,13 @@ function mockAssetId(ticker: string): string {
   for (const c of ticker) h = (h * 31 + c.charCodeAt(0)) >>> 0;
   return `rgb:mock-${ticker.toLowerCase()}-${h.toString(36)}`;
 }
+
+/** Amount in sats from a BOLT11 human-readable part ("lntbs10u…" → 1000), or null. */
+function bolt11Sats(invoice: string): number | null {
+  const m = invoice.toLowerCase().match(/^ln(?:bcrt|tbs|bc|tb)(\d+)([munp])?1/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const mult = { m: 1e5, u: 100, n: 0.1, p: 0.0001 }[m[2] ?? ''] ?? 1e8;
+  const sats = n * mult;
+  return sats >= 1 ? Math.round(sats) : null;
+}