docs(discord): explain typing lifecycle invariants

steipete · steipete · commit 21c911c1bd92 · 2026-05-30T18:28:08.000+01:00
diff --git a/extensions/discord/src/monitor/inbound-job.ts b/extensions/discord/src/monitor/inbound-job.ts
@@ -12,6 +12,8 @@ type DiscordInboundJobRuntimeField =
   | "guildHistories"
   | "client"
   | "threadBindings"
+  // Function-backed feedback stays runtime-only; payload must remain
+  // materializable data so queued jobs cannot accidentally serialize it.
   | "replyTypingFeedback"
   | "discordRestFetch";
 
@@ -27,6 +29,8 @@ export type DiscordInboundJob = {
 };
 
 export function resolveDiscordInboundJobQueueKey(ctx: DiscordMessagePreflightContext): string {
+  // This key is both the run-queue serialization key and the typing prestart
+  // dedupe key, so keep it aligned with the eventual session route.
   const sessionKey = ctx.route.sessionKey?.trim();
   if (sessionKey) {
     return sessionKey;
diff --git a/extensions/discord/src/monitor/message-handler.process.ts b/extensions/discord/src/monitor/message-handler.process.ts
@@ -442,6 +442,8 @@ async function processDiscordMessageInner(
   const typingChannelId = deliverTarget.startsWith("channel:")
     ? deliverTarget.slice("channel:".length)
     : messageChannelId;
+  // Deliver target can move into a thread after preflight accepted the message.
+  // The typing owner follows the final target before reply dispatch starts.
   const typingFeedback =
     replyTypingFeedback ??
     createDiscordReplyTypingFeedback({
diff --git a/extensions/discord/src/monitor/message-handler.reply-typing-policy.ts b/extensions/discord/src/monitor/message-handler.reply-typing-policy.ts
@@ -21,6 +21,8 @@ export type DiscordAcceptedTypingPrestartDecision = {
 export function resolveDiscordSourceReplyDeliveryMode(
   ctx: DiscordMessagePreflightContext,
 ): SourceReplyDeliveryMode {
+  // Keep prestart policy keyed to the same source-reply mode as dispatch.
+  // Otherwise message-tool-only group replies would wait behind "message" mode.
   return resolveChannelMessageSourceReplyDeliveryMode({
     cfg: ctx.cfg,
     ctx: {
@@ -51,13 +53,17 @@ export function resolveDiscordAcceptedTypingPrestart(
   }
   const configuredTypingMode = ctx.cfg.session?.typingMode ?? ctx.cfg.agents?.defaults?.typingMode;
   if (configuredTypingMode !== undefined) {
+    // Explicit operator config wins over Discord heuristics.
+    // Non-instant modes intentionally defer to the normal reply pipeline.
     return {
       sourceReplyDeliveryMode,
       shouldPrestart: configuredTypingMode === "instant",
       reason: configuredTypingMode === "instant" ? "configured-instant" : "configured-not-instant",
     };
   }
   if (sourceReplyDeliveryMode === "message_tool_only") {
+    // Message-tool-only replies have no visible default response path.
+    // Prestart preserves user feedback while the tool-delivered reply waits.
     return { sourceReplyDeliveryMode, shouldPrestart: true, reason: "tool-only" };
   }
   if (!ctx.isGuildMessage && !ctx.isGroupDm) {
diff --git a/extensions/discord/src/monitor/message-handler.ts b/extensions/discord/src/monitor/message-handler.ts
@@ -133,6 +133,8 @@ export function createDiscordMessageHandler(
     "group-mentions";
   const preflightDiscordMessageImpl = params.testing?.preflightDiscordMessage;
   const replayGuard = createDiscordInboundReplayGuard();
+  // The map owns pre-dispatch typing leases, not queued work itself.
+  // Each lease is released by the feedback cleanup hook installed below.
   const prestartedTypingFeedback = new Map<string, PrestartedTypingFeedbackEntry>();
   const messageRunQueue = createDiscordMessageRunQueue({
     runtime: params.runtime,
diff --git a/extensions/discord/src/monitor/message-run-queue.ts b/extensions/discord/src/monitor/message-run-queue.ts
@@ -107,6 +107,8 @@ export function createDiscordMessageRunQueue(
   let lifecycleActive = !params.abortSignal?.aborted;
 
   const cleanupSkippedQueuedMessages = () => {
+    // These callbacks represent jobs accepted into the queue but not started.
+    // Running jobs remove their callback before processDiscordMessage owns cleanup.
     if (!lifecycleActive && skippedCleanup.size === 0) {
       return;
     }
@@ -135,6 +137,8 @@ export function createDiscordMessageRunQueue(
       }
       skippedCleanup.add(cleanupSkipped);
       runQueue.enqueue(job.queueKey, async ({ lifecycleSignal }) => {
+        // Once the task starts, normal process/commit handling owns cleanup.
+        // Leaving it in skippedCleanup would double-release replay/typing state.
         skippedCleanup.delete(cleanupSkipped);
         await processDiscordQueuedMessage({
           job,
diff --git a/extensions/discord/src/monitor/reply-typing-feedback.ts b/extensions/discord/src/monitor/reply-typing-feedback.ts
@@ -7,6 +7,8 @@ import { sendTyping } from "./typing.js";
 
 export const DISCORD_REPLY_TYPING_MAX_DURATION_MS = 20 * 60_000;
 
+// Discord can keep long tool-heavy replies alive, but not forever.
+// The dispatch restart path refreshes this TTL after queue wait time.
 export type DiscordReplyTypingFeedback = ReturnType<typeof createTypingCallbacks> & {
   updateChannelId: (channelId: string) => void;
   getChannelId: () => string;
@@ -51,6 +53,8 @@ export function createDiscordReplyTypingFeedback(params: {
   };
   let callbacks = createCallbacks();
   return {
+    // Expose one stable owner while allowing the inner typing controller to
+    // rotate between prequeue feedback and the actual dispatch lifecycle.
     onReplyStart: () => callbacks.onReplyStart(),
     onIdle: () => callbacks.onIdle?.(),
     onCleanup: () => callbacks.onCleanup?.(),
