@kaleidorg/mind 0.9.0 → 0.10.1

package/src/kaleidoswap/contract.ts

@@ -70,14 +70,16 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
 
   t('market',
     'kaleidoswap_get_quote',
-    'Get an executable quote for swapping a specific amount on one pair. Returns a quote id (use it with atomic_init), the expected receive amount, fees, slippage, and how long the quote is valid for. Re-quote rather than reusing a stale id.',
+    'Get an executable quote for one pair. Amounts are DISPLAY units (0.0005 = 0.0005 BTC = 50,000 sats). Give exactly one of from_amount (sell a fixed input) or to_amount (buy a fixed output). Returns rfq_id, from_asset/to_asset with amount_display and amount_raw, price and expires_at (~60s).',
     {
-      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_id: { type: 'string', description: "Asset to sell: ticker ('BTC', 'USDT') or RGB id ('rgb:…')." },
+      to_asset_id:   { type: 'string', description: "Asset to buy: ticker ('USDT', 'BTC') or RGB id ('rgb:…')." },
+      from_layer:    { type: 'string', description: "Optional: 'BTC_LN', 'RGB_LN', 'BTC_SPARK'. Derived from the asset when omitted." },
+      to_layer:      { type: 'string', description: "Optional: 'RGB_LN', 'BTC_LN', 'BTC_SPARK'. Derived from the asset when omitted." },
+      from_amount:   { type: 'number', description: 'Amount to SELL in display units (e.g. 0.001 BTC, 10 USDT).' },
+      to_amount:     { type: 'number', description: 'Amount to BUY in display units (e.g. 10 USDT).' },
     },
-    ['from_asset', 'to_asset', 'amount']),
+    ['from_asset_id', 'to_asset_id']),
 
   t('market',
     'kaleidoswap_get_nodeinfo',
@@ -86,30 +88,36 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
   // ─── 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.",
+    'Start an atomic swap from a fresh quote. SPEND: confirmation-gated. Pass the quote rfq_id, both asset ids and the quote legs\' amount_raw values unchanged. Returns swapstring, payment_hash and access_token (keep it for status).',
     {
-      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." },
+      rfq_id:          { type: 'string', description: 'rfq_id from kaleidoswap_get_quote.' },
+      from_asset_id:   { type: 'string', description: 'from_asset.asset_id from the quote.' },
+      from_amount_raw: { type: 'integer', description: 'from_asset.amount_raw from the quote, unchanged.' },
+      to_asset_id:     { type: 'string', description: 'to_asset.asset_id from the quote.' },
+      to_amount_raw:   { type: 'integer', description: 'to_asset.amount_raw from the quote, unchanged.' },
     },
-    ['quote_id', 'receive_invoice'],
+    ['rfq_id', 'from_asset_id', 'from_amount_raw', 'to_asset_id', 'to_amount_raw'],
     /* 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.",
+    'Confirm the swap after rln_atomic_taker whitelisted the swapstring. SPEND: confirmation-gated. taker_pubkey is the pubkey from rln_get_node_info.',
     {
-      atomic_id: { type: 'string', description: 'The atomic id from kaleidoswap_atomic_init.' },
+      swapstring:   { type: 'string', description: 'swapstring from kaleidoswap_atomic_init.' },
+      taker_pubkey: { type: 'string', description: 'Node pubkey from rln_get_node_info.' },
+      payment_hash: { type: 'string', description: 'payment_hash from kaleidoswap_atomic_init.' },
     },
-    ['atomic_id'],
+    ['swapstring', 'taker_pubkey', 'payment_hash'],
     /* 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.',
+    'Poll an atomic swap by payment_hash: Waiting → Pending → Succeeded | Expired | Failed.',
     {
-      atomic_id: { type: 'string', description: 'The atomic id from kaleidoswap_atomic_init.' },
+      payment_hash: { type: 'string', description: 'payment_hash from kaleidoswap_atomic_init.' },
+      access_token: { type: 'string', description: 'access_token from kaleidoswap_atomic_init, when the host needs it.' },
     },
-    ['atomic_id']),
+    ['payment_hash']),
 
   // ─── liquidity (buy a NEW channel pre-loaded with an asset — onboarding) ──
   t('liquidity',
@@ -157,6 +165,46 @@ export function kaleidoswapTools(
   return KALEIDOSWAP_TOOLS.filter((x) => groups.has(x.group));
 }
 
+const isBtc = (asset: unknown) => typeof asset === 'string' && /^(btc|sats?)$/i.test(asset.trim());
+
+/**
+ * Map kaleido-mcp argument names onto the pre-0.9 contract names (and back), so
+ * one call shape works on every surface and older host handlers keep working.
+ * Canonical names win; legacy names are only filled in when absent. The legacy
+ * quote `amount` is sats for BTC and display units otherwise.
+ */
+export function normalizeKaleidoswapArgs(name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const a: Record<string, unknown> = { ...args };
+  const alias = (canonical: string, legacy: string) => {
+    if (a[canonical] == null && a[legacy] != null) a[canonical] = a[legacy];
+    if (a[legacy] == null && a[canonical] != null) a[legacy] = a[canonical];
+  };
+  if (name === 'kaleidoswap_get_quote') {
+    if (a.from_asset_id == null && a.from_asset != null) a.from_asset_id = a.from_asset;
+    if (a.to_asset_id == null && a.to_asset != null) a.to_asset_id = a.to_asset;
+    if (a.from_amount == null && a.to_amount == null && a.amount != null) {
+      const side = a.amount_side === 'to' || a.side === 'buy' ? 'to' : 'from';
+      const asset = side === 'to' ? a.to_asset_id : a.from_asset_id;
+      const display = isBtc(asset) ? Number(a.amount) / 1e8 : Number(a.amount);
+      a[side === 'to' ? 'to_amount' : 'from_amount'] = display;
+    }
+    a.from_asset ??= a.from_asset_id;
+    a.to_asset ??= a.to_asset_id;
+    if (a.amount == null) {
+      const toSide = a.from_amount == null && a.to_amount != null;
+      const display = Number(toSide ? a.to_amount : a.from_amount);
+      const asset = toSide ? a.to_asset_id : a.from_asset_id;
+      if (Number.isFinite(display)) a.amount = isBtc(asset) ? Math.round(display * 1e8) : display;
+      if (toSide) a.amount_side = 'to';
+    }
+  } else if (name === 'kaleidoswap_atomic_init') {
+    alias('rfq_id', 'quote_id');
+  } else if (name === 'kaleidoswap_atomic_execute' || name === 'kaleidoswap_atomic_status') {
+    alias('payment_hash', 'atomic_id');
+  }
+  return a;
+}
+
 /** A handler bound to one contract tool. Args validated by JSON schema upstream. */
 export type KaleidoswapHandler = (args: Record<string, unknown>) => Promise<unknown>;
 
@@ -199,7 +247,7 @@ export function bindKaleidoswapTools(
       description: def.description,
       parameters: def.parameters,
       requiresConfirmation: def.requiresConfirmation,
-      handler,
+      handler: (args) => handler(normalizeKaleidoswapArgs(def.name, args)),
     });
   }
   return new InProcessToolSource(opts.id ?? 'kaleidoswap', bound);

package/src/kaleidoswap/index.ts

@@ -3,6 +3,7 @@ export {
   KALEIDOSWAP_TOOLS,
   KALEIDOSWAP_SPEND_TOOLS,
   isKaleidoswapSpendTool,
+  normalizeKaleidoswapArgs,
   getKaleidoswapTool,
   kaleidoswapTools,
   bindKaleidoswapTools,

package/src/qvac/parse.test.ts

@@ -126,3 +126,17 @@ describe('finalToTurn', () => {
     });
   });
 });
+
+describe('extractTextToolCalls: skill example notation', () => {
+  it('recovers a reply that is only `tool_name {json}`', () => {
+    expect(extractTextToolCalls('`rln_create_ln_invoice {"amount_sats":5000}`')).toEqual([
+      { name: 'rln_create_ln_invoice', arguments: { amount_sats: 5000 } },
+    ]);
+    expect(extractTextToolCalls('rln_list_assets {}')).toEqual([{ name: 'rln_list_assets', arguments: {} }]);
+  });
+
+  it('ignores prose that mentions a call', () => {
+    expect(extractTextToolCalls('I would call rln_list_assets {} next.')).toEqual([]);
+    expect(extractTextToolCalls('listassets {"a":1}')).toEqual([]);
+  });
+});

package/src/qvac/parse.ts

@@ -136,6 +136,17 @@ export function extractTextToolCalls(
     if (c) calls.push(c);
   }
   if (calls.length) return calls;
+  // The whole reply is one call in the skills' example notation,
+  // `tool_name {"arg": 1}` (models without native tool calling copy it).
+  const bare = text.trim().match(/^`?([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\s*(\{[\s\S]*\})`?$/);
+  if (bare) {
+    try {
+      const args = JSON.parse(bare[2]!);
+      if (args && typeof args === 'object' && !Array.isArray(args)) return [{ name: bare[1]!, arguments: args }];
+    } catch {
+      /* not a call */
+    }
+  }
   // No tags — accept a bare tool-call object only at the very start of the
   // text (so we don't misread JSON the model is merely talking about).
   if (/^\s*\{?\s*"name"\s*:/i.test(text)) {

package/src/qvac/provider.test.ts

@@ -123,6 +123,39 @@ describe('createQvacProvider.runTurn', () => {
     expect(deleted).toEqual([{ kvCacheKey: 'run-1' }]);
   });
 
+  it('retries a turn without reasoning when the tool grammar rejects the inserted </think>', async () => {
+    const calls: any[] = [];
+    const fn = (params: any) => {
+      calls.push(params);
+      if (calls.length === 1) throw new Error('Unexpected empty grammar stack after accepting piece: </think> (248069)');
+      return { requestId: 'req-2', events: (async function* () {})(), final: Promise.resolve({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } }) };
+    };
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1', maxThinkingTokens: 128 });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(out.text).toBe('ok');
+    expect(calls.map((c) => c.generationParams?.reasoning_budget)).toEqual([128, 0]);
+    await expect(
+      createQvacProvider({ completion: (() => { throw new Error('boom'); }) as any, cancel: noopCancel, getModelId: () => 'm1' })
+        .runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] }),
+    ).rejects.toThrow('boom');
+  });
+
+  it("retries without tool_choice when the chat template can't force a tool call", async () => {
+    const calls: any[] = [];
+    const fn = (params: any) => {
+      calls.push(params);
+      if (params.generationParams?.tool_choice) {
+        throw new Error('[TextLlm] generationParams.tool_choice demanded a tool call, but the chat template did not render the tool definitions');
+      }
+      return { requestId: 'r', events: (async function* () {})(), final: Promise.resolve({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } }) };
+    };
+    const tool = { name: 'get_balance', description: 'b', parameters: { type: 'object', properties: {} } };
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [tool as any], toolChoice: 'required' });
+    expect(out.text).toBe('ok');
+    expect(calls.map((c) => c.generationParams?.tool_choice)).toEqual(['required', undefined]);
+  });
+
   it('keeps the reasoning budget below the output cap', async () => {
     const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
     const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1', defaultMaxTokens: 512, maxThinkingTokens: 512 });

package/src/qvac/provider.ts

@@ -76,11 +76,26 @@ export interface QvacTurnInput extends TurnInput {
   onStats?: (stats: QvacTurnStats) => void;
 }
 
-export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
-  return {
-    name: 'qvac',
+/**
+ * llama.cpp's tool-call grammar can reject the `</think>` it inserts when a
+ * reasoning budget runs out ("Unexpected empty grammar stack after accepting
+ * piece: </think>"), which aborts the turn.
+ */
+function isReasoningGrammarError(err: unknown): boolean {
+  return /empty grammar stack/i.test(err instanceof Error ? err.message : String(err));
+}
 
-    async runTurn(input: QvacTurnInput): Promise<TurnOutput> {
+/**
+ * Some chat templates (e.g. Llama 3.2 tool-calling 1B) don't render the tool
+ * definitions the way a forced `tool_choice` needs ("tool_choice demanded a
+ * tool call, but the chat template did not render the tool definitions").
+ */
+function isToolChoiceTemplateError(err: unknown): boolean {
+  return /did not render the tool definitions/i.test(err instanceof Error ? err.message : String(err));
+}
+
+export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
+  const runTurnOnce = async (input: QvacTurnInput): Promise<TurnOutput> => {
       const modelId = options.getModelId();
       if (!modelId) throw new Error('QVAC model not loaded');
 
@@ -192,6 +207,24 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         inference,
         ...(incomplete ? { incomplete: true } : {}),
       };
+  };
+
+  return {
+    name: 'qvac',
+
+    async runTurn(input: QvacTurnInput): Promise<TurnOutput> {
+      try {
+        return await runTurnOnce(input);
+      } catch (err) {
+        // Retry once without reasoning: no budget, so nothing to insert.
+        if (input.thinking !== 'off' && isReasoningGrammarError(err)) return runTurnOnce({ ...input, thinking: 'off' });
+        // Retry once without forcing a tool call; the model may still call one.
+        if (input.toolChoice && isToolChoiceTemplateError(err)) {
+          const { toolChoice: _forced, ...rest } = input;
+          return runTurnOnce(rest);
+        }
+        throw err;
+      }
     },
 
     async endSession(sessionKey: string): Promise<void> {

package/src/recipe/asset-send.ts

@@ -69,7 +69,7 @@ export const assetSendRecipe: Recipe = {
     tool: 'rln_send_asset',
     args: (ctx: RecipeContext) => {
       const contact = ctx.results.contact as { ln_address?: string } | undefined;
-      return { asset: ctx.slots.asset, amount: ctx.slots.amount, to: contact?.ln_address ?? ctx.slots.recipient };
+      return { asset_id: ctx.slots.asset, amount: ctx.slots.amount, recipient_id: contact?.ln_address ?? ctx.slots.recipient };
     },
   },
   summary: (ctx) => {

package/src/recipe/recipe.test.ts

@@ -257,7 +257,7 @@ describe('runRecipe — asset send', () => {
     const res = await runRecipe(assetSendRecipe, 'send 10 usdt to bob', { provider: approve, tools, onConfirm });
     expect(res.status).toBe('done');
     expect(onConfirm).toHaveBeenCalledOnce();
-    expect(sent[0]).toEqual({ asset: 'USDT', amount: 10, to: 'bob@x.com' });
+    expect(sent[0]).toEqual({ asset_id: 'USDT', amount: 10, recipient_id: 'bob@x.com' });
   });
 });
 

package/src/skills/catalog.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Skill catalog checks: every packaged skill must name real tools and every
+ * worked example must be a valid call, both against the in-app contracts and
+ * against kaleido-mcp (src/skills/mcp-tools.snapshot.json, refreshed with
+ * scripts/snapshot-mcp-tools.mjs).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ToolDef } from '../types.js';
+import { loadSkillsDir, packagedSkillsDir } from './loader.js';
+import { SkillRegistry } from './registry.js';
+import { selectAvailableSkill } from './select.js';
+import { createSkillReferenceToolSource } from './reference-source.js';
+import { WALLET_TOOLS } from '../wallet/contract.js';
+import { KALEIDOSWAP_TOOLS } from '../kaleidoswap/contract.js';
+import { LSPS1_TOOLS } from '../lsps1/contract.js';
+import { SUBMARINE_TOOLS } from '../submarine/contract.js';
+import { FLASHNET_TOOLS } from '../flashnet/contract.js';
+import { BITREFILL_TOOLS } from '../bitrefill/contract.js';
+import { createBtcMapToolSource } from '../knowledge/btc-map.js';
+import { createL402ToolSource } from '../tools/l402.js';
+import { createRagToolSource } from '../rag/tool.js';
+import type { Retriever } from '../rag/retriever.js';
+import { validateToolArgs } from '../guards.js';
+import { estimateTokens } from '../context/budget.js';
+
+interface SnapshotTool {
+  required: string[];
+  properties: Record<string, { type: string; description?: string }>;
+}
+
+const SKILLS_DIR = packagedSkillsDir();
+const skills = loadSkillsDir(SKILLS_DIR);
+const registry = new SkillRegistry(skills);
+
+const mcp: Record<string, SnapshotTool> = JSON.parse(
+  readFileSync(new URL('./mcp-tools.snapshot.json', import.meta.url), 'utf8'),
+).tools;
+
+const core = new Map<string, ToolDef>();
+for (const def of [
+  ...WALLET_TOOLS,
+  ...KALEIDOSWAP_TOOLS,
+  ...LSPS1_TOOLS,
+  ...SUBMARINE_TOOLS,
+  ...FLASHNET_TOOLS,
+  ...BITREFILL_TOOLS,
+  ...createBtcMapToolSource({}).listTools(),
+  ...createL402ToolSource({ payInvoice: async () => ({ preimage: '' }) }).listTools(),
+  ...createRagToolSource({} as Retriever).listTools(),
+  ...createSkillReferenceToolSource(registry).listTools(),
+] as ToolDef[]) core.set(def.name, def);
+
+/**
+ * Same name, different tool. kaleido-mcp keeps `spark_pay_invoice` as a legacy
+ * alias of `spark_pay_spark_invoice` (Spark invoices); its BOLT11 payer is
+ * `spark_pay_lightning_invoice`. The in-app `spark_pay_invoice` pays BOLT11, so
+ * skills that use it must require an in-app-only tool.
+ */
+const NAME_COLLISIONS = new Set(['spark_pay_invoice']);
+
+const mcpDef = (name: string): ToolDef => ({
+  name,
+  description: '',
+  parameters: { type: 'object', properties: mcp[name]!.properties, required: mcp[name]!.required },
+});
+
+function surfaces(name: string): Array<{ surface: string; def: ToolDef }> {
+  const out: Array<{ surface: string; def: ToolDef }> = [];
+  if (core.has(name)) out.push({ surface: 'core', def: core.get(name)! });
+  if (mcp[name] && !NAME_COLLISIONS.has(name)) out.push({ surface: 'kaleido-mcp', def: mcpDef(name) });
+  return out;
+}
+
+function props(def: ToolDef): string[] {
+  return Object.keys((def.parameters as { properties?: object }).properties ?? {});
+}
+
+function required(def: ToolDef): string[] {
+  return ((def.parameters as { required?: string[] }).required ?? []);
+}
+
+function frontmatterList(name: string, key: string): string[] {
+  const skill = skills.find((s) => s.name === name)!;
+  if (key === 'tools') return skill.tools ?? [];
+  return (skill.metadata?.[key] ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+}
+
+/** Every `tool_name {json}` call written in a skill or one of its references. */
+function exampleCalls(dir: string): Array<{ file: string; tool: string; json: string }> {
+  const files = [join(dir, 'SKILL.md')];
+  const refs = join(dir, 'references');
+  if (existsSync(refs)) files.push(...readdirSync(refs).filter((f) => f.endsWith('.md')).map((f) => join(refs, f)));
+  const out: Array<{ file: string; tool: string; json: string }> = [];
+  for (const file of files) {
+    for (const m of readFileSync(file, 'utf8').matchAll(/`([a-z][a-z0-9_]*) (\{[^`]*\})`/g)) {
+      if (core.has(m[1]!) || mcp[m[1]!]) out.push({ file, tool: m[1]!, json: m[2]! });
+    }
+  }
+  return out;
+}
+
+const isPlaceholder = (v: unknown) => typeof v === 'string' && /^<.*>$|…/.test(v);
+
+describe('skill catalog', () => {
+  it('ships skills', () => {
+    expect(skills.length).toBeGreaterThan(5);
+  });
+
+  it.each(skills.map((s) => [s.name]))('%s: every tool exists on a surface', (name) => {
+    const missing = [...frontmatterList(name, 'tools'), ...frontmatterList(name, 'requires-tools')]
+      .filter((t) => !core.has(t) && !mcp[t]);
+    expect(missing).toEqual([]);
+  });
+
+  it.each(skills.map((s) => [s.name]))('%s: requires-tools are in tools', (name) => {
+    const tools = new Set(frontmatterList(name, 'tools'));
+    expect(frontmatterList(name, 'requires-tools').filter((t) => !tools.has(t))).toEqual([]);
+  });
+
+  it.each(skills.map((s) => [s.name]))('%s: a colliding tool name is scoped to the app', (name) => {
+    const uses = frontmatterList(name, 'tools').some((t) => NAME_COLLISIONS.has(t));
+    if (!uses) return;
+    const req = frontmatterList(name, 'requires-tools');
+    expect(req.length > 0 && req.some((t) => core.has(t) && !mcp[t])).toBe(true);
+  });
+
+  it.each(skills.map((s) => [s.name, s.dir!]))('%s: examples are valid calls', (name, dir) => {
+    const scoped = new Set(frontmatterList(name, 'tools'));
+    const errors: string[] = [];
+    for (const call of exampleCalls(dir)) {
+      const where = `${call.file.slice(SKILLS_DIR.length)}: ${call.tool} ${call.json}`;
+      let args: Record<string, unknown>;
+      try {
+        args = JSON.parse(call.json);
+      } catch {
+        errors.push(`${where} — not JSON`);
+        continue;
+      }
+      if (call.file.endsWith('SKILL.md') && scoped.size && !scoped.has(call.tool)) {
+        errors.push(`${where} — tool not in the skill's tools`);
+      }
+      for (const { surface, def } of surfaces(call.tool)) {
+        const known = props(def);
+        for (const k of Object.keys(args)) if (!known.includes(k)) errors.push(`${where} — "${k}" unknown on ${surface}`);
+        for (const k of required(def)) if (args[k] == null) errors.push(`${where} — "${k}" required on ${surface}`);
+        const concrete = Object.fromEntries(Object.entries(args).filter(([, v]) => !isPlaceholder(v)));
+        const check = validateToolArgs(def, concrete);
+        for (const e of check.errors) if (!/is required/.test(e)) errors.push(`${where} — ${surface}: ${e}`);
+      }
+    }
+    expect(errors).toEqual([]);
+  });
+
+  it.each(skills.map((s) => [s.name]))('%s: tool names in the prose exist', (name) => {
+    const body = skills.find((s) => s.name === name)!.instructions;
+    const prefixed = /^(rln|wdk|kaleidoswap|kaleido_node|spark|flashnet|bitrefill|mpp|l402|liquid|arkade)_[a-z0-9_]+$/;
+    const unknown = [...body.matchAll(/`([a-z][a-z0-9_]*)[` ]/g)]
+      .map((m) => m[1]!)
+      .filter((w) => prefixed.test(w) && !core.has(w) && !mcp[w]);
+    expect([...new Set(unknown)]).toEqual([]);
+  });
+
+  it.each(skills.map((s) => [s.name]))('%s: body stays short', (name) => {
+    const skill = skills.find((s) => s.name === name)!;
+    expect(estimateTokens(skill.instructions)).toBeLessThanOrEqual(600);
+    expect(skill.description.length).toBeLessThanOrEqual(320);
+  });
+});
+
+describe('core contracts match kaleido-mcp', () => {
+  it('shared tool names take the same arguments', () => {
+    const errors: string[] = [];
+    for (const [name, def] of core) {
+      const m = mcp[name];
+      if (!m || NAME_COLLISIONS.has(name)) continue;
+      const mcpProps = Object.keys(m.properties);
+      const coreProps = props(def);
+      for (const p of coreProps) if (!mcpProps.includes(p)) errors.push(`${name}: "${p}" is not a kaleido-mcp argument`);
+      for (const r of m.required) if (!coreProps.includes(r)) errors.push(`${name}: kaleido-mcp requires "${r}"`);
+    }
+    expect(errors).toEqual([]);
+  });
+});
+
+describe('skill selection by surface', () => {
+  const mcpTools = Object.keys(mcp);
+  const inApp = [...core.keys()];
+
+  it.each([
+    ['Which RGB assets do I hold, and what are the balances?', 'rgb-lightning-node'],
+    ['Get a quote to swap 0.0005 BTC into USDT on KaleidoSwap.', 'kaleido-trading'],
+    ['Issue a token named Skill Test, ticker SKT, supply 1000, precision 0.', 'rgb-lightning-node'],
+    ['Send 1 QTWO to this RGB invoice: rgb:~/~/~/sig/any/1/utxob:test-recipient', 'rgb-lightning-node'],
+    ['Create a Lightning invoice for 5000 sats.', 'rgb-lightning-node'],
+    ["what's my balance?", 'rgb-lightning-node'],
+    ['buy 500k sats of inbound liquidity', 'channel-manager'],
+    ['unlock my node', 'kaleido-node'],
+    ['pay lntbs10u1pexample with L-USDT', 'submarine-swaps'],
+  ])('kaleido-mcp: %s → %s', (query, expected) => {
+    expect(selectAvailableSkill(registry, query, mcpTools)?.name).toBe(expected);
+  });
+
+  it.each([
+    ["what's my balance?", 'wallet-assistant'],
+    ['what is my spark balance', 'spark-wallet'],
+    ['swap 100k sats to USDB on flashnet', 'flashnet-swaps'],
+    ['buy a $25 amazon gift card', 'bitrefill'],
+    ['where can I spend sats in Turin', 'merchant-finder'],
+  ])('in-app: %s → %s', (query, expected) => {
+    expect(selectAvailableSkill(registry, query, inApp)?.name).toBe(expected);
+  });
+});