@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/monitor/listeners.test.ts

@@ -0,0 +1,200 @@
+import { beforeAll, describe, expect, it, vi } from "vitest";
+
+let DiscordMessageListener: typeof import("./listeners.js").DiscordMessageListener;
+let DiscordInteractionListener: typeof import("./listeners.js").DiscordInteractionListener;
+
+beforeAll(async () => {
+  ({ DiscordMessageListener, DiscordInteractionListener } = await import("./listeners.js"));
+});
+
+function createLogger() {
+  return {
+    error: vi.fn(),
+    warn: vi.fn(),
+  };
+}
+
+function fakeEvent(channelId: string) {
+  return { channel_id: channelId } as never;
+}
+
+function createDeferred() {
+  let resolve: (() => void) | undefined;
+  const promise = new Promise<void>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+async function flushAsyncWork() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("DiscordMessageListener", () => {
+  it("returns immediately without awaiting handler completion", async () => {
+    let resolveHandler: (() => void) | undefined;
+    const handlerDone = new Promise<void>((resolve) => {
+      resolveHandler = resolve;
+    });
+    const handler = vi.fn(async () => {
+      await handlerDone;
+    });
+    const logger = createLogger();
+    const listener = new DiscordMessageListener(handler as never, logger as never);
+
+    await expect(listener.handle(fakeEvent("ch-1"), {} as never)).resolves.toBeUndefined();
+    // Handler was dispatched but may not have been called yet (fire-and-forget).
+    // Wait for the microtask to flush so the handler starts.
+    await flushAsyncWork();
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(logger.error).not.toHaveBeenCalled();
+
+    resolveHandler?.();
+    await handlerDone;
+  });
+
+  it("runs handlers for the same channel concurrently (no per-channel serialization)", async () => {
+    const order: string[] = [];
+    const deferredA = createDeferred();
+    const deferredB = createDeferred();
+    let callCount = 0;
+    const handler = vi.fn(async () => {
+      callCount += 1;
+      const id = callCount;
+      order.push(`start:${id}`);
+      if (id === 1) {
+        await deferredA.promise;
+      } else {
+        await deferredB.promise;
+      }
+      order.push(`end:${id}`);
+    });
+    const listener = new DiscordMessageListener(handler as never, createLogger() as never);
+
+    // Both messages target the same channel — previously serialized, now concurrent.
+    await listener.handle(fakeEvent("ch-1"), {} as never);
+    await listener.handle(fakeEvent("ch-1"), {} as never);
+
+    await flushAsyncWork();
+    expect(handler).toHaveBeenCalledTimes(2);
+    // Both handlers started without waiting for the first to finish.
+    expect(order).toContain("start:1");
+    expect(order).toContain("start:2");
+
+    deferredB.resolve?.();
+    await flushAsyncWork();
+    expect(order).toContain("end:2");
+    // First handler is still running — no serialization.
+    expect(order).not.toContain("end:1");
+
+    deferredA.resolve?.();
+    await flushAsyncWork();
+    expect(order).toContain("end:1");
+  });
+
+  it("runs handlers for different channels in parallel", async () => {
+    const deferredA = createDeferred();
+    const deferredB = createDeferred();
+    const order: string[] = [];
+    const handler = vi.fn(async (data: { channel_id: string }) => {
+      order.push(`start:${data.channel_id}`);
+      if (data.channel_id === "ch-a") {
+        await deferredA.promise;
+      } else {
+        await deferredB.promise;
+      }
+      order.push(`end:${data.channel_id}`);
+    });
+    const listener = new DiscordMessageListener(handler as never, createLogger() as never);
+
+    await listener.handle(fakeEvent("ch-a"), {} as never);
+    await listener.handle(fakeEvent("ch-b"), {} as never);
+
+    await flushAsyncWork();
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(order).toContain("start:ch-a");
+    expect(order).toContain("start:ch-b");
+
+    deferredB.resolve?.();
+    await flushAsyncWork();
+    expect(order).toContain("end:ch-b");
+    expect(order).not.toContain("end:ch-a");
+
+    deferredA.resolve?.();
+    await flushAsyncWork();
+    expect(order).toContain("end:ch-a");
+  });
+
+  it("logs async handler failures", async () => {
+    const handler = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const logger = createLogger();
+    const listener = new DiscordMessageListener(handler as never, logger as never);
+
+    await expect(listener.handle(fakeEvent("ch-1"), {} as never)).resolves.toBeUndefined();
+    await flushAsyncWork();
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("discord handler failed: Error: boom"),
+    );
+  });
+
+  it("calls onEvent callback for each message", async () => {
+    const handler = vi.fn(async () => {});
+    const onEvent = vi.fn();
+    const listener = new DiscordMessageListener(handler as never, undefined, onEvent);
+
+    await listener.handle(fakeEvent("ch-1"), {} as never);
+    await listener.handle(fakeEvent("ch-2"), {} as never);
+
+    expect(onEvent).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("DiscordInteractionListener", () => {
+  it("returns immediately without awaiting Discord interaction handling", async () => {
+    const handlerDone = createDeferred();
+    const handleInteraction = vi.fn(async () => {
+      await handlerDone.promise;
+    });
+    const logger = createLogger();
+    const listener = new DiscordInteractionListener(logger as never);
+
+    await expect(
+      listener.handle({ id: "interaction-1" } as never, { handleInteraction } as never),
+    ).resolves.toBeUndefined();
+    await flushAsyncWork();
+    expect(handleInteraction).toHaveBeenCalledTimes(1);
+    expect(logger.error).not.toHaveBeenCalled();
+
+    handlerDone.resolve?.();
+    await flushAsyncWork();
+  });
+
+  it("logs async interaction failures", async () => {
+    const handleInteraction = vi.fn(async () => {
+      throw new Error("interaction boom");
+    });
+    const logger = createLogger();
+    const listener = new DiscordInteractionListener(logger as never);
+
+    await listener.handle({ id: "interaction-1" } as never, { handleInteraction } as never);
+    await flushAsyncWork();
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("discord interaction handler failed: Error: interaction boom"),
+    );
+  });
+
+  it("calls onEvent callback for each interaction", async () => {
+    const handleInteraction = vi.fn(async () => {});
+    const onEvent = vi.fn();
+    const listener = new DiscordInteractionListener(undefined, onEvent);
+
+    await listener.handle({ id: "interaction-1" } as never, { handleInteraction } as never);
+    await listener.handle({ id: "interaction-2" } as never, { handleInteraction } as never);
+
+    expect(onEvent).toHaveBeenCalledTimes(2);
+  });
+});

package/src/monitor/listeners.ts

@@ -0,0 +1,150 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { danger } from "openclaw/plugin-sdk/runtime-env";
+import {
+  type Client,
+  InteractionCreateListener,
+  MessageCreateListener,
+  PresenceUpdateListener,
+  ThreadUpdateListener,
+} from "../internal/discord.js";
+import { discordEventQueueLog, runDiscordListenerWithSlowLog } from "./listeners.queue.js";
+export { DiscordReactionListener, DiscordReactionRemoveListener } from "./listeners.reactions.js";
+import { setPresence } from "./presence-cache.js";
+import { isThreadArchived } from "./thread-bindings.discord-api.js";
+import { closeDiscordThreadSessions } from "./thread-session-close.js";
+
+type Logger = ReturnType<typeof import("openclaw/plugin-sdk/runtime-env").createSubsystemLogger>;
+
+export type DiscordMessageEvent = Parameters<MessageCreateListener["handle"]>[0];
+export type DiscordInteractionEvent = Parameters<InteractionCreateListener["handle"]>[0];
+
+export type DiscordMessageHandler = (
+  data: DiscordMessageEvent,
+  client: Client,
+  options?: { abortSignal?: AbortSignal },
+) => Promise<void>;
+
+export function registerDiscordListener(listeners: Array<object>, listener: object) {
+  if (listeners.some((existing) => existing.constructor === listener.constructor)) {
+    return false;
+  }
+  listeners.push(listener);
+  return true;
+}
+
+export class DiscordMessageListener extends MessageCreateListener {
+  constructor(
+    private handler: DiscordMessageHandler,
+    private logger?: Logger,
+    private onEvent?: () => void,
+  ) {
+    super();
+  }
+
+  async handle(data: DiscordMessageEvent, client: Client) {
+    this.onEvent?.();
+    // Fire-and-forget: hand off to the handler without blocking gateway dispatch.
+    // Per-session ordering is owned by the message run queue.
+    void Promise.resolve()
+      .then(() => this.handler(data, client))
+      .catch((err) => {
+        const logger = this.logger ?? discordEventQueueLog;
+        logger.error(danger(`discord handler failed: ${String(err)}`));
+      });
+  }
+}
+
+export class DiscordInteractionListener extends InteractionCreateListener {
+  constructor(
+    private logger?: Logger,
+    private onEvent?: () => void,
+  ) {
+    super();
+  }
+
+  async handle(data: DiscordInteractionEvent, client: Client) {
+    this.onEvent?.();
+    // Hand off immediately so slash/component handling can wait on session locks
+    // or compaction without blocking later gateway events.
+    void Promise.resolve()
+      .then(() => client.handleInteraction(data as Parameters<Client["handleInteraction"]>[0], {}))
+      .catch((err) => {
+        const logger = this.logger ?? discordEventQueueLog;
+        logger.error(danger(`discord interaction handler failed: ${String(err)}`));
+      });
+  }
+}
+
+type PresenceUpdateEvent = Parameters<PresenceUpdateListener["handle"]>[0];
+
+export class DiscordPresenceListener extends PresenceUpdateListener {
+  private logger?: Logger;
+  private accountId?: string;
+
+  constructor(params: { logger?: Logger; accountId?: string }) {
+    super();
+    this.logger = params.logger;
+    this.accountId = params.accountId;
+  }
+
+  async handle(data: PresenceUpdateEvent) {
+    try {
+      const userId =
+        "user" in data && data.user && typeof data.user === "object" && "id" in data.user
+          ? data.user.id
+          : undefined;
+      if (!userId) {
+        return;
+      }
+      setPresence(this.accountId, userId, data);
+    } catch (err) {
+      const logger = this.logger ?? discordEventQueueLog;
+      logger.error(danger(`discord presence handler failed: ${String(err)}`));
+    }
+  }
+}
+
+type ThreadUpdateEvent = Parameters<ThreadUpdateListener["handle"]>[0];
+
+export class DiscordThreadUpdateListener extends ThreadUpdateListener {
+  constructor(
+    private cfg: OpenClawConfig,
+    private accountId: string,
+    private logger?: Logger,
+  ) {
+    super();
+  }
+
+  async handle(data: ThreadUpdateEvent) {
+    await runDiscordListenerWithSlowLog({
+      logger: this.logger,
+      listener: this.constructor.name,
+      event: this.type,
+      run: async () => {
+        // Discord only fires THREAD_UPDATE when a field actually changes, so
+        // `thread_metadata.archived === true` in this payload means the thread
+        // just transitioned to the archived state.
+        if (!isThreadArchived(data)) {
+          return;
+        }
+        const threadId = "id" in data && typeof data.id === "string" ? data.id : undefined;
+        if (!threadId) {
+          return;
+        }
+        const logger = this.logger ?? discordEventQueueLog;
+        const count = await closeDiscordThreadSessions({
+          cfg: this.cfg,
+          accountId: this.accountId,
+          threadId,
+        });
+        if (count > 0) {
+          logger.info("Discord thread archived — reset sessions", { threadId, count });
+        }
+      },
+      onError: (err) => {
+        const logger = this.logger ?? discordEventQueueLog;
+        logger.error(danger(`discord thread-update handler failed: ${String(err)}`));
+      },
+    });
+  }
+}

package/src/monitor/message-channel-info.ts

@@ -0,0 +1,96 @@
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { normalizeOptionalStringifiedId } from "openclaw/plugin-sdk/text-runtime";
+import type { ChannelType, Message } from "../internal/discord.js";
+import { resolveDiscordChannelInfoSafe } from "./channel-access.js";
+
+export type DiscordChannelInfo = {
+  type: ChannelType;
+  name?: string;
+  topic?: string;
+  parentId?: string;
+  ownerId?: string;
+};
+export type DiscordChannelInfoClient = {
+  fetchChannel(channelId: string): Promise<unknown>;
+};
+
+type DiscordMessageWithChannelId = Message & {
+  channel_id?: unknown;
+  rawData?: { channel_id?: unknown };
+};
+
+const DISCORD_CHANNEL_INFO_CACHE_TTL_MS = 5 * 60 * 1000;
+const DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS = 30 * 1000;
+const DISCORD_CHANNEL_INFO_CACHE = new Map<
+  string,
+  { value: DiscordChannelInfo | null; expiresAt: number }
+>();
+
+export function __resetDiscordChannelInfoCacheForTest() {
+  DISCORD_CHANNEL_INFO_CACHE.clear();
+}
+
+function normalizeDiscordChannelId(value: unknown): string {
+  return normalizeOptionalStringifiedId(value) ?? "";
+}
+
+export function resolveDiscordMessageChannelId(params: {
+  message: Message;
+  eventChannelId?: string | number | null;
+}): string {
+  const message = params.message as DiscordMessageWithChannelId;
+  return (
+    normalizeDiscordChannelId(message.channelId) ||
+    normalizeDiscordChannelId(message.channel_id) ||
+    normalizeDiscordChannelId(message.rawData?.channel_id) ||
+    normalizeDiscordChannelId(params.eventChannelId)
+  );
+}
+
+export async function resolveDiscordChannelInfo(
+  client: DiscordChannelInfoClient,
+  channelId: string,
+): Promise<DiscordChannelInfo | null> {
+  const cached = DISCORD_CHANNEL_INFO_CACHE.get(channelId);
+  if (cached) {
+    if (cached.expiresAt > Date.now()) {
+      return cached.value;
+    }
+    DISCORD_CHANNEL_INFO_CACHE.delete(channelId);
+  }
+  try {
+    const channel = await client.fetchChannel(channelId);
+    if (!channel) {
+      DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+        value: null,
+        expiresAt: Date.now() + DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS,
+      });
+      return null;
+    }
+    const channelInfo = resolveDiscordChannelInfoSafe(channel);
+    const rawChannel = channel as { type?: ChannelType };
+    const type = (channelInfo.type as ChannelType | undefined) ?? rawChannel.type;
+    if (type === undefined) {
+      return null;
+    }
+    const payload: DiscordChannelInfo = {
+      type,
+      name: channelInfo.name,
+      topic: channelInfo.topic,
+      parentId: channelInfo.parentId,
+      ownerId: channelInfo.ownerId,
+    };
+    DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+      value: payload,
+      expiresAt: Date.now() + DISCORD_CHANNEL_INFO_CACHE_TTL_MS,
+    });
+    return payload;
+  } catch (err) {
+    logVerbose(`discord: failed to fetch channel ${channelId}: ${String(err)}`);
+    DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+      value: null,
+      expiresAt: Date.now() + DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS,
+    });
+    return null;
+  }
+}

package/src/monitor/message-forwarded.ts

@@ -0,0 +1,107 @@
+import type { APIAttachment, APIStickerItem } from "discord-api-types/v10";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import type { Message } from "../internal/discord.js";
+
+export type DiscordSnapshotAuthor = {
+  id?: string | null;
+  username?: string | null;
+  discriminator?: string | null;
+  global_name?: string | null;
+  name?: string | null;
+};
+
+export type DiscordSnapshotMessage = {
+  content?: string | null;
+  components?: unknown;
+  embeds?: Array<{ description?: string | null; title?: string | null }> | null;
+  attachments?: APIAttachment[] | null;
+  stickers?: APIStickerItem[] | null;
+  sticker_items?: APIStickerItem[] | null;
+  author?: DiscordSnapshotAuthor | null;
+};
+
+export type DiscordMessageSnapshot = {
+  message?: DiscordSnapshotMessage | null;
+};
+
+const FORWARD_MESSAGE_REFERENCE_TYPE = 1;
+
+export function normalizeDiscordStickerItems(value: unknown): APIStickerItem[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (entry): entry is APIStickerItem =>
+      Boolean(entry) &&
+      typeof entry === "object" &&
+      typeof (entry as { id?: unknown }).id === "string" &&
+      typeof (entry as { name?: unknown }).name === "string",
+  );
+}
+
+export function resolveDiscordMessageStickers(message: Message): APIStickerItem[] {
+  const stickers = (message as { stickers?: unknown }).stickers;
+  const normalized = normalizeDiscordStickerItems(stickers);
+  if (normalized.length > 0) {
+    return normalized;
+  }
+  const rawData = (message as { rawData?: { sticker_items?: unknown; stickers?: unknown } })
+    .rawData;
+  return normalizeDiscordStickerItems(rawData?.sticker_items ?? rawData?.stickers);
+}
+
+export function resolveDiscordSnapshotStickers(snapshot: DiscordSnapshotMessage): APIStickerItem[] {
+  return normalizeDiscordStickerItems(snapshot.stickers ?? snapshot.sticker_items);
+}
+
+export function hasDiscordMessageStickers(message: Message): boolean {
+  return resolveDiscordMessageStickers(message).length > 0;
+}
+
+export function resolveDiscordMessageSnapshots(message: Message): DiscordMessageSnapshot[] {
+  const rawData = (message as { rawData?: { message_snapshots?: unknown } }).rawData;
+  return normalizeDiscordMessageSnapshots(
+    rawData?.message_snapshots ??
+      (message as { message_snapshots?: unknown }).message_snapshots ??
+      (message as { messageSnapshots?: unknown }).messageSnapshots,
+  );
+}
+
+export function normalizeDiscordMessageSnapshots(snapshots: unknown): DiscordMessageSnapshot[] {
+  if (!Array.isArray(snapshots)) {
+    return [];
+  }
+  return snapshots.filter(
+    (entry): entry is DiscordMessageSnapshot => Boolean(entry) && typeof entry === "object",
+  );
+}
+
+export function resolveDiscordReferencedForwardMessage(message: Message): Message | null {
+  const referenceType = message.messageReference?.type;
+  return Number(referenceType) === FORWARD_MESSAGE_REFERENCE_TYPE
+    ? message.referencedMessage
+    : null;
+}
+
+export function formatDiscordSnapshotAuthor(
+  author: DiscordSnapshotAuthor | null | undefined,
+): string | undefined {
+  if (!author) {
+    return undefined;
+  }
+  const globalName = normalizeOptionalString(author.global_name) ?? undefined;
+  const username = normalizeOptionalString(author.username) ?? undefined;
+  const name = normalizeOptionalString(author.name) ?? undefined;
+  const discriminator = normalizeOptionalString(author.discriminator) ?? undefined;
+  const base = globalName || username || name;
+  if (username && discriminator && discriminator !== "0") {
+    return `@${username}#${discriminator}`;
+  }
+  if (base) {
+    return `@${base}`;
+  }
+  if (author.id) {
+    return `@${author.id}`;
+  }
+  return undefined;
+}

package/src/monitor/message-handler.batch-gate.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { applyImplicitReplyBatchGate } from "./message-handler.batch-gate.js";
+
+describe("applyImplicitReplyBatchGate", () => {
+  it("leaves context unchanged when replyToMode is not batched", () => {
+    const ctx: Record<string, unknown> = {};
+    applyImplicitReplyBatchGate(ctx, "first", true);
+    expect(ctx.ReplyThreading).toBeUndefined();
+  });
+
+  it("marks single-message turns as not eligible for implicit reply refs", () => {
+    const ctx: Record<string, unknown> = {};
+    applyImplicitReplyBatchGate(ctx, "batched", false);
+    expect(ctx.ReplyThreading).toEqual({ implicitCurrentMessage: "deny" });
+  });
+
+  it("marks batched turns as eligible for implicit reply refs", () => {
+    const ctx: Record<string, unknown> = {};
+    applyImplicitReplyBatchGate(ctx, "batched", true);
+    expect(ctx.ReplyThreading).toEqual({ implicitCurrentMessage: "allow" });
+  });
+});

package/src/monitor/message-handler.batch-gate.ts

@@ -0,0 +1,19 @@
+import type { ReplyToMode } from "openclaw/plugin-sdk/config-types";
+import type { ReplyThreadingPolicy } from "openclaw/plugin-sdk/reply-reference";
+import { resolveBatchedReplyThreadingPolicy } from "openclaw/plugin-sdk/reply-reference";
+
+type ReplyThreadingContext = {
+  ReplyThreading?: ReplyThreadingPolicy;
+};
+
+export function applyImplicitReplyBatchGate(
+  ctx: object,
+  replyToMode: ReplyToMode,
+  isBatched: boolean,
+) {
+  const replyThreading = resolveBatchedReplyThreadingPolicy(replyToMode, isBatched);
+  if (!replyThreading) {
+    return;
+  }
+  (ctx as ReplyThreadingContext).ReplyThreading = replyThreading;
+}

package/src/monitor/message-handler.bot-self-filter.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  createDiscordMessageHandler,
+  preflightDiscordMessageMock,
+  processDiscordMessageMock,
+} from "./message-handler.module-test-helpers.js";
+import {
+  DEFAULT_DISCORD_BOT_USER_ID,
+  createDiscordHandlerParams,
+  createDiscordPreflightContext,
+} from "./message-handler.test-helpers.js";
+
+async function flushAsyncWork() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function createMessageData(authorId: string, channelId = "ch-1") {
+  return {
+    author: { id: authorId, bot: authorId === DEFAULT_DISCORD_BOT_USER_ID },
+    message: {
+      id: "msg-1",
+      author: { id: authorId, bot: authorId === DEFAULT_DISCORD_BOT_USER_ID },
+      content: "hello",
+      channel_id: channelId,
+    },
+    channel_id: channelId,
+  };
+}
+
+function createPreflightContext(channelId = "ch-1") {
+  return createDiscordPreflightContext(channelId);
+}
+
+describe("createDiscordMessageHandler bot-self filter", () => {
+  it("skips bot-own messages before the debounce queue", async () => {
+    preflightDiscordMessageMock.mockReset();
+    processDiscordMessageMock.mockReset();
+
+    const handler = createDiscordMessageHandler(createDiscordHandlerParams());
+
+    await expect(
+      handler(createMessageData(DEFAULT_DISCORD_BOT_USER_ID) as never, {} as never),
+    ).resolves.toBeUndefined();
+
+    expect(preflightDiscordMessageMock).not.toHaveBeenCalled();
+    expect(processDiscordMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("enqueues non-bot messages for processing", async () => {
+    preflightDiscordMessageMock.mockReset();
+    processDiscordMessageMock.mockReset();
+    preflightDiscordMessageMock.mockImplementation(
+      async (params: { data: { channel_id: string } }) =>
+        createPreflightContext(params.data.channel_id),
+    );
+
+    const handler = createDiscordMessageHandler(createDiscordHandlerParams());
+
+    await expect(
+      handler(createMessageData("user-456") as never, {} as never),
+    ).resolves.toBeUndefined();
+
+    await flushAsyncWork();
+    expect(preflightDiscordMessageMock).toHaveBeenCalledTimes(1);
+    expect(processDiscordMessageMock).toHaveBeenCalledTimes(1);
+  });
+});