@kaleidorg/mind 0.5.1 → 0.6.0

package/src/autonomy/run-state.ts

@@ -0,0 +1,144 @@
+/**
+ * TaskRunLog — what each task did, when, and what it cost. Port of kaleidoagent's
+ * agent-state.ts (LoopStats + recent-runs + cumulative cost), generalized and
+ * decoupled from the HTTP status server. This is the "memory of the tasks": the
+ * record the UI reads to show "rebalance last ran 2h ago, cost $0.003".
+ *
+ * In-memory with optional injected persistence. Pure TS, zero deps.
+ */
+
+import type {
+  RunLogIO,
+  RunLogSnapshot,
+  TaskRunCost,
+  TaskRunRecord,
+  TaskStats,
+} from './types.js';
+
+const ZERO_COST: TaskRunCost = { usd: 0, inputTokens: 0, outputTokens: 0 };
+const DEFAULT_MAX_RECENT = 20;
+const TEXT_CAP = 800;
+
+export interface RunLogOptions {
+  /** Persistence (load on first use, save on writes). Omit for ephemeral logs. */
+  io?: RunLogIO;
+  /** How many recent runs to retain. Default 20. */
+  maxRecent?: number;
+  /** Clock — injectable for deterministic tests. */
+  now?: () => number;
+}
+
+export class TaskRunLog {
+  private stats: Record<string, TaskStats> = {};
+  private recentRuns: TaskRunRecord[] = [];
+  private cumulative: TaskRunCost = { ...ZERO_COST };
+  private hydrated = false;
+  private readonly io?: RunLogIO;
+  private readonly maxRecent: number;
+  private readonly now: () => number;
+
+  constructor(opts: RunLogOptions = {}) {
+    this.io = opts.io;
+    this.maxRecent = opts.maxRecent ?? DEFAULT_MAX_RECENT;
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  private async hydrate(): Promise<void> {
+    if (this.hydrated) return;
+    this.hydrated = true;
+    if (this.io) {
+      try {
+        const snap = await this.io.load();
+        if (snap) {
+          this.stats = snap.stats ?? {};
+          this.recentRuns = snap.recent ?? [];
+          this.cumulative = snap.cumulative ?? { ...ZERO_COST };
+        }
+      } catch {
+        /* start fresh on a corrupt/absent snapshot */
+      }
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (this.io) await this.io.save(this.snapshotSync());
+  }
+
+  private ensure(taskId: string): TaskStats {
+    const existing = this.stats[taskId];
+    if (existing) return existing;
+    const fresh: TaskStats = {
+      runs: 0,
+      errors: 0,
+      lastRunAt: null,
+      lastDurationMs: null,
+      lastToolCalls: null,
+      lastError: null,
+      lastText: null,
+    };
+    this.stats[taskId] = fresh;
+    return fresh;
+  }
+
+  /** Record a completed run (success or failure). */
+  async record(record: TaskRunRecord): Promise<void> {
+    await this.hydrate();
+    const s = this.ensure(record.taskId);
+    s.runs += 1;
+    s.lastRunAt = record.startedAt;
+    s.lastDurationMs = record.durationMs;
+    s.lastToolCalls = record.toolCalls;
+    if (record.ok) {
+      s.lastError = null;
+      s.lastText = record.text.slice(0, TEXT_CAP);
+    } else {
+      s.errors += 1;
+      s.lastError = record.error;
+    }
+
+    this.cumulative = {
+      usd: this.cumulative.usd + record.cost.usd,
+      inputTokens: this.cumulative.inputTokens + record.cost.inputTokens,
+      outputTokens: this.cumulative.outputTokens + record.cost.outputTokens,
+    };
+
+    this.recentRuns.unshift({ ...record, text: record.text.slice(0, TEXT_CAP) });
+    if (this.recentRuns.length > this.maxRecent) {
+      this.recentRuns.length = this.maxRecent;
+    }
+    await this.persist();
+  }
+
+  async statsFor(taskId: string): Promise<TaskStats | null> {
+    await this.hydrate();
+    return this.stats[taskId] ?? null;
+  }
+
+  async allStats(): Promise<Record<string, TaskStats>> {
+    await this.hydrate();
+    return { ...this.stats };
+  }
+
+  async recent(limit?: number): Promise<TaskRunRecord[]> {
+    await this.hydrate();
+    return this.recentRuns.slice(0, limit ?? this.recentRuns.length);
+  }
+
+  async totalCost(): Promise<TaskRunCost> {
+    await this.hydrate();
+    return { ...this.cumulative };
+  }
+
+  async snapshot(): Promise<RunLogSnapshot> {
+    await this.hydrate();
+    return this.snapshotSync();
+  }
+
+  private snapshotSync(): RunLogSnapshot {
+    return {
+      stats: { ...this.stats },
+      recent: [...this.recentRuns],
+      cumulative: { ...this.cumulative },
+    };
+  }
+}

package/src/autonomy/scheduler.ts

@@ -0,0 +1,120 @@
+/**
+ * Scheduler — fires due tasks on their interval. Replaces the nanobot cron
+ * engine kaleidoagent relied on; here it's pure TS with injectable clock +
+ * timers so it's deterministically testable and runs anywhere (no cron daemon).
+ *
+ * Semantics:
+ *   - A task is "due" when enabled, scheduleSec > 0, and at least scheduleSec
+ *     has elapsed since its last run (or its creation, if never run). A fresh
+ *     task therefore waits one full interval before its first auto-run — unless
+ *     runOnStartup is set, in which case start() runs it immediately.
+ *   - Runs are serial by default (concurrency 1) — safest for a wallet. A task
+ *     never runs concurrently with itself.
+ *   - lastRunAt is stamped at the START of a run, so a slow run doesn't shorten
+ *     the next interval, and a failing run still advances (no hot-loop).
+ */
+
+import type {
+  AgentTask,
+  SchedulerOptions,
+  TaskRunOutcome,
+  TaskScheduler,
+  TimerHandle,
+} from './types.js';
+
+export function createTaskScheduler(opts: SchedulerOptions): TaskScheduler {
+  const { store, run } = opts;
+  const now = opts.now ?? (() => Date.now());
+  const log = opts.log ?? (() => {});
+  const tickMs = opts.tickMs ?? 30_000;
+  const concurrency = Math.max(1, opts.concurrency ?? 1);
+  const setTimer = opts.setTimer ?? ((fn, ms) => setInterval(fn, ms) as unknown as TimerHandle);
+  const clearTimer = opts.clearTimer ?? ((h) => clearInterval(h as ReturnType<typeof setInterval>));
+
+  const active = new Set<string>();
+  let running = false;
+  let timer: TimerHandle | undefined;
+
+  function isDue(task: AgentTask, ref: number): boolean {
+    if (!task.enabled || task.scheduleSec <= 0) return false;
+    const since = ref - (task.lastRunAt ?? task.createdAt);
+    return since >= task.scheduleSec * 1000;
+  }
+
+  /** Run one task, stamping lastRunAt and reporting the outcome. */
+  async function runOne(task: AgentTask): Promise<TaskRunOutcome> {
+    active.add(task.id);
+    const started = now();
+    // Stamp the start time first so a crash mid-run still advances the interval.
+    await store.update(task.id, { lastRunAt: started });
+    let outcome: TaskRunOutcome;
+    try {
+      outcome = await run(task);
+    } catch (e) {
+      outcome = { ok: false, error: (e as Error)?.message ?? String(e) };
+    } finally {
+      active.delete(task.id);
+    }
+    const durationMs = now() - started;
+    log(`ran ${task.id} ok=${outcome.ok} ${durationMs}ms`);
+    opts.onOutcome?.(task, outcome, durationMs);
+    return outcome;
+  }
+
+  async function tick(): Promise<void> {
+    const tasks = await store.list();
+    const ref = now();
+    const launched: Promise<unknown>[] = [];
+    for (const task of tasks) {
+      if (active.size >= concurrency) break;
+      if (active.has(task.id) || !isDue(task, ref)) continue;
+      // active.add (inside runOne) runs synchronously, so the size guard stays
+      // accurate as we launch up to `concurrency` runs that overlap each other;
+      // we await them so `tick()` resolves only once this batch is done.
+      launched.push(runOne(task));
+    }
+    await Promise.all(launched);
+  }
+
+  async function startupPass(): Promise<void> {
+    const tasks = await store.list();
+    for (const task of tasks) {
+      if (task.enabled && task.runOnStartup && !active.has(task.id)) {
+        // Serial on startup — predictable ordering, no thundering herd.
+        await runOne(task);
+      }
+    }
+  }
+
+  return {
+    start(): void {
+      if (running) return;
+      running = true;
+      timer = setTimer(() => {
+        void tick();
+      }, tickMs);
+      log(`scheduler started (tick=${tickMs}ms, concurrency=${concurrency})`);
+      void startupPass();
+    },
+    stop(): void {
+      running = false;
+      if (timer !== undefined) {
+        clearTimer(timer);
+        timer = undefined;
+      }
+      log('scheduler stopped');
+    },
+    tick,
+    async runNow(id: string): Promise<TaskRunOutcome | null> {
+      const task = await store.get(id);
+      if (!task || active.has(id)) return null;
+      return runOne(task);
+    },
+    active(): string[] {
+      return [...active];
+    },
+    isRunning(): boolean {
+      return running;
+    },
+  };
+}

package/src/autonomy/task-store.ts

@@ -0,0 +1,167 @@
+/**
+ * TaskStore implementation — in-memory, with optional injected persistence.
+ * Pure TS, zero deps. Port of kaleidoagent's tasks-store.ts, but storage-agnostic
+ * (host injects IO: fs on a Node sidecar, SQLite on the desktop, AsyncStorage on RN).
+ *
+ *   const store = new InMemoryTaskStore();          // ephemeral
+ *   const store = new InMemoryTaskStore({ io });     // persisted
+ */
+
+import {
+  ZERO_ALLOCATION,
+  type AgentTask,
+  type NewTask,
+  type TaskSeed,
+  type TaskStore,
+  type TaskStoreIO,
+} from './types.js';
+
+export interface TaskStoreOptions {
+  /** Persistence (load on first use, save on writes). Omit for ephemeral tasks. */
+  io?: TaskStoreIO;
+  /** Clock — injectable for deterministic tests. */
+  now?: () => number;
+}
+
+export class InMemoryTaskStore implements TaskStore {
+  private tasks: AgentTask[] = [];
+  private hydrated = false;
+  private counter = 0;
+  private readonly io?: TaskStoreIO;
+  private readonly now: () => number;
+
+  constructor(opts: TaskStoreOptions = {}) {
+    this.io = opts.io;
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  private async hydrate(): Promise<void> {
+    if (this.hydrated) return;
+    this.hydrated = true;
+    if (this.io) {
+      try {
+        this.tasks = await this.io.load();
+        this.counter = this.tasks.length;
+      } catch {
+        this.tasks = [];
+      }
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (this.io) await this.io.save(this.tasks);
+  }
+
+  async list(): Promise<AgentTask[]> {
+    await this.hydrate();
+    return [...this.tasks];
+  }
+
+  async get(id: string): Promise<AgentTask | null> {
+    await this.hydrate();
+    return this.tasks.find((t) => t.id === id) ?? null;
+  }
+
+  async create(input: NewTask): Promise<AgentTask> {
+    await this.hydrate();
+    const task = this.materialize(input);
+    this.tasks.push(task);
+    await this.persist();
+    return task;
+  }
+
+  async update(
+    id: string,
+    patch: Partial<Omit<AgentTask, 'id' | 'createdAt'>>,
+  ): Promise<AgentTask | null> {
+    await this.hydrate();
+    const existing = this.tasks.find((t) => t.id === id);
+    if (!existing) return null;
+    // id + createdAt are immutable; strip them defensively even if cast in.
+    const { id: _id, createdAt: _createdAt, ...safe } = patch as Partial<AgentTask>;
+    const updated: AgentTask = { ...existing, ...safe };
+    this.tasks = this.tasks.map((t) => (t.id === id ? updated : t));
+    await this.persist();
+    return updated;
+  }
+
+  async remove(id: string): Promise<boolean> {
+    await this.hydrate();
+    const before = this.tasks.length;
+    this.tasks = this.tasks.filter((t) => t.id !== id);
+    const removed = this.tasks.length < before;
+    if (removed) await this.persist();
+    return removed;
+  }
+
+  async seedDefaults(seeds: TaskSeed[]): Promise<AgentTask[]> {
+    await this.hydrate();
+    const present = new Set(this.tasks.map((t) => t.id));
+    const added = seeds
+      .filter((s) => !present.has(s.id))
+      .map((s) => this.materialize(s));
+    if (added.length) {
+      // Seeds first, so the default loops sort to the top of the list.
+      this.tasks = [...added, ...this.tasks];
+      await this.persist();
+    }
+    return added;
+  }
+
+  /** Fill defaults + assign id/createdAt for a new or seed task. */
+  private materialize(input: NewTask): AgentTask {
+    return {
+      id: input.id ?? `task_${this.now()}_${++this.counter}`,
+      name: input.name,
+      description: input.description,
+      skill: input.skill,
+      scheduleSec: input.scheduleSec,
+      runOnStartup: input.runOnStartup ?? false,
+      allocation: input.allocation ?? { ...ZERO_ALLOCATION },
+      enabled: input.enabled,
+      createdAt: input.createdAt ?? this.now(),
+      lastRunAt: input.lastRunAt ?? null,
+    };
+  }
+}
+
+/**
+ * The three default loops nanobot seeded — ready to pass to `seedDefaults`.
+ * Disabled by default: a wallet agent must be turned on deliberately, never
+ * auto-arm itself on first launch.
+ */
+export function defaultTaskSeeds(opts: {
+  heartbeatSec?: number;
+  rebalanceSec?: number;
+  dailySummarySec?: number;
+} = {}): TaskSeed[] {
+  return [
+    {
+      id: 'heartbeat',
+      name: 'Heartbeat',
+      description: 'Node health check, channel audit, RGB transfer flush',
+      skill: 'channel-manager',
+      scheduleSec: opts.heartbeatSec ?? 300,
+      runOnStartup: true,
+      enabled: false,
+    },
+    {
+      id: 'rebalance',
+      name: 'Portfolio Rebalance',
+      description: 'Detect allocation drift and execute rebalancing swaps',
+      skill: 'portfolio-manager',
+      scheduleSec: opts.rebalanceSec ?? 3600,
+      runOnStartup: false,
+      enabled: false,
+    },
+    {
+      id: 'daily_summary',
+      name: 'Daily Summary',
+      description: 'Full portfolio snapshot and market report',
+      skill: 'portfolio-manager',
+      scheduleSec: opts.dailySummarySec ?? 86_400,
+      runOnStartup: false,
+      enabled: false,
+    },
+  ];
+}

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