talon-agent 5.18.2 → 5.19.1

package/src/core/vfs/mounts/diagnostics.ts

@@ -0,0 +1,109 @@
+/**
+ * Diagnostic proc views — "what went wrong" without knowing a path:
+ *
+ *   proc/log      the last lines of talon.log, one human line each
+ *   proc/errors   recent warn/error/fatal entries, with stack frames
+ *   proc/alerts   the operator alerts currently raised
+ *
+ * Rendered text, not pino JSON, so `cat` answers the question directly.
+ * The log views read a bounded tail of talon.log (plus its newest
+ * rotated generation when the live file is young) — a regular file
+ * outside ~/.talon/ns, so the FUSE deadlock rule is not in play — and
+ * memoize for a second: FUSE stats a node before reading it, and both
+ * should see the same text without reading the log twice.
+ */
+
+import {
+  formatLogRecord,
+  readLogRecords,
+  type LogRecord,
+} from "../../daemon/log-reader.js";
+
+export type AlertView = {
+  key: string;
+  severity: string;
+  message: string;
+  since: number;
+};
+
+export interface DiagnosticViewDeps {
+  /** talon.log. */
+  logPath: string;
+  /** The live alert table (`activeAlerts`). */
+  alerts: () => ReadonlyArray<AlertView>;
+  now?: () => number;
+}
+
+const LOG_LINES = 200;
+const ERROR_ENTRIES = 100;
+const MEMO_MS = 1_000;
+/** Two generations: the live file and the one it rotated from. */
+const READ_OPTS = { maxFiles: 2, maxBytesPerFile: 1024 * 1024 } as const;
+
+function memo(render: () => string, now: () => number): () => string {
+  let cached: { at: number; text: string } | null = null;
+  return () => {
+    const t = now();
+    if (cached && t - cached.at < MEMO_MS) return cached.text;
+    cached = { at: t, text: render() };
+    return cached.text;
+  };
+}
+
+function body(records: LogRecord[], stackLines: number, max: number): string {
+  return records
+    .map((r) => formatLogRecord(r, { stackLines, maxMsgChars: max }))
+    .join("\n");
+}
+
+function renderLogView(logPath: string): string {
+  const records = readLogRecords(logPath, { limit: LOG_LINES, ...READ_OPTS });
+  if (records.length === 0) return `# ${logPath} is empty or missing\n`;
+  return (
+    `# last ${records.length} lines of ${logPath}, newest last ` +
+    `(older: ${logPath}.1…, or \`talon logs --since 1h\`)\n` +
+    `${body(records, 0, 400)}\n`
+  );
+}
+
+function renderErrorsView(logPath: string): string {
+  const records = readLogRecords(logPath, {
+    limit: ERROR_ENTRIES,
+    filter: { minLevel: "warn" },
+    ...READ_OPTS,
+  });
+  if (records.length === 0) {
+    return `# no warnings or errors in the recent ${logPath}\n`;
+  }
+  return (
+    `# last ${records.length} warn/error entries from ${logPath}, newest last\n` +
+    `${body(records, 5, 500)}\n`
+  );
+}
+
+export function renderAlertsView(
+  alerts: ReadonlyArray<AlertView>,
+  now: number,
+): string {
+  if (alerts.length === 0) return "# no active alerts\n";
+  const lines = alerts.map((a) => {
+    const mins = Math.max(0, Math.round((now - a.since) / 60_000));
+    return (
+      `[${a.severity}] ${a.key} since ${new Date(a.since).toISOString()} ` +
+      `(${mins} min)\n    ${a.message}`
+    );
+  });
+  return `# ${alerts.length} active alert(s)\n${lines.join("\n")}\n`;
+}
+
+/** The proc views, keyed by file name — wired by the vfs index. */
+export function createDiagnosticViews(
+  deps: DiagnosticViewDeps,
+): Record<string, () => string> {
+  const now = deps.now ?? Date.now;
+  return {
+    log: memo(() => renderLogView(deps.logPath), now),
+    errors: memo(() => renderErrorsView(deps.logPath), now),
+    alerts: () => renderAlertsView(deps.alerts(), now()),
+  };
+}

package/src/core/vfs/mounts/proc.ts

@@ -5,6 +5,8 @@
  *   proc/
  *     tasks/<id>   one task table record, pretty JSON
  *     events       the event bus ring, JSON Lines (newest last)
+ *     <view>       any extra text views the index wires (log, errors,
+ *                  alerts — see ./diagnostics.ts)
  *
  * Providers are injected so the mount is a pure projection — the index
  * wires the real task table and bus, tests wire fixtures. Sizes and
@@ -20,6 +22,8 @@ import { vfsError, vfsOk } from "../types.js";
 export interface ProcMountDeps {
   tasks: () => readonly TaskRecord[];
   events: () => readonly PublishedEvent[];
+  /** Extra read-only text files at the proc root, name → renderer. */
+  views?: Readonly<Record<string, () => string>>;
 }
 
 const DIR = (path: string, name: string): VfsStat => ({
@@ -54,6 +58,13 @@ function renderEvents(events: readonly PublishedEvent[]): string {
 }
 
 export function createProcMount(deps: ProcMountDeps): VfsMount {
+  const views: Readonly<Record<string, () => string>> = Object.assign(
+    Object.create(null) as Record<string, () => string>,
+    deps.views,
+  );
+  const viewStats = (): VfsStat[] =>
+    Object.keys(views).map((name) => fileStat(name, views[name]()));
+
   function taskById(id: string): TaskRecord | undefined {
     if (!/^\d+$/.test(id)) return undefined;
     return deps.tasks().find((task) => task.id === Number(id));
@@ -66,6 +77,7 @@ export function createProcMount(deps: ProcMountDeps): VfsMount {
       const events = deps.events();
       return vfsOk(fileStat("events", renderEvents(events), events.at(-1)?.at));
     }
+    if (views[rel]) return vfsOk(fileStat(rel, views[rel]()));
     const taskId = rel.startsWith("tasks/") ? rel.slice("tasks/".length) : null;
     if (taskId !== null && !taskId.includes("/")) {
       const task = taskById(taskId);
@@ -78,7 +90,9 @@ export function createProcMount(deps: ProcMountDeps): VfsMount {
   }
 
   return {
-    description: "Live daemon state: task table and event bus ring",
+    description: deps.views
+      ? "Live daemon state: task table, event bus ring, daemon log views"
+      : "Live daemon state: task table and event bus ring",
     writable: false,
 
     stat: resolveNode,
@@ -89,6 +103,7 @@ export function createProcMount(deps: ProcMountDeps): VfsMount {
         return vfsOk([
           DIR("tasks", "tasks"),
           fileStat("events", renderEvents(events), events.at(-1)?.at),
+          ...viewStats(),
         ]);
       }
       if (rel === "tasks") {
@@ -112,6 +127,7 @@ export function createProcMount(deps: ProcMountDeps): VfsMount {
 
     read(rel) {
       if (rel === "events") return vfsOk(renderEvents(deps.events()));
+      if (views[rel]) return vfsOk(views[rel]());
       if (rel.startsWith("tasks/")) {
         const task = taskById(rel.slice("tasks/".length));
         if (!task) return vfsError("not-found");

package/src/core/vfs/workspace.ts

@@ -20,6 +20,7 @@ import {
 } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
 import { log } from "../../util/log.js";
 import { dirs, files as pathFiles } from "../../util/paths.js";
 import { listSeedPrompts, readPromptAsset } from "#prompt-assets";
@@ -259,8 +260,11 @@ function seedPrompts(): void {
     const pkgHash = sha256(pkg);
 
     if (!existsSync(dst)) {
+      // Atomic: a write cut short (ENOSPC, crash) must leave no file
+      // rather than a truncated one, which the next boot could not tell
+      // from a user edit and would keep forever.
       try {
-        writeFileSync(dst, pkg);
+        writeFileAtomic.sync(dst, pkg);
       } catch (err) {
         log(
           "workspace",
@@ -293,7 +297,7 @@ function seedPrompts(): void {
     } else if (seededHash !== undefined && curHash === seededHash) {
       // Pristine seeded copy + package changed → refresh on upgrade.
       try {
-        writeFileSync(dst, pkg);
+        writeFileAtomic.sync(dst, pkg);
       } catch {
         continue; // manifest keeps the old hash — retried next boot
       }
@@ -308,7 +312,7 @@ function seedPrompts(): void {
 
   if (manifestDirty) {
     try {
-      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+      writeFileAtomic.sync(manifestPath, JSON.stringify(manifest, null, 2));
     } catch {
       /* non-fatal — worst case we re-derive next boot */
     }

package/src/core/weaver/shuttle.ts

@@ -27,6 +27,7 @@ import {
   type AgentResult,
 } from "../agent-runtime/events.js";
 import { recordTurnActivity } from "../../util/watchdog.js";
+import type { TurnToolLog } from "./turn-log.js";
 
 export type EventSink = (event: AgentEvent) => void | Promise<void>;
 
@@ -45,12 +46,14 @@ export const startShuttleTiming = (): ShuttleTiming => ({ deliveryMs: 0 });
 /**
  * Pump the stream to completion. Returns the `completed` event's
  * result (if the backend emitted one); throws `AgentRunError` when the
- * stream terminates with an `error` event.
+ * stream terminates with an `error` event. `tools`, when given, sees
+ * every tool call/result pair for the turn's `tool.call` log lines.
  */
 export async function carryTurnEvents(
   stream: AsyncIterable<AgentEvent>,
   onEvent?: EventSink,
   timing?: ShuttleTiming,
+  tools?: TurnToolLog,
 ): Promise<AgentResult | undefined> {
   let agentResult: AgentResult | undefined;
   const sink: EventSink | undefined =
@@ -73,6 +76,10 @@ export async function carryTurnEvents(
     }
     if (event.type === "completed") {
       agentResult = event.result;
+    } else if (event.type === "tool_call") {
+      tools?.onCall(event);
+    } else if (event.type === "tool_result") {
+      tools?.onResult(event);
     }
 
     if (event.type === "assistant_message" && event.deliveryAck) {

package/src/core/weaver/turn-log.ts

@@ -0,0 +1,320 @@
+/**
+ * Turn log — the greppable lifecycle lines for one turn, so talon.log
+ * alone can answer "what happened in that conversation":
+ *
+ *   turn.queued  turn=… chat=… trigger=… depth=…          (behind a running turn)
+ *   turn.start   turn=… chat=… frontend=… backend=… model=… trigger=… queue=… wait_ms=…
+ *   tool.start   turn=… chat=… name=… id=… args=<≤80>      (debug)
+ *   tool.slow    turn=… chat=… name=… id=… running_ms=…    (still running at 60s)
+ *   tool.call    turn=… chat=… name=… ms=… ok=… [bytes=…] [err=…]
+ *   turn.error   turn=… chat=… class=auth|quota|timeout|tool|backend|unknown msg=…
+ *   turn.end     turn=… chat=… … ms=… outcome=ok|error|aborted|timeout|refused tools=N in_tokens=…
+ *
+ * Every other line written during the turn carries `turn=<id>` too, via
+ * the log context (util/logging/turn-scope.ts). Free text (`msg=`, `err=`) is
+ * always the LAST field, collapsed to one line and capped, so the
+ * key=value fields before it stay machine-parseable.
+ */
+
+import { AgentRunError, type AgentEvent } from "../agent-runtime/events.js";
+import { classify, type TalonError } from "../errors.js";
+import { resolveOwnerFrontendId } from "../frontend-runtime/routing.js";
+import { log, logDebug, logWarn } from "../../util/log.js";
+
+type TurnOutcome = "ok" | "error" | "aborted" | "timeout" | "refused";
+
+type TurnErrorClass =
+  "auth" | "quota" | "timeout" | "tool" | "backend" | "aborted" | "unknown";
+
+/** A tool still running at this age gets a `tool.slow` line. */
+const SLOW_TOOL_MS = 60_000;
+/** Cap for free-text fields (error messages). */
+const MAX_TEXT = 200;
+/** Cap for the debug-level tool args preview. */
+const MAX_ARGS_PREVIEW = 80;
+
+/** One line, capped — safe to put at the end of a key=value log line. */
+function oneLine(text: string, max = MAX_TEXT): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+function errorText(err: unknown): string {
+  return oneLine(err instanceof Error ? err.message : String(err));
+}
+
+/** Serialized size of a tool result, or undefined when there is none. */
+function resultBytes(result: unknown): number | undefined {
+  if (result === undefined) return undefined;
+  if (typeof result === "string") return Buffer.byteLength(result);
+  try {
+    return Buffer.byteLength(JSON.stringify(result) ?? "");
+  } catch {
+    return undefined;
+  }
+}
+
+function argsPreview(input: unknown): string {
+  try {
+    return oneLine(JSON.stringify(input) ?? "", MAX_ARGS_PREVIEW);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+type OpenToolCall = {
+  name: string;
+  startedAt: number;
+  slowTimer: ReturnType<typeof setTimeout>;
+};
+
+/**
+ * Per-turn tool-call ledger, fed by the Shuttle from the canonical
+ * `tool_call` / `tool_result` events — the one place every backend's
+ * tools (SDK built-ins and Talon's MCP tools alike) pass through.
+ */
+export class TurnToolLog {
+  private readonly turnId: string;
+  private readonly chatId: string;
+  private readonly slowMs: number;
+  private readonly open = new Map<string, OpenToolCall>();
+  private calls = 0;
+
+  constructor(turnId: string, chatId: string, slowMs = SLOW_TOOL_MS) {
+    this.turnId = turnId;
+    this.chatId = chatId;
+    this.slowMs = slowMs;
+  }
+
+  /** Tool calls seen this turn. */
+  get count(): number {
+    return this.calls;
+  }
+
+  onCall(event: Extract<AgentEvent, { type: "tool_call" }>): void {
+    this.calls++;
+    const prefix = `turn=${this.turnId} chat=${this.chatId} name=${event.name} id=${event.id}`;
+    logDebug(
+      "dispatcher",
+      `tool.start ${prefix} args=${argsPreview(event.input)}`,
+    );
+    const startedAt = Date.now();
+    const slowTimer = setTimeout(() => {
+      log(
+        "dispatcher",
+        `tool.slow ${prefix} running_ms=${Date.now() - startedAt}`,
+      );
+    }, this.slowMs);
+    // A tool that outlives its turn must not hold the process open.
+    slowTimer.unref?.();
+    const previous = this.open.get(event.id);
+    if (previous) clearTimeout(previous.slowTimer);
+    this.open.set(event.id, { name: event.name, startedAt, slowTimer });
+  }
+
+  onResult(event: Extract<AgentEvent, { type: "tool_result" }>): void {
+    const call = this.open.get(event.id);
+    if (call) {
+      clearTimeout(call.slowTimer);
+      this.open.delete(event.id);
+    }
+    const ms = call ? Date.now() - call.startedAt : 0;
+    const bytes = resultBytes(event.result);
+    const line =
+      `tool.call turn=${this.turnId} chat=${this.chatId} name=${event.name} ms=${ms} ` +
+      `ok=${event.error === undefined}` +
+      (bytes === undefined ? "" : ` bytes=${bytes}`);
+    if (event.error === undefined) log("dispatcher", line);
+    else logWarn("dispatcher", `${line} err=${oneLine(event.error)}`);
+  }
+
+  /** Turn settled: stop the slow-tool timers, note calls that never resolved. */
+  close(): void {
+    for (const [id, call] of this.open) {
+      clearTimeout(call.slowTimer);
+      logDebug(
+        "dispatcher",
+        `tool.unsettled turn=${this.turnId} chat=${this.chatId} name=${call.name} id=${id} ms=${Date.now() - call.startedAt}`,
+      );
+    }
+    this.open.clear();
+  }
+}
+
+/** What one turn's lifecycle lines report — filled in as the turn resolves. */
+export type TurnTrace = {
+  readonly turnId: string;
+  readonly chatId: string;
+  readonly trigger: string;
+  readonly frontend: string;
+  /** Turns queued or running ahead of this one when it was enqueued. */
+  readonly queuedBehind: number;
+  readonly enqueuedAt: number;
+  readonly tools: TurnToolLog;
+  startedAt?: number;
+  backend?: string;
+  model?: string;
+  /** Why the turn was answered with a refusal instead of a backend run. */
+  refused?: string;
+};
+
+function head(trace: TurnTrace): string {
+  return `turn=${trace.turnId} chat=${trace.chatId}`;
+}
+
+/**
+ * The trace for a turn being enqueued. `queuedBehind` is how many turns
+ * the chat's FIFO already holds; when non-zero the turn has to wait, and
+ * that is logged now — the wait is otherwise invisible until it starts.
+ */
+export function createTurnTrace(
+  turnId: string,
+  params: { chatId: string; source: string },
+  queuedBehind: number,
+): TurnTrace {
+  const trace: TurnTrace = {
+    turnId,
+    chatId: params.chatId,
+    trigger: params.source,
+    frontend:
+      resolveOwnerFrontendId(params.chatId, { includeNonMessaging: true }) ??
+      "unknown",
+    queuedBehind,
+    enqueuedAt: Date.now(),
+    tools: new TurnToolLog(turnId, params.chatId),
+  };
+  if (queuedBehind > 0) logTurnQueued(trace);
+  return trace;
+}
+
+/** A turn is waiting behind others in its chat's FIFO. */
+function logTurnQueued(trace: TurnTrace): void {
+  log(
+    "dispatcher",
+    `turn.queued ${head(trace)} trigger=${trace.trigger} depth=${trace.queuedBehind}`,
+  );
+}
+
+/**
+ * The turn resolved its model and is about to reach the backend (or
+ * refuse): bind the resolution onto the trace and write `turn.start`.
+ */
+export function logTurnStart(
+  trace: TurnTrace,
+  warp: { backendId: string; model?: string },
+): void {
+  trace.backend = warp.backendId;
+  trace.model = warp.model;
+  const waitMs = (trace.startedAt ?? trace.enqueuedAt) - trace.enqueuedAt;
+  log(
+    "dispatcher",
+    `turn.start ${head(trace)} frontend=${trace.frontend} ` +
+      `backend=${trace.backend ?? "?"} model=${trace.model ?? "none"} ` +
+      `trigger=${trace.trigger} queue=${trace.queuedBehind} wait_ms=${waitMs}`,
+  );
+}
+
+type TurnUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheRead: number;
+  cacheWrite: number;
+};
+
+/**
+ * The turn returned normally: `ok`, a refusal, or a kill the backend
+ * honoured with a clean early completion.
+ */
+export function logTurnSettled(
+  trace: TurnTrace,
+  killed: boolean,
+  usage: TurnUsage,
+): void {
+  if (killed) logTurnEnd(trace, "aborted", { usage, reason: "killed" });
+  else if (trace.refused)
+    logTurnEnd(trace, "refused", { usage, reason: trace.refused });
+  else logTurnEnd(trace, "ok", { usage });
+}
+
+/** The single closing line of every turn, whatever its outcome. */
+export function logTurnEnd(
+  trace: TurnTrace,
+  outcome: TurnOutcome,
+  opts: { usage?: TurnUsage; reason?: string } = {},
+): void {
+  const ms = Date.now() - (trace.startedAt ?? trace.enqueuedAt);
+  const usage = opts.usage;
+  const line =
+    `turn.end ${head(trace)} backend=${trace.backend ?? "?"} ` +
+    `model=${trace.model ?? "none"} trigger=${trace.trigger} ms=${ms} ` +
+    `outcome=${outcome} tools=${trace.tools.count}` +
+    (usage
+      ? ` in_tokens=${usage.inputTokens} out_tokens=${usage.outputTokens} ` +
+        `cache_read=${usage.cacheRead} cache_write=${usage.cacheWrite}`
+      : "") +
+    (opts.reason ? ` reason=${opts.reason}` : "");
+  log("dispatcher", line);
+}
+
+const AGENT_KIND_CLASS: Record<AgentRunError["kind"], TurnErrorClass> = {
+  context_overflow: "backend",
+  rate_limit: "quota",
+  overload: "backend",
+  session_expired: "backend",
+  auth: "auth",
+  model_unsupported: "backend",
+  tool_failure: "tool",
+  subprocess_exit: "backend",
+  timeout: "timeout",
+  aborted: "aborted",
+  // Re-read through classify(): the message may still say more.
+  unknown: "unknown",
+};
+
+const REASON_CLASS: Record<TalonError["reason"], TurnErrorClass> = {
+  rate_limit: "quota",
+  usage_limit: "quota",
+  overloaded: "backend",
+  network: "backend",
+  auth: "auth",
+  forbidden: "auth",
+  context_length: "backend",
+  session_expired: "backend",
+  bad_request: "backend",
+  telegram_api: "unknown",
+  stopped: "aborted",
+  unknown: "unknown",
+};
+
+/** Bucket a turn failure into the coarse class `turn.error` reports. */
+export function classifyTurnError(err: unknown): TurnErrorClass {
+  if (err instanceof AgentRunError && err.kind !== "unknown") {
+    return AGENT_KIND_CLASS[err.kind];
+  }
+  if (err instanceof Error && err.name === "TimeoutError") return "timeout";
+  return REASON_CLASS[classify(err).reason];
+}
+
+/**
+ * A turn threw. A kill the user asked for closes as `aborted` with no
+ * `turn.error` (nothing went wrong); anything else gets the classified
+ * `turn.error` line, then `turn.end`.
+ */
+export function logTurnFailure(
+  trace: TurnTrace,
+  err: unknown,
+  killed: boolean,
+): void {
+  if (killed) {
+    logTurnEnd(trace, "aborted", { reason: "killed" });
+    return;
+  }
+  const cls = classifyTurnError(err);
+  logWarn(
+    "dispatcher",
+    `turn.error ${head(trace)} backend=${trace.backend ?? "?"} class=${cls} msg=${errorText(err)}`,
+  );
+  const outcome: TurnOutcome =
+    cls === "timeout" ? "timeout" : cls === "aborted" ? "aborted" : "error";
+  logTurnEnd(trace, outcome);
+}