clawmini 0.0.7 → 0.0.9

package/src/adapter-discord/forwarder.ts

@@ -8,25 +8,66 @@ import type {
   ThreadChannel,
   VoiceChannel,
   StageChannel,
+  Message,
 } from 'discord.js';
 import { EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, Colors } from 'discord.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import type { getTRPCClient } from './client.js';
+import type { DiscordConfig } from './config.js';
 import { readDiscordState, updateDiscordState, getDiscordStatePath } from './state.js';
+import { resolveInbound } from './inbound-cache.js';
+import { createTurnLogBuffer, type TurnLogBuffer } from '../shared/adapters/turn-log-buffer.js';
 import type { ChatMessage } from '../shared/chats.js';
 import { getWorkspaceRoot } from '../shared/workspace.js';
 import {
-  shouldDisplayMessage,
+  routeMessage,
   formatMessage,
+  type Destination,
   type FilteringConfig,
 } from '../shared/adapters/filtering.js';
 
+type AnyTextChannel =
+  | TextChannel
+  | DMChannel
+  | NewsChannel
+  | ThreadChannel
+  | VoiceChannel
+  | StageChannel;
+
+interface ThreadLogOptions {
+  maxToolPreview: number;
+  maxLogMessageChars: number;
+  editDebounceMs: number;
+}
+
+const DEFAULT_THREAD_LOG_OPTS: ThreadLogOptions = {
+  maxToolPreview: 400,
+  // Discord caps messages at 2000 chars; leave headroom for the rollover marker.
+  maxLogMessageChars: 1800,
+  editDebounceMs: 1000,
+};
+
+function resolveThreadLogOpts(config?: DiscordConfig): ThreadLogOptions {
+  const v = config?.visibility?.threadLog;
+  return {
+    maxToolPreview: v?.maxToolPreview ?? DEFAULT_THREAD_LOG_OPTS.maxToolPreview,
+    maxLogMessageChars: v?.maxLogMessageChars ?? DEFAULT_THREAD_LOG_OPTS.maxLogMessageChars,
+    editDebounceMs: v?.editDebounceMs ?? DEFAULT_THREAD_LOG_OPTS.editDebounceMs,
+  };
+}
+
+// Suppresses every form of mention (@everyone, @here, role, user) on bot
+// posts. Tool payloads, agent output, and policy descriptions can contain
+// arbitrary text; without this, an `@everyone` substring in (e.g.) a shell
+// command echoed into the activity log would page the entire channel.
+const NO_MENTIONS = { allowedMentions: { parse: [] as [] } } as const;
+
 async function resolveDiscordDestination(
   client: Client,
   discordUserId: string,
   chatId: string
-): Promise<TextChannel | DMChannel | NewsChannel | ThreadChannel | VoiceChannel | StageChannel> {
+): Promise<AnyTextChannel> {
   const state = await readDiscordState();
   const channelChatMap = state.channelChatMap || {};
 
@@ -64,11 +105,14 @@ export async function startDaemonToDiscordForwarder(
     chatId?: string;
     signal?: AbortSignal;
     config?: FilteringConfig;
+    discordConfig?: DiscordConfig;
   } = {}
 ) {
   const defaultChatId = options.chatId ?? 'default';
   const signal = options.signal;
   const config = options.config ?? {};
+  const threadLogOpts = resolveThreadLogOpts(options.discordConfig);
+  const threadsGloballyEnabled = options.discordConfig?.visibility?.threads !== false;
 
   const activeSubscriptions = new Map<string, { unsubscribe: () => void }>();
   const activeTypingSubscriptions = new Map<string, { unsubscribe: () => void }>();
@@ -84,6 +128,258 @@ export async function startDaemonToDiscordForwarder(
     }));
   };
 
+  const postThreaded = async (anchor: ThreadChannel, text: string): Promise<string | undefined> => {
+    const sent = await anchor.send({ content: text || '​', ...NO_MENTIONS });
+    return sent.id;
+  };
+
+  const editThreaded = async (
+    anchor: ThreadChannel,
+    messageId: string,
+    text: string
+  ): Promise<void> => {
+    const msg = await anchor.messages.fetch(messageId);
+    await msg.edit({ content: text || '​', ...NO_MENTIONS });
+  };
+
+  // Discord returns 10008 (Unknown Message) when an activity-log message has
+  // been deleted by the user; Cloudflare/HTTP layers may surface a generic
+  // 404. Either case means the same thing: open a fresh log message.
+  const isMissingMessageError = (err: unknown): boolean => {
+    const code = (err as { code?: number; status?: number })?.code ?? 0;
+    return code === 404 || code === 10008;
+  };
+
+  const turnLog: TurnLogBuffer<ThreadChannel> = createTurnLogBuffer<ThreadChannel>({
+    postThreaded,
+    editThreaded,
+    isMissingMessageError,
+    options: threadLogOpts,
+    threadsEnabled: threadsGloballyEnabled,
+  });
+
+  const collapseDestination = (dest: Destination, turnId?: string): Destination => {
+    // Both the global `visibility.threads: false` kill switch and the
+    // per-channel `threadsDisabled` flag mean "quiet bot": drop thread-log
+    // activity rather than promoting it top-level. Top-level spam is only
+    // opt-in via `filters` (e.g. `/show`), matching pre-threaded behavior.
+    if (dest.kind !== 'thread-log') return dest;
+    if (!threadsGloballyEnabled) return { kind: 'drop' };
+    if (turnId && turnLog.threadsDisabledFor(turnId)) return { kind: 'drop' };
+    return dest;
+  };
+
+  const channelThreadsDisabled = async (chatId: string): Promise<boolean> => {
+    const state = await readDiscordState();
+    for (const [, entry] of Object.entries(state.channelChatMap || {})) {
+      if (entry?.chatId === chatId) return entry.threadsDisabled === true;
+    }
+    return false;
+  };
+
+  const openThreadForTurn = async (
+    externalRef: string | undefined
+  ): Promise<ThreadChannel | undefined> => {
+    if (!externalRef) return undefined;
+    const inbound = resolveInbound(externalRef);
+    if (!inbound) return undefined;
+    let channel: AnyTextChannel | null;
+    try {
+      channel = (await client.channels.fetch(inbound.channelId)) as AnyTextChannel | null;
+    } catch (err) {
+      console.warn(`Failed to fetch channel ${inbound.channelId} for turn anchor:`, err);
+      return undefined;
+    }
+    if (!channel || !channel.isTextBased() || channel.isDMBased() || channel.isThread()) {
+      // DMs and existing threads can't host a new thread. Skip silently —
+      // proactive turns and DM-only flows simply have no activity log.
+      return undefined;
+    }
+    const guildChannel = channel as TextChannel | NewsChannel;
+    let userMessage: Message;
+    try {
+      userMessage = await guildChannel.messages.fetch(inbound.messageId);
+    } catch (err) {
+      console.warn(`Failed to fetch user message ${inbound.messageId} for turn anchor:`, err);
+      return undefined;
+    }
+    // Discord allows only one thread per message. The same inbound can anchor
+    // multiple turns (e.g. a follow-up turn fanned out from the original
+    // request), so reuse an existing thread rather than failing the second
+    // turn's activity log.
+    if (userMessage.hasThread && userMessage.thread) {
+      return userMessage.thread as ThreadChannel;
+    }
+    try {
+      return await userMessage.startThread({
+        name: 'Activity log',
+        // 1 day. Long agent runs (refactors, builds) outlive the previous
+        // 60-minute archive window and end up posting into archived threads
+        // that fall off the channel sidebar.
+        autoArchiveDuration: 1440,
+      });
+    } catch (err) {
+      // Race: another turn for the same inbound created the thread between
+      // our `hasThread` check and `startThread`. Discord returns 160004
+      // (THREAD_ALREADY_CREATED_FOR_MESSAGE). Re-fetch and reuse.
+      const code = (err as { code?: number })?.code;
+      if (code === 160004) {
+        try {
+          const refreshed = await guildChannel.messages.fetch(inbound.messageId);
+          if (refreshed.hasThread && refreshed.thread) {
+            return refreshed.thread as ThreadChannel;
+          }
+        } catch (refetchErr) {
+          console.warn(
+            `Failed to refetch user message ${inbound.messageId} after thread-exists race:`,
+            refetchErr
+          );
+        }
+      }
+      console.warn(`Failed to start thread on message ${inbound.messageId}:`, err);
+      return undefined;
+    }
+  };
+
+  const handleTurnStarted = async (chatId: string, turnId: string, externalRef?: string) => {
+    // Single source of truth for "is the activity log on for this turn":
+    // global kill switch OR per-channel opt-out. The buffer's `engaged()`
+    // and `collapseDestination`'s `threadsDisabledFor()` both consult the
+    // ctx flag set here, so we don't have to re-derive it later.
+    const threadsDisabled = !threadsGloballyEnabled || (await channelThreadsDisabled(chatId));
+    // Skip the API roundtrip when we already know the log is off.
+    const anchor = threadsDisabled ? undefined : await openThreadForTurn(externalRef);
+    // No anchor and threads enabled: proactive turn (cron, subagent, CLI),
+    // DM-only flow, or thread creation failed. Skip start entirely so the
+    // buffer doesn't accrue entries it can never flush.
+    if (!anchor && !threadsDisabled) return;
+    turnLog.start({ turnId, threadsDisabled, anchorThread: anchor });
+  };
+
+  const handleTurnEnded = async (turnId: string) => {
+    await turnLog.end(turnId);
+  };
+
+  const sendPolicyCard = async (chatId: string, message: ChatMessage): Promise<boolean> => {
+    if (message.role !== 'policy' || message.status !== 'pending') return false;
+    try {
+      const dm = await resolveDiscordDestination(client, discordUserId, chatId);
+
+      const embed = new EmbedBuilder()
+        .setTitle('Action Required: Policy Request')
+        .setDescription(message.content || 'A pending policy request requires your attention.')
+        .setColor(Colors.Yellow);
+
+      const policyId = ('requestId' in message && message.requestId) || message.id;
+      const row = new ActionRowBuilder<ButtonBuilder>().addComponents(
+        new ButtonBuilder()
+          .setCustomId(`approve|${policyId}|${chatId}`)
+          .setLabel('Approve')
+          .setStyle(ButtonStyle.Success),
+        new ButtonBuilder()
+          .setCustomId(`reject|${policyId}|${chatId}`)
+          .setLabel('Reject')
+          .setStyle(ButtonStyle.Danger)
+      );
+
+      const optionsMsg: MessageCreateOptions = {
+        embeds: [embed],
+        components: [row],
+        ...NO_MENTIONS,
+      };
+
+      try {
+        await dm.send(optionsMsg);
+      } catch (richError) {
+        console.warn(
+          `Failed to send rich message to Discord user ${discordUserId}, falling back to plain text:`,
+          richError
+        );
+        await dm.send({
+          content: `Action Required: Policy Request\n\n${
+            message.content || 'A pending policy request requires your attention.'
+          }\n\nApprove: \`/approve ${policyId}\`\nReject: \`/reject ${policyId} <optional_rationale>\``,
+          ...NO_MENTIONS,
+        });
+      }
+    } catch (error) {
+      console.error(`Failed to send message to Discord user ${discordUserId}:`, error);
+    }
+    return true;
+  };
+
+  const sendTopLevel = async (chatId: string, message: ChatMessage): Promise<void> => {
+    if ('level' in message && (message as { level?: string }).level === 'verbose') return;
+
+    const hasContent = !!message.content?.trim();
+    const files = 'files' in message ? ((message as { files?: string[] }).files ?? []) : [];
+    const hasFiles = Array.isArray(files) && files.length > 0;
+
+    let absoluteFiles: string[] = [];
+    if (hasFiles) {
+      const workspaceRoot = getWorkspaceRoot(process.cwd());
+      absoluteFiles = files.map((f) => path.resolve(workspaceRoot, f));
+    }
+
+    if (!hasContent && !hasFiles) return;
+
+    try {
+      const dm = await resolveDiscordDestination(client, discordUserId, chatId);
+      const formattedContent = formatMessage(message);
+
+      if (formattedContent && formattedContent.length > 2000) {
+        const chunks = chunkString(formattedContent, 2000);
+        for (let i = 0; i < chunks.length; i++) {
+          if (signal?.aborted) break;
+          const chunkOptions: MessageCreateOptions = {
+            content: chunks[i] as string,
+            ...NO_MENTIONS,
+          };
+          if (i === chunks.length - 1 && hasFiles) {
+            chunkOptions.files = absoluteFiles;
+          }
+          await dm.send(chunkOptions);
+        }
+      } else {
+        const optionsMsg: MessageCreateOptions = { ...NO_MENTIONS };
+        if (formattedContent) optionsMsg.content = formattedContent;
+        if (hasFiles) optionsMsg.files = absoluteFiles;
+        await dm.send(optionsMsg);
+      }
+    } catch (error) {
+      console.error(`Failed to send message to Discord user ${discordUserId}:`, error);
+      throw error;
+    }
+  };
+
+  const handleMessageForChat = async (chatId: string, message: ChatMessage): Promise<void> => {
+    const routed = routeMessage(message, config);
+    const effective = collapseDestination(routed, message.turnId);
+
+    if (effective.kind === 'drop') return;
+
+    if (effective.kind === 'thread-log') {
+      if (!message.turnId) {
+        console.warn(`thread-log event for ${message.role} has no turnId — dropping.`);
+        return;
+      }
+      // No turn context: turnStarted may have been missed (adapter restart,
+      // subscription reconnect) or the turn had no anchor (proactive / DM).
+      // Drop silently rather than flooding the chat.
+      if (!turnLog.has(message.turnId)) return;
+      turnLog.append(message.turnId, message);
+      return;
+    }
+
+    // Top-level.
+    if (message.role === 'policy' && message.status === 'pending') {
+      await sendPolicyCard(chatId, message);
+      return;
+    }
+
+    await sendTopLevel(chatId, message);
+  };
+
   const startSubscriptionForChat = async (chatId: string) => {
     if (activeSubscriptions.has(chatId)) return;
     if (signal?.aborted) return;
@@ -116,6 +412,15 @@ export async function startDaemonToDiscordForwarder(
     let subscription: { unsubscribe: () => void } | null = null;
     let messageQueue = Promise.resolve();
 
+    type StreamItem =
+      | { kind: 'message'; message: ChatMessage }
+      | {
+          kind: 'turn';
+          event:
+            | { type: 'started'; turnId: string; rootMessageId: string; externalRef?: string }
+            | { type: 'ended'; turnId: string; outcome: 'ok' | 'error' };
+        };
+
     const connect = () => {
       if (signal?.aborted || !activeSubscriptions.has(chatId)) {
         return;
@@ -124,141 +429,54 @@ export async function startDaemonToDiscordForwarder(
       subscription = trpc.waitForMessages.subscribe(
         { chatId, lastMessageId },
         {
-          onData: (messages) => {
+          onData: (items) => {
             retryDelay = 1000; // Reset retry delay on successful data
 
-            if (!Array.isArray(messages) || messages.length === 0) {
+            if (!Array.isArray(items) || items.length === 0) {
               return;
             }
 
-            // Queue processing to ensure sequential execution
-            messageQueue = messageQueue.then(async () => {
-              for (const rawMessage of messages) {
-                if (signal?.aborted || !activeSubscriptions.has(chatId)) break;
-
-                const message = rawMessage as ChatMessage;
-
-                const isDisplayed = shouldDisplayMessage(message, config);
-
-                if (isDisplayed) {
-                  const logMessage = message;
-                  const isPolicyRequest =
-                    logMessage.role === 'policy' && logMessage.status === 'pending';
-
-                  if (isPolicyRequest) {
+            messageQueue = messageQueue
+              .then(async () => {
+                for (const raw of items) {
+                  if (signal?.aborted || !activeSubscriptions.has(chatId)) break;
+
+                  const item = raw as StreamItem;
+                  if (item.kind === 'turn') {
+                    // Turn events do disk reads (state.json) and Discord API
+                    // fetches; either can throw transiently. Catch here so a
+                    // single bad event doesn't reject the .then and poison
+                    // the chain — every subsequent batch would silently no-op.
                     try {
-                      const dm = await resolveDiscordDestination(client, discordUserId, chatId);
-
-                      const embed = new EmbedBuilder()
-                        .setTitle('Action Required: Policy Request')
-                        .setDescription(
-                          logMessage.content || 'A pending policy request requires your attention.'
-                        )
-                        .setColor(Colors.Yellow);
-
-                      const policyId =
-                        ('requestId' in logMessage && logMessage.requestId) || logMessage.id;
-                      const row = new ActionRowBuilder<ButtonBuilder>().addComponents(
-                        new ButtonBuilder()
-                          .setCustomId(`approve|${policyId}|${chatId}`)
-                          .setLabel('Approve')
-                          .setStyle(ButtonStyle.Success),
-                        new ButtonBuilder()
-                          .setCustomId(`reject|${policyId}|${chatId}`)
-                          .setLabel('Reject')
-                          .setStyle(ButtonStyle.Danger)
-                      );
-
-                      const optionsMsg: MessageCreateOptions = {
-                        embeds: [embed],
-                        components: [row],
-                      };
-
-                      try {
-                        await dm.send(optionsMsg);
-                      } catch (richError) {
-                        console.warn(
-                          `Failed to send rich message to Discord user ${discordUserId}, falling back to plain text:`,
-                          richError
-                        );
-                        await dm.send({
-                          content: `Action Required: Policy Request\n\n${logMessage.content || 'A pending policy request requires your attention.'}\n\nApprove: \`/approve ${policyId}\`\nReject: \`/reject ${policyId} <optional_rationale>\``,
-                        });
+                      if (item.event.type === 'started') {
+                        await handleTurnStarted(chatId, item.event.turnId, item.event.externalRef);
+                      } else {
+                        await handleTurnEnded(item.event.turnId);
                       }
-                    } catch (error) {
-                      console.error(
-                        `Failed to send message to Discord user ${discordUserId}:`,
-                        error
-                      );
+                    } catch (err) {
+                      console.error('Failed to handle turn event:', err);
                     }
-
-                    await saveLastMessageId(chatId, logMessage.id).catch(console.error);
-                    lastMessageId = logMessage.id;
-                    continue;
-                  }
-
-                  if ('level' in logMessage && logMessage.level === 'verbose') {
-                    await saveLastMessageId(chatId, logMessage.id).catch(console.error);
-                    lastMessageId = logMessage.id;
-                    continue;
-                  }
-
-                  const hasContent = !!logMessage.content?.trim();
-                  const files = 'files' in logMessage ? (logMessage.files as string[]) : undefined;
-                  const hasFiles = Array.isArray(files) && files.length > 0;
-
-                  // The daemon stores logMessage.files as paths relative to the WORKSPACE directory
-                  // (the directory containing .clawmini). We must resolve these against the current
-                  // workspace root so discord.js can successfully locate and read the files.
-                  let absoluteFiles: string[] = [];
-                  if (hasFiles && files) {
-                    const workspaceRoot = getWorkspaceRoot(process.cwd());
-                    absoluteFiles = files.map((f) => path.resolve(workspaceRoot, f));
-                  }
-
-                  if (!hasContent && !hasFiles) {
-                    await saveLastMessageId(chatId, logMessage.id).catch(console.error);
-                    lastMessageId = logMessage.id;
                     continue;
                   }
 
+                  const message = item.message;
                   try {
-                    const dm = await resolveDiscordDestination(client, discordUserId, chatId);
-                    const formattedContent = formatMessage(message);
-
-                    if (formattedContent && formattedContent.length > 2000) {
-                      const chunks = chunkString(formattedContent, 2000);
-                      for (let i = 0; i < chunks.length; i++) {
-                        if (signal?.aborted || !activeSubscriptions.has(chatId)) break;
-                        const chunkOptions: MessageCreateOptions = { content: chunks[i] as string };
-                        if (i === chunks.length - 1 && hasFiles) {
-                          chunkOptions.files = absoluteFiles;
-                        }
-                        await dm.send(chunkOptions);
-                      }
-                    } else {
-                      const optionsMsg: MessageCreateOptions = {};
-                      if (formattedContent) {
-                        optionsMsg.content = formattedContent;
-                      }
-                      if (hasFiles) {
-                        optionsMsg.files = absoluteFiles;
-                      }
-                      await dm.send(optionsMsg);
-                    }
-                  } catch (error) {
-                    console.error(
-                      `Failed to send message to Discord user ${discordUserId}:`,
-                      error
-                    );
-                    break; // don't advance lastMessageId
+                    await handleMessageForChat(chatId, message);
+                  } catch (err) {
+                    console.error('Failed to handle message:', err);
+                    // Don't advance lastMessageId on a hard error so we retry on
+                    // reconnect; matches prior behavior.
+                    break;
                   }
-                }
 
-                await saveLastMessageId(chatId, message.id).catch(console.error);
-                lastMessageId = message.id;
-              }
-            });
+                  await saveLastMessageId(chatId, message.id).catch(console.error);
+                  lastMessageId = message.id;
+                }
+              })
+              // Belt-and-suspenders: anything that escapes the per-item
+              // try/catches above (sync throw before the loop, etc.) must
+              // not leave the chain in a rejected state.
+              .catch((err) => console.error('Message queue chain error:', err));
           },
           onError: (error) => {
             console.error(
@@ -299,7 +517,7 @@ export async function startDaemonToDiscordForwarder(
         { chatId },
         {
           onData: async (event) => {
-            typingRetryDelay = 1000; // Reset retry delay on successful data
+            typingRetryDelay = 1000;
             if (!event) return;
 
             try {
@@ -416,6 +634,7 @@ export async function startDaemonToDiscordForwarder(
       watcher.close();
       for (const sub of activeSubscriptions.values()) sub.unsubscribe();
       for (const sub of activeTypingSubscriptions.values()) sub.unsubscribe();
+      turnLog.shutdown();
       resolve();
     });
   });

package/src/adapter-discord/inbound-cache.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  recordInbound,
+  resolveInbound,
+  INBOUND_TTL_MS,
+  _resetInboundCacheForTests,
+} from './inbound-cache.js';
+
+describe('discord inbound-cache', () => {
+  beforeEach(() => {
+    _resetInboundCacheForTests();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('records and resolves an inbound by message id', () => {
+    recordInbound({ messageId: 'msg-1', channelId: 'chan-1' });
+    expect(resolveInbound('msg-1')).toMatchObject({
+      messageId: 'msg-1',
+      channelId: 'chan-1',
+    });
+  });
+
+  it('returns null for unknown keys', () => {
+    expect(resolveInbound('unknown')).toBeNull();
+  });
+
+  it('expires entries older than INBOUND_TTL_MS on resolve', () => {
+    vi.useFakeTimers();
+    recordInbound({ messageId: 'msg-1', channelId: 'chan-1' });
+    expect(resolveInbound('msg-1')).not.toBeNull();
+
+    vi.advanceTimersByTime(INBOUND_TTL_MS + 1000);
+    expect(resolveInbound('msg-1')).toBeNull();
+  });
+
+  it('sweeps expired entries on every insert', () => {
+    vi.useFakeTimers();
+    recordInbound({ messageId: 'msg-1', channelId: 'chan-1' });
+    vi.advanceTimersByTime(INBOUND_TTL_MS + 1000);
+    recordInbound({ messageId: 'msg-2', channelId: 'chan-2' });
+    expect(resolveInbound('msg-1')).toBeNull();
+    expect(resolveInbound('msg-2')).not.toBeNull();
+  });
+});

package/src/adapter-discord/inbound-cache.ts

@@ -0,0 +1,37 @@
+/**
+ * Discord-side wrapper around the shared inbound-message TTL cache.
+ *
+ * On every inbound user message, the gateway records `{ messageId, channelId
+ * }`. The same `messageId` is sent to the daemon as `externalRef` on the
+ * `sendMessage` mutation. When the forwarder later sees `turnStarted` with
+ * that `externalRef`, it resolves the channel + message id and starts a
+ * Discord thread anchored on the user's message.
+ */
+import { createInboundCache } from '../shared/adapters/inbound-cache.js';
+
+export const INBOUND_TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+interface DiscordInboundValue {
+  channelId: string;
+}
+
+const cache = createInboundCache<DiscordInboundValue>(INBOUND_TTL_MS);
+
+export interface DiscordInboundRecord {
+  messageId: string;
+  channelId: string;
+}
+
+export function recordInbound(entry: DiscordInboundRecord): void {
+  cache.record(entry.messageId, { channelId: entry.channelId });
+}
+
+export function resolveInbound(messageId: string): DiscordInboundRecord | null {
+  const value = cache.resolve(messageId);
+  return value ? { messageId, channelId: value.channelId } : null;
+}
+
+/** Test hook: drop all cached records. */
+export function _resetInboundCacheForTests(): void {
+  cache.reset();
+}