@kaleidorg/mind 0.6.4 → 0.7.0

package/src/qvac/stream.ts

@@ -55,6 +55,28 @@ export interface ConsumedTurn extends ParsedTurn {
   };
 }
 
+/**
+ * Since QVAC 0.11 a cancelled run ends `events` normally but REJECTS `final`
+ * with `InferenceCancelledError { requestId, partial }`. Fold that back into a
+ * `final` frame with stopReason 'cancelled' so a stop or a blown thinking budget
+ * is a result, not an exception. Matched structurally to stay SDK-free.
+ */
+function cancelledFinal(err: unknown): QvacFinalLike | null {
+  const e = err as {
+    requestId?: unknown;
+    partial?: { text?: string; toolCalls?: QvacFinalLike['toolCalls']; stats?: QvacFinalLike['stats'] };
+  } | null;
+  const named = (err as { constructor?: { name?: string } } | null)?.constructor?.name === 'InferenceCancelledError';
+  if (!e || !(named || (typeof e.requestId === 'string' && typeof e.partial === 'object'))) return null;
+  const partial = e.partial ?? {};
+  return {
+    contentText: partial.text ?? '',
+    toolCalls: partial.toolCalls ?? [],
+    ...(partial.stats ? { stats: partial.stats } : {}),
+    stopReason: 'cancelled',
+  };
+}
+
 /** Rough token estimate (~4 chars/token) — same heuristic the context budget uses. */
 function approxTokens(chars: number): number {
   return Math.ceil(chars / 4);
@@ -95,7 +117,14 @@ export async function consumeRun(
       }
     }
   }
-  const final = await run.final;
+  let final: QvacFinalLike;
+  try {
+    final = await run.final;
+  } catch (err) {
+    const recovered = cancelledFinal(err);
+    if (!recovered) throw err;
+    final = recovered;
+  }
   const finishedAt = now();
   return {
     ...finalToTurn(final, streamed),

package/src/qvac/tools.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { toQvacTools } from './tools.js';
+import { WALLET_TOOLS } from '../wallet/contract.js';
+
+describe('toQvacTools', () => {
+  it('returns undefined for no tools', () => {
+    expect(toQvacTools([])).toBeUndefined();
+  });
+
+  it('keeps JSON-Schema parameters as a full function tool', () => {
+    const [tool] = toQvacTools([
+      {
+        name: 'rln_send_btc',
+        description: 'send',
+        parameters: {
+          type: 'object',
+          properties: {
+            address: { type: 'string', description: 'Destination' },
+            amount_sat: { type: 'integer' },
+            note: { type: ['string', 'null'] },
+            mode: { anyOf: [{ type: 'null' }, { type: 'boolean' }] },
+            tags: { type: 'array', items: { type: 'string' } },
+            schema: { type: 'string', enum: ['NIA', 'CFA'] },
+          },
+          required: ['address', 'amount_sat', 'ghost'],
+          additionalProperties: false,
+        },
+      },
+    ])!;
+    expect(tool).toEqual({
+      type: 'function',
+      name: 'rln_send_btc',
+      description: 'send',
+      parameters: {
+        type: 'object',
+        properties: {
+          address: { type: 'string', description: 'Destination' },
+          amount_sat: { type: 'integer' },
+          note: { type: 'string' },
+          mode: { type: 'boolean' },
+          tags: { type: 'array' },
+          schema: { type: 'string', enum: ['NIA', 'CFA'] },
+        },
+        required: ['address', 'amount_sat'],
+      },
+    });
+  });
+
+  it('passes an all-Zod tool list through for the SDK to convert', () => {
+    const zodish = { shape: {} };
+    expect(toQvacTools([{ name: 'a', description: 'd', parameters: zodish }])).toEqual([
+      { name: 'a', description: 'd', parameters: zodish },
+    ]);
+  });
+
+  it('converts Zod-like tools when mixed with JSON-Schema tools', () => {
+    const zodish = {
+      shape: {
+        city: { type: 'string', description: 'City' },
+        unit: { type: 'optional', def: { innerType: { type: 'enum', def: { entries: { c: 'c', f: 'f' } } } } },
+      },
+    };
+    const out = toQvacTools([
+      { name: 'weather', description: 'w', parameters: zodish },
+      { name: 'ping', description: 'p', parameters: { type: 'object', properties: {} } },
+    ])!;
+    expect(out[0]).toEqual({
+      type: 'function',
+      name: 'weather',
+      description: 'w',
+      parameters: {
+        type: 'object',
+        properties: { city: { type: 'string', description: 'City' }, unit: { type: 'string', enum: ['c', 'f'] } },
+        required: ['city'],
+      },
+    });
+  });
+
+  it('every wallet contract tool keeps its arguments', () => {
+    const out = toQvacTools(WALLET_TOOLS) as Array<{ name: string; parameters: { properties: object } }>;
+    for (const def of WALLET_TOOLS) {
+      const mapped = out.find((t) => t.name === def.name)!;
+      expect(Object.keys(mapped.parameters.properties)).toEqual(Object.keys((def.parameters as any).properties));
+    }
+  });
+});

package/src/qvac/tools.ts

@@ -0,0 +1,106 @@
+/**
+ * Map engine ToolDefs to the tool shape `completion({ tools })` accepts.
+ *
+ * The SDK picks a mode from the FIRST tool: a full `Tool`
+ * (`{ type: 'function', name, description, parameters: <flat JSON Schema> }`)
+ * or a Zod `ToolInput`. A plain JSON-Schema def without `type: 'function'`
+ * falls into the Zod branch, which reads `parameters.shape` and silently drops
+ * every argument — the model then sees tool names with no parameters. So
+ * JSON-Schema tools (wallet contract, MCP) are normalised to full `Tool`s here.
+ * An all-Zod tool list is passed through for the SDK to convert, as before.
+ */
+import type { ToolDef } from '../types.js';
+
+type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'integer';
+const PROP_TYPES = new Set<PropType>(['string', 'number', 'boolean', 'object', 'array', 'integer']);
+
+export interface QvacToolProp {
+  type: PropType;
+  description?: string;
+  enum?: Array<string | number | boolean | null>;
+}
+
+export interface QvacTool {
+  type: 'function';
+  name: string;
+  description: string;
+  parameters: { type: 'object'; properties: Record<string, QvacToolProp>; required?: string[] };
+}
+
+type Obj = Record<string, any>;
+
+function isZodLike(p: unknown): boolean {
+  const o = p as Obj | null;
+  return !!o && typeof o === 'object' && ('shape' in o || '_def' in o || 'def' in o) && !('properties' in o);
+}
+
+function pickType(s: Obj): PropType {
+  const t = Array.isArray(s.type) ? s.type.find((x: unknown) => x !== 'null') : s.type;
+  if (PROP_TYPES.has(t)) return t;
+  for (const alt of [...(s.anyOf ?? []), ...(s.oneOf ?? [])]) {
+    if (alt && typeof alt === 'object' && alt.type !== 'null') return pickType(alt);
+  }
+  if (Array.isArray(s.enum) && s.enum.length) {
+    const first = typeof s.enum[0];
+    if (first === 'number' || first === 'boolean') return first;
+  }
+  return 'string';
+}
+
+function jsonProp(s: Obj): QvacToolProp {
+  const prop: QvacToolProp = { type: pickType(s ?? {}) };
+  if (typeof s?.description === 'string') prop.description = s.description;
+  if (Array.isArray(s?.enum)) {
+    const values = s.enum.filter((v: unknown) => v === null || ['string', 'number', 'boolean'].includes(typeof v));
+    if (values.length) prop.enum = values;
+  }
+  return prop;
+}
+
+function zodProp(field: Obj): { prop: QvacToolProp; optional: boolean } {
+  const kind = field?.type ?? field?.def?.type ?? 'string';
+  const optional = kind === 'optional';
+  const inner = optional ? field.def?.innerType ?? {} : field;
+  const innerKind = inner.type ?? inner.def?.type ?? 'string';
+  const prop: QvacToolProp = { type: PROP_TYPES.has(innerKind) ? innerKind : 'string' };
+  const description = field.description ?? inner.description;
+  if (description) prop.description = description;
+  const values = inner.def?.values ?? inner.def?.entries;
+  if (Array.isArray(values)) prop.enum = values;
+  else if (values && typeof values === 'object') prop.enum = Object.values(values);
+  return { prop, optional };
+}
+
+function toQvacTool(t: Pick<ToolDef, 'name' | 'description' | 'parameters'>): QvacTool {
+  const p = (t.parameters ?? {}) as Obj;
+  const properties: Record<string, QvacToolProp> = {};
+  const required: string[] = [];
+  if (isZodLike(p)) {
+    const shape = p.shape ?? p.def?.shape ?? {};
+    for (const [key, field] of Object.entries(shape as Obj)) {
+      const { prop, optional } = zodProp(field as Obj);
+      properties[key] = prop;
+      if (!optional) required.push(key);
+    }
+  } else {
+    for (const [key, s] of Object.entries((p.properties ?? {}) as Obj)) properties[key] = jsonProp(s as Obj);
+    for (const key of Array.isArray(p.required) ? p.required : []) if (key in properties) required.push(key);
+  }
+  return {
+    type: 'function',
+    name: t.name,
+    description: t.description ?? '',
+    parameters: { type: 'object', properties, ...(required.length ? { required } : {}) },
+  };
+}
+
+/** Tools for `completion()`; undefined when there are none. */
+export function toQvacTools(
+  tools: ReadonlyArray<Pick<ToolDef, 'name' | 'description' | 'parameters'>>,
+): QvacTool[] | Array<Pick<ToolDef, 'name' | 'description' | 'parameters'>> | undefined {
+  if (!tools.length) return undefined;
+  if (tools.every((t) => isZodLike(t.parameters))) {
+    return tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters }));
+  }
+  return tools.map(toQvacTool);
+}

package/src/recipe/issue-asset.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi } from 'vitest';
+import { extractIssueAsset, issueAssetRecipe } from './issue-asset.js';
+import { runRecipe } from './runner.js';
+import { Funnel } from '../funnel.js';
+import { confirmReadback } from '../wallet/confirm.js';
+import { MockWallet, scriptedProvider } from '../testing/index.js';
+
+describe('extractIssueAsset (deterministic Tier-0)', () => {
+  it('ticker + supply + quoted-less name', () => {
+    expect(extractIssueAsset('issue 1000 TICKET tokens called Hackathon Ticket')).toEqual({
+      name: 'Hackathon Ticket', ticker: 'TICKET', amount: 1000, schema: 'NIA',
+    });
+  });
+  it('explicit ticker keyword and k shorthand', () => {
+    expect(extractIssueAsset('mint 21k tokens named "Pizza Points" with ticker pizza')).toEqual({
+      name: 'Pizza Points', ticker: 'PIZZA', amount: 21_000, schema: 'NIA',
+    });
+  });
+  it('NFT → UDA with supply 1, ticker derived from the name', () => {
+    expect(extractIssueAsset('mint an NFT called Genesis Badge')).toEqual({
+      name: 'Genesis Badge', ticker: 'GENESISB', amount: 1, schema: 'UDA',
+    });
+  });
+  it('Italian phrasing', () => {
+    expect(extractIssueAsset('crea 500 token CAFE chiamati Caffè Club')).toEqual({
+      name: 'Caffè Club', ticker: 'CAFE', amount: 500, schema: 'NIA',
+    });
+  });
+  it('ignores invoices, channels, sends and swaps', () => {
+    expect(extractIssueAsset('create an invoice for 10 USDT tokens')).toBeNull();
+    expect(extractIssueAsset('create a channel with 100 USDT')).toBeNull();
+    expect(extractIssueAsset('send 10 tokens to bob')).toBeNull();
+    expect(extractIssueAsset('what is my balance')).toBeNull();
+    expect(issueAssetRecipe.match!('buy 100 USDT tokens')).toBe(false);
+  });
+});
+
+describe('issue-asset readback', () => {
+  it('fungible: supply + ticker + name', () => {
+    expect(confirmReadback({ name: 'rln_issue_asset', arguments: { name: 'Hackathon Ticket', ticker: 'TICKET', amount: 1000 } }))
+      .toBe('Issue 1,000 TICKET (Hackathon Ticket), a new RGB asset. Confirm?');
+  });
+  it('UDA: unique asset wording', () => {
+    expect(confirmReadback({ name: 'rln_issue_asset', arguments: { name: 'Genesis Badge', ticker: 'GENESISB', amount: 1, schema: 'UDA' } }))
+      .toBe('Issue unique asset GENESISB (Genesis Badge) on RGB. Confirm?');
+  });
+});
+
+describe('runRecipe — issue asset against MockWallet', () => {
+  it('one confirmation, asset lands in the wallet', async () => {
+    const wallet = new MockWallet();
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const res = await runRecipe(issueAssetRecipe, 'issue 1000 TICKET tokens called Hackathon Ticket', {
+      provider: scriptedProvider(), tools: wallet.registry(), onConfirm,
+    });
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0);
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(wallet.assets.TICKET).toBe(1000);
+    expect(res.text).toMatch(/^Issued 1000 TICKET\. Asset id: rgb:mock-ticket-/);
+  });
+
+  it('declined confirmation issues nothing', async () => {
+    const wallet = new MockWallet();
+    const res = await runRecipe(issueAssetRecipe, 'issue 1000 TICKET tokens', {
+      provider: scriptedProvider(), tools: wallet.registry(), onConfirm: async () => ({ approved: false }),
+    });
+    expect(res.status).toBe('cancelled');
+    expect(wallet.assets.TICKET).toBeUndefined();
+  });
+
+  it('surfaces the node-style "no UTXOs" failure', async () => {
+    const wallet = new MockWallet({ utxos: 0 });
+    const res = await runRecipe(issueAssetRecipe, 'issue 1000 TICKET tokens', {
+      provider: scriptedProvider(), tools: wallet.registry(), onConfirm: async () => ({ approved: true }),
+    });
+    expect(res.status).toBe('error');
+    expect(res.error ?? res.text).toMatch(/rln_create_utxos/);
+  });
+});
+
+describe('Funnel — issue-asset as an opt-in recipe', () => {
+  it('routes to the recipe tier and is listable afterwards', async () => {
+    const wallet = new MockWallet();
+    const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry(), recipes: [issueAssetRecipe] });
+    const out = await funnel.runTurn('mint an NFT called Genesis Badge', { onConfirm: async () => ({ approved: true }) });
+    expect(out.tier).toBe('recipe');
+    expect(out.route).toBe('issue-asset');
+    const listed = (await wallet.registry().execute('rln_list_assets', {})) as { assets: Array<{ ticker: string; schema: string }> };
+    expect(listed.assets.find((a) => a.ticker === 'GENESISB')?.schema).toBe('UDA');
+  });
+});

package/src/recipe/issue-asset.ts

@@ -0,0 +1,95 @@
+/**
+ * "Issue an RGB asset" recipe — the hackathon one-liner:
+ *
+ *   "issue 1000 TICKET tokens called Hackathon Ticket"  → rln_issue_asset 🔒
+ *   "mint an NFT called Genesis Badge"                  → rln_issue_asset 🔒 (UDA)
+ *   "crea 500 token CAFE chiamati Caffè Club"           → rln_issue_asset 🔒
+ *
+ * No intermediate steps: the plan is a single gated call, so the recipe's job
+ * is the slot extraction (name / ticker / supply / schema) and a deterministic
+ * readback — exactly the part a 0.6B model gets wrong. Opt-in: register via
+ * `Funnel.recipes` on hosts that bind `rln_issue_asset`.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+
+const VERB = /\b(issue|mint|create|launch|emetti|conia|crea)\b/i;
+const NOUN = /\b(tokens?|assets?|coins?|nfts?|tickets?|gettoni|badges?)\b/i;
+const NOT_ISSUE = /\b(invoice|fattura|channel|canale|swap|buy|sell|send|pay|compra|vendi|invia|paga)\b/i;
+const NFT = /\b(nfts?|unique|unico|unica)\b/i;
+// Words that look like tickers but are part of the request, not the asset.
+const STOPWORDS = new Set(['RGB', 'NFT', 'NFTS', 'NIA', 'CFA', 'UDA', 'BTC', 'LN', 'AN', 'A']);
+
+function parseAmount(t: string): number | undefined {
+  const m = t.match(/(?:^|\s)(\d[\d.,]*)\s*([km])?(?=\s|$)/i);
+  if (!m) return undefined;
+  let n = Number(m[1]!.replace(/,/g, ''));
+  if (m[2]) n *= m[2].toLowerCase() === 'k' ? 1_000 : 1_000_000;
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+function parseName(t: string): string | undefined {
+  const quoted = t.match(/["“'‘]([^"”'’]{1,40})["”'’]/)?.[1];
+  if (quoted) return quoted.trim();
+  const m = t.match(/\b(?:called|named|chiamat[oaie])\s+(.+?)(?=\s+(?:with|ticker|con)\b|[,.;]|$)/i);
+  return m?.[1]?.trim() || undefined;
+}
+
+function parseTicker(t: string, name?: string): string | undefined {
+  const explicit = t.match(/\bticker\s+([A-Za-z0-9]{1,8})\b/i)?.[1];
+  if (explicit) return explicit.toUpperCase();
+  // An all-caps word that isn't part of the name ("1000 TICKET tokens").
+  const nameWords = new Set((name ?? '').split(/\s+/));
+  for (const w of t.match(/\b[A-Z][A-Z0-9]{1,7}\b/g) ?? []) {
+    if (!STOPWORDS.has(w) && !nameWords.has(w)) return w;
+  }
+  return undefined;
+}
+
+/** Ticker fallback from the name: "Hackathon Ticket" → "HACKATHO". */
+function tickerFromName(name: string): string {
+  return name.replace(/[^A-Za-z0-9]/g, '').toUpperCase().slice(0, 8);
+}
+
+export function extractIssueAsset(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  if (!VERB.test(t) || !NOUN.test(t) || NOT_ISSUE.test(t)) return null;
+  const schema = NFT.test(t) ? 'UDA' : 'NIA';
+  const name = parseName(t);
+  const ticker = parseTicker(t, name) ?? (name ? tickerFromName(name) : undefined);
+  const amount = schema === 'UDA' ? 1 : parseAmount(t);
+  if (!ticker && !name) return null;
+  return { name: name ?? ticker, ticker, amount, schema };
+}
+
+export const issueAssetRecipe: Recipe = {
+  name: 'issue-asset',
+  description: 'Issue a new RGB asset (token, ticket, NFT) on the RLN node — one confirmation-gated call.',
+  match: (t) => VERB.test(t) && NOUN.test(t) && !NOT_ISSUE.test(t),
+  triggers: ['issue', 'mint', 'create token', 'launch token', 'nft'],
+  slots: [
+    { name: 'name', type: 'string', description: 'Asset name, e.g. "Hackathon Ticket"', required: true },
+    { name: 'ticker', type: 'string', description: 'Uppercase ticker, up to 8 chars, e.g. "TICKET"' },
+    { name: 'amount', type: 'number', description: 'Total supply in whole units (1 for an NFT)', required: true },
+    { name: 'schema', type: 'string', description: 'NIA for a fungible token, UDA for a unique NFT' },
+  ],
+  extract: extractIssueAsset,
+  confident: (s) => !!(s.ticker || s.name) && Number(s.amount) > 0,
+  steps: [],
+  final: {
+    tool: 'rln_issue_asset',
+    args: (ctx: RecipeContext) => {
+      const name = String(ctx.slots.name ?? ctx.slots.ticker);
+      const ticker = String(ctx.slots.ticker ?? tickerFromName(name)).toUpperCase();
+      const schema = ctx.slots.schema === 'UDA' ? 'UDA' : 'NIA';
+      return { name, ticker, amount: schema === 'UDA' ? 1 : Number(ctx.slots.amount), schema };
+    },
+  },
+  summary: (ctx, final) => {
+    // wdk/kaleido MCP return `asset_id` flat; the raw node API nests it under `asset`.
+    const r = final as { asset_id?: string; asset?: { asset_id?: string } } | undefined;
+    const id = r?.asset_id ?? r?.asset?.asset_id;
+    const what = ctx.slots.schema === 'UDA' ? `unique asset ${ctx.slots.ticker ?? ctx.slots.name}` : `${ctx.slots.amount} ${ctx.slots.ticker ?? ctx.slots.name}`;
+    return id ? `Issued ${what}. Asset id: ${id}` : `Issued ${what}.`;
+  },
+};

package/src/testing/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @kaleidorg/mind/testing — build and demo an agent with no node, no funds and
+ * no model: a stateful mock wallet bound to the canonical contract, plus a
+ * scripted provider.
+ *
+ *   import { MockWallet, scriptedProvider } from '@kaleidorg/mind/testing';
+ *   const wallet = new MockWallet();
+ *   const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry(), … });
+ */
+
+export { MockWallet } from './mock-wallet.js';
+export type { MockWalletOptions, MockContact, MockRgbAsset, MockTransfer, SendRecord } from './mock-wallet.js';
+export { scriptedProvider } from './scripted-provider.js';
+export type { ScriptedTurn } from './scripted-provider.js';

package/src/testing/mock-wallet.ts

@@ -0,0 +1,211 @@
+/**
+ * A stateful mock wallet — balances per layer, contacts (incl. ambiguous +
+ * injectable), a price, validation (insufficient funds, no route, unknown
+ * contact, no colored UTXOs), RGB issuance, and a record of what actually got
+ * "sent". The canonical contract tools bind to it, so the agent sees real
+ * schemas and real failure modes — not trivial canned stubs.
+ *
+ * Used by the eval harness and exported as `@kaleidorg/mind/testing` so hosts
+ * can build and demo an agent with no node, no funds and no network.
+ */
+
+import { bindWalletTools, type WalletHandler } from '../wallet/contract.js';
+import { ToolRegistry } from '../tools/registry.js';
+
+export interface SendRecord {
+  tool: string;
+  to: string;
+  amount_sats?: number;
+  asset?: string;
+  amount?: number;
+}
+export interface MockContact { name: string; ln_address: string; note?: string }
+export interface MockWalletOptions {
+  priceUsd?: number;
+  failRoute?: boolean;
+  contacts?: MockContact[];
+  balances?: { spark: number; rln: number; arkade: number };
+  assets?: Record<string, number>;
+  /** Free colored UTXOs on the RLN node (issuance / RGB receive consume one). */
+  utxos?: number;
+}
+export interface MockRgbAsset {
+  asset_id: string;
+  ticker: string;
+  name: string;
+  precision: number;
+  schema: 'NIA' | 'CFA' | 'UDA';
+  issued_supply: number;
+}
+export interface MockTransfer {
+  idx: number;
+  asset_id: string;
+  kind: 'Issuance' | 'Send' | 'ReceiveBlind';
+  status: 'Settled' | 'WaitingCounterparty';
+  amount: number;
+}
+
+export class MockWallet {
+  priceUsd: number;
+  failRoute: boolean;
+  balances: { spark: number; rln: number; arkade: number };
+  assets: Record<string, number>;
+  contacts: MockContact[];
+  utxos: number;
+  /** RGB assets the node knows about (seeded USDT/XAUT + anything issued). */
+  rgbAssets: MockRgbAsset[];
+  transfers: MockTransfer[] = [];
+  sends: SendRecord[] = [];
+
+  constructor(o: MockWalletOptions = {}) {
+    this.priceUsd = o.priceUsd ?? 65_000;
+    this.failRoute = o.failRoute ?? false;
+    this.balances = o.balances ?? { spark: 500_000, rln: 300_000, arkade: 200_000 };
+    this.assets = o.assets ?? { USDT: 25_000_000, XAUT: 0 };
+    this.contacts = o.contacts ?? [
+      { name: 'bob', ln_address: 'bob@kaleidoswap.com' },
+      { name: 'alice', ln_address: 'alice@kaleidoswap.com' },
+      { name: 'john', ln_address: 'john.smith@kaleidoswap.com' },
+      { name: 'john', ln_address: 'john.doe@kaleidoswap.com' }, // ambiguous on purpose
+    ];
+    this.utxos = o.utxos ?? 5;
+    this.rgbAssets = Object.keys(this.assets).map((ticker) => ({
+      asset_id: mockAssetId(ticker),
+      ticker,
+      name: ticker === 'USDT' ? 'Tether USD' : ticker === 'XAUT' ? 'Tether Gold' : ticker,
+      precision: 0,
+      schema: 'NIA' as const,
+      issued_supply: this.assets[ticker]!,
+    }));
+  }
+
+  private findAsset(ref: unknown): MockRgbAsset | undefined {
+    const q = String(ref ?? '');
+    return this.rgbAssets.find((a) => a.asset_id === q || a.ticker.toUpperCase() === q.toUpperCase());
+  }
+
+  /** Issue a new RGB asset — mirrors the node: needs a free colored UTXO. */
+  issueAsset(args: Record<string, unknown>): MockRgbAsset {
+    if (this.utxos < 1) throw new Error('No available colored UTXOs — call rln_create_utxos first.');
+    const schema = (['NIA', 'CFA', 'UDA'].includes(String(args.schema)) ? args.schema : 'NIA') as MockRgbAsset['schema'];
+    const ticker = String(args.ticker ?? '').toUpperCase();
+    if (!/^[A-Z0-9]{1,8}$/.test(ticker)) throw new Error('ticker must be 1-8 uppercase letters/digits.');
+    if (this.findAsset(ticker)) throw new Error(`An asset with ticker ${ticker} already exists.`);
+    const supply = schema === 'UDA' ? 1 : Number(args.amount);
+    if (!(supply > 0)) throw new Error('amount must be positive.');
+    const asset: MockRgbAsset = {
+      asset_id: mockAssetId(ticker),
+      ticker,
+      name: String(args.name ?? ticker),
+      precision: Number(args.precision ?? 0),
+      schema,
+      issued_supply: supply,
+    };
+    this.utxos -= 1;
+    this.rgbAssets.push(asset);
+    this.assets[ticker] = supply;
+    this.transfers.push({ idx: this.transfers.length + 1, asset_id: asset.asset_id, kind: 'Issuance', status: 'Settled', amount: supply });
+    this.sends.push({ tool: 'rln_issue_asset', to: 'self', asset: ticker, amount: supply });
+    return asset;
+  }
+
+  totalSats(): number {
+    return this.balances.spark + this.balances.rln + this.balances.arkade;
+  }
+  reset(): void {
+    this.sends = [];
+    this.transfers = [];
+  }
+
+  private send(tool: string, rec: { to: string; amount_sats?: number; asset?: string; amount?: number }) {
+    if (this.failRoute) throw new Error('No route to destination.');
+    if (rec.amount_sats != null && rec.amount_sats > this.totalSats()) {
+      throw new Error(`Insufficient funds: have ${this.totalSats()} sats, need ${rec.amount_sats}.`);
+    }
+    this.sends.push({ tool, ...rec });
+    return { status: 'SUCCESS', payment_hash: 'mock' + this.sends.length };
+  }
+
+  handlers(): Record<string, WalletHandler> {
+    return {
+      get_balances: async () => ({
+        total_sats: this.totalSats(),
+        layers: [
+          { layer: 'spark', btc_sats: this.balances.spark, assets: [] },
+          { layer: 'rln', btc_sats: this.balances.rln, assets: Object.entries(this.assets).filter(([, v]) => v > 0).map(([ticker, amount]) => ({ ticker, amount })) },
+          { layer: 'arkade', btc_sats: this.balances.arkade, assets: [] },
+        ],
+      }),
+      spark_get_balance: async () => ({ btc_sats: this.balances.spark }),
+      rln_get_balances: async () => ({ btc_sats: this.balances.rln, assets: this.assets }),
+      arkade_get_balance: async () => ({ btc_sats: this.balances.arkade }),
+      spark_get_address: async () => ({ address: 'bc1qspark0mockreceiveaddr' }),
+      arkade_get_address: async () => ({ address: 'ark1q0mockreceiveaddr' }),
+      get_price: async ({ fiat }) => ({ asset: 'BTC', price_usd: this.priceUsd, fiat: (fiat as string) ?? 'USD' }),
+      fiat_to_sats: async ({ amount }) => ({ sats: Math.round((Number(amount) / this.priceUsd) * 1e8) }),
+      resolve_contact: async ({ name }) => {
+        const q = String(name).toLowerCase();
+        const matches = this.contacts.filter((c) => c.name.toLowerCase() === q);
+        if (matches.length === 0) throw new Error(`No contact named "${name}".`);
+        if (matches.length > 1) throw new Error(`Ambiguous: ${matches.length} contacts named "${name}" — ask the user which one.`);
+        return matches[0]!;
+      },
+      rln_create_ln_invoice: async ({ amount_sats }) => ({ invoice: `lnbcmock${amount_sats ?? ''}` }),
+      rln_create_rgb_invoice: async ({ asset, amount }) => ({ invoice: 'rgb:mockinvoice', asset, amount }),
+      send_payment: async ({ to, amount_sats }) => this.send('send_payment', { to: String(to), amount_sats: amount_sats != null ? Number(amount_sats) : undefined }),
+      rln_pay_invoice: async ({ invoice }) => this.send('rln_pay_invoice', { to: String(invoice) }),
+      rln_send_asset: async ({ asset, amount, to }) => {
+        const a = String(asset);
+        if ((this.assets[a] ?? 0) < Number(amount)) throw new Error(`Insufficient ${a} balance.`);
+        const res = this.send('rln_send_asset', { to: String(to), asset: a, amount: Number(amount) });
+        const found = this.findAsset(a);
+        if (found) this.transfers.push({ idx: this.transfers.length + 1, asset_id: found.asset_id, kind: 'Send', status: 'Settled', amount: Number(amount) });
+        return res;
+      },
+      rln_list_assets: async () => ({
+        assets: this.rgbAssets.map((a) => ({ ...a, balance: { spendable: this.assets[a.ticker] ?? 0 } })),
+      }),
+      rln_list_transfers: async ({ asset_id, asset }) => {
+        const ref = asset_id ?? asset;
+        const found = this.findAsset(ref);
+        if (!found) throw new Error(`Unknown asset "${String(ref)}".`);
+        return { transfers: this.transfers.filter((x) => x.asset_id === found.asset_id) };
+      },
+      rln_create_utxos: async ({ num }) => {
+        const n = Number(num ?? 5);
+        this.utxos += n;
+        this.sends.push({ tool: 'rln_create_utxos', to: 'self', amount: n });
+        return { created: true, num: n, free_utxos: this.utxos };
+      },
+      rln_issue_asset: async (args) => {
+        const a = this.issueAsset(args);
+        return { issued: true, asset_id: a.asset_id, ticker: a.ticker, name: a.name, schema: a.schema, issued_supply: a.issued_supply };
+      },
+      get_swap_quote: async ({ from_asset, to_asset, amount }) => ({
+        quote_id: 'quote-mock',
+        from_asset,
+        to_asset,
+        amount: Number(amount),
+        // toy rate: 1 USDT ≈ 1538 sats at $65k; otherwise echo.
+        receive_amount: String(from_asset).toUpperCase() === 'USDT' ? Math.round(Number(amount) * (1e8 / this.priceUsd)) : Number(amount),
+      }),
+      execute_swap: async ({ from_asset, to_asset, amount }) => {
+        this.sends.push({ tool: 'execute_swap', to: `${from_asset}->${to_asset}`, amount: Number(amount) });
+        return { status: 'SUCCESS', swap_id: 'swap' + this.sends.length };
+      },
+    };
+  }
+
+  /** Bind the contract tools to this wallet (optionally overriding some — e.g. to inject). */
+  registry(overrides?: Partial<Record<string, WalletHandler>>): ToolRegistry {
+    const h = { ...this.handlers(), ...(overrides ?? {}) } as Record<string, WalletHandler>;
+    return new ToolRegistry([bindWalletTools(h, { layers: ['spark', 'rln', 'arkade', 'core'], allowMissing: true })]);
+  }
+}
+
+/** Deterministic fake RGB contract id per ticker (stable across runs). */
+function mockAssetId(ticker: string): string {
+  let h = 0;
+  for (const c of ticker) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+  return `rgb:mock-${ticker.toLowerCase()}-${h.toString(36)}`;
+}