@kaleidorg/mind 0.7.0 → 0.8.1

package/src/qvac/provider.ts

@@ -24,6 +24,7 @@ import { toQvacTools } from './tools.js';
 
 type CompletionFn = typeof QvacSdk.completion;
 type CancelFn = typeof QvacSdk.cancel;
+type DeleteCacheFn = typeof QvacSdk.deleteCache;
 
 export interface QvacProviderOptions {
   /** The SDK's `completion` (injected — see module docs). */
@@ -41,12 +42,21 @@ export interface QvacProviderOptions {
   /** Default max output tokens — caps a turn so it can't ramble. Omit for uncapped. */
   defaultMaxTokens?: number;
   /**
-   * Cap `<think>` reasoning at this many TOKENS (not seconds — tok/s varies, and
-   * the SDK has no numeric reasoning budget). When a turn's thinking exceeds it,
-   * the run is cancelled and a short fallback is returned instead of hanging on
-   * "Thinking…". Omit for unlimited reasoning.
+   * Cap `<think>` reasoning at this many TOKENS (not seconds — tok/s varies).
+   * Sent as the SDK's `reasoning_budget`, so the model closes its reasoning and
+   * answers. If the stream still runs well past it, the run is cancelled and a
+   * short fallback is returned instead of hanging on "Thinking…". Omit for
+   * unlimited reasoning.
    */
   maxThinkingTokens?: number;
+  /**
+   * Keep each agentic run in a QVAC KV-cache session (`kvCache: sessionKey`),
+   * so calls after the first send only the new message instead of re-reading
+   * the whole prompt. Needs `deleteCache` to drop the session at the end.
+   */
+  sessionCache?: boolean;
+  /** The SDK's `deleteCache` (injected); used with `sessionCache`. */
+  deleteCache?: DeleteCacheFn;
   /** Stream the model's `<think>` reasoning, when a host wants to surface it. */
   onThinking?: (token: string) => void;
   /**
@@ -93,13 +103,23 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
       // when a value is set so a host that passes neither keeps SDK defaults.
       const temp = input.temperature ?? options.defaultTemperature;
       const predict = input.maxTokens ?? options.defaultMaxTokens;
-      const generationParams =
-        temp !== undefined || predict !== undefined
-          ? {
-              ...(temp !== undefined ? { temp } : {}),
-              ...(predict !== undefined ? { predict } : {}),
-            }
-          : undefined;
+      // A thinking budget at or above the output cap never binds: the model can
+      // spend the whole turn reasoning and return no answer. Keep half for it.
+      const thinkingCap = input.thinking === 'off' ? 0 : (input.maxThinkingTokens ?? options.maxThinkingTokens);
+      const maxThinkingTokens =
+        thinkingCap !== undefined && predict !== undefined && thinkingCap >= predict
+          ? Math.floor(predict / 2)
+          : thinkingCap;
+      // `tool_choice` is only meaningful with tools; the SDK rejects a named
+      // choice that isn't among them.
+      const toolChoice = tools && input.toolChoice ? input.toolChoice : undefined;
+      const generationParamsRaw = {
+        ...(temp !== undefined ? { temp } : {}),
+        ...(predict !== undefined ? { predict } : {}),
+        ...(maxThinkingTokens !== undefined ? { reasoning_budget: maxThinkingTokens } : {}),
+        ...(toolChoice ? { tool_choice: toolChoice } : {}),
+      };
+      const generationParams = Object.keys(generationParamsRaw).length ? generationParamsRaw : undefined;
 
       const run = options.completion({
         modelId,
@@ -108,6 +128,7 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         // Split `<think>` into separate thinkingDelta events so reasoning never
         // pollutes the visible answer.
         captureThinking: true,
+        ...(options.sessionCache && input.sessionKey ? { kvCache: input.sessionKey } : {}),
         ...(generationParams ? { generationParams } : {}),
         ...(tools ? { tools } : {}),
       } as unknown as Parameters<CompletionFn>[0]);
@@ -129,11 +150,13 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         }
       }
 
-      const maxThinkingTokens = input.maxThinkingTokens ?? options.maxThinkingTokens;
       const result = await consumeRun(run, {
         onToken: input.onToken,
         onThinking: input.onThinking ?? options.onThinking,
-        maxThinkingTokens,
+        // Backstop only: the SDK enforces the budget itself, and our count is a
+        // char-based estimate, so leave headroom before cancelling.
+        maxThinkingTokens:
+          maxThinkingTokens === undefined ? undefined : Math.ceil(maxThinkingTokens * 1.25) + 32,
         // Cancel the in-flight run the moment the thinking budget is blown — the
         // SDK keeps generating otherwise. Fire-and-forget; `final` then resolves.
         onThinkingBudgetExceeded: () => {
@@ -175,15 +198,28 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         ...(result.stopReason ? { stopReason: result.stopReason } : {}),
       };
 
+      const incomplete =
+        !result.text && result.toolCalls.length === 0 && (result.thinkingBudgetExceeded || !!result.truncated);
       return {
         text,
         rawContent: result.rawContent,
         toolCalls: result.toolCalls,
+        ...(result.toolErrors ? { toolErrors: result.toolErrors } : {}),
         requestId: result.requestId,
         inference,
+        ...(incomplete ? { incomplete: true } : {}),
       };
     },
 
+    async endSession(sessionKey: string): Promise<void> {
+      if (!options.sessionCache || !options.deleteCache) return;
+      try {
+        await options.deleteCache({ kvCacheKey: sessionKey });
+      } catch (err) {
+        console.warn('[qvac] deleteCache failed:', err);
+      }
+    },
+
     async cancel(requestId: string): Promise<void> {
       // The cancel only lands once the server has begun the request; a same-tick
       // cancel may race the begin and is logged as a no-match by the SDK.

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