@kaleidorg/mind 0.8.1 → 0.10.0

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/bitrefill/index.ts

@@ -0,0 +1,13 @@
+/** Bitrefill (gift cards, top-ups, eSIMs): tool contract. */
+export {
+  BITREFILL_TOOLS,
+  BITREFILL_SPEND_TOOLS,
+  isBitrefillSpendTool,
+  getBitrefillTool,
+  bindBitrefillTools,
+} from './contract.js';
+export type {
+  BitrefillToolDef,
+  BitrefillHandler,
+  BindBitrefillOptions,
+} from './contract.js';

package/src/capabilities.ts

@@ -16,8 +16,8 @@ export interface CapabilityInput {
   modelCtxTokens: number;
   /** Whether an EmbeddingProvider is wired (QVAC embed, etc.). */
   hasEmbeddings?: boolean;
-  /** Running inference on a remote provider (desktop/server) — relaxes limits. */
-  delegated?: boolean;
+  /** Inference runs on a larger remote model (e.g. an OpenAI-compatible server) — relaxes limits. */
+  remote?: boolean;
 }
 
 export interface MindCapabilities {
@@ -27,7 +27,7 @@ export interface MindCapabilities {
   semanticMemory: boolean;
   /** Embedding-only dedup of near-duplicate memories (zero inference — mobile-safe). */
   dedupeMemory: boolean;
-  /** LLM merge of near-duplicate memories (an extra inference — capable/delegated only). */
+  /** LLM merge of near-duplicate memories (an extra inference — capable/remote only). */
   mergeMemory: boolean;
   /** Retrieval-augmented generation (needs embeddings + enough RAM/context). */
   rag: boolean;
@@ -42,7 +42,7 @@ export interface MindCapabilities {
 const GiB = 1024 * 1024 * 1024;
 
 export function capabilityProfile(input: CapabilityInput): MindCapabilities {
-  const ramGb = input.delegated ? Infinity : (input.ramBytes ?? 0) / GiB;
+  const ramGb = input.remote ? Infinity : (input.ramBytes ?? 0) / GiB;
   const ctx = input.modelCtxTokens;
   const hasEmb = !!input.hasEmbeddings;
 
@@ -54,13 +54,13 @@ export function capabilityProfile(input: CapabilityInput): MindCapabilities {
 
   // Consolidation: embedding-only dedup is cheap (no inference) — on wherever
   // semantic memory is. The LLM merge costs an extra inference, so reserve it
-  // for delegated or roomy on-device setups; never run it on a tiny phone model.
+  // for remote or roomy on-device setups; never run it on a tiny phone model.
   const dedupeMemory = semanticMemory;
-  const mergeMemory = dedupeMemory && (input.delegated || (ramGb >= 4 && ctx >= 4096));
+  const mergeMemory = dedupeMemory && (input.remote || (ramGb >= 4 && ctx >= 4096));
 
   // RAG is the expensive one: needs embeddings, a non-tiny context window, and
   // (on-device) enough RAM to hold an embedding model + index.
-  const rag = hasEmb && ctx >= 4096 && (input.delegated || ramGb >= 3);
+  const rag = hasEmb && ctx >= 4096 && (input.remote || ramGb >= 3);
 
   // Scale how much we pull in with the available window.
   const topKMemory = budget >= 1500 ? 4 : budget >= 700 ? 3 : 2;

package/src/context/context.test.ts

@@ -69,8 +69,8 @@ describe('capabilityProfile', () => {
     expect(c.mergeMemory).toBe(false); // never run merge inference on a tiny phone
   });
 
-  it('desktop / delegated: RAG on, memory merge on', () => {
-    const c = capabilityProfile({ modelCtxTokens: 8192, hasEmbeddings: true, delegated: true });
+  it('remote model: RAG on, memory merge on', () => {
+    const c = capabilityProfile({ modelCtxTokens: 8192, hasEmbeddings: true, remote: true });
     expect(c.rag).toBe(true);
     expect(c.topKRag).toBeGreaterThan(0);
     expect(c.semanticMemory).toBe(true);

package/src/engine/answer.ts

@@ -0,0 +1,66 @@
+/**
+ * How an agentic run ends: the Engine's fixed replies, and the checks every
+ * answer the model wrote goes through before the user sees it.
+ *
+ * An answer is tagged with where it came from. Fixed replies are final; only
+ * model text is rewritten (amount fixes) or replaced (payment data no tool
+ * returned). Keeping that rule in one place is what stops a fixed reply that
+ * 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 { fixRgbBalanceUnits } from '../context/rgb-units.js';
+
+export interface Answer {
+  text: string;
+  /** `engine`: one of the fixed replies below, never rewritten. */
+  source: 'model' | 'engine';
+}
+
+export const model = (text: string): Answer => ({ text, source: 'model' });
+export const engine = (text: string): Answer => ({ text, source: 'engine' });
+
+export const STOPPED_REPLY = 'I had to stop after several steps — please try a more specific request.';
+
+export const TOOL_CALL_FAILED_REPLY =
+  "I couldn't put together a valid request for that. Please rephrase it with the exact values (asset, amount, recipient).";
+
+export const REPEATED_CALL_REPLY = 'I could not get a different result from the wallet — please try a more specific request.';
+
+export function cancelledReply(declined: string[]): string {
+  return `Cancelled — you declined: ${declined.join('; ')}. Nothing was sent or changed.`;
+}
+
+/** Fed back to the model after a tool call it emitted could not be parsed. */
+export function toolErrorFeedback(errors: ToolCallError[], cutOff: boolean): string {
+  if (cutOff) {
+    return 'Your tool call was cut off because the output got too long. Make ONE tool call at a time with only the required arguments, or answer from the results you already have.';
+  }
+  const detail = errors.map((e) => e.message).join('; ');
+  return `Your tool call could not be read (${detail}). Call the tool again with valid JSON arguments that match its schema, or ask the user for the missing values.`;
+}
+
+export interface FinalizeOptions {
+  /** Recompute BTC figures and relabel RGB balances. */
+  fixAmounts: boolean;
+  /** Replace answers carrying payment data no tool returned and the user never typed. */
+  guardPaymentData: boolean;
+  /** What the answer may legitimately quote: the user's messages and the tool results. */
+  sources: unknown[];
+  /** Tool results, for relabelling RGB balances. */
+  toolResults: unknown[];
+  aborted: boolean;
+}
+
+/** The text the user sees. */
+export function finalizeAnswer(answer: Answer, opts: FinalizeOptions): string {
+  if (!answer.text) return opts.aborted ? '' : STOPPED_REPLY;
+  if (answer.source === 'engine') return answer.text;
+  let text = answer.text;
+  if (opts.fixAmounts) text = fixRgbBalanceUnits(fixSatsBtcConversions(text), opts.toolResults);
+  if (opts.guardPaymentData) {
+    const ungrounded = findUngroundedPaymentData(text, opts.sources);
+    if (ungrounded.length) text = ungroundedReply(ungrounded);
+  }
+  return text;
+}