talon-agent 5.18.2 → 5.19.1

package/src/core/daemon/log-reader.ts

@@ -0,0 +1,289 @@
+/**
+ * Daemon log reader — one parser for talon.log shared by every surface
+ * that shows it: `talon logs` filters, the proc/log + proc/errors views
+ * in the namespace, and doctor's recent-errors probe.
+ *
+ * talon.log is pino JSON Lines (see util/log.ts). The live file rotates
+ * at runtime into numbered generations (`talon.log.1` newest …) and, at
+ * daemon start, into `talon.log.old`; readers walk them newest-first so
+ * a question like "errors in the last hour" survives a rotation.
+ *
+ * Everything here is synchronous and bounded by a byte window per file:
+ * callers are a CLI process, a doctor pass, or a FUSE view read — none
+ * may slurp an unbounded history.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { tailFile } from "../../util/tail-file.js";
+
+type LogLevelName = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+const LEVEL_BY_NUM: Record<number, LogLevelName> = {
+  10: "trace",
+  20: "debug",
+  30: "info",
+  40: "warn",
+  50: "error",
+  60: "fatal",
+};
+
+const LEVEL_RANK: Record<LogLevelName, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+/** One parsed talon.log line. */
+export type LogRecord = {
+  /** Epoch ms (0 when the line carried none). */
+  ts: number;
+  level: LogLevelName;
+  component?: string;
+  msg: string;
+  err?: string;
+  stack?: string;
+  /** Turn id — a `turn` field, or a `turn=<id>` pair in the message. */
+  turn?: string;
+};
+
+export type LogFilter = {
+  /** Drop records below this severity. */
+  minLevel?: LogLevelName;
+  /** Exact component match. */
+  component?: string;
+  /** Drop records older than this epoch ms. */
+  since?: number;
+  /** Case-insensitive substring of the message or error text. */
+  grep?: string;
+  /** Exact turn id match. */
+  turn?: string;
+};
+
+const TURN_IN_MSG = /\bturn=([^\s,;)]+)/;
+
+function turnOf(obj: Record<string, unknown>, msg: string): string | undefined {
+  if (typeof obj.turn === "string" || typeof obj.turn === "number") {
+    return String(obj.turn);
+  }
+  return TURN_IN_MSG.exec(msg)?.[1];
+}
+
+/** Parse one line; null for anything that is not a pino record. */
+export function parseLogLine(line: string): LogRecord | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return null;
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    return null; // partial first line of a byte window, torn write
+  }
+  const msg = typeof obj.msg === "string" ? obj.msg : "";
+  const turn = turnOf(obj, msg);
+  return {
+    ts: typeof obj.time === "number" ? obj.time : 0,
+    level: LEVEL_BY_NUM[obj.level as number] ?? "info",
+    ...(typeof obj.component === "string" ? { component: obj.component } : {}),
+    msg,
+    ...(typeof obj.err === "string" ? { err: obj.err } : {}),
+    ...(typeof obj.stack === "string" ? { stack: obj.stack } : {}),
+    ...(turn !== undefined ? { turn } : {}),
+  };
+}
+
+export function matchesLogFilter(rec: LogRecord, filter: LogFilter): boolean {
+  if (filter.minLevel && LEVEL_RANK[rec.level] < LEVEL_RANK[filter.minLevel])
+    return false;
+  if (filter.component && rec.component !== filter.component) return false;
+  if (filter.since !== undefined && rec.ts < filter.since) return false;
+  if (filter.turn && rec.turn !== filter.turn) return false;
+  if (filter.grep) {
+    const needle = filter.grep.toLowerCase();
+    const hay = `${rec.msg}\n${rec.err ?? ""}`.toLowerCase();
+    if (!hay.includes(needle)) return false;
+  }
+  return true;
+}
+
+/** Parse + filter a raw chunk of the log, oldest first. */
+function parseLogChunk(raw: string, filter: LogFilter): LogRecord[] {
+  const out: LogRecord[] = [];
+  // pino writes `"component":"<c>"` verbatim — a substring test skips the
+  // JSON.parse for every other component's line (most of a trace log).
+  const tag = filter.component
+    ? `"component":${JSON.stringify(filter.component)}`
+    : null;
+  for (const line of raw.split("\n")) {
+    if (tag !== null && !line.includes(tag)) continue;
+    const rec = parseLogLine(line);
+    if (rec && matchesLogFilter(rec, filter)) out.push(rec);
+  }
+  return out;
+}
+
+/**
+ * The live file and its rotated generations that exist, newest first:
+ * the live file, then every `<name>.<n>` (util/log.ts's runtime shift)
+ * and the start-time `<name>.old`, ordered by mtime — the two schemes
+ * interleave in time. Found by listing the directory, so the reader
+ * needs no knowledge of how many generations the writer keeps.
+ */
+export function logGenerations(path: string): string[] {
+  const dir = dirname(path);
+  const prefix = `${basename(path)}.`;
+  const isGeneration = (name: string): boolean =>
+    name.startsWith(prefix) && /^(\d+|old)$/.test(name.slice(prefix.length));
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter(isGeneration);
+  } catch {
+    names = [];
+  }
+  const rotated: Array<{ path: string; mtime: number }> = [];
+  for (const name of names) {
+    try {
+      const full = join(dir, name);
+      rotated.push({ path: full, mtime: statSync(full).mtimeMs });
+    } catch {
+      /* rotated away between the listing and the stat */
+    }
+  }
+  rotated.sort((a, b) => b.mtime - a.mtime);
+  return [...(existsSync(path) ? [path] : []), ...rotated.map((r) => r.path)];
+}
+
+export type ReadLogOptions = {
+  /** Max records returned (the newest ones, oldest first). */
+  limit: number;
+  filter?: LogFilter;
+  /** Trailing byte window read from each file (default 2 MB). */
+  maxBytesPerFile?: number;
+  /** Generations consulted at most (default: all). */
+  maxFiles?: number;
+};
+
+/**
+ * The newest `limit` records matching `filter`, oldest first, walking
+ * back through rotated generations until the limit is met, the `since`
+ * cutoff is passed, or `maxFiles` is spent. Missing files read as empty.
+ */
+export function readLogRecords(
+  path: string,
+  opts: ReadLogOptions,
+): LogRecord[] {
+  const filter = opts.filter ?? {};
+  const maxBytes = opts.maxBytesPerFile ?? 2 * 1024 * 1024;
+  const files = logGenerations(path).slice(0, opts.maxFiles);
+  let collected: LogRecord[] = [];
+  for (const file of files) {
+    let raw: string;
+    let mtime: number;
+    try {
+      mtime = statSync(file).mtimeMs;
+      if (filter.since !== undefined && mtime < filter.since) break;
+      raw = tailFile(file, Number.MAX_SAFE_INTEGER, maxBytes);
+    } catch {
+      continue;
+    }
+    collected = [...parseLogChunk(raw, filter), ...collected];
+    if (collected.length >= opts.limit) break;
+  }
+  return collected.slice(-opts.limit);
+}
+
+const LEVEL_TAG: Record<LogLevelName, string> = {
+  trace: "TRC",
+  debug: "DBG",
+  info: "INF",
+  warn: "WRN",
+  error: "ERR",
+  fatal: "FTL",
+};
+
+/**
+ * One human line: ISO time, level, component, message, turn id (when
+ * it came as a field rather than in the message), error — the
+ * shape an agent or operator reads without a JSON parser. `stackLines`
+ * appends that many stack frames, indented, under error records.
+ */
+export function formatLogRecord(
+  rec: LogRecord,
+  opts: { stackLines?: number; maxMsgChars?: number } = {},
+): string {
+  const time = rec.ts > 0 ? new Date(rec.ts).toISOString() : "-";
+  const comp = (rec.component ?? "?").padEnd(10);
+  const max = opts.maxMsgChars ?? 1000;
+  const msg = rec.msg.length > max ? `${rec.msg.slice(0, max)}…` : rec.msg;
+  let line = `${time} ${LEVEL_TAG[rec.level]} ${comp} ${msg}`;
+  if (rec.turn && !TURN_IN_MSG.test(rec.msg)) line += ` turn=${rec.turn}`;
+  if (rec.err) line += ` (${rec.err})`;
+  const frames = opts.stackLines ?? 0;
+  if (frames > 0 && rec.stack) {
+    const stack = rec.stack
+      .split("\n")
+      .slice(1, frames + 1)
+      .map((f) => `    ${f.trim()}`);
+    if (stack.length > 0) line += `\n${stack.join("\n")}`;
+  }
+  return line;
+}
+
+const DURATION_UNITS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** "90s" / "15m" / "2h" / "1d" → ms; a bare number is minutes. */
+export function parseLogDuration(input: string): number | null {
+  const match = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(input.trim().toLowerCase());
+  if (!match) return null;
+  const ms = Number(match[1]) * DURATION_UNITS[match[2] || "m"];
+  return ms > 0 ? ms : null;
+}
+
+export type LoggedAlert = {
+  key: string;
+  severity: string;
+  message: string;
+  since: number;
+};
+
+// The shapes alerts.ts logs: raiseAlert → `[<severity>] <key>: <message>`,
+// resolveAlert → `resolved <key> after <n> min`, both as component "alert".
+const ALERT_RAISED = /^\[(\w+)\] (\S+): ([\s\S]*)$/;
+const ALERT_RESOLVED = /^resolved (\S+) after /;
+/** The daemon's first boot line — in-memory alert state starts empty. */
+const DAEMON_START = "Starting Talon...";
+
+/**
+ * Replay alert raise/resolve lines to the set still open at the end of
+ * `records` (oldest first). For a process that cannot see the daemon's
+ * in-memory alert table — `talon doctor` runs standalone. A daemon
+ * restart clears the table, so a boot line clears the replay too.
+ */
+export function replayAlerts(records: readonly LogRecord[]): LoggedAlert[] {
+  const open = new Map<string, LoggedAlert>();
+  for (const rec of records) {
+    if (rec.component === "bot" && rec.msg === DAEMON_START) {
+      open.clear();
+      continue;
+    }
+    if (rec.component !== "alert") continue;
+    const raised = ALERT_RAISED.exec(rec.msg);
+    if (raised) {
+      const [, severity, key, message] = raised;
+      const prior = open.get(key);
+      open.set(key, { key, severity, message, since: prior?.since ?? rec.ts });
+      continue;
+    }
+    const resolved = ALERT_RESOLVED.exec(rec.msg);
+    if (resolved) open.delete(resolved[1]);
+  }
+  return [...open.values()];
+}

package/src/core/doctor/index.ts

@@ -16,6 +16,7 @@ import { stat } from "node:fs/promises";
 import { NATIVE_MODULES } from "../../native/registry.js";
 import { dirs } from "../../util/paths.js";
 import { getBackend, listBackends } from "../agent-runtime/backend-registry.js";
+import { checkOpenAlerts, checkRecentErrors } from "./logs.js";
 import type {
   DoctorCheck,
   DoctorConfigSlice,
@@ -270,6 +271,22 @@ async function checkOneBackend(
   }
 }
 
+/**
+ * What the deployment is doing rather than what it is built from: the
+ * provisioned plugin runtimes, the backends, and what the daemon's log
+ * and alert table say went wrong lately (./logs.ts).
+ */
+async function checkRunningState(
+  config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  return [
+    ...(await checkPluginRuntimes(config)),
+    ...(await checkBackend(config)),
+    checkRecentErrors(),
+    ...checkOpenAlerts(),
+  ];
+}
+
 /**
  * Run every check and return the structured report. `config` is
  * undefined when no config file exists yet (first run).
@@ -440,8 +457,7 @@ export async function collectDoctorReport(opts: {
   }
 
   const native = await checkNativeModules();
-  checks.push(...(await checkPluginRuntimes(opts.config)));
-  checks.push(...(await checkBackend(opts.config)));
+  checks.push(...(await checkRunningState(opts.config)));
 
   const issues =
     checks.filter((c) => c.status === "fail" || c.issue).length +

package/src/core/doctor/logs.ts

@@ -0,0 +1,124 @@
+/**
+ * Doctor's "what went wrong lately" probes: the last hour of talon.log
+ * summarised by component, and the operator alerts still open — so
+ * `talon doctor` points at the failing subsystem instead of only at the
+ * environment.
+ *
+ * Alerts come from the daemon's in-memory table when doctor runs inside
+ * the daemon (the chat /doctor command). `talon doctor` is its own
+ * process and sees an empty table, so it replays the alert lines in the
+ * log instead; those are reported as warnings without counting toward
+ * the issue total — the log can only say what was last announced.
+ */
+
+import {
+  readLogRecords,
+  replayAlerts,
+  type LogRecord,
+} from "../daemon/log-reader.js";
+import { activeAlerts } from "../frontend-runtime/alerts.js";
+import { files } from "../../util/paths.js";
+import type { DoctorCheck } from "./types.js";
+
+const HOUR_MS = 3_600_000;
+/** How far back the alert replay looks for a raise still unresolved. */
+const ALERT_WINDOW_MS = 24 * HOUR_MS;
+const READ = { limit: Number.MAX_SAFE_INTEGER, maxBytesPerFile: 16 << 20 };
+const DETAIL_CHARS = 160;
+
+export type RecentLogOptions = {
+  logPath?: string;
+  now?: number;
+  /** The live alert table; defaults to this process's `activeAlerts()`. */
+  liveAlerts?: ReturnType<typeof activeAlerts>;
+};
+
+function clip(text: string): string {
+  return text.length > DETAIL_CHARS ? `${text.slice(0, DETAIL_CHARS)}…` : text;
+}
+
+function byComponent(records: readonly LogRecord[]): string {
+  const counts = new Map<string, number>();
+  for (const r of records) {
+    const c = r.component ?? "?";
+    counts.set(c, (counts.get(c) ?? 0) + 1);
+  }
+  return [...counts]
+    .sort((a, b) => b[1] - a[1])
+    .map(([c, n]) => `${c} ${n}`)
+    .join(", ");
+}
+
+/** The last hour's warn/error lines, as one doctor check. */
+export function checkRecentErrors(opts: RecentLogOptions = {}): DoctorCheck {
+  const logPath = opts.logPath ?? files.log;
+  const now = opts.now ?? Date.now();
+  const recent = readLogRecords(logPath, {
+    ...READ,
+    filter: { since: now - HOUR_MS, minLevel: "warn" },
+  });
+  const errors = recent.filter(
+    (r) => r.level === "error" || r.level === "fatal",
+  );
+  const warnings = recent.length - errors.length;
+  if (errors.length === 0) {
+    return warnings === 0
+      ? { label: "Log: no errors or warnings in the last hour", status: "ok" }
+      : {
+          label: `Log: ${warnings} warning(s) in the last hour`,
+          status: "info",
+          detail: byComponent(recent),
+        };
+  }
+  const last = errors.at(-1)!;
+  const at = new Date(last.ts).toTimeString().slice(0, 5);
+  const what = clip(`${last.msg}${last.err ? ` (${last.err})` : ""}`);
+  return {
+    label: `Log: ${errors.length} error(s) in the last hour — ${byComponent(errors)}`,
+    status: "warn",
+    detail:
+      `latest ${at} ${last.component ?? "?"}: ${what} — ` +
+      `talon logs --errors --since 1h, or ~/.talon/ns/proc/errors`,
+  };
+}
+
+/** Open alerts, one check each (or one "none" line). */
+export function checkOpenAlerts(opts: RecentLogOptions = {}): DoctorCheck[] {
+  const now = opts.now ?? Date.now();
+  const live = opts.liveAlerts ?? activeAlerts();
+  const fromLog = live.length === 0;
+  const alerts = fromLog ? loggedAlerts(opts.logPath ?? files.log, now) : live;
+  if (alerts.length === 0)
+    return [{ label: "Alerts: none open", status: "ok" }];
+  return alerts.map((a) => {
+    const mins = Math.max(0, Math.round((now - a.since) / 60_000));
+    const label = `Alert ${a.key} (${a.severity}, ${mins} min)`;
+    if (fromLog) {
+      return {
+        label,
+        status: "warn",
+        detail: `last logged: ${clip(a.message)}`,
+      };
+    }
+    return {
+      label,
+      status: a.severity === "warn" ? "warn" : "fail",
+      detail: clip(a.message),
+      issue: true,
+    };
+  });
+}
+
+/** Replay the last day's alert lines (plus boot lines, which reset them). */
+function loggedAlerts(logPath: string, now: number) {
+  const since = now - ALERT_WINDOW_MS;
+  const alertLines = readLogRecords(logPath, {
+    ...READ,
+    filter: { since, component: "alert" },
+  });
+  const boots = readLogRecords(logPath, {
+    ...READ,
+    filter: { since, component: "bot", grep: "Starting Talon" },
+  });
+  return replayAlerts([...alertLines, ...boots].sort((a, b) => a.ts - b.ts));
+}

package/src/core/doctor/types.ts

@@ -1,7 +1,7 @@
 /**
  * The doctor's data shapes, on their own so a backend factory can declare
  * its checks (`BackendFactory.doctor`) without importing the collector —
- * `core/doctor.ts` reads the registry, so the types living there would
+ * `core/doctor/index.ts` reads the registry, so the types living there would
  * close a cycle. Checks are pure data (label / status / detail); renderers
  * decide presentation.
  */

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

@@ -10,7 +10,7 @@
  * Different roles, and different chats, have different cost/latency/
  * quality needs. Typical post-Anthropic-metering setup: chat default
  * on free-tier OpenAI Agents, heartbeats on Claude Sonnet, dream
- * shared with chat — plus Pandario stays on Claude while DMs use the
+ * shared with chat — plus one group chat stays on Claude while DMs use the
  * cheap default. A single-active model can't express that. The pool
  * lets each holder bind independently while deduplicating instances
  * when ids overlap.
@@ -24,7 +24,6 @@
  *   - `pool`     — init/teardown, role accessors, availability, snapshot,
  *                  listeners.
  *   - `rebind`   — rebind/release holders + per-chat accessors.
- *   - `legacy`   — single-active aliases routed to the chat role.
  */
 
 export * from "./types.js";
@@ -57,14 +56,3 @@ export {
   hasChatBackendOverride,
   resolveChatBackend,
 } from "./rebind.js";
-export {
-  initBackendController,
-  getActiveBackend,
-  hasActiveBackend,
-  getActiveBackendOrNull,
-  getActiveBackendId,
-  getActiveBackendLabel,
-  switchBackend,
-  cleanupBackendController,
-  resetBackendControllerForTest,
-} from "./legacy.js";

package/src/core/engine/backend-router/router.ts

@@ -2,7 +2,7 @@
  * Plan-aware backend routing for background work.
  *
  * Background work — `spawn_agent` sub-agents, cron `query` jobs, the
- * heartbeat — used to inherit whichever backend the chat happened to be on.
+ * heartbeat — would otherwise inherit whichever backend the chat is on.
  * On a multi-subscription install that is a good way to burn one plan to its
  * ceiling while another sits idle. When nothing is pinned, this picks the
  * backend with the most headroom instead.

package/src/core/engine/dispatcher.ts

@@ -12,8 +12,15 @@ import type { ExecuteParams, ExecuteResult } from "../types.js";
 import { formatRelayBlock, takePendingRelay } from "./cross-chat-relay.js";
 import { recordMessageSignal } from "../memory/taps.js";
 import { log } from "../../util/log.js";
+import { setStuckLoopListener } from "../../util/watchdog.js";
 import { taskTable, type KillOutcome } from "../tasks/index.js";
 import { initWeaver, type Weaver, type WeaverDeps } from "../weaver/index.js";
+import {
+  noteTurnFailed,
+  noteTurnSucceeded,
+  stuckLoopAlert,
+  type TurnBinding,
+} from "./turn-health.js";
 
 // ── Dependencies (injected at startup) ──────────────────────────────────────
 
@@ -21,7 +28,7 @@ import { initWeaver, type Weaver, type WeaverDeps } from "../weaver/index.js";
  * `getBackend` takes the string chat id so it can route per-chat —
  * a chat with a backend override returns its override backend, others
  * fall through to the global chat-role backend. Tests can pass a
- * stub that ignores the chat id. See `core/backend-controller.ts`.
+ * stub that ignores the chat id. See `core/engine/backend-controller/`.
  *
  * `resolveActiveModel` walks the 5-step active-model resolution
  * chain for the chat and returns both the resolved `ModelRef` and
@@ -33,9 +40,18 @@ import { initWeaver, type Weaver, type WeaverDeps } from "../weaver/index.js";
 type DispatcherDeps = WeaverDeps;
 
 let weaver: Weaver | null = null;
+let backendIdFor: (chatId: string) => string = () => "unknown";
 
 export function initDispatcher(d: DispatcherDeps): void {
   weaver = initWeaver(d);
+  backendIdFor = (chatId) => {
+    try {
+      return d.getBackend(chatId).id;
+    } catch {
+      return "unknown";
+    }
+  };
+  setStuckLoopListener(stuckLoopAlert);
   log("dispatcher", "Initialized (per-chat serial, cross-chat parallel)");
 }
 
@@ -94,5 +110,42 @@ export async function execute(params: ExecuteParams): Promise<ExecuteResult> {
   const prompt = relayed.length
     ? formatRelayBlock(relayed) + params.prompt
     : params.prompt;
-  return weaver.runTurn(relayed.length ? { ...params, prompt } : params);
+  const startedAt = Date.now();
+  try {
+    const result = await weaver.runTurn(
+      relayed.length ? { ...params, prompt } : params,
+    );
+    // Only a turn that reached a backend vouches for it — a refusal or a
+    // turn killed in the queue binds no warp this turn.
+    const bound = turnBinding(weaver, params, startedAt, false);
+    if (bound) noteTurnSucceeded(bound);
+    return result;
+  } catch (err) {
+    const bound = turnBinding(weaver, params, startedAt, true);
+    if (bound) noteTurnFailed(bound, err);
+    throw err;
+  }
+}
+
+/**
+ * The backend/model this turn ran on, for turn-health alerts: the warp
+ * the Weaver bound for it, or — when the turn failed before binding one
+ * — the backend currently serving the chat.
+ */
+function turnBinding(
+  w: Weaver,
+  params: ExecuteParams,
+  startedAt: number,
+  failed: boolean,
+): TurnBinding | null {
+  const common = {
+    chatId: params.chatId,
+    source: params.source,
+    durationMs: Date.now() - startedAt,
+  };
+  const warp = w.loom.get(params.chatId)?.warp;
+  if (warp && warp.boundAt >= startedAt) {
+    return { ...common, backendId: warp.backendId, model: warp.model };
+  }
+  return failed ? { ...common, backendId: backendIdFor(params.chatId) } : null;
 }

package/src/core/engine/fault-text.ts

@@ -0,0 +1,40 @@
+/**
+ * The error text an operator alert or a key=value log line may carry.
+ *
+ * Alerts land on a phone and log lines get pasted into issues, so the
+ * raw message is flattened to one line, clipped, and stripped of the
+ * credential shapes a provider error can echo back (bearer tokens, API
+ * keys, `token=` query parameters).
+ */
+
+const SECRET_PATTERNS: readonly RegExp[] = [
+  /\bBearer\s+[\w.~+/=-]+/gi,
+  /\b(?:sk|pk|rk)-[\w-]{8,}/g,
+  /\b(?:gh[pousr]|github_pat)_\w{8,}/g,
+  /\bxox[abprs]-[\w-]{8,}/g,
+  /\b(access_token|refresh_token|api_key|apikey|token|key|secret|password)=[^\s&"']+/gi,
+];
+
+/** One-line, clipped, secret-free text for `err`. */
+export function faultText(err: unknown, max = 200): string {
+  let raw: string;
+  if (err instanceof Error) raw = err.message || err.name;
+  else if (typeof err === "string") raw = err;
+  else {
+    try {
+      raw = String(err);
+    } catch {
+      raw = "[unprintable error]";
+    }
+  }
+  let text = raw.replace(/\s+/g, " ").trim();
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, (match, name?: string) =>
+      typeof name === "string" && match.includes("=")
+        ? `${name}=[redacted]`
+        : "[redacted]",
+    );
+  }
+  if (!text) return "unknown error";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/src/core/engine/gateway-actions/agents/index.ts

@@ -3,8 +3,9 @@
  *
  *   - `control` — what a parent calls: spawn / list / status / wait / send /
  *     kill. Works from a chat and from inside another agent.
- *   - `report`  — what a sub-agent calls about itself: report_result /
- *     message_parent / check_inbox.
+ *   - `report`  — what a sub-agent calls about itself and its siblings:
+ *     report_result / message_parent / check_inbox / list_peers /
+ *     message_peer.
  *
  * Both sets are reachable from an `agent:<id>` context: the gateway routes
  * those chat keys straight here (see `Gateway.handleAction`), because a