talon-agent 3.34.0 → 3.34.1

package/src/backend/shared/index.ts

@@ -24,6 +24,8 @@
  *   - `stream-state` — backend-agnostic accumulator for stream loops.
  *   - `turn-interrupt` — user-driven mid-turn interrupt registry (the
  *     shared `ChatBackend.interruptChatTurn` for callback backends).
+ *   - `turn-phases` — the post-stream phases (accounting, session name,
+ *     trailing-prose contract, result tail) every handler runs.
  *
  * What's NOT here (intentionally):
  *   - SDK-specific event types — those live in each backend.
@@ -34,11 +36,6 @@
 
 export { captureDeliveredText } from "./delivered-text.js";
 
-export {
-  FLOW_VIOLATION_MAX_RETRIES,
-  detectFlowViolation,
-} from "./flow-violation.js";
-
 export { registerTurnInterrupt } from "./turn-interrupt.js";
 
 export { formatUserPrompt } from "./prompt-format.js";
@@ -49,8 +46,6 @@ export {
   buildFirstTurnReminder,
 } from "./delivery-contract.js";
 
-export { extractSessionName } from "../../util/session-name.js";
-
 export { summarizeUsage } from "./usage.js";
 
 // Only what is consumed THROUGH the barrel. Everything else in
@@ -66,8 +61,6 @@ export {
 
 export { prepareSystemPrompt, appendBackendSuffix } from "./system-prompt.js";
 
-export { classifyRetry } from "./model-retry.js";
-
 export {
   createStreamState,
   appendText,
@@ -88,11 +81,17 @@ export {
 
 export { sleep } from "./sleep.js";
 
-export {
-  recordToolCall,
-  recordTurnMetrics,
-  recordFailedTurnAccounting,
-  recordFlowViolation,
-} from "./metrics.js";
+export { recordToolCall } from "./metrics.js";
 
 export { applyRetryDecision } from "./handle-retry.js";
+
+export {
+  accountTurn,
+  accountFailedTurn,
+  nameSessionFromFirstMessage,
+  enforceTrailingProse,
+  finishCallbackTurn,
+  turnUsageSnapshot,
+} from "./turn-phases.js";
+
+export { buildResultEvents } from "./result-events.js";

package/src/backend/shared/result-events.ts

@@ -0,0 +1,30 @@
+/**
+ * The `usage` + `completed` pair that closes every successful
+ * `runChatTurn` stream, whether the backend emits events natively
+ * (Claude SDK) or through `handlerToEvents`. Kept free of storage and
+ * logging imports so the adapter stays a pure event translator.
+ */
+
+import type { AgentEvent } from "../../core/agent-runtime/events.js";
+import type { TokenUsageSnapshot } from "./usage.js";
+
+export function buildResultEvents(inputs: {
+  text: string;
+  durationMs: number;
+  usage: TokenUsageSnapshot;
+  modelId: string;
+}): [AgentEvent, AgentEvent] {
+  const usage = { ...inputs.usage, modelId: inputs.modelId };
+  return [
+    { type: "usage", usage },
+    {
+      type: "completed",
+      result: {
+        text: inputs.text,
+        durationMs: inputs.durationMs,
+        usage,
+        modelId: inputs.modelId,
+      },
+    },
+  ];
+}

package/src/backend/shared/turn-phases.ts

@@ -0,0 +1,277 @@
+/**
+ * The phases every chat turn runs once its SDK stream loop has ended.
+ *
+ * Each backend handler owns its options build, its `for await` loop and
+ * its event translation — everything that depends on the SDK's shape.
+ * What comes after is the same four steps in every backend:
+ *
+ *   1. `accountTurn` — per-turn metrics, session id, session usage
+ *      (or `accountFailedTurn` on the terminal-failure path).
+ *   2. `nameSessionFromFirstMessage` — the session title.
+ *   3. `enforceTrailingProse` — the tool-only delivery contract and the
+ *      flow-violation re-prompt decision.
+ *   4. `finishCallbackTurn` — the delivery summary log lines and the
+ *      `QueryResult` (the event-stream tail is `result-events.ts`).
+ *
+ * The functions take the stream state and explicit config bits and return
+ * explicit results; the handler decides what to do with a retry decision
+ * because recursion is the handler's own entry point.
+ */
+
+import {
+  getSession,
+  recordUsage,
+  setSessionId,
+  setSessionName,
+} from "../../storage/sessions.js";
+import { log } from "../../util/log.js";
+import { extractSessionName } from "../../util/session-name.js";
+import { traceMessage } from "../../util/trace.js";
+import {
+  FLOW_VIOLATION_MAX_RETRIES,
+  detectFlowViolation,
+  type FlowViolationResult,
+} from "./flow-violation.js";
+import type { QueryResult } from "./handler-types.js";
+import {
+  recordFailedTurnAccounting,
+  recordFlowViolation,
+  recordTurnMetrics,
+} from "./metrics.js";
+import type { StreamState } from "./stream-state.js";
+import { summarizeUsage, type TokenUsageSnapshot } from "./usage.js";
+
+// ── Usage snapshot ──────────────────────────────────────────────────────────
+
+/** The slice of a stream state the post-loop phases read. */
+export type TurnUsageState = Pick<
+  StreamState,
+  | "sdkInputTokens"
+  | "sdkOutputTokens"
+  | "sdkCacheRead"
+  | "sdkCacheWrite"
+  | "toolCalls"
+  | "numApiCalls"
+  | "contextTokens"
+  | "contextWindow"
+>;
+
+/** The turn's token totals as the metrics + session layers consume them. */
+export function turnUsageSnapshot(state: TurnUsageState): TokenUsageSnapshot {
+  return {
+    inputTokens: state.sdkInputTokens,
+    outputTokens: state.sdkOutputTokens,
+    cacheRead: state.sdkCacheRead,
+    cacheWrite: state.sdkCacheWrite,
+  };
+}
+
+// ── Phase 1: accounting ─────────────────────────────────────────────────────
+
+/** Context-fill fields persisted alongside the token totals. */
+type TurnContextUsage = {
+  contextTokens?: number;
+  contextWindow?: number;
+  numApiCalls?: number;
+  costUsd?: number;
+};
+
+export type AccountTurnInputs = {
+  chatId: string;
+  /** Backend id — the `backend.<id>.*` metric dimension. */
+  backend: string;
+  state: TurnUsageState;
+  durationMs: number;
+  model: string;
+  /** Provider session id to persist; skipped when absent or unchanged. */
+  sessionId?: string;
+  /** True when the turn ended in a delivered failure (Codex `turn.failed`). */
+  failed?: boolean;
+  /** Override for backends that count tool calls outside the stream state. */
+  toolCalls?: number;
+  /**
+   * Context-fill fields for `recordUsage`. Only backends whose stream
+   * reports them pass this; the others leave the session's context
+   * display untouched (zeroed) as they always have.
+   */
+  context?: TurnContextUsage;
+};
+
+/**
+ * Record the per-turn metric rollup, persist the provider session id and
+ * fold the turn's usage into the session. Each write is independent, so
+ * the order here is not load-bearing.
+ */
+export function accountTurn(inputs: AccountTurnInputs): void {
+  const { chatId, state, durationMs } = inputs;
+  const usage = turnUsageSnapshot(state);
+  recordTurnMetrics({
+    chatId,
+    backend: inputs.backend,
+    durationMs,
+    toolCalls: inputs.toolCalls ?? state.toolCalls,
+    apiCalls: state.numApiCalls,
+    ...(inputs.failed !== undefined ? { failed: inputs.failed } : {}),
+    usage,
+  });
+  persistSessionId(chatId, inputs.sessionId);
+  recordUsage(chatId, {
+    ...usage,
+    durationMs,
+    model: inputs.model,
+    ...inputs.context,
+  });
+}
+
+function persistSessionId(chatId: string, sessionId: string | undefined): void {
+  if (!sessionId) return;
+  if (getSession(chatId).sessionId === sessionId) return;
+  setSessionId(chatId, sessionId);
+}
+
+export type AccountFailedTurnInputs = {
+  chatId: string;
+  backend: string;
+  state: TurnUsageState;
+  durationMs: number;
+  model: string;
+  /** Overrides for backends that count outside the stream state. */
+  toolCalls?: number;
+  apiCalls?: number;
+  usage?: TokenUsageSnapshot;
+};
+
+/**
+ * Terminal-failure accounting from the stream state — the tokens a
+ * failed turn burned still count. Not for retry paths: the recursive
+ * attempt accounts for itself.
+ */
+export function accountFailedTurn(inputs: AccountFailedTurnInputs): void {
+  const { state } = inputs;
+  recordFailedTurnAccounting({
+    backend: inputs.backend,
+    chatId: inputs.chatId,
+    durationMs: inputs.durationMs,
+    toolCalls: inputs.toolCalls ?? state.toolCalls,
+    apiCalls: inputs.apiCalls ?? state.numApiCalls,
+    model: inputs.model,
+    usage: inputs.usage ?? turnUsageSnapshot(state),
+    contextTokens: state.contextTokens,
+    contextWindow: state.contextWindow,
+  });
+}
+
+// ── Phase 2: session name ───────────────────────────────────────────────────
+
+/**
+ * Title the session from the user's first message. Skipped on retries,
+ * whose `text` is a synthetic reminder rather than what the user said.
+ */
+export function nameSessionFromFirstMessage(inputs: {
+  chatId: string;
+  text: string;
+  previousTurns: number;
+  isRetry?: boolean;
+}): void {
+  if (inputs.previousTurns !== 0 || inputs.isRetry) return;
+  const name = extractSessionName(inputs.text);
+  if (name) setSessionName(inputs.chatId, name);
+}
+
+// ── Phase 3: trailing-prose contract ────────────────────────────────────────
+
+export type TrailingProseInputs = {
+  chatId: string;
+  state: Pick<
+    StreamState,
+    "lastTrailingText" | "turnTerminated" | "deliveredTextNorms" | "toolCalls"
+  >;
+  /** Synthetic flow-violation retries already spent on this message. */
+  flowRetries: number;
+  /** Frontend-aware reminder; omit for the default telegram-shaped text. */
+  reminder?: string;
+};
+
+/**
+ * Apply the tool-only delivery contract to a finished turn: detect a
+ * flow violation, count it, log it, and say whether the handler should
+ * re-prompt with `reminder`. Callers gate this on the contract actually
+ * being in force (a messaging frontend with delivery tools registered).
+ */
+export function enforceTrailingProse(
+  inputs: TrailingProseInputs,
+): FlowViolationResult {
+  const { chatId, state, flowRetries } = inputs;
+  const violation = detectFlowViolation({
+    trailingText: state.lastTrailingText,
+    turnTerminated: state.turnTerminated,
+    deliveredTextNorms: state.deliveredTextNorms,
+    toolCalls: state.toolCalls,
+    retried: flowRetries > 0,
+    retryCount: flowRetries,
+    maxRetries: FLOW_VIOLATION_MAX_RETRIES,
+    ...(inputs.reminder !== undefined ? { reminder: inputs.reminder } : {}),
+  });
+  if (!violation.violated) return violation;
+
+  recordFlowViolation(
+    chatId,
+    violation.shouldRetry ? "retried" : "cap_exhausted",
+  );
+  log(
+    "agent",
+    `[${chatId}] flow violation: ${violation.reason}. ${
+      violation.shouldRetry
+        ? "Re-prompting with reminder."
+        : `Retry cap (${FLOW_VIOLATION_MAX_RETRIES}) exhausted — accepting silent drop.`
+    }`,
+  );
+  return violation;
+}
+
+// ── Phase 4: result ─────────────────────────────────────────────────────────
+
+export type FinishCallbackTurnInputs = {
+  chatId: string;
+  state: TurnUsageState &
+    Pick<StreamState, "turnTerminated" | "deliveredTextNorms">;
+  responseText: string;
+  durationMs: number;
+  setupMs: number;
+  turnMs: number;
+  /** `routeDelivery`'s decision, or a backend's own route (`silent`). */
+  delivery: { route: string; chars: number };
+  /** Extra `key=value` diagnostics appended to the summary line. */
+  detail?: string;
+};
+
+/**
+ * The end-of-turn log lines and trace for a callback-shaped handler, and
+ * the `QueryResult` it returns.
+ */
+export function finishCallbackTurn(
+  inputs: FinishCallbackTurnInputs,
+): QueryResult {
+  const { chatId, state, responseText, durationMs, delivery } = inputs;
+  const usage = turnUsageSnapshot(state);
+  log(
+    "agent",
+    `[${chatId}] delivery: ${delivery.route} (${delivery.chars} chars)`,
+  );
+  log(
+    "agent",
+    `[${chatId}] -> (${summarizeUsage(usage, {
+      durationMs,
+      toolCalls: state.toolCalls,
+    })} terminator=${state.turnTerminated ? "yes" : "no"} ` +
+      `delivered=${state.deliveredTextNorms.length} ` +
+      `respLen=${responseText.length} ` +
+      `setup=${inputs.setupMs}ms turn=${inputs.turnMs}ms` +
+      `${inputs.detail ? ` ${inputs.detail}` : ""})`,
+  );
+  traceMessage(chatId, "out", responseText, {
+    durationMs,
+    toolCalls: state.toolCalls,
+  });
+  return { text: responseText, durationMs, ...usage };
+}

package/src/core/background/triggers/exit.ts

@@ -8,16 +8,18 @@ import type { ChildProcess } from "node:child_process";
 import {
   getTrigger,
   updateTrigger,
+  SHUTDOWN_KILL_ERROR,
   type Trigger,
   type TriggerStatus,
 } from "../../../storage/trigger-store.js";
-import { log, logError } from "../../../util/log.js";
+import { log, logDebug, logError } from "../../../util/log.js";
 import { appendDailyLog } from "../../../storage/daily-log.js";
 import {
   children,
   timeouts,
   logStreams,
   lineBuffers,
+  lifecycle,
   wardened,
   SIGTERM_GRACE_MS,
   WARDEN_GRACE_SLACK_MS,
@@ -53,6 +55,9 @@ export function cancelTrigger(id: string): boolean {
 
 /** Kill all running children — called during shutdown. */
 export async function shutdownTriggers(): Promise<void> {
+  // Flag first, unconditionally: a child that exits on its own from here on
+  // must not dispatch a wake either — the backend pool is going away.
+  lifecycle.shuttingDown = true;
   if (children.size === 0) return;
   log("triggers", `Shutting down ${children.size} running trigger(s)`);
   const ids = Array.from(children.keys());
@@ -70,7 +75,7 @@ export async function shutdownTriggers(): Promise<void> {
     } else {
       updateTrigger(id, {
         status: "terminated",
-        lastError: "Killed by Talon shutdown",
+        lastError: SHUTDOWN_KILL_ERROR,
       });
     }
     killChild(id, c);
@@ -188,6 +193,18 @@ export async function finalizeExit(
     status === "cancelled" ||
     status === "terminated"
   ) {
+    // During shutdown the backend pool is being torn down alongside us, so a
+    // dispatch here can only fail ("Backend role not bound"). Skip it; the
+    // record keeps status=terminated + SHUTDOWN_KILL_ERROR and no lastFireAt
+    // bump, which is exactly what resumeAfterRestart's late death notice
+    // keys on — the chat hears about it on the next boot instead.
+    if (lifecycle.shuttingDown) {
+      logDebug(
+        "triggers",
+        `Skipped ${status} wake for "${t.name}" [${id}] — shutting down; deferred to next boot`,
+      );
+      return;
+    }
     await fireWake(id, status, payload, /* terminal */ true);
   }
 }

package/src/core/background/triggers/resume.ts

@@ -9,6 +9,7 @@ import {
   getAllTriggers,
   updateTrigger,
   RESTART_KILL_ERROR,
+  SHUTDOWN_KILL_ERROR,
   type Trigger,
 } from "../../../storage/trigger-store.js";
 import { log, logError } from "../../../util/log.js";
@@ -50,19 +51,25 @@ export async function resumeAfterRestart(): Promise<void> {
     // Late death notice. Two cases earn one:
     //   - never fired at all (the old rule) — the chat heard nothing
     //     from this trigger, so its termination is news; and
-    //   - killed by THIS restart (recoverInterrupted stamped the
-    //     marker error) — even a multi-fire watcher that signalled
-    //     mid-run was still an active promise when the process died,
-    //     and without this wake the chat never learns its watcher is
-    //     gone. (Previously gated on lastFireAt === undefined alone,
-    //     which silently dropped exactly those watchers.)
+    //   - killed by THIS restart — either the crash path
+    //     (recoverInterrupted stamped RESTART_KILL_ERROR) or the clean
+    //     path (shutdownTriggers stamped SHUTDOWN_KILL_ERROR and
+    //     finalizeExit deliberately skipped the wake because the
+    //     backend pool was already going away). Even a multi-fire
+    //     watcher that signalled mid-run was still an active promise
+    //     when the process died, and without this wake the chat never
+    //     learns its watcher is gone. (Previously gated on
+    //     lastFireAt === undefined alone, which silently dropped
+    //     exactly those watchers.)
     // Triggers that exited on their own already fired their terminal
     // wake (lastFireAt set, no marker) — they stay silent here.
     if (
       t.status === "terminated" &&
       t.endedAt &&
       Date.now() - t.endedAt < 5 * 60_000 &&
-      (t.lastFireAt === undefined || t.lastError === RESTART_KILL_ERROR)
+      (t.lastFireAt === undefined ||
+        t.lastError === RESTART_KILL_ERROR ||
+        t.lastError === SHUTDOWN_KILL_ERROR)
     ) {
       await fireWake(t.id, "terminated", t.lastError, /* terminal */ true);
     }

package/src/core/background/triggers/state.ts

@@ -20,6 +20,14 @@ export type TriggerDeps = {
 /** Reassignable on a holder object so submodules see the injected deps. */
 export const depsHolder: { deps: TriggerDeps | null } = { deps: null };
 
+/**
+ * Set by shutdownTriggers for the rest of the process lifetime. finalizeExit
+ * consults it so the children it kills don't dispatch wakes into a backend
+ * pool that is being torn down at the same time. initTriggers clears it so a
+ * fresh lifecycle (next boot, or the next test) starts clean.
+ */
+export const lifecycle = { shuttingDown: false };
+
 /** Live child handles, keyed by trigger id. */
 export const children = new Map<string, ChildProcess>();
 export const timeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -43,6 +51,7 @@ export const WARDEN_GRACE_SLACK_MS = 2_000;
 
 export function initTriggers(d: TriggerDeps): void {
   depsHolder.deps = d;
+  lifecycle.shuttingDown = false;
   log("triggers", "Initialized");
 }