@kaleidorg/mind 0.6.0 → 0.6.2

package/skills/merchant-finder/SKILL.md

@@ -2,7 +2,7 @@
 name: merchant-finder
 description: "Find Bitcoin-accepting merchants near the user using live BTC Map data and the device's real location. Triggers when the user asks where to spend Bitcoin, buy pizza/food with sats or bitcoin, eat at restaurants/cafes paying with sats, for a shop, store, restaurant, cafe, bar, or ATM that accepts Bitcoin, or for merchants nearby or in a city like turin."
 tools: find_merchant_locations, search_knowledge
-triggers: merchant, merchants, shop, shops, store, stores, restaurant, restaurants, cafe, cafes, bar, bars, atm, atms, accept, accepts, accepting, nearby, near me, around, place, places, spend, find, pizza, pizz, food, coffee, eat, dinner, lunch, buy, bitcoin map, btcmap
+triggers: merchant, merchants, shop, shops, store, stores, restaurant, restaurants, cafe, cafes, bar, bars, atm, atms, accept, accepts, accepting, nearby, near me, around me, where can i spend, pizza, pizz, food, coffee, eat, dinner, lunch, bitcoin map, btcmap
 metadata:
   author: kaleidoswap
   version: "0.3.0"

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

@@ -1,8 +1,8 @@
 ---
 name: rgb-lightning-node
-description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, needs an invoice, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
-tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_atomic_taker, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice
-triggers: node, nodeinfo, pubkey, peer, channels, whitelist, taker, swapstring, invoice, receive, rgb invoice, ln invoice
+description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, list channels and their capacities, check RGB asset balances, manage channels/peers, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, their channels or capacities, needs an invoice, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
+tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_list_assets, rln_get_asset_balance, rln_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_whitelist_swap, rln_atomic_taker, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice
+triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, inbound, capacity, asset balance, whitelist, taker, swapstring, invoice, receive, rgb invoice, ln invoice
 metadata:
   author: kaleidoswap
   version: "0.1.0"
@@ -47,10 +47,37 @@ Call this when:
   `kaleidoswap_atomic_execute`.
 
 **Do NOT** use this tool's `local_balance_sat` to answer a question about
-**inbound liquidity / receive capacity** — that is a different quantity
-(the peer's side of each channel, not yours). For "how much can I receive?",
-the LSPS skill answers what's available to BUY (`lsp_get_info`); the current
-remote-balance breakdown isn't exposed by this skill's tools.
+**inbound liquidity / receive capacity** — that is a different quantity (the
+peer's side of each channel). For per-channel inbound/outbound and total
+capacity, use `rln_list_channels` (below), NOT this tool.
+
+### `rln_list_channels` — no args
+Returns `{ channels: [...], count }`. Each channel carries:
+- `channel_id`, `peer_alias`, `status`, `ready`, `is_usable`
+- `capacity_sat` — total channel size.
+- `outbound_sat` — what YOU can send (your local balance).
+- `inbound_sat` — what you can RECEIVE on this channel (the peer's side).
+- `asset_id`, `asset_local_amount`, `asset_remote_amount` — for RGB asset
+  channels: the asset and how much is on each side.
+
+Call this when the user asks to **list channels**, asks about **per-channel
+capacity**, **inbound/receive capacity**, or wants to **verify a channel they
+just bought** opened with the requested size. Report each channel as one line:
+`capacity_sat total — outbound_sat / inbound_sat (asset if present), status`.
+
+When verifying a freshly-bought channel: a channel order opens
+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_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.
 
 ### `rln_atomic_taker` — { swapstring } — 🔒 confirm-gated
 Tell the node "I accept this swap." Args: the `swapstring` returned by
@@ -92,7 +119,7 @@ A user-driven swap on KaleidoSwap is a two-service flow. Keep them straight:
 | Pubkey | **node** | `rln_get_node_info` (read `pubkey`) |
 | Whitelist | **node** | `rln_atomic_taker` (pass the swapstring) |
 | Execute | maker | `kaleidoswap_atomic_execute` (needs swapstring + taker_pubkey + payment_hash) |
-| Status | maker | `kaleidoswap_atomic_status` |
+| Status | maker | `kaleidoswap_atomic_status` (pass atomic_id or payment_hash from the atomic recipe summary or prior init result; see "remember" line in history) |
 
 The node's two contributions to the swap are the **pubkey** and the
 **whitelist ack** — nothing more. Don't reach for `/makerinit` or

package/skills/spark-wallet/SKILL.md

@@ -0,0 +1,235 @@
+---
+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
+metadata:
+  author: kaleidoswap
+  version: "1.0.0"
+  layer: spark
+---
+
+# Spark wallet
+
+Spark is one of the user's connected BTC layers (alongside RLN/RGB and Arkade
+on some hosts). It speaks Lightning natively — receive via `spark_create_invoice`,
+send via `spark_pay_invoice` (BOLT11) or `spark_send` (on-chain). All numbers
+are in **satoshis** unless stated otherwise.
+
+## Three "addresses", three different tools (read this carefully)
+
+The word "address" can mean three completely different things on Spark.
+Each has a DIFFERENT tool, a DIFFERENT shape, and a DIFFERENT use. If you
+return the wrong one, the user loses money on a bad deposit. Pick by what
+the user is trying to DO, not just by the word "address":
+
+| User intent | Tool | What you get | Looks like |
+|---|---|---|---|
+| Receive a **Spark-to-Spark** transfer (off-chain, within Spark) | `spark_get_address` | Spark identity / pubkey | `sparkrt1…` / `spark1…` |
+| Deposit **L1 Bitcoin** into Spark from the on-chain world | `spark_get_onchain_address` | Real Bitcoin on-chain address | `bc1…` / `tb1…` / `bcrt1…` |
+| Receive over **Lightning** (BOLT11) | `spark_create_invoice` | A Lightning invoice string | `lnbc…` / `lntb…` / `lnbcrt…` |
+
+**Disambiguation by phrasing — examples:**
+
+- "give me my **on-chain address**" / "**bitcoin address** to fund Spark"
+  / "**deposit address**" / "where do I send BTC from my hardware wallet
+  / mainnet" → `spark_get_onchain_address`. Result starts with bc1/tb1/
+  bcrt1 — verify before replying.
+- "my **Spark address**" / "give me a **Spark address**" / "where do I
+  receive a **Spark transfer**" → `spark_get_address`. Result starts with
+  spark1/sparkrt1. **DO NOT label this as an on-chain address — it is
+  off-chain.**
+- "give me an **invoice for N sats**" / "an **LN invoice**" / "**pay me**
+  N sats" → `spark_create_invoice({amount_sats: N})`. Result is a `lnbc…`
+  string.
+
+**Critical: when the user says "on-chain", they mean L1 Bitcoin.** Never
+return a `sparkrt1…` and call it "on-chain". If you return a
+`spark_get_address` result, you MUST describe it as a Spark (off-chain)
+address — never as an on-chain or Bitcoin address. If you return a
+`spark_get_onchain_address` result, you can call it an on-chain Bitcoin
+deposit address.
+
+A useful sanity check before you send the reply: glance at the
+`address` string's prefix. If it begins with `spark`, it's the off-chain
+Spark identity. If it begins with `bc1`/`tb1`/`bcrt1`, it's an on-chain
+BTC address. If it begins with `lnbc`/`lntb`/`lnbcrt`, it's a Lightning
+invoice. Whatever you call it in your reply MUST match its actual prefix.
+
+## What Spark holds (and what it does NOT)
+
+This is the single most important thing to get right when the user asks
+about "assets on Spark" or "what can I trade on Spark".
+
+**Spark holds:**
+- **BTC** (sats) — Spark's native on-chain-pegged BTC.
+- **Spark-native tokens** — e.g. **USDB**. These are tokens issued on the
+  Spark protocol itself, traded on **Flashnet** (Spark-native AMM).
+
+**Spark does NOT hold:**
+- **RGB assets** (USDT, XAUT, …). RGB assets are a DIFFERENT protocol on
+  Bitcoin/Lightning — they live on the user's **RLN** (RGB Lightning Node),
+  NOT Spark. A USDT balance, if the user has one, is on RLN — never on
+  Spark.
+- Tokens from any other chain (Ethereum USDT, Tron USDT, Solana, …). The
+  wallet does not custody those at all.
+
+**Asset → which skill / venue:**
+
+| Asset | Layer | Swap venue | Skill |
+|---|---|---|---|
+| BTC / sats | Spark / RLN / on-chain | Either (depends on direction) | spark-wallet (Spark side), wallet-assistant |
+| USDB (and other Spark tokens) | Spark | **Flashnet** (AMM) | **flashnet-swaps** |
+| USDT, XAUT (RGB assets) | RLN/RGB | **KaleidoSwap maker** | **kaleido-trading** |
+
+If the user asks "what can I trade on Spark?", the correct answer lists
+Spark-native tokens (BTC + USDB and anything else
+`flashnet_list_pools` shows). **Never** answer USDT/XAUT for Spark.
+Conversely, if asked "what can I trade on KaleidoSwap?", that's RGB
+assets (USDT, XAUT) — **not** USDB.
+
+When in doubt about what's actually tradeable, the source of truth is the
+TOOL, not your training data — call `flashnet_list_pools` (Spark side) or
+`kaleidoswap_get_assets` (RGB side) and report what comes back.
+
+## Critical rules (read first)
+
+1. **Always re-fetch volatile state — every turn, every time.** Balance,
+   address, invoice status, and any number that can change MUST come from a
+   tool call THIS turn. Do NOT reuse a value from a previous turn, even if
+   the user asked the exact same question 30 seconds ago. The user wouldn't
+   ask twice if they didn't want a fresh check.
+
+   - "what's my balance?" → ALWAYS call `spark_get_balance`. Yes, even if
+     you just called it. The whole point of asking again is to get a new
+     reading.
+   - "give me my address" → ALWAYS call `spark_get_address`. Spark may
+     rotate or surface a fresh address.
+   - "did my invoice settle?" → ALWAYS re-fetch the invoice/order status.
+
+   The ONLY thing you can reuse from history is the user's own input
+   (e.g. "the invoice I just made" → look up its id in history and call
+   the status tool on it).
+
+2. **Never invent a balance, invoice or address.** Every BTC number, BOLT11
+   string, and address in your reply MUST come from a Spark tool result
+   returned in the CURRENT turn — never guessed, never quoted from memory.
+
+3. **Read the tool result exactly.** `spark_get_balance` returns
+   `{ total, layer, network, connected }`. `connected: true` means the
+   Spark wallet IS active and reachable; `total: 0` with `connected: true`
+   simply means the user has no sats yet (perfectly normal for a fresh
+   wallet on regtest). Do NOT say "your wallet isn't connected" unless
+   `connected: false` or the tool threw an error. Say "your Spark wallet
+   is connected but empty — fund it with `spark_get_address`" when
+   `total: 0, connected: true`.
+
+4. **Choose the right send tool by destination shape.**
+   - Starts with `lnbc…` / `lntb…` / `lnbcrt…` → BOLT11 Lightning invoice → use
+     **`spark_pay_invoice`**.
+   - Starts with `bc1…` / `tb1…` / `bcrt1…` → on-chain Bitcoin address → use
+     **`spark_send`**.
+   - Looks like `name@domain` (a Lightning address) → not a Spark target;
+     either ask the host to resolve it first or use the cross-cutting
+     `send_payment` router. Spark itself doesn't dereference LNURL.
+
+5. **BOLT11 invoices encode their amount.** Don't pass `amount_sats` to
+   `spark_pay_invoice` unless the invoice is amount-less. Re-stating the
+   amount can produce silently-wrong sends on amount-less invoices.
+
+6. **Confirm before spending.** `spark_pay_invoice` and `spark_send` are
+   confirmation-gated by the contract — the host fires the gate
+   automatically. Before the call, summarize in one line:
+   `Paying 12,540 sats to lnbc12540n… from Spark. Confirm?`
+
+7. **Spark genuinely unavailable = stop, don't guess.** If the tool
+   THROWS with "Your SPARK wallet isn't connected yet" (an actual error,
+   not a 0 balance), say so plainly and stop — don't substitute RLN or
+   Arkade silently. The user may genuinely want Spark.
+
+8. **Never refuse an action a listed tool performs.** If a tool in your
+   set does what the user asked, CALL IT — do not reason about whether
+   "get" means "create", whether the wording is an exact match, or
+   whether some other tool would be "more correct". The user asking to
+   "create an address" when you have `spark_get_address` means: call
+   `spark_get_address`. Refusing to use an available tool is always wrong.
+
+## How to call the tools
+
+### Reads
+
+- **`spark_get_balance({})`** — current Spark balances. Returns the BTC
+  balance (`total` in sats) AND every Spark-native **token** the wallet
+  holds (`tokens[]` — each with `address`, `balance`, optional `symbol`
+  and `decimals`). When the user asks "what do I have on Spark" or
+  "what's my Spark balance", surface BOTH the sats AND any non-zero
+  token balances; an answer that only mentions BTC when tokens are
+  present is incomplete.
+  - `flashnet_get_balance` returns the same numbers (it's the AMM-client
+    view of the same wallet) — there's no need to call it just to learn
+    the token balance.
+- **`spark_get_address({})`** — the user's **Spark identity**
+  (`sparkrt1…`/`spark1…`), an OFF-CHAIN Spark-to-Spark receive target.
+  Reusable — getting and creating are the same operation, so the right
+  response to "create a Spark address" is ALSO this tool. NEVER call its
+  result an on-chain address or a Bitcoin address; it is neither. NEVER
+  reply "I cannot create an address" — this tool IS how you create one.
+- **`spark_get_onchain_address({})`** — a real Bitcoin **on-chain
+  deposit** address (`bc1…`/`tb1…`/`bcrt1…`) for funding Spark from L1.
+  Use whenever the user says "on-chain", "bitcoin address", "deposit
+  address", "fund Spark", or otherwise indicates they want to send L1
+  BTC. NEVER substitute `spark_get_address` here.
+
+### Receive
+
+- **`spark_create_invoice({ amount_sats? })`** — Spark Lightning invoice.
+  - Omit `amount_sats` for an "any amount" invoice.
+  - Returns `{ invoice: "lnbc…", … }`.
+  - This is the tool for "give me an invoice for N sats", NOT for any
+    "address" ask.
+
+### Send — pick by destination
+
+- **`spark_pay_invoice({ invoice, amount_sats? })`** — pay a BOLT11 invoice.
+  - The model's default Lightning spend tool. Use this for invoices from
+    Bitrefill, a contact's invoice paste, or any `ln…` string.
+  - Pass `amount_sats` ONLY when the invoice is amount-less (a 0-amount
+    invoice). For ordinary amount-bound invoices, OMIT it.
+- **`spark_send({ amount_sats, to })`** — on-chain Bitcoin send.
+  - Use only when `to` is an on-chain address (`bc1…`). Never pass a BOLT11
+    invoice here.
+
+### Helpers
+
+- **`get_price({ fiat? })`** / **`fiat_to_sats({ amount, currency })`** —
+  for "how many sats is €10" style sub-questions before a Spark spend.
+
+## Cross-skill flow with Bitrefill
+
+When the user wants to buy something from Bitrefill and pay with Spark, the
+typical chain is:
+
+1. Call `bitrefill_search` / `bitrefill_get_product` to confirm the product +
+   the right `package_id` (see the `bitrefill` skill).
+2. Call `bitrefill_create_invoice({ products, payment_method: "lightning",
+   refund_address: <a Spark or on-chain address> })` — Bitrefill returns a
+   BOLT11 invoice on the response under `payment.lightning_invoice` (or
+   similar — relay whatever the host surfaces).
+3. **Pay with Spark**: `spark_pay_invoice({ invoice: <that BOLT11> })`. One
+   confirmation gate; Spark settles the invoice in seconds.
+4. Poll `bitrefill_get_invoice` until `status:"complete"`, then
+   `bitrefill_get_order` for the redemption code.
+
+If the user pre-funded a Bitrefill account, prefer
+`payment_method:"balance"` instead — no Spark spend, instant settlement. Use
+the Lightning path when the user explicitly says "pay with Spark/Lightning"
+or has no Bitrefill balance.
+
+## Reply style
+
+- One short sentence per fact ("Spark holds 124,500 sats.").
+- For invoices: show the invoice on its own line so the user can copy it.
+- For sends: one-line pre-spend summary (amount + destination + "from
+  Spark"), then the result.
+- When `spark_get_balance` says zero and the user asked to spend, stop and
+  say so — don't try to source funds from another layer silently.

package/skills/wallet-assistant/SKILL.md

@@ -1,8 +1,8 @@
 ---
 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, resolve_contact, send_payment, rln_send_btc, wdk_send_btc, rln_send_asset, wdk_send_asset, spark_send_sats, rln_pay_invoice, wdk_pay_invoice, spark_pay_lightning_invoice, rln_create_ln_invoice, wdk_create_ln_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, sats
+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
 ---
 
 # Wallet assistant

package/src/bitrefill/contract.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BITREFILL_TOOLS,
+  BITREFILL_SPEND_TOOLS,
+  isBitrefillSpendTool,
+  getBitrefillTool,
+  bindBitrefillTools,
+  type BitrefillHandler,
+} from './contract.js';
+
+describe('BITREFILL_TOOLS — shape invariants', () => {
+  it('exposes the expected tool names in order', () => {
+    expect(BITREFILL_TOOLS.map((t) => t.name)).toEqual([
+      'bitrefill_search',
+      'bitrefill_get_product',
+      'bitrefill_get_balance',
+      'bitrefill_create_invoice',
+      'bitrefill_get_invoice',
+      'bitrefill_get_order',
+    ]);
+  });
+
+  it('every tool has an object parameters schema', () => {
+    for (const t of BITREFILL_TOOLS) {
+      expect((t.parameters as any)?.type).toBe('object');
+    }
+  });
+
+  it('aligns spend ↔ requiresConfirmation', () => {
+    for (const t of BITREFILL_TOOLS) {
+      expect(!!t.spend).toBe(!!t.requiresConfirmation);
+    }
+  });
+
+  it('marks only bitrefill_create_invoice as spend', () => {
+    expect([...BITREFILL_SPEND_TOOLS]).toEqual(['bitrefill_create_invoice']);
+    expect(isBitrefillSpendTool('bitrefill_create_invoice')).toBe(true);
+    expect(isBitrefillSpendTool('bitrefill_search')).toBe(false);
+    expect(isBitrefillSpendTool('bitrefill_get_balance')).toBe(false);
+  });
+
+  it('getBitrefillTool returns by name', () => {
+    expect(getBitrefillTool('bitrefill_get_product')?.name).toBe('bitrefill_get_product');
+    expect(getBitrefillTool('nope')).toBeUndefined();
+  });
+
+  it('create_invoice requires products + payment_method', () => {
+    const def = getBitrefillTool('bitrefill_create_invoice')!;
+    expect((def.parameters as any).required).toEqual(['products', 'payment_method']);
+  });
+});
+
+describe('bindBitrefillTools', () => {
+  const echoHandlers = (): Record<string, BitrefillHandler> => ({
+    bitrefill_search:         async (a) => ({ ok: true, t: 'search', args: a }),
+    bitrefill_get_product:    async (a) => ({ ok: true, t: 'get_product', args: a }),
+    bitrefill_get_balance:    async () => ({ balance: 100, currency: 'USD' }),
+    bitrefill_create_invoice: async (a) => ({ ok: true, t: 'create_invoice', args: a }),
+    bitrefill_get_invoice:    async (a) => ({ ok: true, t: 'get_invoice', args: a }),
+    bitrefill_get_order:      async (a) => ({ ok: true, t: 'get_order', args: a }),
+  });
+
+  it('binds every tool and preserves the spend gate', () => {
+    const src = bindBitrefillTools(echoHandlers());
+    expect(src.listTools().length).toBe(6);
+    const create = src.listTools().find((t) => t.name === 'bitrefill_create_invoice');
+    expect(create?.requiresConfirmation).toBe(true);
+    const search = src.listTools().find((t) => t.name === 'bitrefill_search');
+    expect(search?.requiresConfirmation).toBeFalsy();
+  });
+
+  it('dispatches with args', async () => {
+    const src = bindBitrefillTools(echoHandlers());
+    const r = await src.execute('bitrefill_search', { query: 'amazon', country: 'US' });
+    expect(r).toMatchObject({ ok: true, t: 'search', args: { query: 'amazon', country: 'US' } });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    const partial = { bitrefill_search: echoHandlers().bitrefill_search };
+    expect(() => bindBitrefillTools(partial)).toThrow(/no handler/);
+    const src = bindBitrefillTools(partial, { allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['bitrefill_search']);
+  });
+
+  it('uses opts.id for the ToolSource id', () => {
+    const src = bindBitrefillTools(echoHandlers(), { id: 'bitrefill-personal' });
+    expect(src.id).toBe('bitrefill-personal');
+  });
+});

package/src/bitrefill/contract.ts

@@ -0,0 +1,190 @@
+/**
+ * Canonical Bitrefill tool contract — gift cards, mobile top-ups, eSIMs.
+ *
+ * Same pattern as the LSPS1 contract: the tool *names + schemas* live here so
+ * every host (CLI REST adapter, desktop MCP, mobile WDK adapter) exposes the
+ * exact same surface to the agent. Only the transport differs.
+ *
+ *   - CLI / desktop server → REST against `https://api.bitrefill.com/v2`
+ *     (see `apps/cli/src/bitrefillTools.ts`).
+ *   - Desktop sidecar      → the remote MCP at `api.bitrefill.com/mcp` already
+ *     exposes equivalent tools under different names; a binder there can
+ *     rename them to this contract for parity.
+ *
+ * `bitrefill_create_invoice` is the spend — confirmation-gated by the contract.
+ * Everything else is read-only (search, product details, balance, invoice/order
+ * status). Invoice creation supports `payment_method:"balance"` (instant, pulls
+ * from pre-funded account) or `lightning|bitcoin|usdc_base|...` (the response
+ * carries a payment URI/invoice; the user pays out-of-band, then the order is
+ * fulfilled).
+ *
+ * Pure data — no deps, no fetch, RN-safe.
+ */
+
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { InProcessTool } from '../tools/in-process.js';
+
+export interface BitrefillToolDef extends ToolDef {
+  /** Moves real money → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<
+  string,
+  { type: string; description?: string; enum?: string[]; items?: unknown }
+>;
+
+function t(
+  name: string,
+  description: string,
+  properties: Props = {},
+  required: string[] = [],
+  spend = false,
+): BitrefillToolDef {
+  return {
+    name,
+    description,
+    spend,
+    requiresConfirmation: spend,
+    parameters: { type: 'object', properties, required },
+  };
+}
+
+/**
+ * The canonical Bitrefill tool list. Each host's binder translates these
+ * args into the Bitrefill REST body (CLI) or MCP/CLI call (other hosts).
+ */
+export const BITREFILL_TOOLS: BitrefillToolDef[] = [
+  t(
+    'bitrefill_search',
+    "Search Bitrefill's product catalog by keyword (brand, country, type). Returns up to ~20 matches with `id`, `name`, `country`, `category` and `denominations`. The model picks the right product id and then calls `bitrefill_get_product` for the package list.",
+    {
+      query: { type: 'string', description: 'Search keyword. e.g. "amazon", "steam", "vodafone uk", "esim europe".' },
+      country: { type: 'string', description: 'OPTIONAL — ISO country code to scope results (e.g. "US", "GB", "DE"). Many brands are country-specific.' },
+      limit: { type: 'number', description: 'OPTIONAL — max results (1–25, default 10).' },
+    },
+    ['query'],
+  ),
+
+  t(
+    'bitrefill_get_product',
+    "Get full details for one product, including its `packages` array (each package = a denomination with `id`, `value`, `price`, `currency`). Use the package `id` (NOT the bare value) when creating an invoice.",
+    {
+      product_id: { type: 'string', description: 'Product slug from bitrefill_search, e.g. "amazon-us", "steam-us".' },
+    },
+    ['product_id'],
+  ),
+
+  t(
+    'bitrefill_get_balance',
+    "Get the user's Bitrefill account balance (the pre-funded pool used by `payment_method:\"balance\"`). Returns `{ balance, currency }`. No args.",
+  ),
+
+  t(
+    'bitrefill_create_invoice',
+    "SPEND: confirmation-gated. Create an invoice for one or more products. Pass `payment_method:\"balance\"` + `auto_pay:true` for instant fulfillment from the account balance (lowest blast radius). For Lightning/on-chain, omit `auto_pay`, set `payment_method:\"lightning\"` (etc.) and `refund_address` — the response carries the payment URI; poll `bitrefill_get_invoice` until status=\"complete\" and then read the order. Up to 20 line items per invoice.",
+    {
+      products: {
+        type: 'array',
+        description: 'Line items. Each: { product_id, package_id, quantity }. Get `package_id` from bitrefill_get_product (NOT the bare denomination value).',
+        items: {
+          type: 'object',
+          properties: {
+            product_id: { type: 'string' },
+            package_id: { type: 'string' },
+            quantity: { type: 'number' },
+          },
+          required: ['product_id', 'package_id', 'quantity'],
+        },
+      },
+      payment_method: {
+        type: 'string',
+        description: 'How to pay: "balance" (account balance, instant), "lightning", "bitcoin", "usdc_base" (x402), "usdc_polygon", "usdt_tron", etc.',
+        enum: ['balance', 'lightning', 'bitcoin', 'usdc_base', 'usdc_polygon', 'usdc_ethereum', 'usdt_tron', 'usdt_ethereum'],
+      },
+      auto_pay: { type: 'boolean', description: 'Required true with `payment_method:"balance"` for instant settlement. Omit for crypto methods.' },
+      refund_address: { type: 'string', description: 'REQUIRED for non-balance crypto methods — refund destination if the invoice expires or partially pays.' },
+      email: { type: 'string', description: 'OPTIONAL — delivery / receipt email. Defaults to the account email when authenticated.' },
+      webhook_url: { type: 'string', description: 'OPTIONAL — URL Bitrefill calls when the order is delivered.' },
+    },
+    ['products', 'payment_method'],
+    /* spend */ true,
+  ),
+
+  t(
+    'bitrefill_get_invoice',
+    "Get the invoice's current status: `unpaid`, `pending`, `paid`, `complete`, `expired`, `failed`. For crypto payment methods, poll this until `complete`; then call `bitrefill_get_order` for redemption details.",
+    {
+      invoice_id: { type: 'string', description: 'Invoice id returned by bitrefill_create_invoice.' },
+    },
+    ['invoice_id'],
+  ),
+
+  t(
+    'bitrefill_get_order',
+    "Get an order's redemption details once delivered. Returns `redemption_info` containing the code, PIN (for prepaid cards), redemption link, instructions. ONLY call after the corresponding invoice status is `complete`. Treat the returned code as cash — never paste it in shared chats.",
+    {
+      order_id: { type: 'string', description: 'Order id from a completed invoice (`order_id` on the invoice or in its `orders[]`).' },
+    },
+    ['order_id'],
+  ),
+];
+
+/** All Bitrefill tool names that move money (confirmation-gated). */
+export const BITREFILL_SPEND_TOOLS: Set<string> = new Set(
+  BITREFILL_TOOLS.filter((t) => t.spend).map((t) => t.name),
+);
+
+export function isBitrefillSpendTool(name: string): boolean {
+  return BITREFILL_SPEND_TOOLS.has(name);
+}
+
+export function getBitrefillTool(name: string): BitrefillToolDef | undefined {
+  return BITREFILL_TOOLS.find((t) => t.name === name);
+}
+
+/** A handler bound to one Bitrefill tool. */
+export type BitrefillHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindBitrefillOptions {
+  /** Skip tools without a handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  /** ToolSource id for the registry (default 'bitrefill'). */
+  id?: string;
+}
+
+/**
+ * Bind Bitrefill contract tools to in-process handlers → an InProcessToolSource.
+ *
+ *   const source = bindBitrefillTools({
+ *     bitrefill_search:         async (args) => api.search(args),
+ *     bitrefill_get_product:    async ({ product_id }) => api.product(product_id),
+ *     bitrefill_get_balance:    async () => api.balance(),
+ *     bitrefill_create_invoice: async (args) => api.createInvoice(args),
+ *     bitrefill_get_invoice:    async ({ invoice_id }) => api.invoice(invoice_id),
+ *     bitrefill_get_order:      async ({ order_id }) => api.order(order_id),
+ *   });
+ *   tools.register(source);
+ */
+export function bindBitrefillTools(
+  handlers: Record<string, BitrefillHandler>,
+  opts: BindBitrefillOptions = {},
+): InProcessToolSource {
+  const bound: InProcessTool[] = [];
+  for (const def of BITREFILL_TOOLS) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindBitrefillTools: no handler for "${def.name}"`);
+    }
+    bound.push({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+      requiresConfirmation: def.requiresConfirmation,
+      handler,
+    });
+  }
+  return new InProcessToolSource(opts.id ?? 'bitrefill', bound);
+}