talon-agent 5.26.5 → 5.27.0

package/src/core/agents/registry.ts

@@ -6,10 +6,12 @@
  * it owns no timers, no backends and no delivery. The runner drives it, the
  * gateway actions read it, and `GET /agents` serves `list()`.
  *
- * In-memory by design, same reasoning as the task table: an agent is a live
- * run and a daemon restart ends every run, so persisted rows could only
- * describe work that no longer exists. What *happened* is already durable —
- * every `agent.*` event lands in the journal (see `docs/bus.md`).
+ * The live map is in memory, but every lifecycle change is mirrored to the
+ * `agents` table through the `persist` hook (the singleton wires
+ * `storage/agents/repo.ts`), so a daemon restart no longer kills an
+ * agent: the next boot finds its row still `running` and resumes it —
+ * `restore()` is the re-entry point. Tests constructing their own registry
+ * pass no hook and stay purely in memory.
  */
 
 import { randomBytes } from "node:crypto";
@@ -24,6 +26,8 @@ import type {
 import type { TaskUsage } from "../tasks/types.js";
 import type { AgentSettledEvent, AgentSpawnedEvent } from "../bus/events.js";
 import type { ReasoningEffortLevel } from "../types.js";
+import type { PersistedAgent } from "../../storage/agents/repo.js";
+import * as agentsRepo from "../../storage/agents/repo.js";
 import { bus } from "../bus/index.js";
 import { logWarn } from "../../util/log.js";
 import { RunKilledError } from "./abort-reason.js";
@@ -40,6 +44,14 @@ export interface AgentRegistration {
   readonly parent: AgentParent;
   readonly backendId: string;
   readonly reasoningEffort?: ReasoningEffortLevel;
+  /** The model the caller asked for (unset = backend default). */
+  readonly requestedModel?: string;
+  /** The run's hard wall-clock cap. */
+  readonly timeoutMs?: number;
+  /** Working directory the run executes in. */
+  readonly cwd?: string;
+  /** The spawn asked for the pre-flight lane instruction. */
+  readonly preflight?: boolean;
 }
 
 /** What the runner knows once the run is actually under way. */
@@ -74,6 +86,15 @@ export interface AgentRegistryOptions {
   readonly publish?: (event: AgentSpawnedEvent | AgentSettledEvent) => void;
   /** Id factory; overridden in tests for deterministic ids. */
   readonly newId?: () => string;
+  /**
+   * Durable mirror of every lifecycle change — the singleton writes the
+   * `agents` table here so a restart can resume the agent. Must not throw
+   * (the registry guards it anyway: persistence is never allowed to break a
+   * run).
+   */
+  readonly persist?: (snapshot: PersistedAgent) => void;
+  /** Drop a persisted row (a registration that never started). */
+  readonly unpersist?: (id: string) => void;
 }
 
 type MutableAgentRecord = {
@@ -87,6 +108,21 @@ interface LiveAgent {
   abort?: AbortController;
   reported: boolean;
   killRequested: boolean;
+  /** Persistence-only facts — see `AgentRegistration` / `PersistedAgent`. */
+  requestedModel?: string;
+  timeoutMs?: number;
+  cwd?: string;
+  preflight?: boolean;
+  sessionId?: string;
+  elapsedMs: number;
+  resumeCount: number;
+  interruptedAt?: number;
+  /**
+   * Set when a daemon shutdown interrupts the run. The abort that follows
+   * must not be recorded as a kill: the row stays `running` so the next boot
+   * resumes it, and the parent is not told the agent died.
+   */
+  interrupted: boolean;
 }
 
 /**
@@ -114,6 +150,68 @@ function snapshot(entry: LiveAgent): AgentRecord {
   };
 }
 
+/**
+ * The abort reason for a kill. A daemon shutdown parks the run rather than
+ * killing it (it resumes on the next boot), so its abort must not carry
+ * `RunKilledError` — the run log would say "killed on request".
+ */
+function killReason(entry: LiveAgent, id: string): Error {
+  return entry.interrupted
+    ? new Error(`agent ${id} interrupted by a daemon shutdown`)
+    : new RunKilledError(`agent ${id} killed`);
+}
+
+/** The durable shape of one live entry. */
+function toPersisted(entry: LiveAgent): PersistedAgent {
+  const { record } = entry;
+  const saved: PersistedAgent = {
+    id: record.id,
+    label: record.label,
+    brief: record.brief,
+    parentKind: record.parent.kind,
+    parentId:
+      record.parent.kind === "chat"
+        ? record.parent.chatId
+        : record.parent.agentId,
+    backendId: record.backendId,
+    depth: record.depth,
+    state: record.state,
+    createdAt: record.createdAt,
+    updatedAt: Date.now(),
+    inbox: entry.mailbox.map((m) => ({ from: m.from, text: m.text, at: m.at })),
+    reported: entry.reported,
+    elapsedMs: entry.elapsedMs,
+    resumeCount: entry.resumeCount,
+  };
+  if (record.parent.kind === "chat") {
+    saved.parentNumericChatId = record.parent.numericChatId;
+  }
+  if (record.model !== undefined) saved.model = record.model;
+  if (entry.requestedModel !== undefined) {
+    saved.requestedModel = entry.requestedModel;
+  }
+  if (record.reasoningEffort !== undefined) {
+    saved.reasoningEffort = record.reasoningEffort;
+  }
+  if (entry.timeoutMs !== undefined) saved.timeoutMs = entry.timeoutMs;
+  if (entry.cwd !== undefined) saved.cwd = entry.cwd;
+  if (entry.preflight) saved.preflight = true;
+  if (record.startedAt !== undefined) saved.startedAt = record.startedAt;
+  if (record.endedAt !== undefined) saved.endedAt = record.endedAt;
+  if (entry.sessionId !== undefined) saved.sessionId = entry.sessionId;
+  if (record.result) {
+    saved.resultSummary = record.result.summary;
+    if (record.result.details !== undefined) {
+      saved.resultDetails = record.result.details;
+    }
+  }
+  if (record.error !== undefined) saved.error = record.error;
+  if (entry.interruptedAt !== undefined) {
+    saved.interruptedAt = entry.interruptedAt;
+  }
+  return saved;
+}
+
 export class AgentRegistry {
   private readonly live = new Map<string, LiveAgent>();
   private readonly history: AgentRecord[] = [];
@@ -123,6 +221,8 @@ export class AgentRegistry {
     event: AgentSpawnedEvent | AgentSettledEvent,
   ) => void;
   private readonly newId: () => string;
+  private readonly persistHook?: (snapshot: PersistedAgent) => void;
+  private readonly unpersistHook?: (id: string) => void;
 
   constructor(options: AgentRegistryOptions = {}) {
     this.historyLimit = options.historyLimit ?? DEFAULT_HISTORY_LIMIT;
@@ -130,6 +230,8 @@ export class AgentRegistry {
     if (options.publish) this.publish = options.publish;
     this.newId =
       options.newId ?? (() => `agt_${randomBytes(4).toString("hex")}`);
+    if (options.persist) this.persistHook = options.persist;
+    if (options.unpersist) this.unpersistHook = options.unpersist;
   }
 
   // ── Lifecycle ─────────────────────────────────────────────────────────────
@@ -188,14 +290,188 @@ export class AgentRegistry {
       waiters: new Set(),
       reported: false,
       killRequested: false,
+      elapsedMs: 0,
+      resumeCount: 0,
+      interrupted: false,
     };
+    if (spec.requestedModel !== undefined) {
+      entry.requestedModel = spec.requestedModel;
+    }
+    if (spec.timeoutMs !== undefined) entry.timeoutMs = spec.timeoutMs;
+    if (spec.cwd !== undefined) entry.cwd = spec.cwd;
+    if (spec.preflight) entry.preflight = true;
     this.live.set(id, entry);
     if (spec.parent.kind === "agent") {
       this.live.get(spec.parent.agentId)?.record.children.push(id);
     }
+    this.persist(entry);
     return { ok: true, record: snapshot(entry) };
   }
 
+  /**
+   * Bring a persisted agent back into the live map after a restart, under
+   * its original id, with its mailbox, report and resume bookkeeping. It
+   * re-enters as `queued` — the runner `start()`s it again like any spawn.
+   * Caps are not re-checked: the agent was admitted before the restart.
+   *
+   * Refused (null) when the id is already live, or when its parent is an
+   * agent that did not come back (its report would have nowhere to go).
+   */
+  restore(saved: PersistedAgent): AgentRecord | null {
+    if (this.live.has(saved.id)) return null;
+    let parent: AgentParent;
+    if (saved.parentKind === "agent") {
+      if (!this.live.has(saved.parentId)) return null;
+      parent = { kind: "agent", agentId: saved.parentId };
+    } else {
+      parent = {
+        kind: "chat",
+        chatId: saved.parentId,
+        numericChatId: saved.parentNumericChatId ?? Number(saved.parentId),
+      };
+    }
+    const record: MutableAgentRecord = {
+      id: saved.id,
+      label: saved.label,
+      brief: saved.brief,
+      parent,
+      backendId: saved.backendId,
+      state: "queued",
+      depth: saved.depth,
+      createdAt: saved.createdAt,
+      result: null,
+      children: [],
+      inboxDepth: 0,
+    };
+    if (saved.model !== undefined) record.model = saved.model;
+    if (saved.reasoningEffort !== undefined) {
+      record.reasoningEffort = saved.reasoningEffort as ReasoningEffortLevel;
+    }
+    if (saved.reported && saved.resultSummary !== undefined) {
+      record.result = {
+        summary: saved.resultSummary,
+        ...(saved.resultDetails !== undefined
+          ? { details: saved.resultDetails }
+          : {}),
+      };
+    }
+    const entry: LiveAgent = {
+      record,
+      mailbox: saved.inbox.map((m) => ({ ...m })),
+      waiters: new Set(),
+      reported: saved.reported,
+      killRequested: false,
+      elapsedMs: saved.elapsedMs,
+      resumeCount: saved.resumeCount,
+      interrupted: false,
+    };
+    if (saved.requestedModel !== undefined) {
+      entry.requestedModel = saved.requestedModel;
+    }
+    if (saved.timeoutMs !== undefined) entry.timeoutMs = saved.timeoutMs;
+    if (saved.cwd !== undefined) entry.cwd = saved.cwd;
+    if (saved.preflight) entry.preflight = true;
+    if (saved.sessionId !== undefined) entry.sessionId = saved.sessionId;
+    if (saved.interruptedAt !== undefined) {
+      entry.interruptedAt = saved.interruptedAt;
+    }
+    this.live.set(saved.id, entry);
+    if (parent.kind === "agent") {
+      this.live.get(parent.agentId)?.record.children.push(saved.id);
+    }
+    return snapshot(entry);
+  }
+
+  /** Count one more restart-resume against this agent and persist it. */
+  markResumed(id: string): void {
+    const entry = this.live.get(id);
+    if (!entry) return;
+    entry.resumeCount += 1;
+    this.persist(entry);
+  }
+
+  /**
+   * Record the backend's conversation handle (Claude SDK session id, Codex
+   * thread id) as soon as the run reports it — the thing a restart resumes.
+   */
+  setSessionId(id: string, sessionId: string): void {
+    const entry = this.live.get(id);
+    if (!entry || entry.sessionId === sessionId) return;
+    entry.sessionId = sessionId;
+    this.persist(entry);
+  }
+
+  /** The persistence-only facts a resume needs, for a live agent. */
+  resumeInfo(id: string): {
+    sessionId?: string;
+    requestedModel?: string;
+    timeoutMs?: number;
+    cwd?: string;
+    elapsedMs: number;
+    resumeCount: number;
+    interruptedAt?: number;
+  } | null {
+    const entry = this.live.get(id);
+    if (!entry) return null;
+    return {
+      ...(entry.sessionId !== undefined ? { sessionId: entry.sessionId } : {}),
+      ...(entry.requestedModel !== undefined
+        ? { requestedModel: entry.requestedModel }
+        : {}),
+      ...(entry.timeoutMs !== undefined ? { timeoutMs: entry.timeoutMs } : {}),
+      ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
+      elapsedMs: entry.elapsedMs,
+      resumeCount: entry.resumeCount,
+      ...(entry.interruptedAt !== undefined
+        ? { interruptedAt: entry.interruptedAt }
+        : {}),
+    };
+  }
+
+  /**
+   * A daemon shutdown is about to abort every run. Stamp each live agent as
+   * interrupted — charging the time it has run so far against its timeout —
+   * and persist that while the row is still `running`, so the next boot
+   * resumes it. From here on the abort that tears the run down is not a
+   * kill: `isInterrupted` tells the runner to leave the row alone.
+   * Returns how many agents were parked.
+   */
+  interruptAll(now: number = Date.now()): number {
+    let parked = 0;
+    for (const entry of this.live.values()) {
+      if (entry.interrupted) continue;
+      entry.interrupted = true;
+      if (entry.record.startedAt !== undefined) {
+        entry.elapsedMs += Math.max(0, now - entry.record.startedAt);
+      }
+      entry.interruptedAt = now;
+      this.persist(entry);
+      parked++;
+    }
+    return parked;
+  }
+
+  /** Whether a shutdown interrupted this (still live) agent. */
+  isInterrupted(id: string): boolean {
+    return this.live.get(id)?.interrupted ?? false;
+  }
+
+  /**
+   * Drop an interrupted agent from the live map WITHOUT recording a terminal
+   * state — the persisted row stays `running` for the next boot. Waiters are
+   * released with the current snapshot; no `agent.settled` is published,
+   * because nothing settled.
+   */
+  releaseInterrupted(id: string): AgentRecord | null {
+    const entry = this.live.get(id);
+    if (!entry || !entry.interrupted) return null;
+    const record = snapshot(entry);
+    this.live.delete(id);
+    for (const waiter of entry.waiters) waiter(record);
+    entry.waiters.clear();
+    return record;
+  }
+
   /**
    * Drop a registration that never started (backend/model resolution failed).
    * It leaves no trace: nothing ran, so there is nothing to report on.
@@ -204,6 +480,7 @@ export class AgentRegistry {
     const entry = this.live.get(id);
     if (!entry) return;
     this.live.delete(id);
+    this.unpersist(id);
     const parent = entry.record.parent;
     if (parent.kind === "agent") {
       const children = this.live.get(parent.agentId)?.record.children;
@@ -225,7 +502,7 @@ export class AgentRegistry {
     // right after start() and settles the run as "killed".
     if (entry.killRequested) {
       try {
-        binding.abort.abort(new RunKilledError(`agent ${id} killed`));
+        binding.abort.abort(killReason(entry, id));
       } catch (err) {
         logWarn(
           "agents",
@@ -237,6 +514,7 @@ export class AgentRegistry {
     entry.record.state = "running";
     entry.record.startedAt = Date.now();
     if (binding.taskId !== undefined) entry.record.taskId = binding.taskId;
+    this.persist(entry);
     const { record } = entry;
     this.publish?.({
       type: "agent.spawned",
@@ -262,6 +540,7 @@ export class AgentRegistry {
     if (!entry || entry.reported) return false;
     entry.reported = true;
     entry.record.result = result;
+    this.persist(entry);
     return true;
   }
 
@@ -282,6 +561,7 @@ export class AgentRegistry {
     if (patch.usage !== undefined) record.usage = patch.usage;
 
     const settled = snapshot(entry);
+    this.persist(entry);
     this.live.delete(id);
     this.history.push(settled);
     if (this.history.length > this.historyLimit) {
@@ -313,7 +593,7 @@ export class AgentRegistry {
     if (!entry.killRequested) {
       entry.killRequested = true;
       try {
-        entry.abort?.abort(new RunKilledError(`agent ${id} killed`));
+        entry.abort?.abort(killReason(entry, id));
       } catch (err) {
         // An abort hook must not be able to break the kill path — but a
         // throwing one may leave the agent running, so say so.
@@ -352,6 +632,7 @@ export class AgentRegistry {
     if (!entry) return false;
     if (entry.mailbox.length >= this.mailboxLimit) return false;
     entry.mailbox.push(message);
+    this.persist(entry);
     return true;
   }
 
@@ -359,7 +640,9 @@ export class AgentRegistry {
   drain(id: string): AgentMessage[] {
     const entry = this.live.get(id);
     if (!entry) return [];
-    return entry.mailbox.splice(0, entry.mailbox.length);
+    const drained = entry.mailbox.splice(0, entry.mailbox.length);
+    if (drained.length > 0) this.persist(entry);
+    return drained;
   }
 
   /** The mailbox cap, for the error text the actions surface. */
@@ -461,6 +744,31 @@ export class AgentRegistry {
 
   // ── Internals ─────────────────────────────────────────────────────────────
 
+  /** Mirror one entry to the durable store. Never throws into a run. */
+  private persist(entry: LiveAgent): void {
+    if (!this.persistHook) return;
+    try {
+      this.persistHook(toPersisted(entry));
+    } catch (err) {
+      logWarn(
+        "agents",
+        `persist failed agent=${entry.record.id}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  private unpersist(id: string): void {
+    if (!this.unpersistHook) return;
+    try {
+      this.unpersistHook(id);
+    } catch (err) {
+      logWarn(
+        "agents",
+        `unpersist failed agent=${id}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
   /**
    * Depth a child of this parent would have, or null when the parent is an
    * agent that is no longer live (its children would have nowhere to report).
@@ -488,4 +796,6 @@ export class AgentRegistry {
 /** The daemon-wide registry. Tests needing isolation construct their own. */
 export const agentRegistry = new AgentRegistry({
   publish: (event) => bus.publish(event),
+  persist: (saved) => agentsRepo.upsert(saved),
+  unpersist: (id) => void agentsRepo.remove(id),
 });