talon-agent 5.18.2 → 5.19.0

package/src/util/log.ts

@@ -19,8 +19,10 @@ import {
   openSync,
   writeSync,
   closeSync,
+  fstatSync,
 } from "node:fs";
 import { dirs, files } from "./paths.js";
+import { currentTurnId } from "./logging/turn-scope.js";
 
 export type LogComponent =
   | "bot"
@@ -31,8 +33,10 @@ export type LogComponent =
   | "kv"
   | "media"
   | "notify"
+  | "alert"
   | "agent"
   | "agents"
+  | "tasks"
   | "pulse"
   | "userbot"
   | "users"
@@ -107,6 +111,47 @@ function rotateIfLarge(path: string): void {
 
 rotateIfLarge(LOG_FILE);
 
+/**
+ * Runtime retention for talon.log: once the live file passes the cap the
+ * sink shifts it to `talon.log.1` (…`.1` → `.2`, oldest dropped), so a
+ * long-running daemon keeps a bounded, numbered history instead of one
+ * ever-growing file. The start-time `.old` rule above stays as it was;
+ * readers treat `.old` as one more generation.
+ */
+const LOG_ROTATE_KEEP = 5;
+
+/** The disk name of rotated generation `n` (1 = newest) of `path`. */
+function rotatedLogPath(path: string, n: number): string {
+  return `${path}.${n}`;
+}
+
+/**
+ * Shift `path` into the numbered generations: drop `.keep`, move each
+ * `.n` to `.n+1`, then `path` to `.1`. Every step is one rename, so a
+ * crash part-way leaves a gap in the numbering, never a lost line — the
+ * only file ever deleted is the oldest generation. Throws on the first
+ * failure other than a missing generation.
+ */
+export function shiftLogGenerations(
+  path: string,
+  keep: number = LOG_ROTATE_KEEP,
+): void {
+  const skipMissing = (step: () => void): void => {
+    try {
+      step();
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  };
+  skipMissing(() => unlinkSync(rotatedLogPath(path, keep)));
+  for (let n = keep - 1; n >= 1; n--) {
+    skipMissing(() =>
+      renameSync(rotatedLogPath(path, n), rotatedLogPath(path, n + 1)),
+    );
+  }
+  renameSync(path, rotatedLogPath(path, 1));
+}
+
 // Suppress console output for terminal frontend (stdout belongs to the REPL)
 let quiet = process.env.TALON_QUIET === "1";
 if (!quiet) {
@@ -169,6 +214,8 @@ const SINK_MAX_RETRY_MS = 5 * 60_000;
 export type SyncLogTarget = {
   /** Append one already-serialized line. Throws on failure. */
   write(line: string): void;
+  /** Bytes already in the file when it was opened, when known. */
+  readonly initialSize?: number;
   /** Release the underlying handle. Never throws. */
   close(): void;
 };
@@ -182,6 +229,13 @@ export type ResilientFileSinkOptions = {
   retryMs?: number;
   /** Backoff ceiling (default 5 min). */
   maxRetryMs?: number;
+  /**
+   * Rotate the file once it passes this many bytes (default 10 MB);
+   * 0 disables runtime rotation.
+   */
+  rotateAtBytes?: number;
+  /** Numbered generations kept by a rotation (default 5). */
+  keep?: number;
 };
 
 /**
@@ -221,6 +275,14 @@ export type ResilientFileSinkOptions = {
  *     many lines were lost.
  * The console sink keeps working throughout, and carries the two
  * notices.
+ *
+ * It also owns retention: after a write carries the file past
+ * `rotateAtBytes` it shifts the generations (see
+ * {@link shiftLogGenerations}) and reopens a fresh file, all inside the
+ * same synchronous write — a few renames every 10 MB, no queue, no lost
+ * line. The size is re-read from disk before rotating, so a file another
+ * process already rotated is not rotated twice; a rotation that fails
+ * keeps appending to the current file and tries again one cap later.
  */
 export class ResilientFileSink {
   private readonly path: string;
@@ -233,6 +295,12 @@ export class ResilientFileSink {
   private retryTimer: ReturnType<typeof setTimeout> | null = null;
   private droppedWhileDown = 0;
   private down = false;
+  private readonly rotateAtBytes: number;
+  private readonly keep: number;
+  /** Bytes in the current file, as far as this process has seen. */
+  private bytes = 0;
+  /** Size at which the next rotation check runs. */
+  private rotateCheckAt: number;
 
   constructor(path: string, opts: ResilientFileSinkOptions = {}) {
     this.path = path;
@@ -241,6 +309,9 @@ export class ResilientFileSink {
     this.baseRetryMs = opts.retryMs ?? SINK_RETRY_MS;
     this.maxRetryMs = opts.maxRetryMs ?? SINK_MAX_RETRY_MS;
     this.retryMs = this.baseRetryMs;
+    this.rotateAtBytes = opts.rotateAtBytes ?? MAX_LOG_SIZE;
+    this.keep = opts.keep ?? LOG_ROTATE_KEEP;
+    this.rotateCheckAt = this.rotateAtBytes;
     this.openInner();
   }
 
@@ -269,6 +340,10 @@ export class ResilientFileSink {
       return;
     }
     this.markHealthy();
+    this.bytes += Buffer.byteLength(line, "utf-8");
+    if (this.rotateAtBytes > 0 && this.bytes > this.rotateCheckAt) {
+      this.rotate();
+    }
   }
 
   /** No-op: every write already reached the fd. Part of pino's shape. */
@@ -283,11 +358,59 @@ export class ResilientFileSink {
   private openInner(): void {
     try {
       this.target = this.openTarget(this.path);
+      this.bytes = this.target.initialSize ?? 0;
+      this.rotateCheckAt = this.rotateAtBytes;
     } catch (err) {
       this.fail(err);
     }
   }
 
+  /**
+   * The current file passed the cap: shift the generations and reopen.
+   * Never throws — a failed rename reopens the same file and appends
+   * on, a failed reopen goes through the ordinary pause/retry path.
+   */
+  private rotate(): void {
+    let onDisk: number;
+    try {
+      onDisk = statSync(this.path).size;
+    } catch {
+      // Unlinked under us: nothing to shift, just start a fresh file.
+      this.detachInner();
+      this.openInner();
+      return;
+    }
+    if (onDisk <= this.rotateAtBytes) {
+      // Someone else (another Talon process) already rotated it.
+      this.bytes = onDisk;
+      return;
+    }
+    // Close before renaming: a platform that refuses to rename an open
+    // file (Windows) then fails the shift cleanly instead of half-way.
+    this.detachInner();
+    let failure: unknown = null;
+    try {
+      shiftLogGenerations(this.path, this.keep);
+    } catch (err) {
+      failure = err;
+    }
+    this.openInner();
+    if (failure !== null) {
+      this.rotateCheckAt = this.bytes + this.rotateAtBytes;
+      const code = (failure as NodeJS.ErrnoException).code ?? String(failure);
+      this.emitNotice(
+        "warn",
+        `log.rotate failed file=${this.path} code=${code} — still appending`,
+      );
+      return;
+    }
+    this.emitNotice(
+      "info",
+      `log.rotate file=${this.path} bytes=${onDisk} keep=${this.keep} ` +
+        `previous=${rotatedLogPath(this.path, 1)}`,
+    );
+  }
+
   /** Give up on the current handle and arm a reopen. Never throws. */
   private fail(err: unknown): void {
     const firstFailure = !this.down;
@@ -378,7 +501,14 @@ function appendLine(fd: number, line: string): void {
 export function openSyncLogFile(path: string): SyncLogTarget {
   // 0600: turns and tool output land here — same sensitivity as history.
   const fd = openSync(path, "a", 0o600);
+  let initialSize = 0;
+  try {
+    initialSize = fstatSync(fd).size;
+  } catch {
+    /* unknown size: rotation counts from zero */
+  }
   return {
+    initialSize,
     write: (line) => appendLine(fd, line),
     close: () => {
       try {
@@ -443,8 +573,57 @@ function emit(write: () => void): void {
   }
 }
 
+/**
+ * Append `turn=<id>` when the line is written from inside a running
+ * turn (see logging/turn-scope.ts), unless the caller already named it. The
+ * id goes in the message text, not a field, so a plain `grep` over
+ * talon.log and the pretty console both show it.
+ */
+function tagTurn(message: string): string {
+  const turnId = currentTurnId();
+  if (!turnId) return message;
+  const tag = `turn=${turnId}`;
+  return message.includes(tag) ? message : `${message} ${tag}`;
+}
+
 export function log(component: LogComponent, message: string): void {
-  emit(() => logger.info({ component }, message));
+  emit(() => logger.info({ component }, tagTurn(message)));
+}
+
+type LogErrorListener = (
+  component: LogComponent,
+  message: string,
+  err?: unknown,
+) => void;
+
+let errorListener: LogErrorListener | null = null;
+let inErrorListener = false;
+
+/**
+ * Register (or clear, with null) the one listener every `logError` call
+ * reaches — core's error-rate alarm (core/daemon/health-alerts.ts). util
+ * cannot import core, so core registers itself here. The listener runs
+ * synchronously and must be cheap; it cannot throw into the caller, and
+ * a `logError` it makes itself is not fed back to it.
+ */
+export function onLogError(fn: LogErrorListener | null): void {
+  errorListener = fn;
+}
+
+function notifyErrorListener(
+  component: LogComponent,
+  message: string,
+  err: unknown,
+): void {
+  if (!errorListener || inErrorListener) return;
+  inErrorListener = true;
+  try {
+    errorListener(component, message, err);
+  } catch {
+    /* an alarm must never break the error path it watches */
+  } finally {
+    inErrorListener = false;
+  }
 }
 
 export function logError(
@@ -452,26 +631,30 @@ export function logError(
   message: string,
   err?: unknown,
 ): void {
+  notifyErrorListener(component, message, err);
   if (err instanceof Error) {
     // Capture both the concise message (for log consumers that look at `err`)
     // and the full stack (for diagnostics). pino-pretty renders the `stack`
     // field on its own line; JSON consumers can read either field.
     emit(() =>
-      logger.error({ component, err: err.message, stack: err.stack }, message),
+      logger.error(
+        { component, err: err.message, stack: err.stack },
+        tagTurn(message),
+      ),
     );
   } else if (err !== undefined) {
-    emit(() => logger.error({ component, err: String(err) }, message));
+    emit(() => logger.error({ component, err: String(err) }, tagTurn(message)));
   } else {
-    emit(() => logger.error({ component }, message));
+    emit(() => logger.error({ component }, tagTurn(message)));
   }
 }
 
 export function logWarn(component: LogComponent, message: string): void {
-  emit(() => logger.warn({ component }, message));
+  emit(() => logger.warn({ component }, tagTurn(message)));
 }
 
 export function logDebug(component: LogComponent, message: string): void {
-  emit(() => logger.debug({ component }, message));
+  emit(() => logger.debug({ component }, tagTurn(message)));
 }
 
 // Expose logger to plugins running in the same process

package/src/util/logging/turn-scope.ts

@@ -0,0 +1,85 @@
+/**
+ * Log context — which turn a log line belongs to, carried implicitly.
+ *
+ * A turn fans out across the weaver, the backend adapter, the event
+ * shuttle and the gateway's tool actions; threading an id through every
+ * call site would touch dozens of signatures. Instead the Weaver runs
+ * each turn inside an AsyncLocalStorage scope and `log.ts` appends
+ * `turn=<id>` to every line written while that scope is live. One
+ * `grep turn=t-…` over talon.log then reconstructs the whole turn.
+ *
+ * Two traps shape the API:
+ *
+ *   - **Stale scopes.** Async resources created during a turn (a
+ *     long-lived subprocess, a timer a tool left behind) keep that turn's
+ *     scope forever. A scope is therefore closed when its turn settles,
+ *     and a closed scope tags nothing: a late line goes untagged rather
+ *     than blamed on a turn that already ended.
+ *   - **Tool actions arrive out of band.** The MCP subprocess calls the
+ *     gateway over HTTP, so a tool action starts a fresh async root with
+ *     no scope. The chat → open-scope map lets the gateway re-enter the
+ *     chat's running turn by chat id.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+
+export type TurnLogScope = {
+  readonly turnId: string;
+  readonly chatId: string;
+  /** False once the turn has settled — the scope then tags nothing. */
+  open: boolean;
+};
+
+const storage = new AsyncLocalStorage<TurnLogScope>();
+/** The running turn per chat (queued turns are not registered). */
+const runningByChat = new Map<string, TurnLogScope>();
+
+/** A short, greppable turn id: `t-` + 7 base36 chars. */
+function mintTurnId(): string {
+  return `t-${randomBytes(4).readUInt32BE(0).toString(36).padStart(7, "0")}`;
+}
+
+/** A fresh scope for a turn that has been accepted but not yet started. */
+export function createTurnScope(chatId: string): TurnLogScope {
+  return { turnId: mintTurnId(), chatId, open: true };
+}
+
+/**
+ * Run `fn` as the chat's running turn: every log line written from its
+ * async chain carries `turn=<id>` until {@link closeTurnScope}.
+ */
+export function runInTurnScope<T>(scope: TurnLogScope, fn: () => T): T {
+  runningByChat.set(scope.chatId, scope);
+  return storage.run(scope, fn);
+}
+
+/** Mark the turn settled: its scope stops tagging lines. Idempotent. */
+export function closeTurnScope(scope: TurnLogScope): void {
+  scope.open = false;
+  if (runningByChat.get(scope.chatId) === scope) {
+    runningByChat.delete(scope.chatId);
+  }
+}
+
+/**
+ * Run `fn` inside the running turn of the first chat id in `chatIds`
+ * that has one, or plainly when none does. Used by the gateway so a
+ * tool action's lines join the turn that issued it.
+ */
+export function runInChatTurnScope<T>(
+  chatIds: readonly (string | null | undefined)[],
+  fn: () => T,
+): T {
+  for (const chatId of chatIds) {
+    const scope = chatId ? runningByChat.get(chatId) : undefined;
+    if (scope?.open) return storage.run(scope, fn);
+  }
+  return fn();
+}
+
+/** The live turn id for the current async chain, if any. */
+export function currentTurnId(): string | undefined {
+  const scope = storage.getStore();
+  return scope?.open ? scope.turnId : undefined;
+}

package/src/util/time.ts

@@ -1,8 +1,8 @@
 /**
  * Timezone-aware time formatting utilities.
  *
- * All functions accept a timezone string (IANA, e.g. "Europe/Warsaw").
- * If none is set, falls back to the system default.
+ * Every helper formats in the IANA timezone set via `setTimezone`
+ * (e.g. "Europe/Warsaw"), falling back to the system default.
  */
 
 let configuredTz: string | undefined;
@@ -94,7 +94,7 @@ export function formatRelativeAge(ts: number): string {
 
 /**
  * Full datetime for system prompt injection.
- * Example: "2026-03-21 14:32 (Europe/Warsaw, Fri)"
+ * Example: "2026-03-21 14:32 Fri (Europe/Warsaw)"
  */
 export function formatFullDatetime(): string {
   const now = new Date();

package/src/util/watchdog.ts

@@ -126,9 +126,33 @@ let watchdogTimer: ReturnType<typeof setInterval> | null = null;
 let stuckWarnBackoffMs = STUCK_WARN_MS;
 let nextStuckWarnAt = 0;
 
+/**
+ * Who hears about a wedged loop beyond the log. util is a leaf, so the
+ * engine registers this (it raises the operator alert and knows what is
+ * queued); the watchdog only says when it starts and when it ends.
+ */
+export type StuckLoopListener = {
+  onStuck(info: { pendingMins: number; silentMins: number }): void;
+  onRecovered(): void;
+};
+let stuckListener: StuckLoopListener | null = null;
+let stuckReported = false;
+
+export function setStuckLoopListener(listener: StuckLoopListener | null): void {
+  stuckListener = listener;
+}
+
 function resetStuckWarnBackoff(): void {
   stuckWarnBackoffMs = STUCK_WARN_MS;
   nextStuckWarnAt = 0;
+  if (stuckReported) {
+    stuckReported = false;
+    try {
+      stuckListener?.onRecovered();
+    } catch {
+      /* a listener fault must not break turn bookkeeping */
+    }
+  }
 }
 
 export function startWatchdog(workspaceDir?: string): void {
@@ -150,6 +174,12 @@ export function startWatchdog(workspaceDir?: string): void {
         "watchdog",
         `Message received ${pendingMins} minutes ago is still unprocessed with no turn activity for ${silentMins} minutes — the message loop may be wedged`,
       );
+      stuckReported = true;
+      try {
+        stuckListener?.onStuck({ pendingMins, silentMins });
+      } catch (err) {
+        logWarn("watchdog", `stuck-loop listener failed: ${String(err)}`);
+      }
       nextStuckWarnAt = now + stuckWarnBackoffMs;
       stuckWarnBackoffMs = Math.min(
         stuckWarnBackoffMs * 2,

package/src/core/engine/backend-controller/legacy.ts

@@ -1,111 +0,0 @@
-/**
- * Legacy single-active aliases (chat role).
- *
- * Preserved so consumers that pre-date the pool refactor stay green.
- * All route to the chat role — the canonical "default" backend.
- */
-
-import type { Backend } from "../../agent-runtime/capabilities.js";
-import type { TalonConfig } from "../../config/index.js";
-import { type BackendInitContext } from "../../agent-runtime/backend-registry.js";
-import { log } from "../../../util/log.js";
-import { roleHolder } from "./holders.js";
-import { pool, bindings, ctx, ensurePoolEntry } from "./state.js";
-import {
-  getBackendForRole,
-  getBackendIdForRole,
-  getBackendLabelForRole,
-  cleanupBackendPool,
-  resetBackendPoolForTest,
-} from "./pool.js";
-import { rebindRole } from "./rebind.js";
-import type { RebindResult } from "./types.js";
-
-/**
- * Initialise the controller with a single backend bound to the chat
- * role. Convenience for tests; production should use `initBackendPool`.
- */
-export async function initBackendController(
-  id: string,
-  config: TalonConfig,
-  initContext: BackendInitContext,
-): Promise<Backend> {
-  ctx.initCtx = initContext;
-  ctx.poolConfig = config;
-  const entry = await ensurePoolEntry(id, config);
-  const holder = roleHolder("chat");
-  entry.holders.add(holder);
-  bindings.set(holder, id);
-  log("backend-controller", `Active backend (chat): ${entry.label} (${id})`);
-  return entry.backend;
-}
-
-/** Equivalent to `getBackendForRole("chat")`. Legacy alias. */
-export function getActiveBackend(): Backend {
-  if (!bindings.has(roleHolder("chat"))) {
-    throw new Error(
-      "Backend controller not initialised — call initBackendController first",
-    );
-  }
-  return getBackendForRole("chat");
-}
-
-/** Whether the chat role has been bound. Legacy alias. */
-export function hasActiveBackend(): boolean {
-  return bindings.has(roleHolder("chat"));
-}
-
-/** Like `getActiveBackend` but returns `null` instead of throwing. */
-export function getActiveBackendOrNull(): Backend | null {
-  if (!bindings.has(roleHolder("chat"))) return null;
-  try {
-    return getBackendForRole("chat");
-  } catch {
-    return null;
-  }
-}
-
-/** Id of the chat-role backend. Legacy alias. */
-export function getActiveBackendId(): string {
-  if (!bindings.has(roleHolder("chat"))) {
-    throw new Error("Backend controller not initialised");
-  }
-  return getBackendIdForRole("chat");
-}
-
-/** Label of the chat-role backend. Legacy alias. */
-export function getActiveBackendLabel(): string {
-  if (!bindings.has(roleHolder("chat"))) {
-    throw new Error("Backend controller not initialised");
-  }
-  return getBackendLabelForRole("chat");
-}
-
-/** Rebind the chat role. Legacy alias for `rebindRole("chat", id, config)`. */
-export async function switchBackend(
-  id: string,
-  config: TalonConfig,
-): Promise<RebindResult> {
-  if (!bindings.has(roleHolder("chat"))) {
-    return { ok: false, error: "Backend controller not initialised" };
-  }
-  const current = bindings.get(roleHolder("chat"));
-  if (current === id) {
-    const entry = pool.get(current);
-    return {
-      ok: false,
-      error: `Already on ${entry?.label ?? current}`,
-    };
-  }
-  return rebindRole("chat", id, config);
-}
-
-/** Tear down the entire pool. Legacy alias for `cleanupBackendPool`. */
-export async function cleanupBackendController(): Promise<void> {
-  await cleanupBackendPool();
-}
-
-/** Reset state. Test-only. Legacy alias. */
-export function resetBackendControllerForTest(): void {
-  resetBackendPoolForTest();
-}