@kaleidorg/mind 0.5.1 → 0.6.1

package/src/autonomy/types.ts

@@ -0,0 +1,186 @@
+/**
+ * Autonomy — the agent's task brain.
+ *
+ * This is the half of "the agent's memory" the {@link ../memory/types MemoryStore}
+ * (soul + facts) does NOT cover: the *operational* state nanobot kept across
+ * `tasks.json` + `cron/jobs.json` + its run history. Lifted into core so every
+ * host (desktop sidecar, agent, cli) runs the same autonomous loop — storage
+ * and timers are injected (fs/SQLite on Node, AsyncStorage on RN), the logic is
+ * pure TS with zero runtime deps.
+ *
+ * Three pieces:
+ *   - TaskStore   — the registry of scheduled/manual tasks (was tasks-store.ts)
+ *   - TaskRunLog  — what each task did, when, and what it cost (was agent-state.ts)
+ *   - Scheduler   — fires due tasks on their interval (was nanobot cron)
+ *
+ * Spend safety lives alongside in {@link ./risk}.
+ */
+
+/** Capital earmarked for a task — isolates how much a single task may touch. */
+export interface TaskAllocation {
+  /** Satoshis of BTC the task may spend. */
+  btcSat: number;
+  /** USDT (display units) the task may spend. */
+  usdt: number;
+  /** XAUT (display units) the task may spend. */
+  xaut: number;
+}
+
+/** A zero allocation — the default for read-only / monitoring tasks. */
+export const ZERO_ALLOCATION: TaskAllocation = { btcSat: 0, usdt: 0, xaut: 0 };
+
+/**
+ * A scheduled (or manual) autonomous task — the unit nanobot stored in
+ * `tasks.json`. A task names a skill to run on an interval, with an optional
+ * capital budget and an enable switch.
+ */
+export interface AgentTask {
+  id: string;
+  name: string;
+  description: string;
+  /** Skill that scopes the run, e.g. 'portfolio-manager'. */
+  skill: string;
+  /** Seconds between runs. 0 = manual-only (never auto-fires). */
+  scheduleSec: number;
+  /** Run once immediately when the scheduler starts. */
+  runOnStartup: boolean;
+  /** Capital this task is allowed to move. */
+  allocation: TaskAllocation;
+  enabled: boolean;
+  /** Epoch ms. */
+  createdAt: number;
+  /** Epoch ms of the last run, or null if never run. */
+  lastRunAt: number | null;
+}
+
+/**
+ * What `create` accepts — id/createdAt/lastRunAt are filled by the store, and
+ * allocation/runOnStartup default when omitted.
+ */
+export type NewTask = Omit<
+  AgentTask,
+  'id' | 'createdAt' | 'lastRunAt' | 'allocation' | 'runOnStartup'
+> &
+  Partial<Pick<AgentTask, 'id' | 'createdAt' | 'lastRunAt' | 'allocation' | 'runOnStartup'>>;
+
+/** A default/seed task — carries a stable id so seeding is idempotent. */
+export type TaskSeed = NewTask & { id: string };
+
+/** The task registry. Mirrors {@link ../memory/types.MemoryStore}'s shape. */
+export interface TaskStore {
+  list(): Promise<AgentTask[]>;
+  get(id: string): Promise<AgentTask | null>;
+  create(input: NewTask): Promise<AgentTask>;
+  /** Patch a task. id/createdAt are immutable. Returns null if not found. */
+  update(id: string, patch: Partial<Omit<AgentTask, 'id' | 'createdAt'>>): Promise<AgentTask | null>;
+  remove(id: string): Promise<boolean>;
+  /** Insert any seed whose id isn't already present. Returns the ones added. */
+  seedDefaults(seeds: TaskSeed[]): Promise<AgentTask[]>;
+}
+
+/** Injected persistence — load once, save on every mutation. */
+export interface TaskStoreIO {
+  load(): Promise<AgentTask[]>;
+  save(tasks: AgentTask[]): Promise<void>;
+}
+
+// ── Run history ────────────────────────────────────────────────────────────
+
+/** Token + dollar cost of a single run. */
+export interface TaskRunCost {
+  usd: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** Aggregated stats for one task across all its runs. */
+export interface TaskStats {
+  runs: number;
+  errors: number;
+  lastRunAt: number | null;
+  lastDurationMs: number | null;
+  lastToolCalls: number | null;
+  lastError: string | null;
+  /** First ~800 chars of the last final response. */
+  lastText: string | null;
+}
+
+/** One completed run, newest-first in the recent ring buffer. */
+export interface TaskRunRecord {
+  taskId: string;
+  taskName: string;
+  /** Epoch ms the run started. */
+  startedAt: number;
+  durationMs: number;
+  toolCalls: number;
+  ok: boolean;
+  error: string | null;
+  /** Final response text (truncated by the log). */
+  text: string;
+  cost: TaskRunCost;
+}
+
+/** A serializable point-in-time view of the run log, for persistence. */
+export interface RunLogSnapshot {
+  stats: Record<string, TaskStats>;
+  recent: TaskRunRecord[];
+  cumulative: TaskRunCost;
+}
+
+/** Injected persistence for the run log. */
+export interface RunLogIO {
+  load(): Promise<RunLogSnapshot | null>;
+  save(snapshot: RunLogSnapshot): Promise<void>;
+}
+
+// ── Scheduler ──────────────────────────────────────────────────────────────
+
+/** The result of running a task once. The host's `run` callback returns this. */
+export interface TaskRunOutcome {
+  ok: boolean;
+  text?: string;
+  toolCalls?: number;
+  error?: string;
+  cost?: Partial<TaskRunCost>;
+}
+
+/** Host-provided runner — typically wraps `Funnel.runTurn(buildTaskPrompt(task))`. */
+export type RunTask = (task: AgentTask) => Promise<TaskRunOutcome>;
+
+/** Opaque timer handle so the scheduler stays platform-agnostic. */
+export type TimerHandle = unknown;
+
+export interface SchedulerOptions {
+  store: TaskStore;
+  /** Runs a task and resolves with its outcome. Errors are caught by the scheduler. */
+  run: RunTask;
+  /** Notified after every run (success or error) — wire to a {@link TaskRunLog}. */
+  onOutcome?: (task: AgentTask, outcome: TaskRunOutcome, durationMs: number) => void;
+  /** Diagnostics sink. Default: silent. */
+  log?: (msg: string) => void;
+  /** Injectable clock. Default: Date.now. */
+  now?: () => number;
+  /** How often `start()` evaluates due tasks, ms. Default 30_000. */
+  tickMs?: number;
+  /** Max tasks running at once. Default 1 (serial — safest for a wallet). */
+  concurrency?: number;
+  /** Injectable timer. Default: setInterval. */
+  setTimer?: (fn: () => void, ms: number) => TimerHandle;
+  /** Injectable timer-clear. Default: clearInterval. */
+  clearTimer?: (handle: TimerHandle) => void;
+}
+
+export interface TaskScheduler {
+  /** Begin firing due tasks; runs `runOnStartup` tasks immediately. Idempotent. */
+  start(): void;
+  /** Stop firing. In-flight runs finish; no new ones start. */
+  stop(): void;
+  /** Evaluate all tasks once and run those that are due. Safe to call directly (tests). */
+  tick(): Promise<void>;
+  /** Force-run a task now regardless of schedule/enabled. Null if unknown/already running. */
+  runNow(id: string): Promise<TaskRunOutcome | null>;
+  /** Ids of tasks currently running. */
+  active(): string[];
+  /** Whether `start()` is in effect. */
+  isRunning(): boolean;
+}

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);
+}

package/src/context/compress.test.ts

@@ -0,0 +1,120 @@
+/** Tool-output compression tests — savings + the safety guarantees. */
+
+import { describe, it, expect } from 'vitest';
+import { compressToolResult } from './compress.js';
+import { estimateTokens } from './budget.js';
+
+/** Build a verbose merchant-list-like result the agentic loop would crush. */
+function merchants(n: number): { results: Array<Record<string, unknown>> } {
+  return {
+    results: Array.from({ length: n }, (_, i) => ({
+      name: `Coffee Shop ${i}`,
+      category: 'cafe',
+      description:
+        'Accepts Bitcoin on-chain and Lightning. Open daily. ' +
+        'A cozy spot with reliable wifi and great espresso for digital nomads.',
+      lat: 41.0 + i / 1000,
+      lng: 12.0 + i / 1000,
+      tags: ['bitcoin', 'lightning', 'cafe'],
+    })),
+  };
+}
+
+describe('compressToolResult', () => {
+  it('passes small results through untouched', () => {
+    const small = { total_sats: 123_456, layers: 2 };
+    const r = compressToolResult(small);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(JSON.stringify(small));
+  });
+
+  it('elides the middle of a long array and reports the omitted count', () => {
+    const r = compressToolResult(merchants(40), { maxArrayItems: 6 });
+    expect(r.changed).toBe(true);
+    expect(r.compressedTokens).toBeLessThan(r.originalTokens);
+    expect(r.elided).toBeGreaterThan(0);
+
+    const parsed = JSON.parse(r.content) as { results: Array<Record<string, unknown>> };
+    const marker = parsed.results.find((x) => '__elided__' in x);
+    expect(marker).toBeDefined();
+    expect(marker!.__elided__).toBe(r.elided);
+    // Kept first/last anchors → fewer items than the original 40.
+    expect(parsed.results.length).toBeLessThan(40);
+  });
+
+  it('dedupes identical array items before eliding', () => {
+    const dup = { rows: Array.from({ length: 30 }, () => ({ status: 'ok', code: 200 })) };
+    const r = compressToolResult(dup, { maxArrayItems: 4 });
+    const parsed = JSON.parse(r.content) as { rows: Array<Record<string, unknown>> };
+    const real = parsed.rows.filter((x) => !('__elided__' in x));
+    // 30 identical rows collapse to a single unique row (≤ maxArrayItems).
+    expect(real.length).toBe(1);
+  });
+
+  it('never regresses: returns the original when crushing would not save tokens', () => {
+    // A flat array of unique short numbers compresses to roughly itself; the
+    // elision marker can cost more than it saves — must fall back to original.
+    const flat = { xs: Array.from({ length: 60 }, (_, i) => i) };
+    const r = compressToolResult(flat, { maxArrayItems: 50, dedupe: false });
+    expect(r.compressedTokens).toBeLessThanOrEqual(r.originalTokens);
+  });
+
+  it('SAFETY: never truncates whitespace-free identifiers (invoices/addresses)', () => {
+    const invoice = 'lnbc' + '1'.repeat(1500); // long BOLT11-like, no spaces
+    const addr = 'bc1q' + 'a'.repeat(800);
+    const payload = {
+      filler: Array.from({ length: 20 }, (_, i) => ({ note: 'x'.repeat(50), i })),
+      invoice,
+      address: addr,
+    };
+    const r = compressToolResult(payload, { maxArrayItems: 4, maxStringLength: 80 });
+    expect(r.content).toContain(invoice); // intact, not truncated
+    expect(r.content).toContain(addr);
+  });
+
+  it('SAFETY: never elides/truncates values under preserved money keys', () => {
+    const payload = {
+      // A long prose string under a preserve key stays intact.
+      balance: 'x '.repeat(1000),
+      // Numbers are never touched regardless.
+      total_sats: 4_800_123,
+      history: Array.from({ length: 40 }, (_, i) => ({ memo: 'spent on coffee number ' + i, i })),
+    };
+    const r = compressToolResult(payload, { maxArrayItems: 4, maxStringLength: 40 });
+    const parsed = JSON.parse(r.content) as Record<string, unknown>;
+    expect(parsed.balance).toBe(payload.balance); // preserved verbatim
+    expect(parsed.total_sats).toBe(4_800_123);
+  });
+
+  it('SAFETY: numbers are never altered', () => {
+    const payload = {
+      quotes: Array.from({ length: 30 }, (_, i) => ({
+        amount_sats: 1000 + i,
+        rate: 0.00012345,
+        fee: 7,
+      })),
+    };
+    const r = compressToolResult(payload, { maxArrayItems: 5 });
+    const parsed = JSON.parse(r.content) as { quotes: Array<Record<string, number>> };
+    for (const q of parsed.quotes) {
+      if ('__elided__' in q) continue;
+      expect(Number.isInteger(q.amount_sats)).toBe(true);
+      expect(q.rate).toBe(0.00012345);
+      expect(q.fee).toBe(7);
+    }
+  });
+
+  it('truncates long prose strings (with whitespace) when over the limit', () => {
+    const payload = { log: ('error happened at step ').repeat(200) };
+    const r = compressToolResult(payload, { maxStringLength: 100, minTokens: 1 });
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain('… (+');
+    expect(estimateTokens(r.content)).toBeLessThan(r.originalTokens);
+  });
+
+  it('collapses nesting beyond maxDepth to a shape summary', () => {
+    const deep = { a: { b: { c: { d: { e: { f: { g: 'too deep' } } } } } }, pad: 'p'.repeat(900) };
+    const r = compressToolResult(deep, { maxDepth: 3, minTokens: 1 });
+    expect(r.content).toMatch(/\[object: \d+ keys\]/);
+  });
+});