@kaleidorg/mind 0.6.4 → 0.8.0

package/src/recipe/issue-asset.ts

@@ -0,0 +1,123 @@
+/**
+ * "Issue an RGB asset" recipe — the hackathon one-liner:
+ *
+ *   "issue 1000 TICKET tokens called Hackathon Ticket"  → rln_issue_asset 🔒
+ *   "mint an NFT called Genesis Badge"                  → rln_issue_asset 🔒 (UDA)
+ *   "crea 500 token CAFE chiamati Caffè Club"           → rln_issue_asset 🔒
+ *
+ * No intermediate steps: the plan is a single gated call, so the recipe's job
+ * is the slot extraction (name / ticker / supply / schema) and a deterministic
+ * readback — exactly the part a 0.6B model gets wrong. Opt-in: register via
+ * `Funnel.recipes` on hosts that bind `rln_issue_asset`.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+
+// 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']);
+
+// "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 {
+  // "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*[:=]?\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+/));
+  for (const w of t.match(/\b[A-Z][A-Z0-9]{1,7}\b/g) ?? []) {
+    if (!STOPWORDS.has(w) && !nameWords.has(w)) return w;
+  }
+  return undefined;
+}
+
+/** Ticker fallback from the name: "Hackathon Ticket" → "HACKATHO". */
+function tickerFromName(name: string): string {
+  return name.replace(/[^A-Za-z0-9]/g, '').toUpperCase().slice(0, 8);
+}
+
+export function extractIssueAsset(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  if (!VERB.test(t) || !NOUN.test(t) || NOT_ISSUE.test(t)) return 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, name);
+  if (!ticker && !name) return null;
+  return { name: name ?? ticker, ticker, amount, schema };
+}
+
+export const issueAssetRecipe: Recipe = {
+  name: 'issue-asset',
+  description: 'Issue a new RGB asset (token, ticket, NFT) on the RLN node — one confirmation-gated call.',
+  match: (t) => VERB.test(t) && NOUN.test(t) && !NOT_ISSUE.test(t),
+  triggers: ['issue', 'mint', 'create token', 'launch token', 'nft'],
+  slots: [
+    { name: 'name', type: 'string', description: 'Asset name, e.g. "Hackathon Ticket"', required: true },
+    { name: 'ticker', type: 'string', description: 'Uppercase ticker, up to 8 chars, e.g. "TICKET"' },
+    { name: 'amount', type: 'number', description: 'Total supply in whole units (1 for an NFT)', required: true },
+    { name: 'schema', type: 'string', description: 'NIA for a fungible token, UDA for a unique NFT' },
+  ],
+  extract: extractIssueAsset,
+  confident: (s) => !!(s.ticker || s.name) && Number(s.amount) > 0,
+  steps: [],
+  final: {
+    tool: 'rln_issue_asset',
+    args: (ctx: RecipeContext) => {
+      const name = String(ctx.slots.name ?? ctx.slots.ticker);
+      const ticker = String(ctx.slots.ticker ?? tickerFromName(name)).toUpperCase();
+      const schema = ctx.slots.schema === 'UDA' ? 'UDA' : 'NIA';
+      return { name, ticker, amount: schema === 'UDA' ? 1 : Number(ctx.slots.amount), schema };
+    },
+  },
+  summary: (ctx, final) => {
+    // wdk/kaleido MCP return `asset_id` flat; the raw node API nests it under `asset`.
+    const r = final as { asset_id?: string; asset?: { asset_id?: string } } | undefined;
+    const id = r?.asset_id ?? r?.asset?.asset_id;
+    const what = ctx.slots.schema === 'UDA' ? `unique asset ${ctx.slots.ticker ?? ctx.slots.name}` : `${ctx.slots.amount} ${ctx.slots.ticker ?? ctx.slots.name}`;
+    return id ? `Issued ${what}. Asset id: ${id}` : `Issued ${what}.`;
+  },
+};

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/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @kaleidorg/mind/testing — build and demo an agent with no node, no funds and
+ * no model: a stateful mock wallet bound to the canonical contract, plus a
+ * scripted provider.
+ *
+ *   import { MockWallet, scriptedProvider } from '@kaleidorg/mind/testing';
+ *   const wallet = new MockWallet();
+ *   const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry(), … });
+ */
+
+export { MockWallet } from './mock-wallet.js';
+export type { MockWalletOptions, MockContact, MockRgbAsset, MockTransfer, SendRecord } from './mock-wallet.js';
+export { scriptedProvider } from './scripted-provider.js';
+export type { ScriptedTurn } from './scripted-provider.js';