@kaleidorg/mind 0.5.1 → 0.6.1

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, resolve_contact, send_payment, rln_pay_invoice, rln_create_ln_invoice, spark_create_invoice, 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/autonomy/autonomy.test.ts

@@ -0,0 +1,348 @@
+/** Autonomy tests — deterministic: injected clock + timer, no real wallet/LLM. */
+
+import { describe, it, expect, vi } from 'vitest';
+import { InMemoryTaskStore, defaultTaskSeeds } from './task-store.js';
+import { createTaskScheduler } from './scheduler.js';
+import { TaskRunLog } from './run-state.js';
+import { evaluateSpend, DEFAULT_RISK_LIMITS } from './risk.js';
+import { buildTaskPrompt } from './prompt.js';
+import type { AgentTask, RunLogSnapshot, RunLogIO, TaskStoreIO } from './types.js';
+
+const SEC = 1000;
+
+/** Drain pending microtasks (real timer — these tests don't fake setTimeout). */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('InMemoryTaskStore', () => {
+  it('creates with defaults and lists', async () => {
+    const store = new InMemoryTaskStore({ now: () => 1 });
+    const t = await store.create({
+      name: 'Rebalance',
+      description: 'd',
+      skill: 'portfolio-manager',
+      scheduleSec: 3600,
+      enabled: true,
+    });
+    expect(t.id).toBe('task_1_1');
+    expect(t.runOnStartup).toBe(false);
+    expect(t.allocation).toEqual({ btcSat: 0, usdt: 0, xaut: 0 });
+    expect(t.lastRunAt).toBeNull();
+    expect(await store.list()).toHaveLength(1);
+  });
+
+  it('update cannot mutate id/createdAt; remove works', async () => {
+    const store = new InMemoryTaskStore({ now: () => 5 });
+    const t = await store.create({ name: 'x', description: '', skill: 's', scheduleSec: 0, enabled: false });
+    const patched = await store.update(t.id, {
+      enabled: true,
+      lastRunAt: 99,
+      // @ts-expect-error — id is not patchable, proving the type guard
+      id: 'evil',
+    } as Partial<AgentTask>);
+    expect(patched?.id).toBe(t.id);
+    expect(patched?.createdAt).toBe(5);
+    expect(patched?.enabled).toBe(true);
+    expect(patched?.lastRunAt).toBe(99);
+    expect(await store.remove(t.id)).toBe(true);
+    expect(await store.remove(t.id)).toBe(false);
+  });
+
+  it('seedDefaults is idempotent by id', async () => {
+    const store = new InMemoryTaskStore({ now: () => 1 });
+    const first = await store.seedDefaults(defaultTaskSeeds());
+    expect(first.map((t) => t.id)).toEqual(['heartbeat', 'rebalance', 'daily_summary']);
+    const second = await store.seedDefaults(defaultTaskSeeds());
+    expect(second).toHaveLength(0); // already present
+    expect(await store.list()).toHaveLength(3);
+    // seeds disabled by default — an agent never auto-arms itself
+    expect((await store.list()).every((t) => !t.enabled)).toBe(true);
+  });
+
+  it('persists through injected IO and a fresh store hydrates', async () => {
+    let saved: AgentTask[] = [];
+    const io: TaskStoreIO = {
+      load: vi.fn(async () => [...saved]),
+      save: vi.fn(async (tasks) => {
+        saved = [...tasks];
+      }),
+    };
+    const store = new InMemoryTaskStore({ io, now: () => 1 });
+    await store.create({ name: 'a', description: '', skill: 's', scheduleSec: 60, enabled: true });
+    expect(io.save).toHaveBeenCalled();
+
+    const store2 = new InMemoryTaskStore({ io, now: () => 2 });
+    expect(await store2.list()).toHaveLength(1);
+  });
+});
+
+describe('createTaskScheduler', () => {
+  function fixtureTask(over: Partial<AgentTask> = {}): AgentTask {
+    return {
+      id: 't1',
+      name: 'Heartbeat',
+      description: '',
+      skill: 'channel-manager',
+      scheduleSec: 300,
+      runOnStartup: false,
+      allocation: { btcSat: 0, usdt: 0, xaut: 0 },
+      enabled: true,
+      createdAt: 0,
+      lastRunAt: null,
+      ...over,
+    };
+  }
+
+  it('runs a task only once its interval has elapsed since creation', async () => {
+    let t = 0;
+    const store = new InMemoryTaskStore({ now: () => t });
+    await store.create(fixtureTask());
+    const run = vi.fn(async () => ({ ok: true }));
+    const sched = createTaskScheduler({ store, run, now: () => t });
+
+    t = 200 * SEC; // < 300s since createdAt=0 → not due
+    await sched.tick();
+    expect(run).not.toHaveBeenCalled();
+
+    t = 300 * SEC; // exactly due
+    await sched.tick();
+    expect(run).toHaveBeenCalledTimes(1);
+    // lastRunAt stamped at run start
+    expect((await store.get('t1'))?.lastRunAt).toBe(300 * SEC);
+
+    t = 400 * SEC; // < 300s since last run → not due again
+    await sched.tick();
+    expect(run).toHaveBeenCalledTimes(1);
+
+    t = 600 * SEC; // 300s elapsed → due
+    await sched.tick();
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips disabled tasks and scheduleSec=0 (manual-only)', async () => {
+    const store = new InMemoryTaskStore({ now: () => 0 });
+    await store.create(fixtureTask({ id: 'off', enabled: false, createdAt: 0 }));
+    await store.create(fixtureTask({ id: 'manual', scheduleSec: 0, createdAt: 0 }));
+    const run = vi.fn(async () => ({ ok: true }));
+    const sched = createTaskScheduler({ store, run, now: () => 10 ** 9 });
+    await sched.tick();
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it('start() runs runOnStartup tasks immediately via injected timer', async () => {
+    const store = new InMemoryTaskStore({ now: () => 0 });
+    await store.create(fixtureTask({ id: 'boot', runOnStartup: true, createdAt: 0 }));
+    const run = vi.fn(async () => ({ ok: true }));
+    const setTimer = vi.fn(() => 'h');
+    const clearTimer = vi.fn();
+    const sched = createTaskScheduler({ store, run, now: () => 0, setTimer, clearTimer });
+
+    sched.start();
+    expect(setTimer).toHaveBeenCalledTimes(1);
+    await flush(); // let the async startup pass settle
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(sched.isRunning()).toBe(true);
+
+    sched.stop();
+    expect(clearTimer).toHaveBeenCalledWith('h');
+    expect(sched.isRunning()).toBe(false);
+  });
+
+  it('runNow forces a run regardless of schedule/enabled and reports outcome', async () => {
+    const store = new InMemoryTaskStore({ now: () => 0 });
+    await store.create(fixtureTask({ id: 'x', enabled: false, scheduleSec: 0 }));
+    const run = vi.fn(async () => ({ ok: true, text: 'done', toolCalls: 2 }));
+    const sched = createTaskScheduler({ store, run, now: () => 42 });
+    const outcome = await sched.runNow('x');
+    expect(outcome).toEqual({ ok: true, text: 'done', toolCalls: 2 });
+    expect((await store.get('x'))?.lastRunAt).toBe(42);
+    expect(await sched.runNow('nope')).toBeNull();
+  });
+
+  it('advances lastRunAt even when the run throws (no hot-loop)', async () => {
+    let t = 10 ** 6;
+    const store = new InMemoryTaskStore({ now: () => t });
+    await store.create(fixtureTask({ id: 'boom', createdAt: 0 }));
+    const onOutcome = vi.fn();
+    const run = vi.fn(async () => {
+      throw new Error('rpc down');
+    });
+    const sched = createTaskScheduler({ store, run, now: () => t, onOutcome });
+    await sched.tick();
+    expect((await store.get('boom'))?.lastRunAt).toBe(t);
+    expect(onOutcome).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'boom' }),
+      expect.objectContaining({ ok: false, error: 'rpc down' }),
+      expect.any(Number),
+    );
+  });
+
+  it('honors concurrency=1 — a slow task does not overlap itself', async () => {
+    let t = 10 ** 6;
+    const store = new InMemoryTaskStore({ now: () => t });
+    await store.create(fixtureTask({ id: 'a', createdAt: 0 }));
+    await store.create(fixtureTask({ id: 'b', createdAt: 0 }));
+    let resolveA: (() => void) | null = null;
+    const run = vi.fn((task: AgentTask) =>
+      task.id === 'a'
+        ? new Promise<{ ok: boolean }>((res) => {
+            resolveA = () => res({ ok: true });
+          })
+        : Promise.resolve({ ok: true }),
+    );
+    const sched = createTaskScheduler({ store, run, now: () => t, concurrency: 1 });
+    void sched.tick();
+    await flush();
+    // a is in-flight (its run never resolves); concurrency 1 holds b off this tick
+    expect(sched.active()).toEqual(['a']);
+    expect(run).toHaveBeenCalledTimes(1);
+    resolveA?.();
+  });
+});
+
+describe('TaskRunLog', () => {
+  it('aggregates stats, recent runs, and cumulative cost', async () => {
+    const log = new TaskRunLog({ now: () => 1, maxRecent: 2 });
+    await log.record({
+      taskId: 'r', taskName: 'Rebalance', startedAt: 100, durationMs: 5, toolCalls: 3,
+      ok: true, error: null, text: 'ok', cost: { usd: 0.01, inputTokens: 10, outputTokens: 5 },
+    });
+    await log.record({
+      taskId: 'r', taskName: 'Rebalance', startedAt: 200, durationMs: 7, toolCalls: 1,
+      ok: false, error: 'boom', text: '', cost: { usd: 0.02, inputTokens: 4, outputTokens: 2 },
+    });
+    const s = await log.statsFor('r');
+    expect(s?.runs).toBe(2);
+    expect(s?.errors).toBe(1);
+    expect(s?.lastError).toBe('boom');
+    expect(await log.totalCost()).toEqual({ usd: 0.03, inputTokens: 14, outputTokens: 7 });
+    expect((await log.recent()).map((r) => r.startedAt)).toEqual([200, 100]); // newest first
+  });
+
+  it('caps the recent ring buffer at maxRecent', async () => {
+    const log = new TaskRunLog({ now: () => 1, maxRecent: 2 });
+    for (let i = 0; i < 5; i++) {
+      await log.record({
+        taskId: 't', taskName: 'T', startedAt: i, durationMs: 1, toolCalls: 0,
+        ok: true, error: null, text: '', cost: { usd: 0, inputTokens: 0, outputTokens: 0 },
+      });
+    }
+    expect(await log.recent()).toHaveLength(2);
+  });
+
+  it('persists + hydrates through injected IO', async () => {
+    let snap: RunLogSnapshot | null = null;
+    const io: RunLogIO = {
+      load: vi.fn(async () => snap),
+      save: vi.fn(async (s) => {
+        snap = s;
+      }),
+    };
+    const log = new TaskRunLog({ io, now: () => 1 });
+    await log.record({
+      taskId: 't', taskName: 'T', startedAt: 1, durationMs: 1, toolCalls: 0,
+      ok: true, error: null, text: 'hello', cost: { usd: 1, inputTokens: 0, outputTokens: 0 },
+    });
+    expect(io.save).toHaveBeenCalled();
+    const log2 = new TaskRunLog({ io, now: () => 2 });
+    expect((await log2.totalCost()).usd).toBe(1);
+  });
+});
+
+describe('evaluateSpend (risk guardrails)', () => {
+  const live = { ...DEFAULT_RISK_LIMITS, dryRun: false };
+
+  it('blocks every spend when dry-run is on', () => {
+    const v = evaluateSpend({ kind: 'swap', amountUsd: 1 }, DEFAULT_RISK_LIMITS);
+    expect(v.outcome).toBe('block');
+    expect(v.reason).toMatch(/dry-run/);
+  });
+
+  it('blocks at/below the stop-loss floor', () => {
+    const v = evaluateSpend(
+      { kind: 'pay', amountSat: 1 },
+      { ...live, stopLossBtcSat: 50_000 },
+      { btcBalanceSat: 50_000 },
+    );
+    expect(v.outcome).toBe('block');
+    expect(v.reason).toMatch(/stop-loss/);
+  });
+
+  it('blocks a spend that would dip below the reserve', () => {
+    const v = evaluateSpend(
+      { kind: 'send', amountSat: 60_000 },
+      { ...live, minBtcReserveSat: 50_000, stopLossBtcSat: 0 },
+      { btcBalanceSat: 100_000 },
+    );
+    expect(v.outcome).toBe('block');
+    expect(v.reason).toMatch(/reserve/);
+  });
+
+  it('blocks above the max single spend', () => {
+    const v = evaluateSpend({ kind: 'swap', amountUsd: 100 }, { ...live, maxSpendUsd: 50 });
+    expect(v.outcome).toBe('block');
+    expect(v.reason).toMatch(/exceeds/);
+  });
+
+  it('blocks a new swap when the open-order cap is reached', () => {
+    const v = evaluateSpend(
+      { kind: 'swap', amountUsd: 1 },
+      { ...live, maxOpenOrders: 3, autoApproveUnderUsd: 100 },
+      { openOrders: 3 },
+    );
+    expect(v.outcome).toBe('block');
+    expect(v.reason).toMatch(/open orders/);
+  });
+
+  it('auto-approves a small spend under the threshold', () => {
+    const v = evaluateSpend(
+      { kind: 'pay', amountUsd: 2, amountSat: 3000 },
+      { ...live, autoApproveUnderUsd: 5, maxSpendUsd: 50, minBtcReserveSat: 0, stopLossBtcSat: 0 },
+      { btcBalanceSat: 1_000_000 },
+    );
+    expect(v.outcome).toBe('allow');
+    expect(v.requiresConfirmation).toBe(false);
+  });
+
+  it('requires confirmation above the auto-approve threshold', () => {
+    const v = evaluateSpend(
+      { kind: 'swap', amountUsd: 20 },
+      { ...live, autoApproveUnderUsd: 5, maxSpendUsd: 50 },
+    );
+    expect(v.outcome).toBe('confirm');
+    expect(v.requiresConfirmation).toBe(true);
+  });
+
+  it('requires confirmation when the USD value is unknown (never spends blind)', () => {
+    const v = evaluateSpend({ kind: 'channel' }, { ...live, autoApproveUnderUsd: 100 });
+    expect(v.outcome).toBe('confirm');
+  });
+});
+
+describe('buildTaskPrompt', () => {
+  const task: AgentTask = {
+    id: 'rebalance',
+    name: 'Portfolio Rebalance',
+    description: 'detect drift',
+    skill: 'portfolio-manager',
+    scheduleSec: 3600,
+    runOnStartup: false,
+    allocation: { btcSat: 100, usdt: 5, xaut: 0 },
+    enabled: true,
+    createdAt: 0,
+    lastRunAt: null,
+  };
+
+  it('embeds skill, dry-run flag, allocation, and the strict-JSON contract', () => {
+    const p = buildTaskPrompt(task, { dryRun: true, nowIso: '2026-06-19T00:00:00.000Z' });
+    expect(p).toMatch(/portfolio-manager/);
+    expect(p).toMatch(/dry_run: true/);
+    expect(p).toMatch(/Do NOT pay, send, swap/);
+    expect(p).toMatch(/"task":"rebalance"/);
+    expect(p).toMatch(/"btcSat":100/);
+  });
+
+  it('switches guidance to fund-safety language when live', () => {
+    const p = buildTaskPrompt(task, { dryRun: false, nowIso: '2026-06-19T00:00:00.000Z' });
+    expect(p).toMatch(/reserve or stop-loss/);
+  });
+});

package/src/autonomy/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Autonomy — the agent's task brain: a registry of scheduled tasks (TaskStore),
+ * the record of what they did (TaskRunLog), an interval engine that fires them
+ * (createTaskScheduler), and enforced spend guardrails (evaluateSpend).
+ *
+ * This is the half of the agent's memory the MemoryStore (soul + facts) doesn't
+ * cover — the operational state nanobot kept in tasks.json + cron + run history.
+ * Storage and timers are injected; the logic is pure TS.
+ */
+
+export type {
+  TaskAllocation,
+  AgentTask,
+  NewTask,
+  TaskSeed,
+  TaskStore,
+  TaskStoreIO,
+  TaskRunCost,
+  TaskStats,
+  TaskRunRecord,
+  RunLogSnapshot,
+  RunLogIO,
+  TaskRunOutcome,
+  RunTask,
+  TimerHandle,
+  SchedulerOptions,
+  TaskScheduler,
+} from './types.js';
+export { ZERO_ALLOCATION } from './types.js';
+
+export { InMemoryTaskStore, defaultTaskSeeds } from './task-store.js';
+export type { TaskStoreOptions } from './task-store.js';
+
+export { TaskRunLog } from './run-state.js';
+export type { RunLogOptions } from './run-state.js';
+
+export { createTaskScheduler } from './scheduler.js';
+
+export { evaluateSpend, DEFAULT_RISK_LIMITS } from './risk.js';
+export type {
+  SpendKind,
+  RiskLimits,
+  SpendAction,
+  RiskContext,
+  RiskOutcome,
+  RiskVerdict,
+} from './risk.js';
+
+export { buildTaskPrompt } from './prompt.js';
+export type { TaskPromptOptions } from './prompt.js';