@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/message-handler.draft-preview.ts

@@ -0,0 +1,426 @@
+import { EmbeddedBlockChunker } from "klaw/plugin-sdk/agent-runtime";
+import {
+  createChannelProgressDraftGate,
+  type ChannelProgressDraftLine,
+  formatChannelProgressDraftText,
+  isChannelProgressDraftWorkToolName,
+  mergeChannelProgressDraftLine,
+  normalizeChannelProgressDraftLineIdentity,
+  resolveChannelProgressDraftMaxLines,
+  resolveChannelStreamingBlockEnabled,
+  resolveChannelStreamingPreviewToolProgress,
+  resolveChannelStreamingSuppressDefaultToolProgressMessages,
+} from "klaw/plugin-sdk/channel-streaming";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import {
+  convertMarkdownTables,
+  stripInlineDirectiveTagsForDelivery,
+  stripReasoningTagsFromText,
+} from "klaw/plugin-sdk/text-chunking";
+import { chunkDiscordTextWithMode } from "../chunk.js";
+import { resolveDiscordDraftStreamingChunking } from "../draft-chunking.js";
+import { createDiscordDraftStream } from "../draft-stream.js";
+import type { RequestClient } from "../internal/discord.js";
+import { resolveDiscordPreviewStreamMode } from "../preview-streaming.js";
+
+type DraftReplyReference = {
+  peek: () => string | undefined;
+};
+
+type DiscordConfig = NonNullable<KlawConfig["channels"]>["discord"];
+
+export function createDiscordDraftPreviewController(params: {
+  cfg: KlawConfig;
+  discordConfig: DiscordConfig;
+  accountId: string;
+  sourceRepliesAreToolOnly: boolean;
+  textLimit: number;
+  deliveryRest: RequestClient;
+  deliverChannelId: string;
+  replyReference: DraftReplyReference;
+  tableMode: Parameters<typeof convertMarkdownTables>[1];
+  maxLinesPerMessage: number | undefined;
+  chunkMode: Parameters<typeof chunkDiscordTextWithMode>[1]["chunkMode"];
+  log: (message: string) => void;
+}) {
+  const discordStreamMode = resolveDiscordPreviewStreamMode(params.discordConfig);
+  const draftMaxChars = Math.min(params.textLimit, 2000);
+  const accountBlockStreamingEnabled =
+    resolveChannelStreamingBlockEnabled(params.discordConfig) ??
+    params.cfg.agents?.defaults?.blockStreamingDefault === "on";
+  const canStreamProgressDraftForToolOnlySource =
+    params.sourceRepliesAreToolOnly && discordStreamMode === "progress";
+  const canStreamDraft =
+    (!params.sourceRepliesAreToolOnly || canStreamProgressDraftForToolOnlySource) &&
+    discordStreamMode !== "off" &&
+    !accountBlockStreamingEnabled;
+  const draftStream = canStreamDraft
+    ? createDiscordDraftStream({
+        rest: params.deliveryRest,
+        channelId: params.deliverChannelId,
+        maxChars: draftMaxChars,
+        replyToMessageId: () => params.replyReference.peek(),
+        minInitialChars: discordStreamMode === "progress" ? 0 : 30,
+        suppressEmbeds: params.discordConfig?.suppressEmbeds ?? true,
+        throttleMs: 1200,
+        log: params.log,
+        warn: params.log,
+      })
+    : undefined;
+  const draftChunking =
+    draftStream && discordStreamMode === "block"
+      ? resolveDiscordDraftStreamingChunking(params.cfg, params.accountId)
+      : undefined;
+  const shouldSplitPreviewMessages = discordStreamMode === "block";
+  const draftChunker = draftChunking ? new EmbeddedBlockChunker(draftChunking) : undefined;
+  let lastPartialText = "";
+  let draftText = "";
+  let hasStreamedMessage = false;
+  let finalizedViaPreviewMessage = false;
+  let finalReplyDelivered = false;
+  const previewToolProgressEnabled =
+    Boolean(draftStream) && resolveChannelStreamingPreviewToolProgress(params.discordConfig);
+  const suppressDefaultToolProgressMessages =
+    Boolean(draftStream) &&
+    resolveChannelStreamingSuppressDefaultToolProgressMessages(params.discordConfig, {
+      draftStreamActive: true,
+      previewToolProgressEnabled,
+    });
+  let previewToolProgressSuppressed = false;
+  let previewToolProgressLines: Array<string | ChannelProgressDraftLine> = [];
+  let reasoningProgressRawText = "";
+  let lastReasoningProgressLine: string | undefined;
+  const progressSeed = `${params.accountId}:${params.deliverChannelId}`;
+
+  const renderProgressDraft = async (options?: { flush?: boolean }) => {
+    if (!draftStream || discordStreamMode !== "progress") {
+      return;
+    }
+    const previewText = formatChannelProgressDraftText({
+      entry: params.discordConfig,
+      lines: previewToolProgressLines,
+      seed: progressSeed,
+    });
+    if (!previewText || previewText === lastPartialText) {
+      return;
+    }
+    lastPartialText = previewText;
+    draftText = previewText;
+    hasStreamedMessage = true;
+    draftChunker?.reset();
+    draftStream.update(previewText);
+    if (options?.flush) {
+      await draftStream.flush();
+    }
+  };
+
+  const progressDraftGate = createChannelProgressDraftGate({
+    onStart: () => renderProgressDraft({ flush: true }),
+  });
+
+  const resetProgressState = () => {
+    lastPartialText = "";
+    draftText = "";
+    draftChunker?.reset();
+    previewToolProgressSuppressed = false;
+    previewToolProgressLines = [];
+    reasoningProgressRawText = "";
+    lastReasoningProgressLine = undefined;
+  };
+
+  const forceNewMessageIfNeeded = () => {
+    if (shouldSplitPreviewMessages && hasStreamedMessage) {
+      params.log("discord: calling forceNewMessage() for draft stream");
+      draftStream?.forceNewMessage();
+    }
+    resetProgressState();
+  };
+
+  return {
+    draftStream,
+    previewToolProgressEnabled,
+    suppressDefaultToolProgressMessages,
+    get isProgressMode() {
+      return discordStreamMode === "progress";
+    },
+    get hasProgressDraftStarted() {
+      return progressDraftGate.hasStarted;
+    },
+    get finalizedViaPreviewMessage() {
+      return finalizedViaPreviewMessage;
+    },
+    markFinalReplyDelivered() {
+      finalReplyDelivered = true;
+    },
+    markPreviewFinalized() {
+      finalizedViaPreviewMessage = true;
+    },
+    disableBlockStreamingForDraft: draftStream ? true : undefined,
+    async startProgressDraft() {
+      if (!draftStream || discordStreamMode !== "progress") {
+        return;
+      }
+      await progressDraftGate.startNow();
+    },
+    async pushToolProgress(
+      line?: string | ChannelProgressDraftLine,
+      options?: { toolName?: string },
+    ) {
+      if (!draftStream) {
+        return;
+      }
+      if (
+        options?.toolName !== undefined &&
+        !isChannelProgressDraftWorkToolName(options.toolName)
+      ) {
+        return;
+      }
+      if (isEmptyDiscordProgressLine(line)) {
+        return;
+      }
+      const normalized = normalizeChannelProgressDraftLineIdentity(line);
+      if (!normalized) {
+        return;
+      }
+      const progressLine: string | ChannelProgressDraftLine =
+        typeof line === "object" && line !== undefined ? line : normalized;
+      if (discordStreamMode !== "progress") {
+        if (!previewToolProgressEnabled || previewToolProgressSuppressed) {
+          return;
+        }
+        const nextLines = mergeChannelProgressDraftLine(previewToolProgressLines, progressLine, {
+          maxLines: resolveChannelProgressDraftMaxLines(params.discordConfig),
+        });
+        if (nextLines === previewToolProgressLines) {
+          return;
+        }
+        previewToolProgressLines = nextLines;
+        const previewText = formatChannelProgressDraftText({
+          entry: params.discordConfig,
+          lines: previewToolProgressLines,
+          seed: progressSeed,
+        });
+        lastPartialText = previewText;
+        draftText = previewText;
+        hasStreamedMessage = true;
+        draftChunker?.reset();
+        draftStream.update(previewText);
+        return;
+      }
+      if (previewToolProgressEnabled && !previewToolProgressSuppressed && normalized) {
+        previewToolProgressLines = mergeChannelProgressDraftLine(
+          previewToolProgressLines,
+          progressLine,
+          {
+            maxLines: resolveChannelProgressDraftMaxLines(params.discordConfig),
+          },
+        );
+      }
+      const alreadyStarted = progressDraftGate.hasStarted;
+      if (shouldStartDiscordProgressDraftNow(line)) {
+        await progressDraftGate.startNow();
+      } else {
+        await progressDraftGate.noteWork();
+      }
+      if (alreadyStarted && progressDraftGate.hasStarted) {
+        await renderProgressDraft();
+      }
+    },
+    async pushReasoningProgress(text?: string) {
+      if (!draftStream || discordStreamMode !== "progress" || !text) {
+        return;
+      }
+      reasoningProgressRawText = mergeReasoningProgressText(reasoningProgressRawText, text);
+      const normalized = normalizeReasoningProgressLine(reasoningProgressRawText);
+      if (!normalized) {
+        return;
+      }
+      if (previewToolProgressEnabled && !previewToolProgressSuppressed) {
+        const priorIndex =
+          lastReasoningProgressLine === undefined
+            ? -1
+            : previewToolProgressLines.lastIndexOf(lastReasoningProgressLine);
+        if (priorIndex >= 0) {
+          previewToolProgressLines = [...previewToolProgressLines];
+          previewToolProgressLines[priorIndex] = normalized;
+        } else {
+          previewToolProgressLines = [...previewToolProgressLines, normalized].slice(
+            -resolveChannelProgressDraftMaxLines(params.discordConfig),
+          );
+        }
+        lastReasoningProgressLine = normalized;
+      }
+      const alreadyStarted = progressDraftGate.hasStarted;
+      await progressDraftGate.noteWork();
+      if (alreadyStarted && progressDraftGate.hasStarted) {
+        await renderProgressDraft();
+      }
+    },
+    resolvePreviewFinalText(text?: string) {
+      if (typeof text !== "string") {
+        return undefined;
+      }
+      const formatted = convertMarkdownTables(
+        stripInlineDirectiveTagsForDelivery(text).text,
+        params.tableMode,
+      );
+      const chunks = chunkDiscordTextWithMode(formatted, {
+        maxChars: draftMaxChars,
+        maxLines: params.maxLinesPerMessage,
+        chunkMode: params.chunkMode,
+      });
+      if (!chunks.length && formatted) {
+        chunks.push(formatted);
+      }
+      if (chunks.length !== 1) {
+        return undefined;
+      }
+      const trimmed = chunks[0].trim();
+      if (!trimmed) {
+        return undefined;
+      }
+      const currentPreviewText = discordStreamMode === "block" ? draftText : lastPartialText;
+      if (
+        currentPreviewText &&
+        currentPreviewText.startsWith(trimmed) &&
+        trimmed.length < currentPreviewText.length
+      ) {
+        return undefined;
+      }
+      return trimmed;
+    },
+    updateFromPartial(text?: string) {
+      if (!draftStream || !text) {
+        return;
+      }
+      const cleaned = stripInlineDirectiveTagsForDelivery(
+        stripReasoningTagsFromText(text, { mode: "strict", trim: "both" }),
+      ).text;
+      if (!cleaned || cleaned.startsWith("Reasoning:\n")) {
+        return;
+      }
+      if (cleaned === lastPartialText) {
+        return;
+      }
+      if (discordStreamMode === "progress") {
+        return;
+      }
+      previewToolProgressSuppressed = true;
+      previewToolProgressLines = [];
+      hasStreamedMessage = true;
+      if (discordStreamMode === "partial") {
+        if (
+          lastPartialText &&
+          lastPartialText.startsWith(cleaned) &&
+          cleaned.length < lastPartialText.length
+        ) {
+          return;
+        }
+        lastPartialText = cleaned;
+        draftStream.update(cleaned);
+        return;
+      }
+
+      let delta = cleaned;
+      if (cleaned.startsWith(lastPartialText)) {
+        delta = cleaned.slice(lastPartialText.length);
+      } else {
+        draftChunker?.reset();
+        draftText = "";
+      }
+      lastPartialText = cleaned;
+      if (!delta) {
+        return;
+      }
+      if (!draftChunker) {
+        draftText = cleaned;
+        draftStream.update(draftText);
+        return;
+      }
+      draftChunker.append(delta);
+      draftChunker.drain({
+        force: false,
+        emit: (chunk) => {
+          draftText += chunk;
+          draftStream.update(draftText);
+        },
+      });
+    },
+    handleAssistantMessageBoundary() {
+      if (discordStreamMode === "progress") {
+        return;
+      }
+      forceNewMessageIfNeeded();
+    },
+    async flush() {
+      if (!draftStream) {
+        return;
+      }
+      if (draftChunker?.hasBuffered()) {
+        draftChunker.drain({
+          force: true,
+          emit: (chunk) => {
+            draftText += chunk;
+          },
+        });
+        draftChunker.reset();
+        if (draftText) {
+          draftStream.update(draftText);
+        }
+      }
+      await draftStream.flush();
+    },
+    async cleanup() {
+      try {
+        progressDraftGate.cancel();
+        if (!finalReplyDelivered) {
+          await draftStream?.discardPending();
+        }
+        if (!finalReplyDelivered && !finalizedViaPreviewMessage && draftStream?.messageId()) {
+          await draftStream.clear();
+        }
+      } catch (err) {
+        params.log(`discord: draft cleanup failed: ${String(err)}`);
+      }
+    },
+  };
+}
+
+function normalizeReasoningProgressLine(text: string): string {
+  return text
+    .replace(/^\s*(?:>\s*)?(?:Reasoning:|Thinking\.{0,3})\s*/i, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function mergeReasoningProgressText(current: string, incoming: string): string {
+  if (!current) {
+    return incoming;
+  }
+  const normalizedCurrent = normalizeReasoningProgressLine(current);
+  const normalizedIncoming = normalizeReasoningProgressLine(incoming);
+  if (!normalizedIncoming || normalizedIncoming === normalizedCurrent) {
+    return current;
+  }
+  if (isReasoningSnapshotText(incoming) || normalizedIncoming.startsWith(normalizedCurrent)) {
+    return incoming;
+  }
+  return `${current}${incoming}`;
+}
+
+function isReasoningSnapshotText(text: string): boolean {
+  return /^\s*(?:>\s*)?(?:Reasoning:|Thinking\.{0,3})\s*/i.test(text);
+}
+
+function isEmptyDiscordProgressLine(line: string | ChannelProgressDraftLine | undefined): boolean {
+  if (!line || typeof line === "string") {
+    return false;
+  }
+  return line.toolName === "apply_patch" && !line.detail && !line.status;
+}
+
+function shouldStartDiscordProgressDraftNow(
+  line: string | ChannelProgressDraftLine | undefined,
+): boolean {
+  return typeof line === "object" && line?.kind === "patch" && Boolean(line.detail);
+}

package/src/monitor/message-handler.hydration.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { Message } from "../internal/discord.js";
+import {
+  createFakeRestClient,
+  createInternalTestClient,
+} from "../internal/test-builders.test-support.js";
+import { hydrateDiscordMessageIfNeeded } from "./message-handler.hydration.js";
+
+describe("hydrateDiscordMessageIfNeeded", () => {
+  it("hydrates partial internal messages without assigning over getters", async () => {
+    const client = createInternalTestClient();
+    const rest = createFakeRestClient([
+      {
+        id: "m1",
+        channel_id: "c1",
+        content: "hello <@u2>",
+        attachments: [{ id: "a1", filename: "note.txt" }],
+        embeds: [{ title: "Embed" }],
+        mentions: [
+          {
+            id: "u2",
+            username: "bob",
+            global_name: "Bob Builder",
+            discriminator: "0",
+            avatar: null,
+          },
+        ],
+        mention_roles: ["role1"],
+        mention_everyone: false,
+        timestamp: new Date().toISOString(),
+        author: {
+          id: "u1",
+          username: "alice",
+          discriminator: "0",
+          avatar: null,
+        },
+        referenced_message: {
+          id: "m0",
+          channel_id: "c1",
+          content: "earlier",
+          attachments: [],
+          embeds: [],
+          mentions: [],
+          mention_roles: [],
+          mention_everyone: false,
+          timestamp: new Date().toISOString(),
+          author: {
+            id: "u3",
+            username: "carol",
+            discriminator: "0",
+            avatar: null,
+          },
+          type: 0,
+          tts: false,
+          pinned: false,
+          flags: 0,
+        },
+        type: 0,
+        tts: false,
+        pinned: false,
+        flags: 0,
+      },
+    ]);
+    const message = new Message<true>(client, { id: "m1", channelId: "c1" }) as unknown as Message;
+
+    const hydrated = await hydrateDiscordMessageIfNeeded({
+      client: { rest },
+      message,
+      messageChannelId: "c1",
+    });
+
+    expect(hydrated).toBeInstanceOf(Message);
+    expect(hydrated.content).toBe("hello <@u2>");
+    expect(hydrated.attachments).toHaveLength(1);
+    expect(hydrated.embeds).toHaveLength(1);
+    expect(hydrated.mentionedUsers[0]?.globalName).toBe("Bob Builder");
+    expect(hydrated.mentionedRoles).toEqual(["role1"]);
+    expect(hydrated.referencedMessage?.content).toBe("earlier");
+  });
+});

package/src/monitor/message-handler.hydration.ts

@@ -0,0 +1,198 @@
+import type { APIMessage, APIUser } from "discord-api-types/v10";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { getChannelMessage, Message as DiscordMessage, type Message } from "../internal/discord.js";
+import { resolveDiscordMessageText, type DiscordChannelInfo } from "./message-utils.js";
+
+function mergeFetchedDiscordMessage(base: Message, fetched: APIMessage): Message {
+  const baseRawData = readMessageRawData(base);
+  const baseFallback = readMessageFallback(base);
+  const rawData = {
+    ...baseRawData,
+    ...fetched,
+    id: fetched.id ?? baseRawData.id ?? baseFallback.id,
+    channel_id: fetched.channel_id ?? baseRawData.channel_id ?? baseFallback.channel_id,
+    content: fetched.content ?? baseRawData.content ?? baseFallback.content,
+    author: fetched.author ?? baseRawData.author ?? baseFallback.author,
+    attachments: fetched.attachments ?? baseRawData.attachments ?? baseFallback.attachments,
+    embeds: fetched.embeds ?? baseRawData.embeds ?? baseFallback.embeds,
+    mentions: fetched.mentions ?? baseRawData.mentions ?? baseFallback.mentions,
+    mention_roles: fetched.mention_roles ?? baseRawData.mention_roles ?? baseFallback.mention_roles,
+    mention_everyone:
+      fetched.mention_everyone ?? baseRawData.mention_everyone ?? baseFallback.mention_everyone,
+    timestamp: fetched.timestamp ?? baseRawData.timestamp ?? baseFallback.timestamp,
+    tts: fetched.tts ?? baseRawData.tts ?? false,
+    pinned: fetched.pinned ?? baseRawData.pinned ?? false,
+    type: fetched.type ?? baseRawData.type ?? 0,
+    message_snapshots:
+      fetched.message_snapshots ?? baseRawData.message_snapshots ?? baseFallback.message_snapshots,
+    sticker_items:
+      (fetched as { sticker_items?: unknown }).sticker_items ??
+      (baseRawData as { sticker_items?: unknown }).sticker_items ??
+      baseFallback.sticker_items,
+  } as APIMessage;
+  const hydrated = new DiscordMessage(readMessageClient(base), rawData);
+  copyRuntimeMessageFields(base, hydrated);
+  return hydrated;
+}
+
+function readMessageClient(message: Message): ConstructorParameters<typeof DiscordMessage>[0] {
+  return (message as unknown as { client: ConstructorParameters<typeof DiscordMessage>[0] }).client;
+}
+
+function readMessageRawData(message: Message): Partial<APIMessage> {
+  try {
+    const rawData = message.rawData as APIMessage | undefined;
+    return rawData && typeof rawData === "object" ? rawData : {};
+  } catch {
+    return {};
+  }
+}
+
+type MessageFallback = Partial<Omit<APIMessage, "message_snapshots" | "sticker_items">> & {
+  channel_id: string;
+  sticker_items?: APIMessage["sticker_items"];
+  message_snapshots?: APIMessage["message_snapshots"];
+};
+
+function readMessageFallback(message: Message): MessageFallback {
+  const value = message as unknown as {
+    id?: unknown;
+    channelId?: unknown;
+    channel_id?: unknown;
+    content?: unknown;
+    author?: unknown;
+    attachments?: unknown;
+    embeds?: unknown;
+    mentionedUsers?: unknown;
+    mentionedRoles?: unknown;
+    mentionedEveryone?: unknown;
+    timestamp?: unknown;
+    stickers?: unknown;
+    sticker_items?: unknown;
+    message_snapshots?: unknown;
+  };
+  return {
+    id: typeof value.id === "string" ? value.id : "",
+    channel_id: readString(value.channel_id) ?? readString(value.channelId) ?? "",
+    content: typeof value.content === "string" ? value.content : "",
+    author: normalizeApiUser(value.author),
+    attachments: Array.isArray(value.attachments) ? value.attachments : [],
+    embeds: Array.isArray(value.embeds) ? value.embeds : [],
+    mentions: normalizeApiUsers(value.mentionedUsers),
+    mention_roles: normalizeStringArray(value.mentionedRoles),
+    mention_everyone: value.mentionedEveryone === true,
+    timestamp: readString(value.timestamp) ?? "1970-01-01T00:00:00.000Z",
+    sticker_items: Array.isArray(value.sticker_items)
+      ? (value.sticker_items as APIMessage["sticker_items"])
+      : Array.isArray(value.stickers)
+        ? (value.stickers as APIMessage["sticker_items"])
+        : undefined,
+    message_snapshots: Array.isArray(value.message_snapshots)
+      ? (value.message_snapshots as APIMessage["message_snapshots"])
+      : undefined,
+  };
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function normalizeStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.flatMap((entry) => (typeof entry === "string" ? [entry] : []))
+    : [];
+}
+
+function normalizeApiUsers(value: unknown): APIUser[] {
+  return Array.isArray(value)
+    ? value.flatMap((entry) => {
+        const user = normalizeApiUser(entry);
+        return user.id ? [user] : [];
+      })
+    : [];
+}
+
+function normalizeApiUser(value: unknown): APIUser {
+  if (!value || typeof value !== "object") {
+    return {
+      id: "",
+      username: "",
+      discriminator: "0",
+      global_name: null,
+      avatar: null,
+    };
+  }
+  const input = value as {
+    id?: unknown;
+    username?: unknown;
+    global_name?: unknown;
+    globalName?: unknown;
+    discriminator?: unknown;
+    avatar?: unknown;
+    bot?: unknown;
+  };
+  return {
+    id: readString(input.id) ?? "",
+    username: readString(input.username) ?? "",
+    discriminator: readString(input.discriminator) ?? "0",
+    global_name: readString(input.global_name) ?? readString(input.globalName) ?? null,
+    avatar: input.avatar === null ? null : (readString(input.avatar) ?? null),
+    ...(typeof input.bot === "boolean" ? { bot: input.bot } : {}),
+  };
+}
+
+function copyRuntimeMessageFields(source: Message, target: Message): void {
+  const channelDescriptor = Object.getOwnPropertyDescriptor(source, "channel");
+  if (channelDescriptor) {
+    Object.defineProperty(target, "channel", channelDescriptor);
+  }
+}
+
+function shouldHydrateDiscordMessage(params: { message: Message }) {
+  let currentText = "";
+  try {
+    currentText = resolveDiscordMessageText(params.message, {
+      includeForwarded: true,
+    });
+  } catch {
+    return true;
+  }
+  if (!currentText) {
+    return true;
+  }
+  const hasMentionMetadata =
+    (params.message.mentionedUsers?.length ?? 0) > 0 ||
+    (params.message.mentionedRoles?.length ?? 0) > 0 ||
+    params.message.mentionedEveryone;
+  if (hasMentionMetadata) {
+    return false;
+  }
+  return /<@!?\d+>|<@&\d+>|@everyone|@here/u.test(currentText);
+}
+
+export async function hydrateDiscordMessageIfNeeded(params: {
+  client: { rest: Parameters<typeof getChannelMessage>[0] };
+  message: Message;
+  messageChannelId: string;
+  channelInfo?: DiscordChannelInfo | null;
+}): Promise<Message> {
+  void params.channelInfo;
+  if (!shouldHydrateDiscordMessage({ message: params.message })) {
+    return params.message;
+  }
+  try {
+    const fetched = (await getChannelMessage(
+      params.client.rest,
+      params.messageChannelId,
+      params.message.id,
+    )) as APIMessage | null | undefined;
+    if (!fetched) {
+      return params.message;
+    }
+    logVerbose(`discord: hydrated inbound payload via REST for ${params.message.id}`);
+    return mergeFetchedDiscordMessage(params.message, fetched);
+  } catch (err) {
+    logVerbose(`discord: failed to hydrate message ${params.message.id}: ${String(err)}`);
+    return params.message;
+  }
+}