talon-agent 5.26.6 → 5.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.26.6",
+  "version": "5.28.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/app.ts

@@ -26,7 +26,11 @@ import {
   runStartupCatchup,
 } from "./core/background/cron/scheduler.js";
 import { shutdownTriggers } from "./core/background/triggers/index.js";
-import { shutdownAgents } from "./core/agents/index.js";
+import {
+  interruptAgentsForRestart,
+  resumeAgentsAfterRestart,
+  shutdownAgents,
+} from "./core/agents/index.js";
 import { stopBackupScheduler } from "./core/backup/index.js";
 import { pruneSettledTriggers } from "./storage/triggers.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
@@ -124,10 +128,18 @@ stampDaemonOwner();
  *
  * Never throws: a failed restore still boots the daemon (with the reason
  * in the log and the request deleted, so the next boot is normal).
+ * Returns the confirmation line and who asked for it, so it can be sent
+ * back to that chat once the frontends are up.
  */
-async function applyStagedRestore(): Promise<string | null> {
+async function applyStagedRestore(): Promise<{
+  text: string;
+  requestedBy?: string;
+  frontend?: string;
+} | null> {
   const { applyPendingRestore, readRestorePending } =
     await import("./core/backup/index.js");
+  const { formatRestoreNotice } =
+    await import("./core/backup/restore/notice.js");
   if (!(await readRestorePending())) return null;
   const { loadConfig } = await import("./core/config/index.js");
   const { resolveBackupSettings } = await import("./core/backup/plan.js");
@@ -137,12 +149,11 @@ async function applyStagedRestore(): Promise<string | null> {
     beforeApply: closeDatabase,
   });
   if (!report) return null;
-  return (
-    `♻️ Restored snapshot ${report.id}` +
-    (report.checkpointId
-      ? ` (previous state saved as checkpoint ${report.checkpointId})`
-      : "")
-  );
+  return {
+    text: formatRestoreNotice(report),
+    requestedBy: report.requestedBy,
+    frontend: report.frontend,
+  };
 }
 
 /**
@@ -340,6 +351,11 @@ async function gracefulShutdown(signal: string): Promise<void> {
   if (shuttingDown) return;
   shuttingDown = true;
   log("shutdown", `${signal} received, shutting down gracefully...`);
+  // Park running sub-agents before anything is torn down: stopping the
+  // frontends and the backend pool aborts their runs, and an agent that is
+  // not parked first would record that abort as its death. Parked agents
+  // stay `running` in the store and the next boot resumes them.
+  crashStep("sub-agent park", () => interruptAgentsForRestart());
 
   const deadlineAt = Date.now() + SHUTDOWN_TIMEOUT_MS;
   const forceTimer = setTimeout(() => {
@@ -432,8 +448,8 @@ async function gracefulShutdown(signal: string): Promise<void> {
     triggerPruneTimer = null;
   });
   await shutdownStep("triggers", shutdownTriggers);
-  // Sub-agents are isolated one-shot runs: aborting them is all the daemon
-  // can do, and their parents are gone with the process anyway.
+  // Sub-agents were parked at the top of the shutdown; this aborts whatever
+  // is still running so the process can exit. They resume on the next boot.
   await shutdownStep("sub-agents", shutdownAgents);
   await shutdownStep("watchdog", stopWatchdog);
   await shutdownStep("resource sampler", stopResourceSampler);
@@ -528,15 +544,30 @@ async function main(): Promise<void> {
   // what follows runs while the daemon is alive — not, as it once did,
   // hours later during shutdown.
   await bootPhase("frontends start", () => startFrontends(frontends));
+  // Sub-agents the previous process left running come back now that their
+  // tools (gateway, frontends) and their parents' wake path are up.
+  // Fire-and-forget: a slow backend acquisition must not hold the boot.
+  resumeAgentsAfterRestart().catch((err) =>
+    logError("agents", "resume after restart failed", err),
+  );
   // Phase 0 accounting (docs/ts-migration-plan.md): the boot is over the
   // moment the frontends are listening, so the totals are folded into the
   // metrics store here, from the same uptime figure the log line prints.
-  // A restore applied at boot happened before any frontend existed, so the
-  // operator hears about it here, on the first channel that can carry it.
+  // A restore applied at boot happened before any frontend existed, so it
+  // is reported here, on the first channels that can carry it: the chat
+  // that asked for it, or the admin's primary chat when that one can't be
+  // reached. Not awaited — delivery may retry while a frontend finishes
+  // connecting, and the boot shouldn't wait on a courtesy message.
   if (restoreReport) {
     const { notifyAdmin } =
       await import("./core/frontend-runtime/admin-notify.js");
-    await notifyAdmin(restoreReport);
+    const { deliverRestoreNotice } =
+      await import("./core/backup/restore/notice.js");
+    void deliverRestoreNotice({
+      text: restoreReport.text,
+      requester: restoreReport,
+      notifyAdmin,
+    });
   }
   // Same reasoning for a crash: the process that died couldn't say so,
   // so the marker it left is announced now. The probes start here too —

package/src/backend/claude-sdk/factory.ts

@@ -62,6 +62,8 @@ const claudeSdkFactory: BackendFactory = {
 
     const background: BackgroundRunner = {
       runOneShotAgent: (p) => host.runOneShot(p),
+      // Honours resumeSessionId (SDK `resume`) and reports the session id.
+      supportsResume: true,
       // Not a protocol-table row yet: subprocess eviction reaches into
       // the SDK's own children, so it belongs to the host — but the
       // design's message table has no request for it. Tracked as an open

package/src/backend/claude-sdk/one-shot.ts

@@ -21,7 +21,7 @@ import { EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
 import { isBackgroundToolContext } from "../../core/agents/context.js";
 import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
-import { emitAssistantText } from "../runtime/one-shot-hooks.js";
+import { emitAssistantText, emitSessionId } from "../runtime/one-shot-hooks.js";
 import {
   isOtherLiveDaemon,
   ownerFromEnviron,
@@ -72,6 +72,8 @@ export async function runOneShotAgent(
     abortController,
     appendLog,
     onAssistantText,
+    resumeSessionId,
+    onSessionId,
   } = params;
 
   // Reasoning effort is opt-in for background runs (config `heartbeatEffort`
@@ -100,7 +102,17 @@ export async function runOneShotAgent(
     // dream). Same as chat minus `Agent` — nested sub-agent dispatch from
     // inside an unattended pass complicates lifecycle tracking.
     tools: [...ALLOWED_TOOLS_BACKGROUND],
+    // A sub-agent interrupted by a daemon restart continues its own SDK
+    // session: the transcript (brief, tool calls, results) is intact on disk
+    // and the prompt below is only the "you were interrupted" note.
+    ...(resumeSessionId ? { resume: resumeSessionId } : {}),
   };
+  if (resumeSessionId) {
+    log(
+      "agent",
+      `[${contextLabel}] Claude one-shot resuming session ${resumeSessionId}`,
+    );
+  }
 
   if (reasoningEffort && !thinkingConfig) {
     // `minimal` / `xhigh` are Codex-side vocabulary with no Claude
@@ -132,7 +144,16 @@ export async function runOneShotAgent(
   // The final `result` message carries the run's total token usage — the
   // settlement figure the task table records.
   let usage: OneShotUsage | undefined;
+  let sessionReported: string | undefined;
   for await (const msg of qi) {
+    // Every SDK message carries the session id; report it the first time it
+    // is seen (and again only if it ever changes — a resumed session can be
+    // forked to a new id).
+    const sid = (msg as { session_id?: unknown }).session_id;
+    if (typeof sid === "string" && sid && sid !== sessionReported) {
+      sessionReported = sid;
+      emitSessionId(onSessionId, sid);
+    }
     await formatAndAppendMessage(appendLog, msg, onAssistantText);
     if (msg.type === "result") {
       const u = msg.usage;

package/src/backend/codex/factory.ts

@@ -60,6 +60,8 @@ const codexFactory: BackendFactory = {
 
     const background: BackgroundRunner = {
       runOneShotAgent: (p) => codexRunOneShotAgent(p),
+      // Honours resumeSessionId (resumeThread) and reports the thread id.
+      supportsResume: true,
       // Codex spawns per-turn CLI subprocesses that the SDK reaps on its own
       // — no explicit orphan-eviction path needed here.
     };

package/src/backend/codex/one-shot.ts

@@ -20,7 +20,7 @@
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
 import { appendBackendSuffix } from "../runtime/index.js";
-import { emitAssistantText } from "../runtime/one-shot-hooks.js";
+import { emitAssistantText, emitSessionId } from "../runtime/one-shot-hooks.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
 import {
   CODEX_SYSTEM_PROMPT_SUFFIX,
@@ -87,6 +87,8 @@ export async function runOneShotAgent(
     abortController,
     appendLog,
     onAssistantText,
+    resumeSessionId,
+    onSessionId,
   } = params;
 
   const codex = ensureCodex(contextLabel);
@@ -99,7 +101,10 @@ export async function runOneShotAgent(
   // Codex SDK doesn't expose `system` on runStreamed — the system
   // prompt gets prepended to the user prompt for a one-shot, since
   // there's no thread continuity to worry about.
-  const inputText = `${finalSystemPrompt}\n\n---\n\n${prompt}`;
+  // A resumed thread already carries the system prompt from its first turn.
+  const inputText = resumeSessionId
+    ? prompt
+    : `${finalSystemPrompt}\n\n---\n\n${prompt}`;
 
   const resolved = resolveOneShotModel(requestedModel);
   const activeModel = resolved.model;
@@ -130,12 +135,16 @@ export async function runOneShotAgent(
     );
   }
 
-  const thread = codex.startThread({
-    model: activeModel,
-    skipGitRepoCheck: true,
-    ...(modelReasoningEffort ? { modelReasoningEffort } : {}),
-    ...CODEX_THREAD_PERMISSIONS,
-  });
+  const thread = openThread(
+    codex,
+    {
+      model: activeModel,
+      skipGitRepoCheck: true,
+      ...(modelReasoningEffort ? { modelReasoningEffort } : {}),
+      ...CODEX_THREAD_PERMISSIONS,
+    },
+    params,
+  );
 
   // The real reason a run failed lives in the stream, not in whatever the
   // SDK throws afterwards: a model the account can't use yields
@@ -159,19 +168,10 @@ export async function runOneShotAgent(
     let usage: OneShotUsage | undefined;
     for await (const event of events) {
       if (abortController.signal.aborted) break;
+      reportThreadStarted(event, onSessionId);
       await appendCodexEvent(appendLog, event, onAssistantText);
       failure.observe(event);
-      if (event.type === "turn.completed") {
-        const u = (event as { usage?: Record<string, number> }).usage;
-        if (u) {
-          usage = {
-            inputTokens: u.input_tokens ?? 0,
-            outputTokens: u.output_tokens ?? 0,
-            cacheRead: u.cached_input_tokens ?? 0,
-            cacheWrite: 0, // Codex doesn't report cache writes
-          };
-        }
-      }
+      usage = turnUsage(event) ?? usage;
     }
     // A stream that ends cleanly after `turn.failed` is still a failed run
     // — returning here is how 26/26 Codex cron runs were stored as "ok".
@@ -202,6 +202,55 @@ export async function runOneShotAgent(
   }
 }
 
+type CodexClient = ReturnType<typeof ensureCodex>;
+type CodexThreadOptions = Parameters<CodexClient["startThread"]>[0];
+
+/**
+ * Start the run's thread — or, for a sub-agent interrupted by a daemon
+ * restart, continue its own thread and re-report the handle.
+ */
+function openThread(
+  codex: CodexClient,
+  options: CodexThreadOptions,
+  params: Pick<
+    OneShotAgentParams,
+    "resumeSessionId" | "onSessionId" | "contextLabel"
+  >,
+): ReturnType<CodexClient["startThread"]> {
+  const { resumeSessionId, onSessionId, contextLabel } = params;
+  if (!resumeSessionId) return codex.startThread(options);
+  log(
+    "agent",
+    `[${contextLabel}] Codex one-shot resuming thread ${resumeSessionId}`,
+  );
+  const thread = codex.resumeThread(resumeSessionId, options);
+  emitSessionId(onSessionId, resumeSessionId);
+  return thread;
+}
+
+/** Report the thread id from `thread.started` so a restart can resume it. */
+function reportThreadStarted(
+  event: { type: string },
+  onSessionId: OneShotAgentParams["onSessionId"],
+): void {
+  if (event.type !== "thread.started") return;
+  const threadId = (event as { thread_id?: unknown }).thread_id;
+  if (typeof threadId === "string") emitSessionId(onSessionId, threadId);
+}
+
+/** The cumulative usage a `turn.completed` event carries, if any. */
+function turnUsage(event: { type: string }): OneShotUsage | undefined {
+  if (event.type !== "turn.completed") return undefined;
+  const u = (event as { usage?: Record<string, number> }).usage;
+  if (!u) return undefined;
+  return {
+    inputTokens: u.input_tokens ?? 0,
+    outputTokens: u.output_tokens ?? 0,
+    cacheRead: u.cached_input_tokens ?? 0,
+    cacheWrite: 0, // Codex doesn't report cache writes
+  };
+}
+
 /**
  * Record a model as OAuth-incompat when a one-shot failed on it with an
  * explicit server mismatch, so the next run pre-emptively swaps.

package/src/backend/runtime/one-shot-hooks.ts

@@ -43,3 +43,27 @@ export function emitAssistantText(
     );
   }
 }
+
+/**
+ * Report the run's conversation handle (Claude SDK session id, Codex thread
+ * id) to the run's optional consumer — the sub-agent runner persists it so a
+ * daemon restart can resume the conversation. Same contract as
+ * `emitAssistantText`: synchronous, no-op without a hook or an id, and a
+ * throwing consumer is logged, never propagated into the run.
+ */
+export function emitSessionId(
+  onSessionId: OneShotAgentParams["onSessionId"],
+  sessionId: string | undefined,
+): void {
+  if (!onSessionId || !sessionId) return;
+  try {
+    onSessionId(sessionId);
+  } catch (err) {
+    logWarn(
+      "agent",
+      `one-shot onSessionId hook threw (ignored): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

package/src/core/agent-runtime/capabilities.ts

@@ -112,6 +112,13 @@ export interface ChatBackend {
  */
 export interface BackgroundRunner {
   runOneShotAgent(params: OneShotAgentParams): Promise<OneShotUsage | void>;
+  /**
+   * Whether `runOneShotAgent` honours `resumeSessionId` (and reports the
+   * handle through `onSessionId`). A sub-agent interrupted by a daemon
+   * restart resumes its conversation on such a backend; on any other it is
+   * re-briefed with its previous transcript instead.
+   */
+  readonly supportsResume?: boolean;
   evictOrphanSubprocesses?(contextLabel: string): Promise<{
     found: number;
     termed: number;

package/src/core/agents/index.ts

@@ -23,7 +23,9 @@ export {
   clampTimeout,
   getAgentCaps,
   initAgents,
+  interruptAgentsForRestart,
   killAgent,
+  resumeAgentsAfterRestart,
   shutdownAgents,
   spawnAgent,
 } from "./runner.js";

package/src/core/agents/prompt.ts

@@ -85,6 +85,81 @@ export function buildAgentPrompt(
   );
 }
 
+/** Human time for an interruption stamp. */
+function stamp(at: number): string {
+  return new Date(at).toISOString().replace("T", " ").slice(0, 19) + " UTC";
+}
+
+/**
+ * The note a resumed agent receives when its own backend conversation is
+ * continued after a daemon restart. The transcript — brief, tool calls,
+ * results — is intact above it, so this only says what happened and what
+ * to be careful of.
+ */
+export function buildResumePrompt(args: {
+  interruptedAt: number;
+  elapsedMinutes: number;
+}): string {
+  return (
+    `[System: You were interrupted by a daemon restart at ` +
+    `${stamp(args.interruptedAt)} (about ${args.elapsedMinutes} min into ` +
+    `your run). Your conversation so far is intact above — continue the ` +
+    `brief from where you left off; do not start over. Anything that was ` +
+    `mid-flight when the restart hit (a shell command, a build, a tool call ` +
+    `with no result) may not have completed: check the actual state (files, ` +
+    `git status, processes) before relying on it or repeating it. Call ` +
+    `check_inbox — messages sent while you were down are still there. When ` +
+    `you are done, call report_result exactly once.]`
+  );
+}
+
+/**
+ * The activation prompt for an interrupted agent whose backend cannot
+ * resume a conversation: the original brief again, plus what the previous
+ * attempt did (the tail of its run log) so it picks up rather than redoes.
+ */
+export function buildRebriefPrompt(args: {
+  brief: string;
+  /** Re-append the pre-flight lane instruction the original spawn carried. */
+  preflight?: boolean;
+  interruptedAt: number;
+  elapsedMinutes: number;
+  logPath: string;
+  logTail: string;
+}): string {
+  const tail = args.logTail.trim()
+    ? `\n\nTail of the previous attempt's run log (full log: ` +
+      `${args.logPath}):\n\n<previous-run-log>\n${args.logTail}\n` +
+      `</previous-run-log>`
+    : `\n\n(The previous attempt's run log is at ${args.logPath}.)`;
+  return (
+    `${buildAgentPrompt(args.brief, { preflight: args.preflight === true })}\n\n` +
+    `[System: RESUMED AFTER A DAEMON RESTART. You already worked on this ` +
+    `brief for about ${args.elapsedMinutes} min before a daemon restart ` +
+    `interrupted you at ${stamp(args.interruptedAt)}; this backend could not ` +
+    `resume that conversation, so you are starting a new one. Do NOT start ` +
+    `over: read what the previous attempt did below, inspect the state it ` +
+    `left (files, branches, commits, processes) and continue from there. ` +
+    `Call check_inbox — messages sent while you were down are still there.]` +
+    tail
+  );
+}
+
+/** Run-log separator written when a restarted agent resumes. */
+export function agentResumeLogHeader(
+  record: AgentRecord,
+  model: string,
+  interruptedAt: number,
+  sessionId?: string,
+): string {
+  return (
+    `\n\n---\n\n# resumed after daemon restart — ${new Date().toISOString()}\n` +
+    `**Interrupted:** ${new Date(interruptedAt).toISOString()} ` +
+    `**Backend:** ${record.backendId} **Model:** ${model} ` +
+    `**Mode:** ${sessionId ? `session resume (${sessionId})` : "re-briefed"}\n\n`
+  );
+}
+
 /** Header line of a run log. */
 export function agentLogHeader(record: AgentRecord, model: string): string {
   return (