@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/monitor/message-handler.preflight-channel-access.ts

@@ -0,0 +1,86 @@
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { logDebug } from "openclaw/plugin-sdk/text-runtime";
+import {
+  isDiscordGroupAllowedByPolicy,
+  resolveGroupDmAllow,
+  type DiscordChannelConfigResolved,
+  type DiscordGuildEntryResolved,
+} from "./allow-list.js";
+
+export function resolveDiscordPreflightChannelAccess(params: {
+  isGuildMessage: boolean;
+  isGroupDm: boolean;
+  groupPolicy: "open" | "disabled" | "allowlist";
+  groupDmChannels?: string[];
+  messageChannelId: string;
+  displayChannelName?: string;
+  displayChannelSlug: string;
+  guildInfo: DiscordGuildEntryResolved | null;
+  channelConfig: DiscordChannelConfigResolved | null;
+  channelMatchMeta: string;
+}): { allowed: boolean; channelAllowlistConfigured: boolean; channelAllowed: boolean } {
+  if (params.isGuildMessage && params.channelConfig?.enabled === false) {
+    logDebug(`[discord-preflight] drop: channel disabled`);
+    logVerbose(
+      `Blocked discord channel ${params.messageChannelId} (channel disabled, ${params.channelMatchMeta})`,
+    );
+    return { allowed: false, channelAllowlistConfigured: false, channelAllowed: false };
+  }
+
+  const groupDmAllowed =
+    params.isGroupDm &&
+    resolveGroupDmAllow({
+      channels: params.groupDmChannels,
+      channelId: params.messageChannelId,
+      channelName: params.displayChannelName,
+      channelSlug: params.displayChannelSlug,
+    });
+  if (params.isGroupDm && !groupDmAllowed) {
+    return { allowed: false, channelAllowlistConfigured: false, channelAllowed: false };
+  }
+
+  const channelAllowlistConfigured =
+    Boolean(params.guildInfo?.channels) && Object.keys(params.guildInfo?.channels ?? {}).length > 0;
+  const channelAllowed = params.channelConfig?.allowed !== false;
+  if (
+    params.isGuildMessage &&
+    !isDiscordGroupAllowedByPolicy({
+      groupPolicy: params.groupPolicy,
+      guildAllowlisted: Boolean(params.guildInfo),
+      channelAllowlistConfigured,
+      channelAllowed,
+    })
+  ) {
+    if (params.groupPolicy === "disabled") {
+      logDebug(`[discord-preflight] drop: groupPolicy disabled`);
+      logVerbose(`discord: drop guild message (groupPolicy: disabled, ${params.channelMatchMeta})`);
+    } else if (!channelAllowlistConfigured) {
+      logDebug(`[discord-preflight] drop: groupPolicy allowlist, no channel allowlist configured`);
+      logVerbose(
+        `discord: drop guild message (groupPolicy: allowlist, no channel allowlist, ${params.channelMatchMeta})`,
+      );
+    } else {
+      logDebug(
+        `[discord] Ignored message from channel ${params.messageChannelId} (not in guild allowlist). Add to guilds.<guildId>.channels to enable.`,
+      );
+      logVerbose(
+        `Blocked discord channel ${params.messageChannelId} not in guild channel allowlist (groupPolicy: allowlist, ${params.channelMatchMeta})`,
+      );
+    }
+    return { allowed: false, channelAllowlistConfigured, channelAllowed };
+  }
+
+  if (params.isGuildMessage && params.channelConfig?.allowed === false) {
+    logDebug(`[discord-preflight] drop: channelConfig.allowed===false`);
+    logVerbose(
+      `Blocked discord channel ${params.messageChannelId} not in guild channel allowlist (${params.channelMatchMeta})`,
+    );
+    return { allowed: false, channelAllowlistConfigured, channelAllowed };
+  }
+  if (params.isGuildMessage) {
+    logDebug(`[discord-preflight] pass: channel allowed`);
+    logVerbose(`discord: allow channel ${params.messageChannelId} (${params.channelMatchMeta})`);
+  }
+
+  return { allowed: true, channelAllowlistConfigured, channelAllowed };
+}

package/src/monitor/message-handler.preflight-channel-context.ts

@@ -0,0 +1,55 @@
+import {
+  normalizeDiscordSlug,
+  resolveDiscordChannelConfigWithFallback,
+  type DiscordGuildEntryResolved,
+} from "./allow-list.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.types.js";
+
+export function resolveDiscordPreflightChannelContext(params: {
+  isGuildMessage: boolean;
+  messageChannelId: string;
+  channelName?: string;
+  guildName?: string;
+  guildInfo: DiscordGuildEntryResolved | null;
+  threadChannel: DiscordMessagePreflightContext["threadChannel"];
+  threadParentId?: string;
+  threadParentName?: string;
+}) {
+  const threadName = params.threadChannel?.name;
+  const configChannelName = params.threadParentName ?? params.channelName;
+  const configChannelSlug = configChannelName ? normalizeDiscordSlug(configChannelName) : "";
+  const displayChannelName = threadName ?? params.channelName;
+  const displayChannelSlug = displayChannelName ? normalizeDiscordSlug(displayChannelName) : "";
+  const guildSlug =
+    params.guildInfo?.slug || (params.guildName ? normalizeDiscordSlug(params.guildName) : "");
+
+  const threadChannelSlug = params.channelName ? normalizeDiscordSlug(params.channelName) : "";
+  const threadParentSlug = params.threadParentName
+    ? normalizeDiscordSlug(params.threadParentName)
+    : "";
+
+  const channelConfig = params.isGuildMessage
+    ? resolveDiscordChannelConfigWithFallback({
+        guildInfo: params.guildInfo,
+        channelId: params.messageChannelId,
+        channelName: params.channelName,
+        channelSlug: threadChannelSlug,
+        parentId: params.threadParentId,
+        parentName: params.threadParentName,
+        parentSlug: threadParentSlug,
+        scope: params.threadChannel ? "thread" : "channel",
+      })
+    : null;
+
+  return {
+    threadName,
+    configChannelName,
+    configChannelSlug,
+    displayChannelName,
+    displayChannelSlug,
+    guildSlug,
+    threadChannelSlug,
+    threadParentSlug,
+    channelConfig,
+  };
+}

package/src/monitor/message-handler.preflight-context.ts

@@ -0,0 +1,54 @@
+import type {
+  DiscordMessagePreflightContext,
+  DiscordMessagePreflightParams,
+} from "./message-handler.preflight.types.js";
+
+type SharedPreflightFields =
+  | "cfg"
+  | "discordConfig"
+  | "accountId"
+  | "token"
+  | "runtime"
+  | "botUserId"
+  | "abortSignal"
+  | "guildHistories"
+  | "historyLimit"
+  | "mediaMaxBytes"
+  | "textLimit"
+  | "replyToMode"
+  | "ackReactionScope"
+  | "groupPolicy"
+  | "threadBindings"
+  | "discordRestFetch";
+
+type BuildDiscordMessagePreflightContextParams = Omit<
+  DiscordMessagePreflightContext,
+  SharedPreflightFields
+> & {
+  preflightParams: DiscordMessagePreflightParams;
+};
+
+export function buildDiscordMessagePreflightContext({
+  preflightParams,
+  ...fields
+}: BuildDiscordMessagePreflightContextParams): DiscordMessagePreflightContext {
+  return {
+    cfg: preflightParams.cfg,
+    discordConfig: preflightParams.discordConfig,
+    accountId: preflightParams.accountId,
+    token: preflightParams.token,
+    runtime: preflightParams.runtime,
+    botUserId: preflightParams.botUserId,
+    abortSignal: preflightParams.abortSignal,
+    guildHistories: preflightParams.guildHistories,
+    historyLimit: preflightParams.historyLimit,
+    mediaMaxBytes: preflightParams.mediaMaxBytes,
+    textLimit: preflightParams.textLimit,
+    replyToMode: preflightParams.replyToMode,
+    ackReactionScope: preflightParams.ackReactionScope,
+    groupPolicy: preflightParams.groupPolicy,
+    ...fields,
+    threadBindings: preflightParams.threadBindings,
+    discordRestFetch: preflightParams.discordRestFetch,
+  };
+}

package/src/monitor/message-handler.preflight-helpers.ts

@@ -0,0 +1,164 @@
+import {
+  implicitMentionKindWhen,
+  matchesMentionWithExplicit,
+} from "openclaw/plugin-sdk/channel-inbound";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { ChannelType, type Message } from "../internal/discord.js";
+import type { DiscordMessagePreflightParams } from "./message-handler.preflight.types.js";
+import type { DiscordChannelInfo } from "./message-utils.js";
+import { isRecentlyUnboundThreadWebhookMessage } from "./thread-bindings.js";
+
+const DISCORD_BOUND_THREAD_SYSTEM_PREFIXES = ["⚙️", "🤖", "🧰"];
+
+export function isBoundThreadBotSystemMessage(params: {
+  isBoundThreadSession: boolean;
+  isBotAuthor: boolean;
+  text?: string;
+}): boolean {
+  if (!params.isBoundThreadSession || !params.isBotAuthor) {
+    return false;
+  }
+  const text = params.text?.trim();
+  if (!text) {
+    return false;
+  }
+  return DISCORD_BOUND_THREAD_SYSTEM_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+type BoundThreadLookupRecordLike = {
+  webhookId?: string | null;
+  metadata?: {
+    webhookId?: string | null;
+  };
+};
+
+function isDiscordThreadChannelType(type: ChannelType | undefined): boolean {
+  return (
+    type === ChannelType.PublicThread ||
+    type === ChannelType.PrivateThread ||
+    type === ChannelType.AnnouncementThread
+  );
+}
+
+export function isDiscordThreadChannelMessage(params: {
+  isGuildMessage: boolean;
+  message: Message;
+  channelInfo: DiscordChannelInfo | null;
+}): boolean {
+  if (!params.isGuildMessage) {
+    return false;
+  }
+  const channel =
+    "channel" in params.message ? (params.message as { channel?: unknown }).channel : undefined;
+  return Boolean(
+    (channel &&
+      typeof channel === "object" &&
+      "isThread" in channel &&
+      typeof (channel as { isThread?: unknown }).isThread === "function" &&
+      (channel as { isThread: () => boolean }).isThread()) ||
+    isDiscordThreadChannelType(params.channelInfo?.type),
+  );
+}
+
+export function resolveInjectedBoundThreadLookupRecord(params: {
+  threadBindings: DiscordMessagePreflightParams["threadBindings"];
+  threadId: string;
+}): BoundThreadLookupRecordLike | undefined {
+  const getByThreadId = (params.threadBindings as { getByThreadId?: (threadId: string) => unknown })
+    .getByThreadId;
+  if (typeof getByThreadId !== "function") {
+    return undefined;
+  }
+  const binding = getByThreadId(params.threadId);
+  return binding && typeof binding === "object"
+    ? (binding as BoundThreadLookupRecordLike)
+    : undefined;
+}
+
+export function resolveDiscordMentionState(params: {
+  authorIsBot: boolean;
+  botId?: string;
+  hasAnyMention: boolean;
+  isDirectMessage: boolean;
+  isExplicitlyMentioned: boolean;
+  mentionRegexes: RegExp[];
+  mentionText: string;
+  mentionedEveryone: boolean;
+  referencedAuthorId?: string;
+  senderIsPluralKit: boolean;
+  transcript?: string;
+}) {
+  if (params.isDirectMessage) {
+    return {
+      implicitMentionKinds: [],
+      wasMentioned: false,
+    };
+  }
+
+  const everyoneMentioned =
+    params.mentionedEveryone && (!params.authorIsBot || params.senderIsPluralKit);
+  const wasMentioned =
+    everyoneMentioned ||
+    matchesMentionWithExplicit({
+      text: params.mentionText,
+      mentionRegexes: params.mentionRegexes,
+      explicit: {
+        hasAnyMention: params.hasAnyMention,
+        isExplicitlyMentioned: params.isExplicitlyMentioned,
+        canResolveExplicit: Boolean(params.botId),
+      },
+      transcript: params.transcript,
+    });
+  const implicitMentionKinds = implicitMentionKindWhen(
+    "reply_to_bot",
+    Boolean(params.botId) &&
+      Boolean(params.referencedAuthorId) &&
+      params.referencedAuthorId === params.botId,
+  );
+
+  return {
+    implicitMentionKinds,
+    wasMentioned,
+  };
+}
+
+export function resolvePreflightMentionRequirement(params: {
+  shouldRequireMention: boolean;
+  bypassMentionRequirement: boolean;
+}): boolean {
+  if (!params.shouldRequireMention) {
+    return false;
+  }
+  return !params.bypassMentionRequirement;
+}
+
+export function shouldIgnoreBoundThreadWebhookMessage(params: {
+  accountId?: string;
+  threadId?: string;
+  webhookId?: string | null;
+  threadBinding?: BoundThreadLookupRecordLike;
+}): boolean {
+  const webhookId = normalizeOptionalString(params.webhookId) ?? "";
+  if (!webhookId) {
+    return false;
+  }
+  const boundWebhookId =
+    normalizeOptionalString(params.threadBinding?.webhookId) ??
+    normalizeOptionalString(params.threadBinding?.metadata?.webhookId) ??
+    "";
+  if (boundWebhookId && webhookId === boundWebhookId) {
+    return true;
+  }
+  const threadId = normalizeOptionalString(params.threadId) ?? "";
+  if (!threadId) {
+    return false;
+  }
+  if (params.threadBinding) {
+    return true;
+  }
+  return isRecentlyUnboundThreadWebhookMessage({
+    accountId: params.accountId,
+    threadId,
+    webhookId,
+  });
+}

package/src/monitor/message-handler.preflight-history.ts

@@ -0,0 +1,23 @@
+import type { HistoryEntry } from "openclaw/plugin-sdk/reply-history";
+import { resolveTimestampMs } from "./format.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.types.js";
+import { resolveDiscordMessageText } from "./message-utils.js";
+
+export function buildDiscordPreflightHistoryEntry(params: {
+  isGuildMessage: boolean;
+  historyLimit: number;
+  message: DiscordMessagePreflightContext["message"];
+  senderLabel: string;
+}): HistoryEntry | undefined {
+  const textForHistory = resolveDiscordMessageText(params.message, {
+    includeForwarded: true,
+  });
+  return params.isGuildMessage && params.historyLimit > 0 && textForHistory
+    ? {
+        sender: params.senderLabel,
+        body: textForHistory,
+        timestamp: resolveTimestampMs(params.message.timestamp),
+        messageId: params.message.id,
+      }
+    : undefined;
+}

package/src/monitor/message-handler.preflight-logging.ts

@@ -0,0 +1,36 @@
+import { logVerbose, shouldLogVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { logDebug } from "openclaw/plugin-sdk/text-runtime";
+import type { DiscordChannelConfigResolved } from "./allow-list.js";
+
+export function logDiscordPreflightChannelConfig(params: {
+  channelConfig: DiscordChannelConfigResolved | null;
+  channelMatchMeta: string;
+  channelId: string;
+}) {
+  if (!shouldLogVerbose()) {
+    return;
+  }
+  const channelConfigSummary = params.channelConfig
+    ? `allowed=${params.channelConfig.allowed} enabled=${params.channelConfig.enabled ?? "unset"} requireMention=${params.channelConfig.requireMention ?? "unset"} ignoreOtherMentions=${params.channelConfig.ignoreOtherMentions ?? "unset"} matchKey=${params.channelConfig.matchKey ?? "none"} matchSource=${params.channelConfig.matchSource ?? "none"} users=${params.channelConfig.users?.length ?? 0} roles=${params.channelConfig.roles?.length ?? 0} skills=${params.channelConfig.skills?.length ?? 0}`
+    : "none";
+  logDebug(
+    `[discord-preflight] channelConfig=${channelConfigSummary} channelMatchMeta=${params.channelMatchMeta} channelId=${params.channelId}`,
+  );
+}
+
+export function logDiscordPreflightInboundSummary(params: {
+  messageId: string;
+  guildId?: string;
+  channelId: string;
+  wasMentioned: boolean;
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  hasContent: boolean;
+}) {
+  if (!shouldLogVerbose()) {
+    return;
+  }
+  logVerbose(
+    `discord: inbound id=${params.messageId} guild=${params.guildId ?? "dm"} channel=${params.channelId} mention=${params.wasMentioned ? "yes" : "no"} type=${params.isDirectMessage ? "dm" : params.isGroupDm ? "group-dm" : "guild"} content=${params.hasContent ? "yes" : "no"}`,
+  );
+}

package/src/monitor/message-handler.preflight-pluralkit.ts

@@ -0,0 +1,27 @@
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { isPreflightAborted, loadPluralKitRuntime } from "./message-handler.preflight-runtime.js";
+import type { DiscordMessageEvent } from "./message-handler.preflight.types.js";
+
+export async function resolveDiscordPreflightPluralKitInfo(params: {
+  message: DiscordMessageEvent["message"];
+  webhookId?: string | null;
+  config?: NonNullable<
+    NonNullable<import("openclaw/plugin-sdk/config-types").OpenClawConfig["channels"]>["discord"]
+  >["pluralkit"];
+  abortSignal?: AbortSignal;
+}): Promise<Awaited<ReturnType<typeof import("../pluralkit.js").fetchPluralKitMessageInfo>>> {
+  if (!params.config?.enabled || params.webhookId) {
+    return null;
+  }
+  try {
+    const { fetchPluralKitMessageInfo } = await loadPluralKitRuntime();
+    const info = await fetchPluralKitMessageInfo({
+      messageId: params.message.id,
+      config: params.config,
+    });
+    return isPreflightAborted(params.abortSignal) ? null : info;
+  } catch (err) {
+    logVerbose(`discord: pluralkit lookup failed for ${params.message.id}: ${String(err)}`);
+    return null;
+  }
+}

package/src/monitor/message-handler.preflight-runtime.ts

@@ -0,0 +1,28 @@
+let pluralkitRuntimePromise: Promise<typeof import("../pluralkit.js")> | undefined;
+let preflightAudioRuntimePromise: Promise<typeof import("./preflight-audio.js")> | undefined;
+let systemEventsRuntimePromise: Promise<typeof import("./system-events.js")> | undefined;
+let discordThreadingRuntimePromise: Promise<typeof import("./threading.js")> | undefined;
+
+export async function loadPluralKitRuntime() {
+  pluralkitRuntimePromise ??= import("../pluralkit.js");
+  return await pluralkitRuntimePromise;
+}
+
+export async function loadPreflightAudioRuntime() {
+  preflightAudioRuntimePromise ??= import("./preflight-audio.js");
+  return await preflightAudioRuntimePromise;
+}
+
+export async function loadSystemEventsRuntime() {
+  systemEventsRuntimePromise ??= import("./system-events.js");
+  return await systemEventsRuntimePromise;
+}
+
+export async function loadDiscordThreadingRuntime() {
+  discordThreadingRuntimePromise ??= import("./threading.js");
+  return await discordThreadingRuntimePromise;
+}
+
+export function isPreflightAborted(abortSignal?: AbortSignal): boolean {
+  return Boolean(abortSignal?.aborted);
+}

package/src/monitor/message-handler.preflight-thread.ts

@@ -0,0 +1,49 @@
+import type { ChannelType } from "../internal/discord.js";
+import {
+  isPreflightAborted,
+  loadDiscordThreadingRuntime,
+} from "./message-handler.preflight-runtime.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.types.js";
+import type { DiscordChannelInfo } from "./message-utils.js";
+
+type DiscordPreflightThreadContext = {
+  earlyThreadChannel: DiscordMessagePreflightContext["threadChannel"];
+  earlyThreadParentId?: string;
+  earlyThreadParentName?: string;
+  earlyThreadParentType?: ChannelType;
+};
+
+export async function resolveDiscordPreflightThreadContext(params: {
+  client: DiscordMessagePreflightContext["client"];
+  isGuildMessage: boolean;
+  message: DiscordMessagePreflightContext["message"];
+  channelInfo: DiscordChannelInfo | null;
+  messageChannelId: string;
+  abortSignal?: AbortSignal;
+}): Promise<DiscordPreflightThreadContext | null> {
+  const { resolveDiscordThreadChannel, resolveDiscordThreadParentInfo } =
+    await loadDiscordThreadingRuntime();
+  const earlyThreadChannel = resolveDiscordThreadChannel({
+    isGuildMessage: params.isGuildMessage,
+    message: params.message,
+    channelInfo: params.channelInfo,
+    messageChannelId: params.messageChannelId,
+  });
+  if (!earlyThreadChannel) {
+    return { earlyThreadChannel: null };
+  }
+  const parentInfo = await resolveDiscordThreadParentInfo({
+    client: params.client,
+    threadChannel: earlyThreadChannel,
+    channelInfo: params.channelInfo,
+  });
+  if (isPreflightAborted(params.abortSignal)) {
+    return null;
+  }
+  return {
+    earlyThreadChannel,
+    earlyThreadParentId: parentInfo.id,
+    earlyThreadParentName: parentInfo.name,
+    earlyThreadParentType: parentInfo.type,
+  };
+}