@kaleidorg/mind 0.9.0 → 0.10.1

package/skills/submarine-swaps/SKILL.md

@@ -1,48 +1,30 @@
 ---
 name: submarine-swaps
-description: "Pay a Lightning invoice from Liquid funds (L-USDT or L-BTC) through a KaleidoSwap submarine swap on the /v2 maker, and follow its status. Triggers when the user wants to pay a Lightning invoice with Liquid USDT / L-USDT / L-BTC, asks what Liquid assets can pay Lightning, or asks about a submarine swap."
+description: "Pay a Lightning invoice from Liquid funds (L-USDT or L-BTC) through a KaleidoSwap submarine swap, and follow its status."
 tools: kaleidoswap_submarine_pairs, kaleidoswap_submarine_create, kaleidoswap_submarine_fund, kaleidoswap_submarine_status
-triggers: l-usdt, liquid usdt, usdt on liquid, l-btc, liquid bitcoin, submarine, submarine swap, pay invoice with liquid, swap status
+requires-tools: kaleidoswap_submarine_create
+triggers: l-usdt, liquid usdt, usdt on liquid, l-btc, liquid bitcoin, submarine, submarine swap, pay invoice with liquid
 metadata:
   author: kaleidoswap
-  version: "0.1.0"
+  version: "0.2.0"
 ---
+# Submarine swaps
 
-# Submarine swaps — pay Lightning from Liquid
+The user locks Liquid funds; the maker pays the Lightning invoice, then claims
+the lockup. If the maker can't pay, the lockup is refundable. Plain "USDT" is
+RGB USDT (`kaleido-trading`), not this skill.
 
-A submarine swap pays a Lightning (BOLT11) invoice with funds the user locks on
-Liquid. The KaleidoSwap maker pays the invoice, then claims the lockup. It is
-atomic: if the maker can't pay, the lockup is refunded to the user.
-
-## Critical rules
-
-- Every amount, fee and status in your reply MUST come from a tool result in the
-  CURRENT turn. Never guess the amount to lock — `kaleidoswap_submarine_create`
-  returns it.
-- `kaleidoswap_submarine_fund` moves money. Call it ONLY after the user has
-  confirmed the exact `expected_amount` returned by `kaleidoswap_submarine_create`.
-- `kaleidoswap_submarine_fund` takes only `swap_id`. Never try to pass an amount
-  or an address.
-- A bare "USDT" means RGB USDT on the Lightning node, which uses the atomic swap
-  tools, not this skill. Use this skill only for Liquid assets (L-USDT, L-BTC).
-
-## Flow
-
-1. `kaleidoswap_submarine_create { invoice, from_asset }` — from_asset is
-   `L-USDT` (default) or `L-BTC`. Returns `swap_id`, `expected_amount` (smallest
-   unit: L-USDT has 8 decimals, L-BTC is sats) and the fees.
+## Do
+1. `kaleidoswap_submarine_create` (`invoice`, `from_asset`) — `from_asset` is
+   `L-USDT` (default) or `L-BTC`. Returns `swap_id`, `expected_amount`
+   (smallest unit, 8 decimals for both) and fees. Nothing moves yet.
 2. Tell the user the amount and ask to confirm.
-3. `kaleidoswap_submarine_fund { swap_id }`.
-4. `kaleidoswap_submarine_status { swap_id }` — `transaction.claimed` means the
-   invoice was paid. `failed: true` on a funded swap means the funds need a refund;
-   say so and quote the `refund` field.
-
-Use `kaleidoswap_submarine_pairs` when the user asks what can pay a Lightning
-invoice, or for the limits and fees.
+3. `kaleidoswap_submarine_fund` (`swap_id` only; confirm-gated).
+4. `kaleidoswap_submarine_status` (`swap_id`) — `transaction.claimed` means paid;
+   `failed: true` on a funded swap needs a refund: quote the `refund` field.
+- Limits and fees: `kaleidoswap_submarine_pairs {}`.
 
 ## Examples
-
-- "pay lntbs10u1p… with L-USDT" →
-  `kaleidoswap_submarine_create { invoice: "lntbs10u1p…", from_asset: "L-USDT" }`
-- "did my Liquid payment go through? swap sub1" →
-  `kaleidoswap_submarine_status { swap_id: "sub1" }`
+- "Pay lntbs10u1p… with L-USDT" → `kaleidoswap_submarine_create {"invoice":"lntbs10u1p…","from_asset":"L-USDT"}`
+- "Did swap sub1 go through?" → `kaleidoswap_submarine_status {"swap_id":"sub1"}`
+- "What can pay Lightning from Liquid?" → `kaleidoswap_submarine_pairs {}`

package/skills/wallet-assistant/SKILL.md

@@ -1,49 +1,31 @@
 ---
 name: wallet-assistant
-description: Everyday wallet tasks on this phone — check the BTC/asset balance, create an invoice to receive, send a payment, look up a contact, or quote a swap (e.g. "how many sats is 10 USDT?"). Triggers when the user asks about their balance, wants to receive or send money, pay an invoice, pay a contact, or convert between BTC and supported assets.
-tools: get_balances, rln_get_balances, wdk_get_balances, spark_get_balance, rln_get_asset_balance, wdk_get_asset_balance, rln_list_assets, wdk_list_assets, rln_get_address, wdk_get_address, spark_get_address, spark_get_onchain_address, resolve_contact, send_payment, rln_send_btc, wdk_send_btc, rln_send_asset, wdk_send_asset, spark_send, spark_send_sats, rln_pay_invoice, wdk_pay_invoice, spark_pay_invoice, spark_pay_lightning_invoice, rln_create_ln_invoice, wdk_create_ln_invoice, spark_create_invoice, spark_create_lightning_invoice, rln_create_rgb_invoice, wdk_create_rgb_invoice, rln_list_payments, wdk_list_payments, kaleidoswap_get_quote
-triggers: balance, pay, send, receive, address, invoice, transactions, contact, funds, money
+description: "Everyday wallet tasks in the app across all layers: balance, receive (invoice or address), send or pay, contacts, BTC price and fiat conversion."
+tools: get_balances, create_invoice, send_payment, resolve_contact, get_price, fiat_to_sats, rln_list_assets, rln_pay_invoice, spark_pay_invoice
+requires-tools: get_balances
+triggers: balance, balances, pay, send, receive, address, invoice, contact, funds, money, price, how much
+metadata:
+  author: kaleidoswap
+  version: "0.3.0"
 ---
-
 # Wallet assistant
 
-You operate the user's on-device multi-L2 Bitcoin wallet. ALWAYS use a tool to
-get real data — NEVER invent a balance, address, amount, price, or quote.
-
-## Critical rules
-
-You have no knowledge of balances, addresses, invoices, prices, or quotes.
-Every value in your reply MUST come from a tool result returned in the CURRENT
-turn — do not reuse a number from a previous turn.
-
-NEVER mention the exact name of any tool (such as "kaleidoswap_get_quote") in
-your text reply to the user. Only use tools via the proper function call
-format when needed; describe what you are doing in plain language.
-
-When a tool returns multiple fields, **report all the load-bearing ones**:
-- The balance tool may return `{confirmed, pending, total}` — when `pending`
-  is non-zero, report BOTH. `confirmed` is spendable; `pending` is settling
-  and is NOT spendable yet. The user needs to know the difference.
-- The quote tool returns display strings (e.g. the to amount and fee in
-  human readable form). Read these strings verbatim — do NOT do unit math
-  yourself.
-
-## Rules
-
-- **Balance / "how much do I have"** → use the balance tool, then state the
-  number.
-- **Receive / "an invoice for N sats"** → use the invoice creation tool (for
-  the appropriate layer) with the amount.
-- **"How many sats is N USDT?" / "What's 0.1 BTC in USDT?" / "convert N X
-  to Y"** → use the quote/conversion tool and
-  read the display fields from the result. Supported pairs: any of
-  BTC/USDT/XAUT against each other. Fiat (EUR/USD/GBP) is NOT quoted by
-  the maker — if the user asks "how much sats is 10 EUR", say so plainly
-  and offer USDT as the closest analogue (USDT is a USD-pegged stablecoin).
-- **Pay a Lightning invoice** → use the lightning payment tool.
-- **Send to a person/amount** → first resolve the contact, then use the send
-  payment tool with the amount in sats and the recipient. State the amount and
-  destination; the app asks the user to confirm before it sends.
-
-Keep replies short, but never drop a balance component, a fee, or the
-quote's `rfq_id` when present.
+The app routes these tools to the right layer (Spark, RLN, Arkade, Liquid).
+`amount_sats` is satoshis; other amounts are display units of the asset.
+
+## Do
+- Balance: `get_balances` (add `layer` for one layer). Report every component;
+  `pending` is not spendable yet.
+- Receive: `create_invoice` with `asset` and optional `amount`; reply with the
+  full invoice or address returned.
+- Send to a name: `resolve_contact` first, then `send_payment`. A BOLT11
+  invoice the user pasted: `rln_pay_invoice` or `spark_pay_invoice`. Every
+  send is confirm-gated; state amount and destination.
+- Fiat: `fiat_to_sats` converts; `get_price` gives the BTC price.
+- Swaps go to `kaleido-trading` (RGB) or `flashnet-swaps` (Spark tokens).
+
+## Examples
+- "What's my balance?" → `get_balances {}`
+- "Invoice for 2000 sats" → `create_invoice {"asset":"BTC","amount":2000}`
+- "Send 5000 sats to bob" → `resolve_contact {"name":"bob"}` then `send_payment {"to":"<bob's address>","amount_sats":5000}`
+- "How many sats is 10 EUR?" → `fiat_to_sats {"amount":10,"currency":"EUR"}`

package/src/engine/answer.ts

@@ -8,7 +8,14 @@
  * quotes a readback from being mistaken for an invented invoice.
  */
 import type { ToolCallError } from '../providers/types.js';
-import { findUngroundedPaymentData, fixSatsBtcConversions, ungroundedReply } from '../guards.js';
+import {
+  findUngroundedPaymentData,
+  fixSatsBtcConversions,
+  paymentStrings,
+  producedPaymentReply,
+  ungroundedReply,
+  type UngroundedItem,
+} from '../guards.js';
 import { fixRgbBalanceUnits } from '../context/rgb-units.js';
 
 export interface Answer {
@@ -49,6 +56,8 @@ export interface FinalizeOptions {
   sources: unknown[];
   /** Tool results, for relabelling RGB balances. */
   toolResults: unknown[];
+  /** Invoices and addresses receive tools returned this run (`producedPaymentData`). */
+  produced?: UngroundedItem[];
   aborted: boolean;
 }
 
@@ -59,8 +68,23 @@ export function finalizeAnswer(answer: Answer, opts: FinalizeOptions): string {
   let text = answer.text;
   if (opts.fixAmounts) text = fixRgbBalanceUnits(fixSatsBtcConversions(text), opts.toolResults);
   if (opts.guardPaymentData) {
+    const produced = opts.produced ?? [];
+    const lower = text.toLowerCase();
+    const missing = produced.filter((p) => !lower.includes(p.value.toLowerCase()));
+    // A partial or garbled copy of a value a tool produced (it shares the
+    // value's start, or is cut out of it): show the tool's value instead.
+    const mangled = paymentStrings(text).some((f) => {
+      const v = f.value.toLowerCase();
+      return missing.some((p) => {
+        const want = p.value.toLowerCase();
+        return want.includes(v) || v.slice(0, 12) === want.slice(0, 12);
+      });
+    });
+    if (mangled) return producedPaymentReply(produced);
     const ungrounded = findUngroundedPaymentData(text, opts.sources);
-    if (ungrounded.length) text = ungroundedReply(ungrounded);
+    if (ungrounded.length) return produced.length ? producedPaymentReply(produced) : ungroundedReply(ungrounded);
+    // The model left out the invoice/address it was asked for: add it verbatim.
+    if (missing.length) text = `${text}\n\n${producedPaymentReply(missing)}`;
   }
   return text;
 }

package/src/engine/rgb-ticker.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from 'vitest';
+import { resolveRgbTicker } from './rgb-ticker.js';
+
+const assets = [
+  { asset_id: 'rgb:usdt-1', ticker: 'USDT', name: 'Tether USD' },
+  { asset_id: 'rgb:xaut-1', ticker: 'XAUT', name: 'Tether Gold' },
+];
+const host = (result: unknown, tools = ['rln_list_assets']) => ({
+  hasTool: async (n: string) => tools.includes(n),
+  run: vi.fn(async () => result),
+});
+
+describe('resolveRgbTicker', () => {
+  it('replaces a ticker with the asset id from the same host', async () => {
+    const h = host(JSON.stringify(assets));
+    expect(await resolveRgbTicker('rln_send_asset', { asset_id: 'usdt', amount: 1 }, h)).toEqual({ asset_id: 'rgb:usdt-1', amount: 1 });
+    expect(h.run).toHaveBeenCalledWith('rln_list_assets', {});
+    expect(await resolveRgbTicker('rln_create_rgb_invoice', { asset: 'XAUT' }, host({ assets }))).toEqual({ asset: 'rgb:xaut-1' });
+    expect(await resolveRgbTicker('wdk_send_asset', { asset_id: 'USDT' }, host({ nia: assets }, ['wdk_list_assets']))).toEqual({ asset_id: 'rgb:usdt-1' });
+  });
+
+  it('leaves ids, unknown tickers, other tools and hosts without a list tool alone', async () => {
+    const h = host(assets);
+    expect(await resolveRgbTicker('rln_send_asset', { asset_id: 'rgb:usdt-1' }, h)).toEqual({ asset_id: 'rgb:usdt-1' });
+    expect(await resolveRgbTicker('rln_send_asset', { asset_id: 'FOO' }, h)).toEqual({ asset_id: 'FOO' });
+    expect(await resolveRgbTicker('rln_issue_asset', { ticker: 'USDT' }, h)).toEqual({ ticker: 'USDT' });
+    expect(await resolveRgbTicker('rln_send_asset', { asset_id: 'USDT' }, host(assets, []))).toEqual({ asset_id: 'USDT' });
+  });
+});

package/src/engine/rgb-ticker.ts

@@ -0,0 +1,54 @@
+/**
+ * RGB tools take an `asset_id` (`rgb:…`), but users say "USDT". Small models
+ * either look the id up first (an extra turn, and some stop after it) or pass
+ * the ticker. When a send / RGB-invoice call carries a ticker, resolve it here
+ * with the same host's `*_list_assets`, so one call does the job on every
+ * host (in-app contract or kaleido-mcp).
+ */
+
+type Obj = Record<string, unknown>;
+
+const NEEDS_ASSET_ID = /(^|_)(send_asset|create_rgb_invoice)$/;
+const ASSET_KEYS = ['asset_id', 'asset'] as const;
+
+function listedAssets(result: unknown): Obj[] {
+  let r = result;
+  if (typeof r === 'string') {
+    try {
+      r = JSON.parse(r);
+    } catch {
+      return [];
+    }
+  }
+  if (Array.isArray(r)) return r as Obj[];
+  if (!r || typeof r !== 'object') return [];
+  const o = r as Obj;
+  if (Array.isArray(o.assets)) return o.assets as Obj[];
+  return ['nia', 'cfa', 'uda', 'ifa'].flatMap((k) => (Array.isArray(o[k]) ? (o[k] as Obj[]) : []));
+}
+
+/**
+ * `args` with a ticker in `asset_id` / `asset` replaced by the asset's id, or
+ * `args` unchanged (not an RGB call, already an id, no list tool, no single
+ * match).
+ */
+export async function resolveRgbTicker(
+  toolName: string,
+  args: Record<string, unknown>,
+  host: {
+    hasTool: (name: string) => Promise<boolean>;
+    run: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  },
+): Promise<Record<string, unknown>> {
+  if (!NEEDS_ASSET_ID.test(toolName)) return args;
+  const key = ASSET_KEYS.find((k) => typeof args[k] === 'string');
+  const ticker = key ? String(args[key]).trim() : '';
+  if (!key || !ticker || ticker.toLowerCase().startsWith('rgb:') || !/^[A-Za-z0-9]{1,12}$/.test(ticker)) return args;
+
+  const listTool = toolName.replace(NEEDS_ASSET_ID, '$1list_assets');
+  if (!(await host.hasTool(listTool))) return args;
+  const matches = listedAssets(await host.run(listTool, {})).filter(
+    (a) => typeof a.ticker === 'string' && a.ticker.toUpperCase() === ticker.toUpperCase() && typeof a.asset_id === 'string',
+  );
+  return matches.length === 1 ? { ...args, [key]: matches[0]!.asset_id } : args;
+}

package/src/engine.ts

@@ -18,9 +18,18 @@ import type { ConfirmDecision, Message, ToolCall, ToolDef, ToolResult } from './
 import type { InferenceMetrics, LLMProvider, ToolChoice } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { compressToolResult, type ToolCrushOptions } from './context/compress.js';
-import { callKey, declinedToolResult, detectWalletAction, hasCapableTool, noToolReply, validateToolArgs } from './guards.js';
+import {
+  callKey,
+  declinedToolResult,
+  detectWalletAction,
+  hasCapableTool,
+  noToolReply,
+  producedPaymentData,
+  validateToolArgs,
+} from './guards.js';
 import { confirmReadback } from './wallet/confirm.js';
 import { annotateRgbBalances } from './context/rgb-units.js';
+import { resolveRgbTicker } from './engine/rgb-ticker.js';
 import {
   REPEATED_CALL_REPLY,
   TOOL_CALL_FAILED_REPLY,
@@ -279,6 +288,7 @@ export class Engine {
       guardPaymentData: this.guardPaymentData,
       sources: [...messages.map((m) => m.content), ...state.executed.map((e) => e.result)],
       toolResults: state.executed.map((e) => e.result),
+      produced: producedPaymentData(state.executed),
       aborted: !!opts.signal?.aborted,
     });
     // Append the final answer so the returned conversation is complete (the
@@ -346,7 +356,11 @@ export class Engine {
     } else if (!def) {
       result = { error: `Unknown tool "${call.name}".` };
     } else {
-      const check = validateToolArgs(def, call.arguments);
+      const callArgs = await resolveRgbTicker(call.name, call.arguments, {
+        hasTool: async (name) => !!(await this.registry.getDef(name)),
+        run: (name, a) => this.safeExecute(name, a),
+      });
+      const check = validateToolArgs(def, callArgs);
       if (!check.ok) {
         result = {
           error: `Invalid arguments for ${call.name}: ${check.errors.join('; ')}. Fix them or ask the user for the missing values.`,

package/src/funnel.mind.test.ts

@@ -318,10 +318,11 @@ describe('desktop mind — skill scoping (real skills)', () => {
     );
   });
 
-  it('wallet-assistant (triggers on "balance") exposes the real rln_*/wdk_* tool names', () => {
+  it('wallet-assistant is the in-app router; the node skill carries the rln_* balance tools', () => {
     const wallet = SKILLS.find((s) => s.name === 'wallet-assistant')!;
-    expect(wallet.tools).toEqual(expect.arrayContaining(['rln_get_balances', 'wdk_get_balances']));
-    expect(wallet.tools).toEqual(expect.arrayContaining(['rln_get_address', 'rln_send_btc', 'rln_create_ln_invoice']));
+    expect(wallet.metadata?.['requires-tools']).toBe('get_balances');
+    const node = SKILLS.find((s) => s.name === 'rgb-lightning-node')!;
+    expect(node.tools).toEqual(expect.arrayContaining(['rln_get_balances', 'rln_get_address', 'rln_send_btc', 'rln_create_ln_invoice']));
   });
 
   it('rgb-lightning-node (triggers on "channels") exposes only canonical rln_* tools', () => {
@@ -361,9 +362,9 @@ describe('desktop mind — skill scoping (real skills)', () => {
     const res = await funnel.runTurn("what's my balance?");
 
     expect(res.tier).toBe('agentic');
-    // wallet-assistant is selected AND rln_get_balances survives its scoping…
+    // Node-only host: the RGB node skill is selected AND rln_get_balances survives its scoping…
     const agenticLine = logs.find((l) => l.startsWith('tier=agentic'));
-    expect(agenticLine).toMatch(/skill=wallet-assistant/);
+    expect(agenticLine).toMatch(/skill=rgb-lightning-node/);
     expect(agenticLine).toMatch(/rln_get_balances/);
     // …and the tool actually executes (not narrated).
     expect(calls.map((c) => c.name)).toContain('rln_get_balances');

package/src/guards.test.ts

@@ -6,6 +6,7 @@ import { InProcessToolSource } from './tools/in-process.js';
 import { parseSkill, SkillRegistry } from './skills/registry.js';
 import { scriptedProvider } from './testing/scripted-provider.js';
 import { confirmReadback } from './wallet/confirm.js';
+import { getKaleidoswapTool } from './kaleidoswap/contract.js';
 import {
   DECLINED_TOOL_MESSAGE,
   detectWalletAction,
@@ -31,7 +32,18 @@ const ISSUE_SCHEMA = {
 
 const INVOICE = 'lnbcrt50u1pn9xyzpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq';
 
+const QUOTE = { name: 'kaleidoswap_get_quote', parameters: getKaleidoswapTool('kaleidoswap_get_quote')!.parameters };
+
 describe('validateToolArgs', () => {
+  it('rejects sats passed as a BTC display amount and names the BTC value', () => {
+    const r = validateToolArgs(QUOTE, { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 50_000 });
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toMatch(/from_amount: 0\.0005/);
+    expect(validateToolArgs(QUOTE, { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 0.0005 }).ok).toBe(true);
+    expect(validateToolArgs(QUOTE, { from_asset_id: 'USDT', to_asset_id: 'BTC', from_amount: 5000 }).ok).toBe(true);
+    expect(validateToolArgs(QUOTE, { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 1, to_amount: 2 }).ok).toBe(false);
+  });
+
   it('accepts valid args and coerces numeric strings', () => {
     const r = validateToolArgs({ name: 'rln_issue_asset', parameters: ISSUE_SCHEMA }, { name: 'Hack', ticker: 'HCK', amount: '1000' });
     expect(r.ok).toBe(true);
@@ -397,3 +409,30 @@ describe('engine replies skip the answer guards', () => {
     expect(res.text).not.toMatch(/won't make one up/);
   });
 });
+
+describe('invoices and addresses come from the tool, not the model', () => {
+  const invoice = 'rgb:~/~/~/sig/rgb:usdt/10/utxob:abcdefghijklmnop';
+  const tools = [{ name: 'rln_create_rgb_invoice', description: '', parameters: {}, handler: async () => ({ invoice }) }];
+
+  it('appends the invoice when the model leaves it out', async () => {
+    const engine = engineWith(tools, [{ tool: 'rln_create_rgb_invoice' }, { text: 'Here is the full invoice string for receiving 10 USDT.' }]);
+    const res = await engine.runAgentic([{ role: 'user', content: 'Create an RGB invoice for 10 USDT' }]);
+    expect(res.text).toBe(`Here is the full invoice string for receiving 10 USDT.\n\nHere is your RGB invoice:\n\n\`${invoice}\``);
+  });
+
+  it("replaces a mangled copy with the tool's value instead of refusing", async () => {
+    const engine = engineWith(tools, [{ tool: 'rln_create_rgb_invoice' }, { text: 'Invoice: rgb:~/~/~/sig/rgb:usdt/10/utxob:abcdefgh' }]);
+    const res = await engine.runAgentic([{ role: 'user', content: 'Create an RGB invoice for 10 USDT' }]);
+    expect(res.text).toBe(`Here is your RGB invoice:\n\n\`${invoice}\``);
+  });
+
+  it('leaves a correct answer alone and ignores payment data from other tools', async () => {
+    const ok = engineWith(tools, [{ tool: 'rln_create_rgb_invoice' }, { text: `Your invoice: ${invoice}` }]);
+    expect((await ok.runAgentic([{ role: 'user', content: 'invoice me 10 USDT' }])).text).toBe(`Your invoice: ${invoice}`);
+    const reads = engineWith(
+      [{ name: 'rln_list_transfers', description: '', parameters: {}, handler: async () => ({ transfers: [{ invoice }] }) }],
+      [{ tool: 'rln_list_transfers' }, { text: 'You have one transfer.' }],
+    );
+    expect((await reads.runAgentic([{ role: 'user', content: 'list my transfers' }])).text).toBe('You have one transfer.');
+  });
+});

package/src/guards.ts

@@ -78,6 +78,26 @@ const SEMANTIC_RULES: Record<string, (a: Record<string, unknown>) => string[]> =
 };
 SEMANTIC_RULES.wdk_issue_asset = SEMANTIC_RULES.rln_issue_asset!;
 
+/** Above this, a BTC amount in display units is almost certainly sats. */
+const MAX_PLAUSIBLE_BTC = 1000;
+
+/** KaleidoSwap quote amounts are display units; reject sats passed as BTC. */
+function btcDisplayAmounts(a: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  const legs: Array<[string, unknown]> = [['from_amount', a.from_asset_id], ['to_amount', a.to_asset_id]];
+  if (a.from_amount != null && a.to_amount != null) errors.push('give only one of "from_amount" or "to_amount"');
+  for (const [key, asset] of legs) {
+    const v = a[key];
+    if (typeof v !== 'number' || !/^btc$/i.test(String(asset ?? '').trim())) continue;
+    if (v >= MAX_PLAUSIBLE_BTC) {
+      errors.push(`"${key}" is in BTC, not sats: ${v} sats is ${+(v / 1e8).toFixed(8)} BTC — pass ${key}: ${+(v / 1e8).toFixed(8)}`);
+    }
+  }
+  return errors;
+}
+SEMANTIC_RULES.kaleidoswap_get_quote = btcDisplayAmounts;
+SEMANTIC_RULES.kaleidoswap_get_spreads = btcDisplayAmounts;
+
 /**
  * Validate (and lightly coerce) a tool call's arguments against its schema.
  * Unknown schema shapes pass through unchanged.
@@ -169,6 +189,47 @@ export function findUngroundedPaymentData(text: string, sources: unknown[]): Ung
   return out;
 }
 
+// Tools whose job is to hand the user a payment request or an address.
+const RECEIVE_TOOL = /(^|_)create_(ln_|lightning_|rgb_)?invoice$|(^|_)get_address$|(^|_)receive(_|$)|_invoice_create$/i;
+
+/**
+ * Invoices and addresses that receive tools returned in this run: what the
+ * user asked for, to be shown verbatim rather than retyped by the model.
+ */
+export function producedPaymentData(executed: Array<{ name: string; result: unknown }>): UngroundedItem[] {
+  const found: UngroundedItem[] = [];
+  for (const { name, result } of executed) {
+    if (!RECEIVE_TOOL.test(name) || (result && typeof result === 'object' && 'error' in result)) continue;
+    let text: string;
+    try {
+      text = typeof result === 'string' ? result : JSON.stringify(result);
+    } catch {
+      continue;
+    }
+    found.push(...paymentStrings(text));
+  }
+  // Keep whole values only: the utxob: inside an RGB invoice is not a second item.
+  const lower = found.map((f) => f.value.toLowerCase());
+  return found.filter((f, i) => {
+    const v = lower[i]!;
+    return lower.indexOf(v) === i && !lower.some((o, j) => j !== i && o !== v && o.includes(v));
+  });
+}
+
+/** Payment strings (invoices, addresses) in a piece of text. */
+export function paymentStrings(text: string): UngroundedItem[] {
+  const out: UngroundedItem[] = [];
+  for (const { kind, re } of PAYMENT_DATA) {
+    for (const m of text.matchAll(re)) out.push({ kind, value: m[0].replace(/[.,;:!?*\\]+$/, '') });
+  }
+  return out;
+}
+
+/** The answer built from the tool's own values, when the model's copy is unusable. */
+export function producedPaymentReply(items: UngroundedItem[]): string {
+  return items.map((i) => `Here is your ${i.kind}:\n\n\`${i.value}\``).join('\n\n');
+}
+
 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. ` +

package/src/index.ts

@@ -49,6 +49,7 @@ export {
   walletTools,
   toToolDefs,
   bindWalletTools,
+  normalizeWalletArgs,
 } from './wallet/contract.js';
 export type {
   WalletLayer,
@@ -63,6 +64,9 @@ export {
   detectWalletAction,
   hasCapableTool,
   wantsToolCall,
+  producedPaymentData,
+  paymentStrings,
+  producedPaymentReply,
   fixSatsBtcConversions,
   formatSatsAsBtc,
   DECLINED_TOOL_MESSAGE,

package/src/kaleidoswap/contract.test.ts

@@ -6,6 +6,7 @@ import {
   getKaleidoswapTool,
   kaleidoswapTools,
   bindKaleidoswapTools,
+  normalizeKaleidoswapArgs,
   type KaleidoswapHandler,
 } from './contract.js';
 
@@ -109,10 +110,14 @@ describe('bindKaleidoswapTools', () => {
     expect(pairs?.requiresConfirmation).toBeFalsy();
   });
 
-  it('dispatches execute() to the right handler with args', async () => {
+  it('dispatches execute() with kaleido-mcp args plus the legacy aliases', async () => {
     const src = bindKaleidoswapTools(echoHandlers());
-    const r = await src.execute('kaleidoswap_get_quote', { from_asset: 'BTC', to_asset: 'USDT', amount: 100_000 });
-    expect(r).toMatchObject({ ok: true, tool: 'get_quote', args: { from_asset: 'BTC', amount: 100_000 } });
+    const r = await src.execute('kaleidoswap_get_quote', { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 0.001 });
+    expect(r).toMatchObject({
+      ok: true,
+      tool: 'get_quote',
+      args: { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 0.001, from_asset: 'BTC', to_asset: 'USDT', amount: 100_000 },
+    });
   });
 
   it('throws when a handler is missing and allowMissing is false', () => {
@@ -142,3 +147,27 @@ describe('bindKaleidoswapTools', () => {
     expect(src.id).toBe('maker-prod');
   });
 });
+
+describe('normalizeKaleidoswapArgs', () => {
+  it('maps a display-unit quote to the legacy sats amount', () => {
+    expect(normalizeKaleidoswapArgs('kaleidoswap_get_quote', { from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 0.0005 }))
+      .toMatchObject({ from_asset: 'BTC', to_asset: 'USDT', amount: 50_000 });
+  });
+
+  it('keeps RGB amounts in display units and marks a buy-side amount', () => {
+    expect(normalizeKaleidoswapArgs('kaleidoswap_get_quote', { from_asset_id: 'BTC', to_asset_id: 'USDT', to_amount: 10 }))
+      .toMatchObject({ amount: 10, amount_side: 'to' });
+  });
+
+  it('maps a legacy sats quote to display units', () => {
+    expect(normalizeKaleidoswapArgs('kaleidoswap_get_quote', { from_asset: 'BTC', to_asset: 'USDT', amount: 100_000 }))
+      .toMatchObject({ from_asset_id: 'BTC', to_asset_id: 'USDT', from_amount: 0.001 });
+    expect(normalizeKaleidoswapArgs('kaleidoswap_get_quote', { from_asset: 'USDT', to_asset: 'BTC', amount: 25 }))
+      .toMatchObject({ from_amount: 25 });
+  });
+
+  it('aliases rfq_id/quote_id and payment_hash/atomic_id', () => {
+    expect(normalizeKaleidoswapArgs('kaleidoswap_atomic_init', { rfq_id: 'r1' })).toMatchObject({ quote_id: 'r1' });
+    expect(normalizeKaleidoswapArgs('kaleidoswap_atomic_status', { atomic_id: 'h1' })).toMatchObject({ payment_hash: 'h1' });
+  });
+});