@kaleidorg/mind 0.7.0 → 0.8.0

package/skills/rgb-lightning-node/SKILL.md

@@ -5,7 +5,7 @@ tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_list_assets,
 triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, open channel, close channel, inbound, capacity, asset balance, whitelist, taker, swapstring, swaps, payments, invoice, receive, send asset, send rgb, on-chain address, deposit, rgb invoice, ln invoice, issue, mint, new token, nft, utxos, transfers
 metadata:
   author: kaleidoswap
-  version: "0.3.2"
+  version: "0.3.3"
 ---
 
 # RGB Lightning Node (taker-side)
@@ -70,14 +70,26 @@ ASYNCHRONOUSLY (seconds to minutes after payment). If the new channel isn't
 listed yet, say it's still opening and suggest checking again — don't claim
 failure.
 
-### `rln_list_assets` — no args
-Lists RGB assets known to the node with per-asset balances (settled, future,
-spendable, offchain_outbound, offchain_inbound). Use for "what assets do I
-hold / what's my USDT balance".
+### `rln_list_assets` — { schemas? }
+Lists RGB assets known to the node: `asset_id`, `ticker`, `name`, `precision`
+(in-app wallets also return balances). `schemas` is an optional filter — an
+array of `"Nia"`, `"Uda"`, `"Cfa"`; call it with `{}` to list everything.
+Use for "what assets do I hold / what's my USDT balance".
+
+Call it **once** per question. An empty list is a real answer: the node holds
+no RGB assets yet — tell the user that (and offer to issue one) instead of
+calling it again.
+
+### Tickers are not asset ids
+`asset_id` arguments take the full RGB id (`rgb:…`), never a ticker like
+`USDT` or `HCK`. When the user names an asset by ticker or name, first call
+`rln_list_assets`, find the entry whose `ticker`/`name` matches, and pass its
+`asset_id`. If nothing matches, say the node has no such asset — do not guess
+an id.
 
 ### `rln_get_asset_balance` — { asset_id }
-Balance for one RGB asset by id. Use after `rln_list_assets` gave you the id,
-or when the user names a specific asset.
+Balance for one RGB asset by id. Resolve a ticker to its `asset_id` with
+`rln_list_assets` first.
 
 | Field | Meaning |
 |---|---|
@@ -105,7 +117,8 @@ the amount.
 Sends an RGB asset to the recipient encoded in an RGB invoice. Use the argument
 names of the schema you were given: in-app wallets take `{ asset, amount, to }`
 (ticker or asset_id, units, the invoice); kaleido-mcp takes
-`{ asset_id, amount, recipient_id }`. Never invent a recipient.
+`{ asset_id, amount, recipient_id }`, where `asset_id` is the `rgb:…` id from
+`rln_list_assets`. Never invent a recipient.
 
 ### `rln_pay_invoice` — { invoice } — 🔒 confirm-gated
 Pays a BOLT11 Lightning invoice from the node. Pass the full invoice string.
@@ -144,16 +157,21 @@ Call this **after** `kaleidoswap_atomic_init` and **before**
 ### `rln_create_ln_invoice` — Lightning invoice for receiving sats
 Args:
 - `amount_sats` (optional) — omit for an amountless invoice.
+- `description` (optional, kaleido-mcp) — memo shown to the payer.
 - `expiry_sec` (default 3600, kaleido-mcp only) — invoice TTL in seconds.
 
+Reply with the full `invoice` string from the result — never write an invoice
+yourself.
+
 Use when the user wants to **receive** a Lightning payment. Do NOT call inside
 an atomic swap flow unless the user explicitly asked to invoice someone.
 
 ### `rln_create_rgb_invoice` — on-chain RGB receive invoice
 Args (use the names in your schema):
 - in-app wallets: `asset` (ticker or asset_id) + `amount`.
-- kaleido-mcp: `asset_id` (omit for an any-asset invoice), `amount` (display
-  units), `duration_seconds` (default 86400).
+- kaleido-mcp: `asset_id` (the `rgb:…` id from `rln_list_assets` — never a
+  ticker; omit for an any-asset invoice), `amount` (display units),
+  `duration_seconds` (default 86400).
 
 Reply with the full `invoice` string; the payer needs all of it.
 
@@ -176,8 +194,10 @@ defaults (`num` 5, `fee_rate` 1) are fine; set `up_to: true` to only top up to
 ### `rln_issue_asset` — { name, ticker?, amount?, precision?, schema?, details? } — 🔒 confirm-gated
 Creates a **new** RGB asset owned by this node. `schema`: `NIA` fungible token
 (default), `CFA` collectible, `UDA` unique asset / NFT (supply 1).
-- `ticker` (uppercase, 1–8 letters/digits) is required for `NIA` and `UDA`.
-- `amount` is the total supply in display units, required for `NIA` and `CFA`;
+- `ticker` (uppercase, 1–8 letters/digits, nothing else) is required for `NIA`
+  and `UDA`.
+- `amount` is the total supply in display units (a number), required for `NIA`
+  and `CFA` — if the user did not say how many, ask before calling;
   the raw supply is `amount × 10^precision` (`precision` defaults to 0).
 - `details` is an optional description for `CFA` and `UDA`.
 

package/skills/spark-wallet/SKILL.md

@@ -3,6 +3,7 @@ name: spark-wallet
 description: "Operate the user's Spark BTC wallet on this device — check Spark balance, get a Spark deposit address, create a Spark Lightning invoice to receive, pay any BOLT11 Lightning invoice with Spark, or send BTC on-chain from Spark. Use this when the user names Spark explicitly OR when paying a Lightning invoice on a phone where Spark is the connected layer. Pairs with the bitrefill skill: a Bitrefill purchase that returns a Lightning invoice is paid with `spark_pay_invoice`."
 tools: spark_get_balance, spark_get_address, spark_get_onchain_address, spark_create_invoice, spark_pay_invoice, spark_send, get_price, fiat_to_sats, bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order
 triggers: spark, sprak, spakr, spark wallet, pay with spark, send with spark, spark balance, spark address, spark invoice, lightning invoice, pay invoice, bolt11, ln invoice, pay this invoice, on-chain address, onchain address, deposit address, deposit btc, fund spark
+requires-tools: spark_get_balance
 metadata:
   author: kaleidoswap
   version: "1.0.0"

package/skills/submarine-swaps/SKILL.md

@@ -0,0 +1,48 @@
+---
+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."
+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
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+---
+
+# Submarine swaps — pay Lightning from Liquid
+
+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.
+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.
+
+## 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" }`

package/src/context/compress.ts

@@ -48,6 +48,7 @@ export const DEFAULT_PRESERVE_KEYS: readonly string[] = [
   'total',
   'total_sats',
   'balance',
+  'balance_display',
   'balance_sat',
   'address',
   'invoice',

package/src/context/rgb-units.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { annotateRgbBalances, fixRgbBalanceUnits, formatRgbAmount } from './rgb-units.js';
+
+const LIST = {
+  assets: [
+    { asset_id: 'rgb:usdt', ticker: 'USDT', name: 'Tether USD', precision: 0, balance: { settled: 1000, spendable: 1000 } },
+    { asset_id: 'rgb:xaut', ticker: 'XAUT', name: 'Tether Gold', precision: 0, balance: { spendable: 2 } },
+    { asset_id: 'rgb:dec', ticker: 'DEC', precision: 6, balance: { spendable: 1_500_000 } },
+  ],
+};
+
+describe('RGB balance units', () => {
+  it('formats raw amounts with the asset precision', () => {
+    expect(formatRgbAmount(1_500_000, 6)).toBe('1.5');
+    expect(formatRgbAmount(1_000_000, 0)).toBe('1,000,000');
+  });
+
+  it('adds balance_display next to each asset balance without touching the rest', () => {
+    const out = annotateRgbBalances(LIST) as typeof LIST & { assets: Array<{ balance_display: Record<string, string> }> };
+    expect(out.assets[0]!.balance_display).toEqual({ settled: '1,000 USDT', spendable: '1,000 USDT' });
+    expect(out.assets[2]!.balance_display).toEqual({ spendable: '1.5 DEC' });
+    expect(out.assets[0]!.balance).toEqual({ settled: 1000, spendable: 1000 });
+    expect(annotateRgbBalances({ vanilla: { spendable: 4277 } })).toEqual({ vanilla: { spendable: 4277 } });
+  });
+
+  it('relabels the asset balances the 2B model called satoshis', () => {
+    const answer =
+      'You hold two RGB assets:\n1. **USDT** (Tether USD)\n   - Balance: 1,000 satoshis (spendable)\n' +
+      '2. **XAUT** (Tether Gold)\n   - Balance: 2 satoshis (spendable)';
+    expect(fixRgbBalanceUnits(answer, [LIST])).toBe(
+      'You hold two RGB assets:\n1. **USDT** (Tether USD)\n   - Balance: 1,000 USDT (spendable)\n' +
+        '2. **XAUT** (Tether Gold)\n   - Balance: 2 XAUT (spendable)',
+    );
+    expect(fixRgbBalanceUnits('DEC balance: 1,500,000 sats', [LIST])).toBe('DEC balance: 1.5 DEC');
+  });
+
+  it('leaves real sats and unmatched numbers alone', () => {
+    const btc = { btc: { vanilla: { spendable: 4277 } } };
+    expect(fixRgbBalanceUnits('Your on-chain balance is 4,277 sats.', [btc, LIST])).toBe('Your on-chain balance is 4,277 sats.');
+    expect(fixRgbBalanceUnits('USDT channel fee: 300 sats', [LIST])).toBe('USDT channel fee: 300 sats');
+  });
+});

package/src/context/rgb-units.ts

@@ -0,0 +1,89 @@
+/**
+ * RGB asset balances are raw integers in the asset's own unit, scaled by its
+ * `precision`. Nothing in the tool result says so, and small models fill the
+ * gap with "satoshis" ("USDT — Balance: 1,000 satoshis").
+ *
+ * `annotateRgbBalances` adds a `balance_display` next to each asset's
+ * `balance` before the result reaches the model ("1,000 USDT").
+ * `fixRgbBalanceUnits` corrects a final answer that still labels an asset
+ * balance as sats: the number must equal one of that asset's balances and the
+ * nearest ticker before it must be that asset's.
+ */
+
+type Obj = Record<string, unknown>;
+
+interface RgbAsset {
+  ticker: string;
+  precision: number;
+  amounts: number[];
+}
+
+const BALANCE_FIELDS = ['settled', 'spendable', 'future'] as const;
+
+const isObj = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+
+function asAsset(v: Obj): RgbAsset | null {
+  if (typeof v.ticker !== 'string' || !v.ticker || !isObj(v.balance)) return null;
+  const amounts = BALANCE_FIELDS.map((k) => (v.balance as Obj)[k]).filter((n): n is number => typeof n === 'number');
+  if (!amounts.length) return null;
+  const precision = typeof v.precision === 'number' && v.precision > 0 ? v.precision : 0;
+  return { ticker: v.ticker, precision, amounts };
+}
+
+/** A raw RGB amount in display units, e.g. 1500000 at precision 6 → "1.5". */
+export function formatRgbAmount(raw: number, precision: number): string {
+  const value = raw / 10 ** precision;
+  return value.toLocaleString('en-US', { maximumFractionDigits: precision });
+}
+
+/** Return a copy of `result` where every RGB asset carries `balance_display`. */
+export function annotateRgbBalances(result: unknown): unknown {
+  if (Array.isArray(result)) return result.map(annotateRgbBalances);
+  if (!isObj(result)) return result;
+  const out: Obj = {};
+  for (const [k, v] of Object.entries(result)) out[k] = annotateRgbBalances(v);
+  const asset = asAsset(result);
+  if (asset) {
+    const balance = result.balance as Obj;
+    const display: Obj = {};
+    for (const k of BALANCE_FIELDS) {
+      if (typeof balance[k] === 'number') display[k] = `${formatRgbAmount(balance[k] as number, asset.precision)} ${asset.ticker}`;
+    }
+    out.balance_display = display;
+  }
+  return out;
+}
+
+function collectAssets(value: unknown, into: RgbAsset[]): void {
+  if (Array.isArray(value)) {
+    for (const v of value) collectAssets(v, into);
+  } else if (isObj(value)) {
+    const asset = asAsset(value);
+    if (asset) into.push(asset);
+    for (const v of Object.values(value)) collectAssets(v, into);
+  }
+}
+
+const AMOUNT_IN_SATS = /(\d[\d,]*(?:\.\d+)?)\s*(?:satoshis|sats?)\b/gi;
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Relabel asset balances that the answer calls sats, using the tool results it was built from. */
+export function fixRgbBalanceUnits(text: string, toolResults: unknown[]): string {
+  const assets: RgbAsset[] = [];
+  for (const r of toolResults) collectAssets(r, assets);
+  if (!assets.length) return text;
+  const tickerRe = new RegExp(`\\b(${[...new Set(assets.map((a) => escapeRe(a.ticker)))].join('|')})\\b`, 'g');
+
+  return text.replace(AMOUNT_IN_SATS, (match: string, num: string, offset: number) => {
+    let nearest: string | undefined;
+    for (const m of text.slice(Math.max(0, offset - 300), offset).matchAll(tickerRe)) nearest = m[1];
+    if (!nearest) return match;
+    const value = Number(num.replace(/,/g, ''));
+    const asset = assets.find(
+      (a) => a.ticker === nearest && a.amounts.some((raw) => raw === value || raw / 10 ** a.precision === value),
+    );
+    if (!asset) return match;
+    const raw = asset.amounts.find((r) => r === value) ?? value * 10 ** asset.precision;
+    return `${formatRgbAmount(raw, asset.precision)} ${asset.ticker}`;
+  });
+}

package/src/engine.test.ts

@@ -111,8 +111,8 @@ describe('Engine agentic loop', () => {
     const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
 
     expect(payTool.handler).not.toHaveBeenCalled();
-    expect(res.toolCalls[0].result).toMatchObject({ declined: true, reason: 'cancelled' });
-    expect(res.text).toBe('Okay, cancelled.');
+    expect(res.toolCalls[0].result).toMatchObject({ status: 'cancelled_by_user', declined_by: 'user', host_reason: 'cancelled' });
+    expect(res.text).toBe('Cancelled — you declined: pay invoice. Nothing was sent or changed.');
   });
 
   it('chains multiple tool calls across turns', async () => {
@@ -138,7 +138,9 @@ describe('Engine agentic loop', () => {
   it('stops at maxTurns if the model never stops calling tools', async () => {
     const engine = new Engine({
       provider: scriptedProvider([
-        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // always calls a tool
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 1 } }] },
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 2 } }] },
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 3 } }] },
       ]),
       tools: freshTools(),
       defaultMaxTurns: 3,
@@ -205,6 +207,95 @@ describe('Engine agentic loop', () => {
     expect(res.toolCalls[0].result).toMatchObject({ error: 'kaboom' });
     expect(res.text).toBe('handled the error');
   });
+
+  it('sends firstTurnToolChoice on the first call only', async () => {
+    const seen: Array<string | undefined> = [];
+    const provider: LLMProvider = {
+      name: 'rec',
+      async runTurn(input) {
+        seen.push(input.toolChoice);
+        return seen.length === 1
+          ? { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] }
+          : { text: 'done', rawContent: 'done', toolCalls: [] };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    await engine.runAgentic([{ role: 'user', content: 'send 1000 sats' }], { firstTurnToolChoice: 'required' });
+    expect(seen).toEqual(['required', undefined]);
+  });
+
+  it('feeds an unparseable tool call back to the model once, then gives up cleanly', async () => {
+    const histories: number[] = [];
+    const provider: LLMProvider = {
+      name: 'broken',
+      async runTurn(input) {
+        histories.push(input.messages.length);
+        return {
+          text: '<tool_call>{"ticker":"HCK',
+          rawContent: '<tool_call>{"ticker":"HCK',
+          toolCalls: [],
+          toolErrors: [{ code: 'PARSE_ERROR', message: 'unterminated string' }],
+        };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'issue HCK' }]);
+    expect(histories).toEqual([1, 3]);
+    expect(res.text).not.toContain('tool_call');
+    expect(res.text).toMatch(/couldn't put together a valid request/i);
+  });
+
+  it('does not count the retry against maxTurns and explains a cut-off call', async () => {
+    const seen: string[] = [];
+    let n = 0;
+    const provider: LLMProvider = {
+      name: 'cutoff',
+      async runTurn(input) {
+        n += 1;
+        seen.push(input.messages[input.messages.length - 1]!.content);
+        if (n === 1) return { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] };
+        if (n === 2) {
+          return {
+            text: '', rawContent: '<tool_call>{"name":"get_balance"', toolCalls: [],
+            toolErrors: [{ code: 'PARSE_ERROR', message: 'eof' }],
+            inference: { durationMs: 1, status: 'truncated' },
+          };
+        }
+        return { text: 'You have 50,000 sats.', rawContent: '', toolCalls: [] };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'balance?' }], { maxTurns: 2 });
+    expect(res.text).toBe('You have 50,000 sats.');
+    expect(seen[2]).toMatch(/cut off/);
+  });
+
+  it('never returns an empty answer', async () => {
+    const engine = new Engine({ provider: scriptedProvider([{ text: '' }]), tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'hi' }]);
+    expect(res.text).toMatch(/had to stop/);
+  });
+
+  it('recovers when the retried call parses', async () => {
+    const engine = new Engine({
+      provider: (() => {
+        let n = 0;
+        return {
+          name: 'retry',
+          async runTurn(): Promise<TurnOutput> {
+            n += 1;
+            if (n === 1) return { text: 'x', rawContent: 'x', toolCalls: [], toolErrors: [{ code: 'PARSE_ERROR', message: 'bad' }] };
+            if (n === 2) return { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] };
+            return { text: 'You have 50,000 sats.', rawContent: '', toolCalls: [] };
+          },
+        };
+      })(),
+      tools: freshTools(),
+    });
+    const res = await engine.runAgentic([{ role: 'user', content: 'balance?' }]);
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('You have 50,000 sats.');
+  });
 });
 
 describe('ToolRegistry', () => {