talon-agent 5.18.2 → 5.19.0

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);
+}

package/src/core/weaver/weaver.ts

@@ -41,6 +41,19 @@ import type { Thread, ThreadSnapshot } from "./thread.js";
 import { startTurnCpu } from "./turn-cpu.js";
 import { startTypingLoop } from "./typing-loop.js";
 import { resolveWarp } from "./warp-resolver.js";
+import {
+  createTurnTrace,
+  logTurnEnd,
+  logTurnFailure,
+  logTurnSettled,
+  logTurnStart,
+  type TurnTrace,
+} from "./turn-log.js";
+import {
+  closeTurnScope,
+  createTurnScope,
+  runInTurnScope,
+} from "../../util/logging/turn-scope.js";
 
 export type WeaverDeps = {
   /**
@@ -84,6 +97,10 @@ export class Weaver {
     const chat = this.deps.getBackend(params.chatId).chat;
     const interrupt = chat?.interruptChatTurn?.bind(chat);
     const lifecycle = { started: false, killed: false, enqueuedAt: Date.now() };
+    // The turn id is minted at enqueue so a queued turn's wait is already
+    // attributable; the log scope goes live when the turn starts running.
+    const scope = createTurnScope(params.chatId);
+    const trace = createTurnTrace(scope.turnId, params, thread.inFlightCount);
     // Registered before enqueueing so a turn waiting in its chat's FIFO is
     // visible as `queued` in the task table, not invisible until it runs.
     const task = taskTable.enqueue({
@@ -99,7 +116,11 @@ export class Weaver {
           }
         : {}),
     });
-    return thread.enqueue(() => this.run(thread, params, task, lifecycle));
+    return thread.enqueue(() =>
+      runInTurnScope(scope, () =>
+        this.run(thread, params, task, lifecycle, trace),
+      ).finally(() => closeTurnScope(scope)),
+    );
   }
 
   /** Number of turns currently running (not queued) across all chats. */
@@ -121,21 +142,28 @@ export class Weaver {
     params: ExecuteParams,
     task: TaskHandle,
     lifecycle: { started: boolean; killed: boolean; enqueuedAt: number },
+    trace: TurnTrace,
   ): Promise<ExecuteResult> {
     if (lifecycle.killed) {
       // Killed while queued — the turn never reaches the backend. The
       // caller still gets a resolved (empty) result; nothing is delivered
       // to the chat, which is the point of the kill.
       task.fail(new Error("killed while queued"));
+      logTurnEnd(trace, "aborted", { reason: "killed-while-queued" });
       return this.emptyResult("Turn killed before it started.", params);
     }
     lifecycle.started = true;
+    trace.startedAt = Date.now();
     this.activeCount++;
     task.start();
     try {
-      const result = await this.executeInner(thread, params, task, {
-        queueWait: Date.now() - lifecycle.enqueuedAt,
-      });
+      const result = await this.executeInner(
+        thread,
+        params,
+        task,
+        { queueWait: Date.now() - lifecycle.enqueuedAt },
+        trace,
+      );
       const usage = {
         inputTokens: result.inputTokens,
         outputTokens: result.outputTokens,
@@ -152,9 +180,11 @@ export class Weaver {
       } else {
         task.succeed(usage);
       }
+      logTurnSettled(trace, lifecycle.killed, usage);
       return result;
     } catch (err) {
       task.fail(err);
+      logTurnFailure(trace, err, lifecycle.killed);
       if (lifecycle.killed) {
         // The backend didn't manage a clean interrupt-completion (some
         // SDK versions surface an interrupted turn as an error result).
@@ -168,6 +198,7 @@ export class Weaver {
       throw err;
     } finally {
       this.activeCount--;
+      trace.tools.close();
     }
   }
 
@@ -176,6 +207,7 @@ export class Weaver {
     params: ExecuteParams,
     task: TaskHandle,
     phases: Partial<Record<TurnPhase, number>>,
+    trace: TurnTrace,
   ): Promise<ExecuteResult> {
     const { context } = this.deps;
     const backend = this.deps.getBackend(params.chatId);
@@ -189,7 +221,12 @@ export class Weaver {
       reqId,
     });
     phases.warpResolve = Date.now() - warpStartedAt;
+    logTurnStart(trace, {
+      backendId: warp.backendId,
+      model: warp.ok ? warp.ref.id : undefined,
+    });
     if (!warp.ok) {
+      trace.refused = "no-model";
       await deliverRefusal(params, warp.message, "no-model");
       return this.emptyResult(warp.message, params);
     }
@@ -202,6 +239,7 @@ export class Weaver {
         "dispatcher",
         `[${reqId}] guest-scoped turn refused chat=${params.chatId}: backend "${backend.id}" cannot enforce the guest tool scope`,
       );
+      trace.refused = "guest-scope";
       await deliverRefusal(params, GUEST_BACKEND_REFUSAL, "guest-scope");
       return this.emptyResult(GUEST_BACKEND_REFUSAL, params);
     }
@@ -270,7 +308,12 @@ export class Weaver {
       // same path `phases.stream` is, so both cover one population.
       const stopCpu = startTurnCpu();
       const streamStartedAt = Date.now();
-      const agentResult = await carryTurnEvents(stream, params.onEvent, timing);
+      const agentResult = await carryTurnEvents(
+        stream,
+        params.onEvent,
+        timing,
+        trace.tools,
+      );
       phases.stream = Date.now() - streamStartedAt;
       stopCpu();
       phases.delivery = timing.deliveryMs;

package/src/frontend/discord/actions/index.ts

@@ -28,6 +28,12 @@ import { messagingHandlers, restoreScheduledMessages } from "./messaging.js";
 import { mediaHandlers } from "./media.js";
 import { chatInfoHandlers } from "./chat-info.js";
 import type { DiscordActionContext, DiscordActionHandlers } from "./types.js";
+import {
+  createDeliveryTracker,
+  trackDeliveries,
+} from "../../health/delivery.js";
+
+const delivery = createDeliveryTracker("discord", "Discord", "discord");
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method via `handlers[action]`.
@@ -44,7 +50,7 @@ export function createDiscordActionHandler(client: Client, gateway: Gateway) {
   // shutdown — the timers died with the process, the store didn't.
   restoreScheduledMessages(client, scheduledMessages);
 
-  return async (
+  const dispatch = async (
     body: Record<string, unknown>,
     chatId: number,
   ): Promise<ActionResult | null> => {
@@ -74,4 +80,5 @@ export function createDiscordActionHandler(client: Client, gateway: Gateway) {
     };
     return handler(body, chatId, ctx);
   };
+  return trackDeliveries(delivery, dispatch);
 }

package/src/frontend/discord/diagnostics.ts

@@ -1,12 +1,19 @@
 /**
- * Client diagnostics — the error/warn/disconnect/rate-limit listeners that
- * only log. discord.js handles reconnects and retries itself; these exist
- * so a silent failure mode (a fatal close code, an approaching IP ban) is
- * visible in the daemon log.
+ * Client diagnostics — the error/warn/disconnect/rate-limit listeners.
+ * discord.js handles reconnects and retries itself; these exist so a
+ * silent failure mode (a fatal close code, an approaching IP ban) is
+ * visible in the daemon log, and so the operator hears when the gateway
+ * stays down: `discord.gateway` is raised once a shard has been
+ * disconnected for `GATEWAY_OUTAGE_MS` (at once, critically, for a close
+ * code discord.js will never recover from) and resolved on ready/resume.
  */
 
 import { type Client, Events } from "discord.js";
-import { logError, logWarn } from "../../util/log.js";
+import { log, logError, logWarn } from "../../util/log.js";
+import { createOutage, errorText, type Outage } from "../health/outage.js";
+
+/** A gateway down this long reaches the operator. */
+const GATEWAY_OUTAGE_MS = 5 * 60_000;
 
 function shardDisconnectLabel(code: number | undefined): string {
   return code === 4004
@@ -18,7 +25,76 @@ function shardDisconnectLabel(code: number | undefined): string {
         : `code=${code}`;
 }
 
-export function bindClientDiagnostics(client: Client): void {
+function createGatewayOutage(thresholdMs: number): Outage {
+  return createOutage({
+    key: "discord.gateway",
+    thresholdMs,
+    describe: (err, mins) =>
+      `The Discord gateway has been disconnected for ${mins} min: ${err}. Messages are not being received.`,
+    recovered: "The Discord gateway is connected again.",
+  });
+}
+
+/**
+ * Gateway connection health: which shards are down, and the outage that
+ * spans them. Reconnect attempts, errors and recoveries are logged with
+ * the shard, attempt number and time down.
+ */
+function bindGatewayHealth(client: Client, thresholdMs: number): void {
+  const outage = createGatewayOutage(thresholdMs);
+  const down = new Set<number>();
+
+  const lost = (shardId: number, event: string, err: unknown): void => {
+    down.add(shardId);
+    const { attempt, downMs } = outage.fail(err);
+    logWarn(
+      "discord",
+      `gateway.${event} shard=${shardId} attempt=${attempt} down_ms=${downMs} err=${errorText(err)}`,
+    );
+  };
+  const back = (shardId: number, event: string): void => {
+    down.delete(shardId);
+    if (down.size > 0) return;
+    const ended = outage.ok();
+    if (ended) {
+      log(
+        "discord",
+        `gateway.${event} shard=${shardId} failed_attempts=${ended.attempts} down_ms=${ended.downMs}`,
+      );
+    }
+  };
+
+  client.on(Events.ShardReconnecting, (shardId) =>
+    lost(shardId, "reconnecting", "connection closed, reconnecting"),
+  );
+  client.on(Events.ShardError, (err, shardId) => {
+    // An error on a live shard is followed by a close if it matters; only
+    // an error during an outage is part of it (its text is the useful one).
+    if (down.has(shardId)) lost(shardId, "error", err);
+  });
+  client.on(Events.ShardDisconnect, (event, shardId) => {
+    const code = event?.code;
+    lost(shardId, "disconnect", shardDisconnectLabel(code));
+    if (code === 4004 || code === 4013 || code === 4014) {
+      outage.raiseNow(
+        `The Discord gateway closed and will not reconnect: ${shardDisconnectLabel(code)}. ` +
+          "Messages are not being received until this is fixed and Talon restarts.",
+        "critical",
+      );
+    }
+  });
+  client.on(Events.Invalidated, () =>
+    lost(0, "invalidated", "session invalidated"),
+  );
+  client.on(Events.ShardReady, (shardId) => back(shardId, "ready"));
+  client.on(Events.ShardResume, (shardId) => back(shardId, "resumed"));
+}
+
+export function bindClientDiagnostics(
+  client: Client,
+  gatewayOutageMs = GATEWAY_OUTAGE_MS,
+): void {
+  bindGatewayHealth(client, gatewayOutageMs);
   client.on("error", (err) => {
     logError("discord", "Client error", err);
   });

package/src/frontend/discord/handlers/index.ts

@@ -11,8 +11,6 @@
  *   - `delivery` — the agent run + reply pipeline (processAndReply)
  *   - `queue`    — per-chat debounce queue
  *   - `messages` — the messageCreate handler (handleMessage)
- *
- * Re-exports the same public surface the old single-file module exposed.
  */
 
 export { registerDiscordChat, lookupDiscordChat } from "./registry.js";

package/src/frontend/discord/middleware.ts

@@ -1,17 +1,11 @@
 /**
- * Discord middleware — wires up message events to handlers.ts.
+ * Discord middleware — wires up message events to handlers/.
  *
- * Equivalent to src/frontend/telegram/middleware.ts. We attach a single
- * messageCreate listener that filters out bots/system messages and delegates
- * to handleMessage. We also push every message into the in-memory history
- * buffer so /admin commands and /status reflect real activity.
- *
- * Discord-specific behavior:
- *  - We don't have a separate "my_chat_member" event; instead, when the bot
- *    is removed from a guild we get `guildDelete`. The handler in index.ts
- *    handles that to revoke access.
- *  - Every guild message gets the chat registered for pulse so periodic
- *    check-ins work (DMs are excluded because we always respond).
+ * A single messageCreate listener filters out bots/system messages and
+ * delegates to handleMessage. Every message is also pushed into the
+ * in-memory history buffer so /admin commands and /status reflect real
+ * activity, and every guild message registers its chat for pulse (DMs are
+ * excluded because we always respond).
  */
 
 import type { Client, Message } from "discord.js";
@@ -24,7 +18,7 @@ import { handleMessage, getSenderName } from "./handlers/index.js";
 
 export function registerMiddleware(client: Client, config: TalonConfig): void {
   client.on("messageCreate", (msg: Message) => {
-    // Ignore self/bots/system here too — handlers.ts will check again, but
+    // Ignore self/bots/system here too — handleMessage checks again, but
     // we don't even want to record those in history.
     if (msg.author.bot || msg.system) return;
     if (msg.author.id === client.user?.id) return;

package/src/frontend/discord/runtime.ts

@@ -1,9 +1,7 @@
 /**
  * Discord frontend runtime — the state every module of this frontend shares.
  *
- * `createDiscordFrontend` used to hold the client and config as closure
- * variables with every gateway-event handler nested inside `init`. It is
- * now one explicit object, constructed once, that each module (ready,
+ * One explicit object, constructed once, that each module (ready,
  * guild-policy, diagnostics, outbound, connection) takes as its first
  * parameter. The runtime carries state only; the modules own the behaviour.
  */