@kaleidorg/mind 0.1.0 → 0.2.0

package/src/tools/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * CLI tool source — the fourth tool mechanism (alongside in-process function
+ * calling, MCP, and skills). Lets the agent run shell commands, e.g. a skill's
+ * documented CLI path (`@bitrefill/cli`, `kaleido`, `git`, …).
+ *
+ * Command execution is INJECTED (`CommandRunner`) so this file has no Node
+ * dependency and stays RN-safe — a Node host provides the runner (ideally via a
+ * non-shell `execFile`-style helper); React Native simply never provides one.
+ * Guarded by a required allowlist of command prefixes, and confirmation-gated
+ * by default since it runs real commands.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+/** Injected shell runner. The Node host supplies a safe implementation. */
+export interface CommandRunner {
+  run(command: string, opts?: { cwd?: string; timeoutMs?: number }): Promise<CommandResult>;
+}
+
+export interface CliToolOptions {
+  runner: CommandRunner;
+  /**
+   * Allowed command prefixes (REQUIRED — no empty allowlist). A command runs
+   * only if it starts with one of these tokens, e.g. ['kaleido', 'git status',
+   * 'npx @bitrefill/cli'].
+   */
+  allow: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  /** Confirmation gate (default true — it executes real commands). */
+  requiresConfirmation?: boolean;
+  /** Tool description override (e.g. name the specific CLI). */
+  description?: string;
+}
+
+const RUN = 'run_command';
+
+/** True if `command` is permitted by the allowlist (prefix match on tokens). */
+export function isAllowed(command: string, allow: string[]): boolean {
+  const cmd = command.trim();
+  return allow.some((prefix) => {
+    const p = prefix.trim();
+    return p.length > 0 && (cmd === p || cmd.startsWith(p + ' '));
+  });
+}
+
+export function createCliToolSource(opts: CliToolOptions): ToolSource {
+  if (!opts.allow || opts.allow.length === 0) {
+    throw new Error('createCliToolSource: a non-empty `allow` allowlist is required');
+  }
+
+  const tool: ToolDef = {
+    name: RUN,
+    description:
+      opts.description ??
+      `Run an allowed shell command and return its output. Allowed commands start ` +
+        `with: ${opts.allow.join(', ')}. Use for documented CLI tools.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The full command line to run' },
+      },
+      required: ['command'],
+    },
+    requiresConfirmation: opts.requiresConfirmation ?? true,
+  };
+
+  async function execute(_name: string, args: Record<string, unknown>): Promise<unknown> {
+    const command = String(args.command ?? '').trim();
+    if (!command) throw new Error('run_command: command is required');
+    if (!isAllowed(command, opts.allow)) {
+      throw new Error(
+        `run_command: "${command.split(' ')[0]}" is not allowed. Allowed: ${opts.allow.join(', ')}`,
+      );
+    }
+    const res = await opts.runner.run(command, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+    const out = (res.stdout || '').trim();
+    const err = (res.stderr || '').trim();
+    if (res.code !== 0) {
+      return `exit ${res.code}${err ? `\n${err}` : ''}${out ? `\n${out}` : ''}`.trim();
+    }
+    return out || '(no output)';
+  }
+
+  return {
+    id: 'cli',
+    listTools: () => [tool],
+    has: (name) => name === RUN,
+    execute,
+  };
+}

package/src/tools/mcp.ts

@@ -13,8 +13,9 @@
  * file type-checks and ships even where the SDK isn't installed; constructing
  * an McpToolSource without it throws a clear error.
  *
- * STATUS: skeleton for the desktop pass. The shape is final; the connect()
- * body is wired when we integrate desktop-app.
+ * Wired end-to-end: connect() (stdio + HTTP transports), listTools() and
+ * execute() are implemented. Used by the desktop sidecar (kaleido-mcp +
+ * Bitrefill MCP) and verified against the remote Bitrefill MCP.
  */
 
 import type { ToolDef } from '../types.js';

package/src/wallet/contract.test.ts

@@ -0,0 +1,89 @@
+/** Wallet contract tests — integrity of the single source of truth. */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  WALLET_TOOLS,
+  SPEND_TOOLS,
+  isSpendTool,
+  walletTools,
+  toToolDefs,
+  bindWalletTools,
+  getWalletTool,
+} from './contract.js';
+
+describe('WALLET_TOOLS contract', () => {
+  it('has unique names and object schemas', () => {
+    const names = WALLET_TOOLS.map((t) => t.name);
+    expect(new Set(names).size).toBe(names.length);
+    for (const t of WALLET_TOOLS) {
+      expect(t.name).toMatch(/^[a-z][a-z0-9_]+$/);
+      expect((t.parameters as any).type).toBe('object');
+    }
+  });
+
+  it('namespaces per-layer tools and keeps core helpers unprefixed', () => {
+    for (const t of WALLET_TOOLS) {
+      if (t.layer === 'core') continue;
+      expect(t.name.startsWith(`${t.layer}_`)).toBe(true);
+    }
+    expect(getWalletTool('send_payment')!.layer).toBe('core');
+    expect(getWalletTool('resolve_contact')!.layer).toBe('core');
+  });
+
+  it('spend tools are confirmation-gated; reads do not move funds', () => {
+    for (const t of WALLET_TOOLS) {
+      expect(!!t.requiresConfirmation).toBe(!!t.spend);
+    }
+    // every fund-moving tool is flagged
+    expect(isSpendTool('send_payment')).toBe(true);
+    expect(isSpendTool('rln_send_asset')).toBe(true);
+    expect(isSpendTool('execute_swap')).toBe(true);
+    expect(isSpendTool('spark_send')).toBe(true);
+    // reads are not
+    expect(isSpendTool('get_balances')).toBe(false);
+    expect(isSpendTool('get_price')).toBe(false);
+    expect([...SPEND_TOOLS].length).toBeGreaterThanOrEqual(5);
+  });
+
+  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']);
+    expect((getWalletTool('rln_create_rgb_invoice')!.parameters as any).required).toEqual(['asset', 'amount']);
+  });
+});
+
+describe('selectors', () => {
+  it('walletTools filters by layer + always includes core unless disabled', () => {
+    const spark = walletTools({ layers: ['spark'] });
+    expect(spark.some((t) => t.name === 'spark_send')).toBe(true);
+    expect(spark.some((t) => t.layer === 'core')).toBe(true); // core included by default
+    expect(spark.some((t) => t.layer === 'rln')).toBe(false);
+
+    const noCore = walletTools({ layers: ['spark'], includeCore: false });
+    expect(noCore.every((t) => t.layer === 'spark')).toBe(true);
+  });
+
+  it('toToolDefs strips metadata but keeps requiresConfirmation', () => {
+    const defs = toToolDefs(walletTools({ layers: ['spark'] }));
+    const send = defs.find((d) => d.name === 'spark_send')!;
+    expect(send.requiresConfirmation).toBe(true);
+    expect('layer' in (send as any)).toBe(false);
+  });
+});
+
+describe('bindWalletTools', () => {
+  it('binds handlers → an InProcessToolSource with spend flags preserved', async () => {
+    const handler = vi.fn(async () => ({ ok: true }));
+    const src = bindWalletTools({ spark_get_balance: handler, spark_send: handler }, { layers: ['spark'], includeCore: false, allowMissing: true });
+    const tools = src.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual(['spark_get_balance', 'spark_send']);
+    expect(tools.find((t) => t.name === 'spark_send')!.requiresConfirmation).toBe(true);
+    expect(await src.execute('spark_get_balance', {})).toEqual({ ok: true });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    expect(() => bindWalletTools({}, { layers: ['spark'], includeCore: false })).toThrow(/no handler/);
+    const src = bindWalletTools({ spark_get_balance: async () => 1 }, { layers: ['spark'], includeCore: false, allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['spark_get_balance']);
+  });
+});

package/src/wallet/contract.ts

@@ -0,0 +1,157 @@
+/**
+ * Canonical multi-L2 wallet tool contract — the single source of truth for
+ * KaleidoMind's wallet tools (names + JSON schemas + spend flags).
+ *
+ * Every surface implements THESE EXACT tools, only the transport differs:
+ *   - mobile  → in-process handlers over the WDK adapters (`bindWalletTools`)
+ *   - desktop → kaleido-mcp (tools namespaced per layer) + a `kaleido` CLI
+ *   - eval    → stub handlers
+ *
+ * Because the schemas are identical everywhere, skills are portable and the
+ * model comparison is honest. Tools are namespaced per layer (`spark_*`,
+ * `rln_*`, `arkade_*`, `liquid_*`); cross-cutting router/helpers are unprefixed.
+ *
+ * Spend tools (move funds) carry `spend: true` → `requiresConfirmation: true`,
+ * so the Engine always pauses for the host's confirm gate before executing.
+ *
+ * Pure data — no deps, RN-safe.
+ */
+
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { InProcessTool } from '../tools/in-process.js';
+
+export type WalletLayer = 'spark' | 'rln' | 'arkade' | 'liquid' | 'core';
+
+export interface WalletToolDef extends ToolDef {
+  /** Which L2 (or 'core' for cross-cutting router/helpers). */
+  layer: WalletLayer;
+  /** Moves funds → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<string, { type: string; description?: string; enum?: string[] }>;
+
+function t(
+  layer: WalletLayer,
+  name: string,
+  description: string,
+  properties: Props = {},
+  required: string[] = [],
+  spend = false,
+): WalletToolDef {
+  return {
+    layer,
+    name,
+    description,
+    spend,
+    requiresConfirmation: spend,
+    parameters: { type: 'object', properties, required },
+  };
+}
+
+const sats = { type: 'number', description: 'Amount in satoshis' } as const;
+const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT', 'BTC'" } as const;
+
+/** 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),
+
+  // ── RLN / RGB ──────────────────────────────────────────────────────────
+  t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),
+  t('rln', 'rln_get_node_info', 'Get RLN node status and sync state.'),
+  t('rln', 'rln_list_channels', 'List the RLN node Lightning channels.'),
+  t('rln', 'rln_create_ln_invoice', 'Create a Lightning (BTC) invoice on the RLN node.', { amount_sats: sats }),
+  t('rln', 'rln_create_rgb_invoice', 'Create an RGB asset invoice to receive an asset (e.g. USDT).', { asset, amount: { type: 'number', description: 'Asset amount' } }, ['asset', 'amount']),
+  t('rln', 'rln_pay_invoice', 'Pay a Lightning invoice from the RLN node.', { invoice: { type: 'string' } }, ['invoice'], true),
+  t('rln', 'rln_send_asset', 'Send an RGB asset (e.g. USDT) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+
+  // ── Arkade ─────────────────────────────────────────────────────────────
+  t('arkade', 'arkade_get_balance', 'Get the Arkade wallet balance.'),
+  t('arkade', 'arkade_get_address', 'Get an Arkade address to receive funds.'),
+  t('arkade', 'arkade_send', 'Send BTC from Arkade to a recipient.', { amount_sats: sats, to: { type: 'string' } }, ['amount_sats', 'to'], true),
+
+  // ── Liquid (later) ─────────────────────────────────────────────────────
+  t('liquid', 'liquid_get_balance', 'Get the Liquid wallet balance (L-BTC + assets).'),
+  t('liquid', 'liquid_create_invoice', 'Create a Liquid invoice/address to receive (L-BTC or L-USDt).', { asset, amount: { type: 'number' } }),
+  t('liquid', 'liquid_send', 'Send a Liquid asset (L-BTC or L-USDt) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+
+  // ── Core: router + helpers ─────────────────────────────────────────────
+  t('core', 'get_balances', 'Get balances across all layers (or one layer).', { layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'], description: 'Optional: a single layer' } }),
+  t('core', 'resolve_contact', 'Resolve a contact name to a Lightning address / Nostr / preferred rail.', { name: { type: 'string', description: 'Contact name, e.g. "bob"' } }, ['name']),
+  t('core', 'get_price', 'Get the current price of an asset, optionally in a fiat currency.', { asset, fiat: { type: 'string', description: "Fiat code, e.g. 'EUR', 'USD'" } }),
+  t('core', 'fiat_to_sats', 'Convert a fiat amount to satoshis at the current rate.', { amount: { type: 'number' }, currency: { type: 'string', description: "Fiat code, e.g. 'EUR'" } }, ['amount', 'currency']),
+  t('core', 'get_swap_quote', 'Quote a swap between two assets.', { from_asset: asset, to_asset: asset, amount: { type: 'number' } }, ['from_asset', 'to_asset', 'amount']),
+  t('core', 'execute_swap', 'Execute a previously quoted swap.', { quote_id: { type: 'string' }, from_asset: asset, to_asset: asset, amount: { type: 'number' } }, [], true),
+  // The high-level entry a skill prefers — picks the rail for the asset, or uses `layer`.
+  t('core', 'send_payment', 'Send a payment, automatically choosing the best layer for the asset (or use `layer`).', { asset, amount_sats: sats, to: { type: 'string', description: 'Contact, address, or invoice' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }, ['to'], true),
+  // High-level receive — picks the right invoice/address tool for the asset/layer.
+  t('core', 'create_invoice', 'Create an invoice or address to receive funds, choosing the rail for the asset (or use `layer`). Omit amount for an any-amount invoice.', { asset, amount: { type: 'number', description: 'Amount (sats for BTC, asset units otherwise) — optional' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }),
+];
+
+// ── Selectors ───────────────────────────────────────────────────────────────
+
+export const WALLET_LAYERS: WalletLayer[] = ['spark', 'rln', 'arkade', 'liquid', 'core'];
+
+/** Names of all spend (fund-moving) tools — these are confirmation-gated. */
+export const SPEND_TOOLS: ReadonlySet<string> = new Set(WALLET_TOOLS.filter((x) => x.spend).map((x) => x.name));
+
+export function isSpendTool(name: string): boolean {
+  return SPEND_TOOLS.has(name);
+}
+
+export function getWalletTool(name: string): WalletToolDef | undefined {
+  return WALLET_TOOLS.find((x) => x.name === name);
+}
+
+/** Pick the contract tools for the given layers (core helpers included by default). */
+export function walletTools(opts: { layers?: WalletLayer[]; includeCore?: boolean } = {}): WalletToolDef[] {
+  const layers = new Set(opts.layers ?? (['spark', 'rln', 'arkade', 'liquid'] as WalletLayer[]));
+  if (opts.includeCore !== false) layers.add('core');
+  return WALLET_TOOLS.filter((x) => layers.has(x.layer));
+}
+
+/** Strip to plain ToolDefs (drop the layer/spend metadata). */
+export function toToolDefs(tools: WalletToolDef[]): ToolDef[] {
+  return tools.map(({ name, description, parameters, requiresConfirmation }) => ({ name, description, parameters, requiresConfirmation }));
+}
+
+/** A handler bound to one contract tool. */
+export type WalletHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindWalletOptions {
+  layers?: WalletLayer[];
+  includeCore?: boolean;
+  /** Skip tools that have no handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  id?: string;
+}
+
+/**
+ * Bind contract tools to in-process handlers → an InProcessToolSource. The
+ * mobile (and eval) binding: pass a map of `{ toolName: handler }` and you get a
+ * ToolSource implementing the canonical schemas with spend flags preserved.
+ */
+export function bindWalletTools(handlers: Record<string, WalletHandler>, opts: BindWalletOptions = {}): InProcessToolSource {
+  const tools = walletTools(opts);
+  const bound: InProcessTool[] = [];
+  for (const def of tools) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindWalletTools: 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 ?? 'wallet', bound);
+}