@kaleidorg/mind 0.6.0 → 0.6.1

package/src/recipe/runner.ts

@@ -95,10 +95,12 @@ export async function extractSlots(
   const system = [
     `Call ${EXTRACT_TOOL} with the fields from the user's message.`,
     recipe.description ? `This extraction is for: ${recipe.description}.` : '',
-    'Only emit values that match the field descriptions.',
+    'Only emit values that match the field descriptions. Use the examples and phrasings listed in each field\'s description (including context like "on the other" when "my side" appears).',
     'Canonical assets: BTC, USDT, XAUT (pass as strings like "BTC" or "USDT").',
     'amount_side: "to" when the named amount is what you receive/buy (e.g. "buy 1 USDT" → to_asset=USDT, amount=1, from_asset=BTC); "from" for sell/swap (amount on from_asset).',
     'The host binding handles per-asset precision scaling (BTC in sats → maker units; USDT/XAUT whole units). Pass the user\'s number as-is for the correct side.',
+    'If a value is ambiguous from the message, prefer the mapping from the field descriptions rather than guessing.',
+    'For status-related follow-ups the history (or recall result) will contain explicit "order_id=... access_token=..." or "atomic_id=..." strings from prior summaries — when relevant extract them exactly.',
     'Do not call any other tool and do not add commentary.',
   ].filter(Boolean).join(' ');
 
@@ -175,10 +177,10 @@ export async function runRecipe(recipe: Recipe, text: string, opts: RunRecipeOpt
     if (recipe.confident && !recipe.confident(ctx.slots)) {
       const missing = recipe.slots
         .filter((s) => s.required && (ctx.slots[s.name] == null || ctx.slots[s.name] === ''))
-        .map((s) => `${s.name} (${s.description})`);
+        .map((s) => s.name);
       const ask =
         missing.length > 0
-          ? `I need a bit more info — please specify: ${missing.join('; ')}.`
+          ? `I need a bit more info — please specify the ${missing.join(' and ')} (rephrase with the numbers, or use recall if this is a follow-up status check).`
           : "I don't have enough info to do that — could you rephrase with the specifics?";
       return { recipe: recipe.name, slots: ctx.slots, results: ctx.results, text: ask, status: 'needs-info', inferences };
     }

package/src/recipe/swap.ts

@@ -12,7 +12,7 @@
 
 import type { Recipe } from './types.js';
 
-const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold)\b/i;
+const ASSET = /\b(btc|bitcoin|sats?|usdt|tether|xaut|gold|usdb)\b/i;
 
 /** Strict: returns a canonical code only for a KNOWN crypto asset, else undefined
  *  (so "kaleido", "the", etc. are not mistaken for an asset). */
@@ -22,6 +22,7 @@ function knownAsset(a?: string): string | undefined {
   if (/^(btc|bitcoin|sat|sats|satoshi|satoshis)$/.test(x)) return 'BTC';
   if (/^(usdt|tether)$/.test(x)) return 'USDT';
   if (/^(xaut|gold)$/.test(x)) return 'XAUT';
+  if (/^usdb$/.test(x)) return 'USDB';
   return undefined;
 }
 
@@ -106,6 +107,20 @@ export function extractPriceQuery(text: string): Record<string, unknown> | null
   // Reject swap intent — those go to the atomic recipe, not the price recipe.
   if (/\b(swap|exchange|convert|trade|buy|sell|get|purchase|acquire)\b/i.test(t)) return null;
 
+  // Natural quantity quote: "how many sats is 10 USDT worth?" The amount is
+  // on the priced asset (TO leg); the requested denomination is the FROM leg.
+  const quantityWorth = t.match(
+    /\bhow\s+(?:many|much)\s+([a-z]+)\s+(?:is|are)\s+(\d[\d.,]*)\s+([a-z]+)\s+worth\b/i,
+  );
+  if (quantityWorth) {
+    const denom = knownAsset(quantityWorth[1]);
+    const amount = parseAmount(quantityWorth[2]);
+    const asset = knownAsset(quantityWorth[3]);
+    if (denom && asset && amount != null) {
+      return { amount, from_asset: denom, to_asset: asset, amount_side: 'to' };
+    }
+  }
+
   // ORDER MATTERS: "how much B for A" (first) must be checked BEFORE
   // "how much X (in Y)?" — otherwise the latter would gobble the first asset
   // and miss the "for/per" tail. Optional "the" article is tolerated

package/src/wallet/confirm.test.ts

@@ -40,6 +40,14 @@ describe('confirmReadback', () => {
     expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over RLN. Confirm?');
   });
 
+  it('spark_pay_invoice: same readback shape, over Spark', () => {
+    const line = confirmReadback({
+      name: 'spark_pay_invoice',
+      arguments: { invoice: 'lnbc1ptestinvoice0123456789abcd' },
+    });
+    expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over Spark. Confirm?');
+  });
+
   it('execute_swap: from → to with amount', () => {
     expect(confirmReadback({ name: 'execute_swap', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 0.01 } }))
       .toBe('Swap 0.01 BTC for USDT. Confirm?');

package/src/wallet/confirm.ts

@@ -64,6 +64,7 @@ export function confirmReadback(call: { name: string; arguments: Record<string,
     case 'liquid_send':
       return ask(`Send ${asset(a.amount, a.asset)} to ${to()}${over(name, a)}`);
     case 'rln_pay_invoice':
+    case 'spark_pay_invoice':
       return ask(`Pay Lightning invoice ${shortRef(String(a.invoice ?? ''))}${over(name, a)}`);
     case 'execute_swap':
       return ask(`Swap ${fmtNum(Number(a.amount))} ${String(a.from_asset)} for ${String(a.to_asset)}`);

package/src/wallet/contract.test.ts

@@ -39,12 +39,22 @@ describe('WALLET_TOOLS contract', () => {
     expect(isSpendTool('rln_send_asset')).toBe(true);
     expect(isSpendTool('execute_swap')).toBe(true);
     expect(isSpendTool('spark_send')).toBe(true);
+    expect(isSpendTool('spark_pay_invoice')).toBe(true);
     // reads are not
     expect(isSpendTool('get_balances')).toBe(false);
     expect(isSpendTool('get_price')).toBe(false);
     expect([...SPEND_TOOLS].length).toBeGreaterThanOrEqual(5);
   });
 
+  it('spark_pay_invoice is its own tool — BOLT11-shaped, amount optional', () => {
+    const def = getWalletTool('spark_pay_invoice');
+    expect(def?.layer).toBe('spark');
+    expect(def?.spend).toBe(true);
+    expect((def!.parameters as any).required).toEqual(['invoice']);
+    expect((def!.parameters as any).properties.invoice.type).toBe('string');
+    expect((def!.parameters as any).properties.amount_sats.type).toBe('number');
+  });
+
   it('required args declared on the actionable tools', () => {
     expect((getWalletTool('send_payment')!.parameters as any).required).toContain('to');
     expect((getWalletTool('fiat_to_sats')!.parameters as any).required).toEqual(['amount', 'currency']);

package/src/wallet/contract.ts

@@ -56,10 +56,32 @@ const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT',
 /** The full contract. Keep descriptions terse — small models read every word. */
 export const WALLET_TOOLS: WalletToolDef[] = [
   // ── Spark ──────────────────────────────────────────────────────────────
-  t('spark', 'spark_get_balance', 'Get the Spark wallet BTC balance.'),
-  t('spark', 'spark_get_address', 'Get a Spark deposit address to receive BTC.'),
-  t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice to receive BTC.', { amount_sats: sats }),
-  t('spark', 'spark_send', 'Send BTC from Spark to an address or invoice.', { amount_sats: sats, to: { type: 'string', description: 'Address or invoice' } }, ['amount_sats', 'to'], true),
+  t('spark', 'spark_get_balance', 'Get the Spark wallet balances — BTC sats AND every Spark-native token (e.g. USDB). Returns `{ total: <sats>, tokens: [{ address, balance, symbol?, decimals?, available_to_send? }], connected, layer, network }`. Use for ANY "balance / how much / what do I have on Spark" question — call it fresh every time, balances change. The `tokens` array surfaces ALL Spark-native tokens the wallet holds, so you do NOT need to call flashnet_get_balance separately for that (flashnet_get_balance is the AMM-client view of the same wallet and returns the same numbers). For RGB asset balances (USDT, XAUT) use the RLN tools — RGB assets are NOT on Spark.'),
+  // The user-facing "Spark address" — an off-chain Spark identity (sparkrt1…/
+  // spark1…). For OFF-CHAIN peer transfers WITHIN Spark. NOT a Bitcoin
+  // on-chain address. Use spark_get_onchain_address for the on-chain deposit
+  // path; use spark_create_invoice for a Lightning invoice.
+  t('spark', 'spark_get_address', 'Get the user\'s Spark address (sparkrt1…/spark1…) — an OFF-CHAIN Spark identity for receiving Spark-to-Spark transfers. NOT a Bitcoin on-chain address (does not start with bc1/tb1/bcrt1) and NOT a Lightning invoice. For "an on-chain address to deposit BTC into Spark" use spark_get_onchain_address. For a Lightning invoice use spark_create_invoice.'),
+  // Real on-chain Bitcoin address used to deposit BTC FROM mainnet INTO the
+  // Spark wallet. The SDK calls this a "static deposit address" — bc1…/tb1…/
+  // bcrt1…. The opposite of spark_get_address.
+  t('spark', 'spark_get_onchain_address', 'Get a real Bitcoin ON-CHAIN address (bc1…/tb1…/bcrt1…) for depositing BTC from the Bitcoin L1 into the Spark wallet. Use ANY time the user asks for "an on-chain address", "deposit address", "Bitcoin address to fund Spark", "where do I send my on-chain BTC". This is NOT the Spark identity (spark_get_address) and NOT a Lightning invoice (spark_create_invoice).'),
+  t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice (BOLT11) to receive BTC over Lightning. Returns an invoice string the user can share. Use when the user asks for "an invoice", "a lightning invoice", "pay me", or names an amount they want received. NOT an address.', { amount_sats: sats }),
+  // Explicit Lightning-invoice payer. BOLT11 invoices encode the amount, so
+  // `amount_sats` is optional and only used for amount-less ("any-amount")
+  // invoices. Prefer this over `spark_send` when the destination is a BOLT11
+  // invoice — it removes ambiguity for small models and gives the cross-skill
+  // bitrefill flow a single, unambiguous target.
+  t('spark', 'spark_pay_invoice',
+    'Pay a Lightning (BOLT11) invoice from the Spark wallet. The invoice already encodes the amount; pass amount_sats ONLY for amount-less invoices. Use this for any BOLT11 destination (Bitrefill, contact, raw invoice).',
+    { invoice: { type: 'string', description: 'BOLT11 Lightning invoice (lnbc…/lntb…/lnbcrt…).' }, amount_sats: { type: 'number', description: 'Required ONLY when the invoice has no amount; omit otherwise.' } },
+    ['invoice'],
+    /* spend */ true),
+  t('spark', 'spark_send',
+    'Send BTC from Spark to an on-chain address (bc1…/tb1…). For BOLT11 invoices, prefer spark_pay_invoice.',
+    { amount_sats: sats, to: { type: 'string', description: 'On-chain Bitcoin address.' } },
+    ['amount_sats', 'to'],
+    /* spend */ true),
 
   // ── RLN / RGB ──────────────────────────────────────────────────────────
   t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),