@kaleidorg/mind 0.6.4 → 0.8.0

package/src/guards.ts

@@ -0,0 +1,299 @@
+/**
+ * Agent guards — deterministic checks around the model's tool use, so a small
+ * local model can't turn a bad tool call into a bad user experience:
+ *
+ *  - validateToolArgs: check a call against the tool's JSON Schema (or Zod
+ *    schema) before it reaches the confirmation gate.
+ *  - findUngroundedPaymentData: payment requests/addresses in a reply that no
+ *    tool returned and the user never typed — i.e. made up by the model.
+ *  - detectWalletAction / hasCapableTool: refuse a wallet action up front when
+ *    no tool in scope can perform it.
+ */
+
+import type { ToolDef } from './types.js';
+
+type Obj = Record<string, any>;
+
+export interface ArgValidation {
+  ok: boolean;
+  /** Arguments with numeric/boolean strings coerced to the schema's type. */
+  args: Record<string, unknown>;
+  errors: string[];
+}
+
+function isZodLike(p: unknown): p is { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: any } } {
+  return !!p && typeof p === 'object' && typeof (p as Obj).safeParse === 'function';
+}
+
+function schemaType(s: Obj): string | undefined {
+  if (Array.isArray(s.type)) return s.type.find((t: unknown) => t !== 'null');
+  if (typeof s.type === 'string') return s.type;
+  for (const alt of [...(s.anyOf ?? []), ...(s.oneOf ?? [])]) {
+    if (alt && typeof alt === 'object' && alt.type !== 'null') return schemaType(alt);
+  }
+  return undefined;
+}
+
+function checkValue(key: string, value: unknown, s: Obj): { value: unknown; error?: string } {
+  const type = schemaType(s);
+  let v = value;
+  if (type === 'number' || type === 'integer') {
+    if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) v = Number(v);
+    if (typeof v !== 'number' || !Number.isFinite(v)) return { value, error: `"${key}" must be a finite number` };
+    if (type === 'integer' && !Number.isInteger(v)) return { value, error: `"${key}" must be an integer` };
+    if (typeof s.minimum === 'number' && v < s.minimum) return { value, error: `"${key}" must be ≥ ${s.minimum}` };
+    if (typeof s.maximum === 'number' && v > s.maximum) return { value, error: `"${key}" must be ≤ ${s.maximum}` };
+  } else if (type === 'boolean') {
+    if (typeof v === 'string' && /^(true|false)$/i.test(v.trim())) v = v.trim().toLowerCase() === 'true';
+    if (typeof v !== 'boolean') return { value, error: `"${key}" must be true or false` };
+  } else if (type === 'string') {
+    if (typeof v !== 'string') return { value, error: `"${key}" must be a string` };
+    if (typeof s.pattern === 'string' && !new RegExp(s.pattern).test(v)) {
+      return { value, error: `"${key}" does not match the expected format` };
+    }
+  } else if (type === 'array') {
+    if (!Array.isArray(v)) return { value, error: `"${key}" must be an array` };
+  } else if (type === 'object') {
+    if (!v || typeof v !== 'object' || Array.isArray(v)) return { value, error: `"${key}" must be an object` };
+  }
+  if (Array.isArray(s.enum) && !s.enum.includes(v)) {
+    return { value, error: `"${key}" must be one of ${s.enum.map((e: unknown) => JSON.stringify(e)).join(', ')}` };
+  }
+  return { value: v };
+}
+
+/** Tool-specific rules the published schemas can't express (conditional requirements). */
+const SEMANTIC_RULES: Record<string, (a: Record<string, unknown>) => string[]> = {
+  rln_issue_asset: (a) => {
+    const errors: string[] = [];
+    const schema = String(a.schema ?? 'NIA').toUpperCase();
+    if (schema !== 'UDA' && a.amount == null) errors.push('"amount" (total supply) is required for NIA and CFA assets');
+    if (schema !== 'CFA') {
+      if (a.ticker == null) errors.push('"ticker" is required for NIA and UDA assets');
+      else if (!/^[A-Z0-9]{1,8}$/.test(String(a.ticker))) errors.push('"ticker" must be 1–8 uppercase letters or digits');
+    }
+    if (typeof a.amount === 'number' && a.amount <= 0) errors.push('"amount" must be greater than 0');
+    return errors;
+  },
+};
+SEMANTIC_RULES.wdk_issue_asset = SEMANTIC_RULES.rln_issue_asset!;
+
+/**
+ * Validate (and lightly coerce) a tool call's arguments against its schema.
+ * Unknown schema shapes pass through unchanged.
+ */
+export function validateToolArgs(def: Pick<ToolDef, 'name' | 'parameters'>, rawArgs: unknown): ArgValidation {
+  const args: Record<string, unknown> =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? { ...(rawArgs as Obj) } : {};
+  if (rawArgs != null && (typeof rawArgs !== 'object' || Array.isArray(rawArgs))) {
+    return { ok: false, args, errors: ['arguments must be a JSON object'] };
+  }
+  const p = def.parameters as Obj | undefined;
+  const errors: string[] = [];
+
+  if (isZodLike(p)) {
+    const r = p.safeParse(args);
+    if (!r.success) {
+      const issues: Obj[] = r.error?.issues ?? [];
+      errors.push(...(issues.length
+        ? issues.map((i) => `${(i.path ?? []).join('.') || 'arguments'}: ${i.message}`)
+        : ['arguments do not match the tool schema']));
+    }
+  } else if (p && typeof p === 'object' && (p.properties || p.required)) {
+    const props: Obj = p.properties ?? {};
+    for (const key of Array.isArray(p.required) ? p.required : []) {
+      if (args[key] == null || args[key] === '') errors.push(`"${key}" is required`);
+    }
+    for (const [key, value] of Object.entries(args)) {
+      const s = props[key];
+      if (value == null) continue;
+      if (!s) {
+        if (p.additionalProperties === false) errors.push(`unknown argument "${key}"`);
+        continue;
+      }
+      const r = checkValue(key, value, s);
+      if (r.error) errors.push(r.error);
+      else args[key] = r.value;
+    }
+  }
+
+  for (const [key, value] of Object.entries(args)) {
+    if (typeof value === 'number' && !Number.isFinite(value)) errors.push(`"${key}" must be a finite number`);
+  }
+  const rule = SEMANTIC_RULES[def.name];
+  if (rule && errors.length === 0) errors.push(...rule(args));
+  return { ok: errors.length === 0, args, errors: [...new Set(errors)] };
+}
+
+/** Payment requests and addresses a model must never make up. */
+const PAYMENT_DATA: Array<{ kind: string; re: RegExp }> = [
+  { kind: 'Lightning invoice', re: /\bln(?:bc|tb|bcrt|tbs|sb)[0-9a-z]{20,}\b/gi },
+  { kind: 'Lightning offer', re: /\blno1[0-9a-z]{20,}\b/gi },
+  { kind: 'LNURL', re: /\blnurl1[0-9a-z]{20,}\b/gi },
+  // An RGB invoice carries a "/" path or a utxob:/wvout: beneficiary; plain
+  // `rgb:` asset ids (contract ids) are not payment data.
+  { kind: 'RGB invoice', re: /\brgb:[^\s`'"<>)|]*(?:\/|utxob:|wvout:)[^\s`'"<>)|]*/gi },
+  { kind: 'blinded UTXO', re: /\butxob:[^\s`'"<>)|]{10,}/gi },
+  { kind: 'Spark address', re: /\bspark(?:rt|t|s)?1[0-9a-z]{20,}\b/gi },
+  { kind: 'Ark address', re: /\b(?:t?ark)1[0-9a-z]{20,}\b/gi },
+  { kind: 'Liquid address', re: /\b(?:lq1|ex1|tlq1|tex1|el1|ert1)[0-9a-z]{20,}\b/gi },
+  { kind: 'Bitcoin address', re: /\b(?:bc1|tb1|bcrt1)[0-9a-z]{20,}\b/gi },
+];
+
+export interface UngroundedItem {
+  kind: string;
+  value: string;
+}
+
+/**
+ * Payment strings in `text` that do not occur in any of the `sources` (tool
+ * results, user and history messages). Comparison is case-insensitive.
+ */
+export function findUngroundedPaymentData(text: string, sources: unknown[]): UngroundedItem[] {
+  if (!text) return [];
+  const haystack = sources
+    .map((s) => (typeof s === 'string' ? s : (() => { try { return JSON.stringify(s); } catch { return ''; } })()))
+    .join('\n')
+    .toLowerCase();
+  const out: UngroundedItem[] = [];
+  const seen = new Set<string>();
+  for (const { kind, re } of PAYMENT_DATA) {
+    for (const m of text.matchAll(re)) {
+      const value = m[0].replace(/[.,;:!?*]+$/, '');
+      const key = value.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      if (!haystack.includes(key)) out.push({ kind, value });
+    }
+  }
+  return out;
+}
+
+export function ungroundedReply(items: UngroundedItem[]): string {
+  const kinds = [...new Set(items.map((i) => i.kind))].join(' / ');
+  return `I can't give you that ${kinds}: no tool produced it in this conversation, and I won't make one up. ` +
+    'Make sure the wallet that should create it is connected, then ask again.';
+}
+
+const NUM = String.raw`(\d[\d,]*(?:\.\d+)?)`;
+const SATS = String.raw`(?:sats?|satoshis)`;
+// `[*_]*` lets markdown emphasis sit between the parts: **300,000 sats** (3 BTC).
+const SATS_THEN_BTC = new RegExp(String.raw`${NUM}\s*${SATS}([*_]*\s*\(\s*~?\s*)${NUM}(\s*BTC\b)`, 'gi');
+const BTC_THEN_SATS = new RegExp(String.raw`${NUM}(\s*BTC[*_]*\s*\(\s*~?\s*)${NUM}(\s*${SATS}\b)`, 'gi');
+
+const toNumber = (s: string): number => Number(s.replace(/,/g, ''));
+
+/** Sats as a BTC decimal string, without trailing zeros. */
+export function formatSatsAsBtc(sats: number): string {
+  return (sats / 1e8).toFixed(8).replace(/\.?0+$/, '');
+}
+
+const sameBtc = (btc: number, sats: number) => Math.abs(btc * 1e8 - sats) < 0.5;
+
+/**
+ * Small models get sats↔BTC conversions wrong ("4,277 sats (42.77 BTC)").
+ * Where the answer pairs a sats amount with a BTC amount, recompute the BTC
+ * figure from the sats figure, which is the one copied from the tool result.
+ */
+export function fixSatsBtcConversions(text: string): string {
+  return text
+    .replace(SATS_THEN_BTC, (m, sats: string, mid: string, btc: string, unit: string) =>
+      sameBtc(toNumber(btc), toNumber(sats)) ? m : m.replace(`${mid}${btc}${unit}`, `${mid}${formatSatsAsBtc(toNumber(sats))}${unit}`))
+    .replace(BTC_THEN_SATS, (m, btc: string, _mid: string, sats: string) =>
+      sameBtc(toNumber(btc), toNumber(sats)) ? m : `${formatSatsAsBtc(toNumber(sats))}${m.slice(btc.length)}`);
+}
+
+/** A wallet action the user asked for, and how to recognise a tool that can do it. */
+export interface WalletAction {
+  id: 'receive-invoice' | 'receive-address' | 'pay' | 'send' | 'issue-asset';
+  label: string;
+  tool: RegExp;
+}
+
+const WALLET_ACTIONS: Array<WalletAction & { request: RegExp }> = [
+  {
+    id: 'receive-invoice',
+    label: 'creating an invoice',
+    request: /\b(create|make|generate|new|give me|get me|send me|i need|request)\b[^.?!]*\binvoice\b|\binvoice\b[^.?!]*\bfor\s+\d/i,
+    tool: /(^|_)create_(ln_|lightning_|rgb_)?invoice$|(^|_)receive(_|$)|_invoice_create$/i,
+  },
+  {
+    id: 'receive-address',
+    label: 'getting a receive address',
+    request: /\b(my|new|receive|receiving|deposit|funding|give me|get me|show me)\b[^.?!]*\baddress\b/i,
+    tool: /address/i,
+  },
+  {
+    id: 'pay',
+    label: 'paying an invoice',
+    request: /\bpay\b[^.?!]*\b(invoice|lnbc|lntb|lnbcrt|lno1|bolt11|bolt12|offer)/i,
+    tool: /pay/i,
+  },
+  {
+    id: 'send',
+    label: 'sending funds',
+    request: /\bsend\b[^.?!]*\b(\d|sats?|btc|usdt|xaut|asset|to)\b/i,
+    tool: /send|pay|transfer/i,
+  },
+  {
+    id: 'issue-asset',
+    label: 'issuing an asset',
+    request: /\b(issue|mint|create)\b[^.?!]*\b(asset|token|coin|nia|cfa|uda)\b/i,
+    tool: /issue_asset/i,
+  },
+];
+
+const HOW_TO_QUESTION = /^\s*(how|what|why|when|where|which|who)\b/i;
+
+/**
+ * True when the request is a wallet action the model should act on with a
+ * tool right away — not a question about how such an action works.
+ */
+export function wantsToolCall(text: string): boolean {
+  return detectWalletAction(text) !== null && !HOW_TO_QUESTION.test(text);
+}
+
+/** The wallet action a request asks for, or null. Payment tools from commerce sources don't count. */
+export function detectWalletAction(text: string): WalletAction | null {
+  const hit = WALLET_ACTIONS.find((a) => a.request.test(text));
+  return hit ? { id: hit.id, label: hit.label, tool: hit.tool } : null;
+}
+
+const NON_WALLET_PREFIXES = /^(bitrefill_|l402_|mpp_|search_|read_skill_reference$|remember$|recall$)/;
+
+export function hasCapableTool(action: WalletAction, toolNames: string[]): boolean {
+  return toolNames.some((n) => !NON_WALLET_PREFIXES.test(n) && action.tool.test(n));
+}
+
+export function noToolReply(action: WalletAction): string {
+  return `I can't do that here: no tool for ${action.label} is available, so I won't make anything up. ` +
+    'Connect a wallet that supports it and ask again.';
+}
+
+/** The text fed back to the model when the user declines at the confirmation gate. */
+export const DECLINED_TOOL_MESSAGE =
+  'Cancelled by the user: the user said no at the confirmation prompt, so this action was not run. ' +
+  'Nothing was sent or changed. Tell the user it was cancelled at their request. ' +
+  'Do not say that the node, the wallet, the recipient or anyone else declined it, and do not retry it.';
+
+/** Tool result for a call the user declined — the same shape for every confirm-gated tool. */
+export function declinedToolResult(tool: string, reason?: string): Record<string, unknown> {
+  return {
+    status: 'cancelled_by_user',
+    declined_by: 'user',
+    tool,
+    message: DECLINED_TOOL_MESSAGE,
+    ...(reason ? { host_reason: reason } : {}),
+  };
+}
+
+/** Stable key for a tool call: name + canonical JSON of its arguments. */
+export function callKey(name: string, args: Record<string, unknown>): string {
+  const canon = (v: unknown): unknown =>
+    Array.isArray(v)
+      ? v.map(canon)
+      : v && typeof v === 'object'
+        ? Object.fromEntries(Object.keys(v as Obj).sort().map((k) => [k, canon((v as Obj)[k])]))
+        : v;
+  return `${name}:${JSON.stringify(canon(args ?? {}))}`;
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export type {
 export type {
   InferenceMetrics,
   LLMProvider,
+  ToolCallError,
+  ToolChoice,
   TurnInput,
   TurnOutput,
 } from './providers/types.js';
@@ -55,6 +57,19 @@ export type {
   BindWalletOptions,
 } from './wallet/contract.js';
 export { confirmReadback } from './wallet/confirm.js';
+export {
+  validateToolArgs,
+  findUngroundedPaymentData,
+  detectWalletAction,
+  hasCapableTool,
+  wantsToolCall,
+  fixSatsBtcConversions,
+  formatSatsAsBtc,
+  DECLINED_TOOL_MESSAGE,
+  declinedToolResult,
+} from './guards.js';
+export { annotateRgbBalances, fixRgbBalanceUnits, formatRgbAmount } from './context/rgb-units.js';
+export type { ArgValidation, UngroundedItem, WalletAction } from './guards.js';
 
 // ── KaleidoSwap maker tool contract (single source of truth) ────────────────
 export {
@@ -86,6 +101,23 @@ export type {
   BindLsps1Options,
 } from './lsps1/contract.js';
 
+// ── KaleidoSwap /v2 submarine swaps (pay Lightning from Liquid) ─────────────
+export {
+  SUBMARINE_TOOLS,
+  SUBMARINE_SPEND_TOOLS,
+  SUBMARINE_FROM_ASSETS,
+  isSubmarineSpendTool,
+  getSubmarineTool,
+  formatSubmarineAmount,
+  bindSubmarineTools,
+} from './submarine/contract.js';
+export type {
+  SubmarineToolDef,
+  SubmarineFromAsset,
+  SubmarineHandler,
+  BindSubmarineOptions,
+} from './submarine/contract.js';
+
 // ── Bitrefill (gift cards / mobile top-ups / eSIMs) ─────────────────────────
 export {
   BITREFILL_TOOLS,
@@ -129,6 +161,12 @@ export {
 // ── Buy-an-asset-channel recipe (opt-in — register via Funnel.recipes) ─────
 export { buyAssetChannelRecipe, extractBuyAsset } from './recipe/buy-asset-channel.js';
 
+// ── Issue-an-RGB-asset recipe (opt-in — register via Funnel.recipes) ───────
+export { issueAssetRecipe, extractIssueAsset } from './recipe/issue-asset.js';
+
+// ── Submarine-pay recipe (opt-in — register via Funnel.recipes, before payments) ──
+export { submarinePayRecipe, extractSubmarinePay } from './recipe/submarine-pay.js';
+
 // ── Recipes (mobile multi-step: "recipes, not planning") ───────────────────
 export { runRecipe, extractSlots, RecipeRegistry } from './recipe/runner.js';
 export type { RunRecipeOptions } from './recipe/runner.js';
@@ -202,10 +240,11 @@ export type {
 } from './knowledge/btc-map.js';
 
 export { Engine } from './engine.js';
-export type { EngineOptions, AgenticOptions, AgenticResult } from './engine.js';
+export type { EngineOptions, AgenticOptions, AgenticResult, ComposedSkill } from './engine.js';
 
 // ── Funnel (T0 fast-path → T2 recipe → T1 agentic — the tiered agent) ───────
 export { Funnel, DEFAULT_WALLET_SYSTEM } from './funnel.js';
+export { skillAvailable, selectAvailableSkill } from './skills/select.js';
 export type { FunnelOptions, FunnelSettings, FunnelCallbacks, FunnelResult } from './funnel.js';
 
 export {

package/src/kaleidoswap/contract.test.ts

@@ -17,9 +17,6 @@ describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
       'kaleidoswap_get_pairs',
       'kaleidoswap_get_quote',
       'kaleidoswap_get_nodeinfo',
-      'kaleidoswap_place_order',
-      'kaleidoswap_get_order_status',
-      'kaleidoswap_get_order_history',
       'kaleidoswap_atomic_init',
       'kaleidoswap_atomic_execute',
       'kaleidoswap_atomic_status',
@@ -30,7 +27,7 @@ describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
 
   it('every tool has a group and a parameters object', () => {
     for (const t of KALEIDOSWAP_TOOLS) {
-      expect(['market', 'orders', 'atomic', 'liquidity']).toContain(t.group);
+      expect(['market', 'atomic', 'liquidity']).toContain(t.group);
       expect(t.parameters).toBeDefined();
       expect((t.parameters as any).type).toBe('object');
     }
@@ -45,17 +42,16 @@ describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
   it('lists every spend tool exactly once in KALEIDOSWAP_SPEND_TOOLS', () => {
     const expected = KALEIDOSWAP_TOOLS.filter((t) => t.spend).map((t) => t.name).sort();
     expect([...KALEIDOSWAP_SPEND_TOOLS].sort()).toEqual(expected);
-    // Sanity: place_order, atomic_init/execute, create_asset_channel are spend; the rest aren't.
+    // Sanity: atomic_init/execute, create_asset_channel are spend; the rest aren't.
     expect(expected).toEqual([
       'kaleidoswap_atomic_execute',
       'kaleidoswap_atomic_init',
       'kaleidoswap_lsp_create_asset_channel',
-      'kaleidoswap_place_order',
     ]);
   });
 
   it('isKaleidoswapSpendTool agrees with the set', () => {
-    expect(isKaleidoswapSpendTool('kaleidoswap_place_order')).toBe(true);
+    expect(isKaleidoswapSpendTool('kaleidoswap_atomic_init')).toBe(true);
     expect(isKaleidoswapSpendTool('kaleidoswap_get_pairs')).toBe(false);
     expect(isKaleidoswapSpendTool('not_a_tool')).toBe(false);
   });
@@ -75,13 +71,13 @@ describe('kaleidoswapTools(groups)', () => {
     const market = kaleidoswapTools({ groups: ['market'] });
     expect(market.every((t) => t.group === 'market')).toBe(true);
     expect(market.map((t) => t.name)).toContain('kaleidoswap_get_quote');
-    expect(market.map((t) => t.name)).not.toContain('kaleidoswap_place_order');
+    expect(market.map((t) => t.name)).not.toContain('kaleidoswap_atomic_init');
   });
 
   it('combines multiple groups', () => {
-    const readPlusOrders = kaleidoswapTools({ groups: ['market', 'orders'] });
-    expect(readPlusOrders.some((t) => t.name === 'kaleidoswap_atomic_init')).toBe(false);
-    expect(readPlusOrders.some((t) => t.name === 'kaleidoswap_place_order')).toBe(true);
+    const readPlusLiquidity = kaleidoswapTools({ groups: ['market', 'liquidity'] });
+    expect(readPlusLiquidity.some((t) => t.name === 'kaleidoswap_atomic_init')).toBe(false);
+    expect(readPlusLiquidity.some((t) => t.name === 'kaleidoswap_lsp_create_asset_channel')).toBe(true);
   });
 });
 
@@ -92,9 +88,6 @@ describe('bindKaleidoswapTools', () => {
     kaleidoswap_get_pairs:         async () => ({ ok: true, tool: 'get_pairs' }),
     kaleidoswap_get_quote:         async (a) => ({ ok: true, tool: 'get_quote', args: a }),
     kaleidoswap_get_nodeinfo:      async () => ({ ok: true, tool: 'get_nodeinfo' }),
-    kaleidoswap_place_order:       async (a) => ({ ok: true, tool: 'place_order', args: a }),
-    kaleidoswap_get_order_status:  async (a) => ({ ok: true, tool: 'get_order_status', args: a }),
-    kaleidoswap_get_order_history: async (a) => ({ ok: true, tool: 'get_order_history', args: a }),
     kaleidoswap_atomic_init:       async (a) => ({ ok: true, tool: 'atomic_init', args: a }),
     kaleidoswap_atomic_execute:    async (a) => ({ ok: true, tool: 'atomic_execute', args: a }),
     kaleidoswap_atomic_status:     async (a) => ({ ok: true, tool: 'atomic_status', args: a }),
@@ -110,7 +103,7 @@ describe('bindKaleidoswapTools', () => {
 
   it('preserves descriptions and the spend gate (requiresConfirmation)', () => {
     const src = bindKaleidoswapTools(echoHandlers());
-    const place = src.listTools().find((t) => t.name === 'kaleidoswap_place_order');
+    const place = src.listTools().find((t) => t.name === 'kaleidoswap_atomic_init');
     const pairs = src.listTools().find((t) => t.name === 'kaleidoswap_get_pairs');
     expect(place?.requiresConfirmation).toBe(true);
     expect(pairs?.requiresConfirmation).toBeFalsy();
@@ -141,7 +134,6 @@ describe('bindKaleidoswapTools', () => {
     const src = bindKaleidoswapTools(echoHandlers(), { groups: ['market'] });
     const names = src.listTools().map((t) => t.name);
     expect(names).toContain('kaleidoswap_get_quote');
-    expect(names).not.toContain('kaleidoswap_place_order');
     expect(names).not.toContain('kaleidoswap_atomic_init');
   });
 

package/src/kaleidoswap/contract.ts

@@ -9,10 +9,10 @@
  *   - eval    → stub handlers, also via `bindKaleidoswapTools`
  *
  * Because the schemas are identical everywhere, skills are portable and the
- * model comparison is honest. Tools are grouped (`market`, `orders`, `atomic`,
+ * model comparison is honest. Tools are grouped (`market`, `atomic`,
  * `liquidity`) so a host can expose a read-only subset for sandbox/eval modes.
  *
- * Spend tools (place an order, init/execute an atomic swap) carry
+ * Spend tools (init/execute an atomic swap, buy an asset channel) carry
  * `spend: true` → `requiresConfirmation: true`, so the Engine always pauses
  * for the host's confirm gate before executing.
  *
@@ -24,7 +24,7 @@ import { InProcessToolSource } from '../tools/in-process.js';
 import type { InProcessTool } from '../tools/in-process.js';
 
 /** Functional grouping for selective binding (e.g. read-only sandbox). */
-export type KaleidoswapGroup = 'market' | 'orders' | 'atomic' | 'liquidity';
+export type KaleidoswapGroup = 'market' | 'atomic' | 'liquidity';
 
 export interface KaleidoswapToolDef extends ToolDef {
   /** Functional group — lets a host expose a subset. */
@@ -70,7 +70,7 @@ 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 place_order or atomic_init), the expected receive amount, fees, slippage, and how long the quote is valid for. Re-quote rather than reusing a stale id.',
+    '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.',
     {
       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".' },
@@ -83,33 +83,6 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
     'kaleidoswap_get_nodeinfo',
     "Get info about the maker's Lightning node — pubkey, host, port, connect URI. Useful before opening a channel or when the user wants to see the counterparty. No args."),
 
-  // ─── orders (orderbook / market-order flow) ─────────────────────────────
-  t('orders',
-    'kaleidoswap_place_order',
-    'Place an order using an executable quote. Returns order_id + access_token (save the token — required for get_order_status). SPEND: the host pauses for user confirmation before the maker is called. Use only after kaleidoswap_get_quote and only when the user has explicitly approved the amount + destination.',
-    {
-      quote_id: { type: 'string', description: 'The quote id returned by kaleidoswap_get_quote (must still be valid).' },
-    },
-    ['quote_id'],
-    /* spend */ true),
-
-  t('orders',
-    'kaleidoswap_get_order_status',
-    'Check the status of an order by id — pending / settling / completed / failed. Poll this after place_order until the order settles. Requires the access_token returned by place_order for authenticated orders.',
-    {
-      order_id: { type: 'string', description: 'The order id returned by kaleidoswap_place_order.' },
-      access_token: { type: 'string', description: 'The per-order access token returned by kaleidoswap_place_order. Required for status checks on the order.' },
-    },
-    ['order_id', 'access_token']),
-
-  t('orders',
-    'kaleidoswap_get_order_history',
-    "Get the user's recent KaleidoSwap orders for context (last N, paginated). Read-only.",
-    {
-      limit:  { type: 'number', description: 'Max rows (default 20, max 100).' },
-      cursor: { type: 'string', description: 'Pagination cursor from a previous call.' },
-    }),
-
   // ─── atomic (the trust-minimised swap chain — used by the recipe) ───────
   t('atomic',
     'kaleidoswap_atomic_init',
@@ -205,7 +178,6 @@ export interface BindKaleidoswapOptions {
  *
  *   const source = bindKaleidoswapTools({
  *     kaleidoswap_get_quote: async (args) => makerSdk.quote(args),
- *     kaleidoswap_place_order: async ({ quote_id }) => makerSdk.placeOrder({ quoteId: quote_id }),
  *     // …
  *   });
  *   tools.register(source);

package/src/providers/openai.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { createOpenAICompatibleProvider, encodeToolCalls, toWireMessages } from './openai.js';
+
+function sse(chunks: unknown[]): Response {
+  const text = chunks.map((c) => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n';
+  const bytes = new TextEncoder().encode(text);
+  // Split mid-line to exercise buffering.
+  const body = new ReadableStream<Uint8Array>({
+    start(ctl) {
+      ctl.enqueue(bytes.slice(0, 17));
+      ctl.enqueue(bytes.slice(17));
+      ctl.close();
+    },
+  });
+  return new Response(body, { status: 200 });
+}
+
+function fakeFetch(responses: Response[]) {
+  const bodies: any[] = [];
+  const fn = (async (_url: string, init: RequestInit) => {
+    bodies.push(JSON.parse(String(init.body)));
+    return responses.shift()!;
+  }) as unknown as typeof fetch;
+  return { fn, bodies };
+}
+
+const balanceTool = {
+  name: 'get_balance',
+  description: 'Wallet balance',
+  parameters: { type: 'object', properties: { account: { type: 'string', enum: ['rln', 'spark'] } }, required: ['account'] },
+};
+
+describe('createOpenAICompatibleProvider', () => {
+  it('streams text and reports usage', async () => {
+    const { fn, bodies } = fakeFetch([
+      sse([
+        { choices: [{ delta: { content: 'Hel' } }] },
+        { choices: [{ delta: { content: 'lo' }, finish_reason: 'stop' }] },
+        { choices: [], usage: { prompt_tokens: 12, completion_tokens: 2, total_tokens: 14 } },
+      ]),
+    ]);
+    const p = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1/', model: 'm', fetch: fn, defaultTemperature: 0.1 });
+    const tokens: string[] = [];
+    const out = await p.runTurn({ system: 'S', messages: [{ role: 'user', content: 'hi' }], tools: [], onToken: (t) => tokens.push(t) });
+    expect(out.text).toBe('Hello');
+    expect(tokens).toEqual(['Hel', 'lo']);
+    expect(out.inference).toMatchObject({ status: 'completed', promptTokens: 12, completionTokens: 2, stopReason: 'stop' });
+    expect(bodies[0]).toMatchObject({ model: 'm', stream: true, temperature: 0.1, messages: [{ role: 'system', content: 'S' }, { role: 'user', content: 'hi' }] });
+    expect(bodies[0].tools).toBeUndefined();
+  });
+
+  it('assembles streamed tool-call fragments and sends tools + tool_choice', async () => {
+    const { fn, bodies } = fakeFetch([
+      sse([
+        { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c1', function: { name: 'get_balance', arguments: '{"acc' } }] } }] },
+        { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: 'ount":"rln"}' } }] }, finish_reason: 'tool_calls' }] },
+      ]),
+    ]);
+    const p = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1', model: 'm', fetch: fn });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'balance' }], tools: [balanceTool], toolChoice: 'required' });
+    expect(out.toolCalls).toEqual([{ id: 'c1', name: 'get_balance', arguments: { account: 'rln' } }]);
+    expect(out.rawContent).toBe('<tool_call>{"name":"get_balance","arguments":{"account":"rln"}}</tool_call>');
+    expect(bodies[0].tool_choice).toBe('required');
+    expect(bodies[0].tools[0]).toEqual({ type: 'function', function: { name: 'get_balance', description: 'Wallet balance', parameters: balanceTool.parameters } });
+  });
+
+  it('maps a named tool choice and reports unparseable arguments as toolErrors', async () => {
+    const { fn, bodies } = fakeFetch([
+      sse([{ choices: [{ delta: { tool_calls: [{ index: 0, function: { name: 'get_balance', arguments: '{"account":"rl' } }] }, finish_reason: 'length' }] }]),
+    ]);
+    const p = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1', model: 'm', fetch: fn });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'b' }], tools: [balanceTool], toolChoice: 'get_balance' });
+    expect(bodies[0].tool_choice).toEqual({ type: 'function', function: { name: 'get_balance' } });
+    expect(out.toolCalls).toEqual([]);
+    expect(out.toolErrors?.[0]).toMatchObject({ code: 'PARSE_ERROR' });
+    expect(out.inference?.status).toBe('truncated');
+  });
+
+  it('works without streaming', async () => {
+    const res = new Response(
+      JSON.stringify({ choices: [{ message: { content: null, tool_calls: [{ id: 'z', type: 'function', function: { name: 'get_balance', arguments: '{"account":"spark"}' } }] }, finish_reason: 'tool_calls' }] }),
+    );
+    const { fn, bodies } = fakeFetch([res]);
+    const p = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1', model: 'm', fetch: fn, stream: false, apiKey: 'k' });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'b' }], tools: [balanceTool] });
+    expect(out.toolCalls).toEqual([{ id: 'z', name: 'get_balance', arguments: { account: 'spark' } }]);
+    expect(bodies[0].stream).toBe(false);
+  });
+
+  it('throws on an HTTP error and returns a cancelled turn on abort', async () => {
+    const p1 = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1', model: 'm', fetch: fakeFetch([new Response('nope', { status: 500 })]).fn });
+    await expect(p1.runTurn({ messages: [{ role: 'user', content: 'b' }], tools: [] })).rejects.toThrow(/500/);
+
+    const abortingFetch = ((_u: string, init: RequestInit) =>
+      new Promise((_, reject) => init.signal!.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError'))))) as unknown as typeof fetch;
+    const p2 = createOpenAICompatibleProvider({ baseUrl: 'http://x/v1', model: 'm', fetch: abortingFetch });
+    const ctl = new AbortController();
+    const pending = p2.runTurn({ messages: [{ role: 'user', content: 'b' }], tools: [], signal: ctl.signal });
+    ctl.abort();
+    expect((await pending).inference?.status).toBe('cancelled');
+  });
+});
+
+describe('toWireMessages', () => {
+  it('rebuilds tool_calls / tool_call_id pairs from engine history', () => {
+    const raw = encodeToolCalls('Checking.', [
+      { name: 'get_balance', arguments: { account: 'rln' } },
+      { name: 'get_balance', arguments: { account: 'spark' } },
+    ]);
+    const wire = toWireMessages(
+      [
+        { role: 'user', content: 'balances?' },
+        { role: 'assistant', content: raw },
+        { role: 'tool', content: '{"sats":1}' },
+        { role: 'tool', content: '{"sats":2}' },
+        { role: 'tool', content: '{"error":"unreadable call"}' },
+      ],
+      'SYS',
+    );
+    expect(wire[0]).toEqual({ role: 'system', content: 'SYS' });
+    expect(wire[2]).toMatchObject({ role: 'assistant', content: 'Checking.', tool_calls: [{ id: 'call_1_0' }, { id: 'call_1_1' }] });
+    expect((wire[2] as any).tool_calls[1].function).toEqual({ name: 'get_balance', arguments: '{"account":"spark"}' });
+    expect(wire[3]).toEqual({ role: 'tool', content: '{"sats":1}', tool_call_id: 'call_1_0' });
+    expect(wire[4]).toEqual({ role: 'tool', content: '{"sats":2}', tool_call_id: 'call_1_1' });
+    expect(wire[5]).toEqual({ role: 'user', content: 'Tool result: {"error":"unreadable call"}' });
+  });
+});