@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/mentions.ts

@@ -0,0 +1,147 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+  normalizeOptionalStringifiedId,
+} from "openclaw/plugin-sdk/text-runtime";
+import { resolveDiscordDirectoryUserId } from "./directory-cache.js";
+
+type DiscordMentionAliasesConfig = Record<string, string>;
+
+const MARKDOWN_CODE_SEGMENT_PATTERN = /```[\s\S]*?```|`[^`\n]*`/g;
+const MENTION_CANDIDATE_PATTERN = /(^|[\s([{"'.,;:!?])@([a-z0-9_.-]{2,32}(?:#[0-9]{4})?)/gi;
+const DISCORD_RESERVED_MENTIONS = new Set(["everyone", "here"]);
+const DISCORD_DISCRIMINATOR_SUFFIX = /#\d{4}$/;
+
+function normalizeSnowflake(value: string | number | bigint): string | null {
+  const text = normalizeOptionalStringifiedId(value) ?? "";
+  if (!/^\d+$/.test(text)) {
+    return null;
+  }
+  return text;
+}
+
+export function formatMention(params: {
+  userId?: string | number | bigint | null;
+  roleId?: string | number | bigint | null;
+  channelId?: string | number | bigint | null;
+}): string {
+  const userId = params.userId == null ? null : normalizeSnowflake(params.userId);
+  const roleId = params.roleId == null ? null : normalizeSnowflake(params.roleId);
+  const channelId = params.channelId == null ? null : normalizeSnowflake(params.channelId);
+  const values = [
+    userId ? { kind: "user" as const, id: userId } : null,
+    roleId ? { kind: "role" as const, id: roleId } : null,
+    channelId ? { kind: "channel" as const, id: channelId } : null,
+  ].filter((entry): entry is { kind: "user" | "role" | "channel"; id: string } => Boolean(entry));
+  if (values.length !== 1) {
+    throw new Error("formatMention requires exactly one of userId, roleId, or channelId");
+  }
+  const target = values[0];
+  if (target.kind === "user") {
+    return `<@${target.id}>`;
+  }
+  if (target.kind === "role") {
+    return `<@&${target.id}>`;
+  }
+  return `<#${target.id}>`;
+}
+
+function normalizeHandleKey(raw: string): string | null {
+  let handle = normalizeOptionalString(raw) ?? "";
+  if (!handle) {
+    return null;
+  }
+  if (handle.startsWith("@")) {
+    handle = normalizeOptionalString(handle.slice(1)) ?? "";
+  }
+  if (!handle || /\s/.test(handle)) {
+    return null;
+  }
+  return normalizeLowercaseStringOrEmpty(handle);
+}
+
+function resolveConfiguredMentionAlias(
+  handle: string,
+  mentionAliases?: DiscordMentionAliasesConfig | null,
+): string | undefined {
+  const key = normalizeHandleKey(handle);
+  if (!key || !mentionAliases) {
+    return undefined;
+  }
+  const withoutDiscriminator = key.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+  for (const [rawAlias, rawUserId] of Object.entries(mentionAliases)) {
+    const alias = normalizeHandleKey(rawAlias);
+    if (!alias) {
+      continue;
+    }
+    const aliasWithoutDiscriminator = alias.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+    if (
+      alias === key ||
+      (withoutDiscriminator && withoutDiscriminator !== key && alias === withoutDiscriminator) ||
+      (aliasWithoutDiscriminator &&
+        aliasWithoutDiscriminator !== alias &&
+        aliasWithoutDiscriminator === key)
+    ) {
+      const userId = normalizeSnowflake(rawUserId);
+      if (userId) {
+        return userId;
+      }
+    }
+  }
+  return undefined;
+}
+
+function rewritePlainTextMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  return text.replace(MENTION_CANDIDATE_PATTERN, (match, prefix, rawHandle) => {
+    const handle = normalizeOptionalString(rawHandle) ?? "";
+    if (!handle) {
+      return match;
+    }
+    const lookup = normalizeLowercaseStringOrEmpty(handle);
+    if (DISCORD_RESERVED_MENTIONS.has(lookup)) {
+      return match;
+    }
+    const userId =
+      resolveConfiguredMentionAlias(handle, params.mentionAliases) ??
+      resolveDiscordDirectoryUserId({
+        accountId: params.accountId,
+        handle,
+      });
+    if (!userId) {
+      return match;
+    }
+    return `${String(prefix ?? "")}${formatMention({ userId })}`;
+  });
+}
+
+export function rewriteDiscordKnownMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  let rewritten = "";
+  let offset = 0;
+  MARKDOWN_CODE_SEGMENT_PATTERN.lastIndex = 0;
+  for (const match of text.matchAll(MARKDOWN_CODE_SEGMENT_PATTERN)) {
+    const matchIndex = match.index ?? 0;
+    rewritten += rewritePlainTextMentions(text.slice(offset, matchIndex), params);
+    rewritten += match[0];
+    offset = matchIndex + match[0].length;
+  }
+  rewritten += rewritePlainTextMentions(text.slice(offset), params);
+  return rewritten;
+}

package/src/monitor/access-groups.ts

@@ -0,0 +1,55 @@
+import {
+  resolveAccessGroupAllowFromMatches,
+  type AccessGroupMembershipResolver,
+} from "openclaw/plugin-sdk/command-auth";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import type { RequestClient } from "../internal/discord.js";
+import { canViewDiscordGuildChannel } from "../send.permissions.js";
+
+export function createDiscordAccessGroupMembershipResolver(params: {
+  token?: string;
+  rest?: RequestClient;
+}): AccessGroupMembershipResolver {
+  return async ({ cfg, name, group, accountId, senderId }) => {
+    if (group.type !== "discord.channelAudience") {
+      return false;
+    }
+    const membership = group.membership ?? "canViewChannel";
+    if (membership !== "canViewChannel") {
+      return false;
+    }
+    return await canViewDiscordGuildChannel(group.guildId, group.channelId, senderId, {
+      cfg,
+      accountId,
+      token: params.token,
+      rest: params.rest,
+    }).catch((err) => {
+      logVerbose(`discord: accessGroup:${name} lookup failed for user ${senderId}: ${String(err)}`);
+      return false;
+    });
+  };
+}
+
+export async function resolveDiscordDmAccessGroupEntries(params: {
+  cfg?: OpenClawConfig;
+  allowFrom: string[];
+  sender: { id: string };
+  accountId: string;
+  token?: string;
+  rest?: RequestClient;
+  isSenderAllowed?: (senderId: string, allowFrom: string[]) => boolean;
+}): Promise<string[]> {
+  return await resolveAccessGroupAllowFromMatches({
+    cfg: params.cfg,
+    allowFrom: params.allowFrom,
+    channel: "discord",
+    accountId: params.accountId,
+    senderId: params.sender.id,
+    isSenderAllowed: params.isSenderAllowed,
+    resolveMembership: createDiscordAccessGroupMembershipResolver({
+      token: params.token,
+      rest: params.rest,
+    }),
+  });
+}

package/src/monitor/ack-reactions.ts

@@ -0,0 +1,70 @@
+import {
+  createStatusReactionController,
+  logAckFailure,
+  type StatusReactionAdapter,
+} from "openclaw/plugin-sdk/channel-feedback";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { createDiscordRuntimeAccountContext } from "../client.js";
+import type { RequestClient } from "../internal/discord.js";
+import { reactMessageDiscord, removeReactionDiscord } from "../send.js";
+import type { DiscordReactionRuntimeContext } from "../send.types.js";
+
+export function createDiscordAckReactionContext(params: {
+  rest: RequestClient;
+  cfg: OpenClawConfig;
+  accountId: string;
+}): DiscordReactionRuntimeContext {
+  return {
+    rest: params.rest,
+    ...createDiscordRuntimeAccountContext({
+      cfg: params.cfg,
+      accountId: params.accountId,
+    }),
+  };
+}
+
+export function createDiscordAckReactionAdapter(params: {
+  channelId: string;
+  messageId: string;
+  reactionContext: DiscordReactionRuntimeContext;
+}): StatusReactionAdapter {
+  return {
+    setReaction: async (emoji) => {
+      await reactMessageDiscord(params.channelId, params.messageId, emoji, params.reactionContext);
+    },
+    removeReaction: async (emoji) => {
+      await removeReactionDiscord(
+        params.channelId,
+        params.messageId,
+        emoji,
+        params.reactionContext,
+      );
+    },
+  };
+}
+
+export function queueInitialDiscordAckReaction(params: {
+  enabled: boolean;
+  shouldSendAckReaction: boolean;
+  ackReaction: string | undefined;
+  statusReactions: ReturnType<typeof createStatusReactionController>;
+  reactionAdapter: StatusReactionAdapter;
+  target: string;
+}) {
+  if (params.enabled) {
+    void params.statusReactions.setQueued();
+    return;
+  }
+  if (!params.shouldSendAckReaction || !params.ackReaction) {
+    return;
+  }
+  void params.reactionAdapter.setReaction(params.ackReaction).catch((err) => {
+    logAckFailure({
+      log: logVerbose,
+      channel: "discord",
+      target: params.target,
+      error: err,
+    });
+  });
+}

package/src/monitor/acp-bind-here.integration.test.ts

@@ -0,0 +1,211 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ChannelType } from "../internal/discord.js";
+
+const loadConfigMock = vi.hoisted(() => vi.fn());
+
+vi.mock("openclaw/plugin-sdk/runtime-config-snapshot", async () => {
+  const actual = await vi.importActual<
+    typeof import("openclaw/plugin-sdk/runtime-config-snapshot")
+  >("openclaw/plugin-sdk/runtime-config-snapshot");
+  return {
+    ...actual,
+    getRuntimeConfig: () => loadConfigMock(),
+  };
+});
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  getSessionBindingService,
+  registerSessionBindingAdapter,
+  type SessionBindingBindInput,
+  type SessionBindingRecord,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import { __testing as sessionBindingTesting } from "openclaw/plugin-sdk/conversation-runtime";
+import { preflightDiscordMessage } from "./message-handler.preflight.js";
+import {
+  createDiscordMessage,
+  createDiscordPreflightArgs,
+  type DiscordClient,
+  type DiscordConfig,
+  type DiscordMessageEvent,
+} from "./message-handler.preflight.test-helpers.js";
+
+const baseCfg = {
+  session: {
+    mainKey: "main",
+    scope: "per-sender",
+  },
+  acp: {
+    enabled: true,
+    dispatch: {
+      enabled: true,
+    },
+    backend: "acpx",
+  },
+  channels: {
+    discord: {
+      threadBindings: {
+        enabled: true,
+      },
+    },
+  },
+} satisfies OpenClawConfig;
+
+function createDmClient(channelId: string): DiscordClient {
+  return {
+    fetchChannel: async (id: string) => {
+      if (id === channelId) {
+        return {
+          id: channelId,
+          type: ChannelType.DM,
+        };
+      }
+      return null;
+    },
+  } as unknown as DiscordClient;
+}
+
+function createInMemoryDiscordBindingAdapter() {
+  const bindings: SessionBindingRecord[] = [];
+
+  const bind = async (input: SessionBindingBindInput) => {
+    const normalizedConversation = {
+      ...input.conversation,
+      parentConversationId:
+        input.conversation.parentConversationId ??
+        (input.placement === "current" ? input.conversation.conversationId : undefined),
+    };
+    const record = {
+      bindingId: `discord:default:${normalizedConversation.conversationId}`,
+      targetSessionKey: input.targetSessionKey,
+      targetKind: input.targetKind,
+      conversation: normalizedConversation,
+      status: "active",
+      boundAt: 1,
+      ...(input.metadata ? { metadata: input.metadata } : {}),
+    } satisfies SessionBindingRecord;
+    const existingIndex = bindings.findIndex((entry) => entry.bindingId === record.bindingId);
+    if (existingIndex >= 0) {
+      bindings.splice(existingIndex, 1, record);
+    } else {
+      bindings.push(record);
+    }
+    return record;
+  };
+
+  registerSessionBindingAdapter({
+    channel: "discord",
+    accountId: "default",
+    capabilities: {
+      placements: ["current", "child"],
+      bindSupported: true,
+      unbindSupported: true,
+    },
+    bind,
+    listBySession: (targetSessionKey) =>
+      bindings.filter((entry) => entry.targetSessionKey === targetSessionKey),
+    resolveByConversation: (ref) =>
+      bindings.find(
+        (entry) =>
+          entry.conversation.channel === ref.channel &&
+          entry.conversation.accountId === ref.accountId &&
+          entry.conversation.conversationId === ref.conversationId,
+      ) ?? null,
+    unbind: async ({ bindingId, targetSessionKey }) => {
+      const removed = bindings.filter(
+        (entry) =>
+          (bindingId && entry.bindingId === bindingId) ||
+          (targetSessionKey && entry.targetSessionKey === targetSessionKey),
+      );
+      for (const entry of removed) {
+        const index = bindings.findIndex((candidate) => candidate.bindingId === entry.bindingId);
+        if (index >= 0) {
+          bindings.splice(index, 1);
+        }
+      }
+      return removed;
+    },
+  });
+
+  return { bindings };
+}
+
+describe("Discord ACP bind here end-to-end flow", () => {
+  beforeEach(() => {
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    loadConfigMock.mockReset().mockReturnValue(baseCfg);
+  });
+
+  it("routes the next Discord DM turn to an existing ACP session binding", async () => {
+    const adapter = createInMemoryDiscordBindingAdapter();
+    const binding = await getSessionBindingService().bind({
+      targetSessionKey: "agent:codex:acp:test-session",
+      targetKind: "session",
+      conversation: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: "user:user-1",
+        parentConversationId: "user:user-1",
+      },
+      placement: "current",
+      metadata: {
+        boundBy: "user-1",
+        agentId: "codex",
+        label: "codex",
+      },
+    });
+
+    expect(adapter.bindings).toHaveLength(1);
+    expect(binding).toMatchObject({
+      targetSessionKey: "agent:codex:acp:test-session",
+      conversation: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: "user:user-1",
+        parentConversationId: "user:user-1",
+      },
+    });
+    expect(
+      getSessionBindingService().resolveByConversation({
+        channel: "discord",
+        accountId: "default",
+        conversationId: "user:user-1",
+      }),
+    )?.toMatchObject({
+      targetSessionKey: binding.targetSessionKey,
+    });
+
+    const message = createDiscordMessage({
+      id: "m-followup-1",
+      channelId: "dm-1",
+      content: "follow up after bind",
+      author: {
+        id: "user-1",
+        bot: false,
+        username: "alice",
+      },
+    });
+
+    const preflight = await preflightDiscordMessage({
+      ...createDiscordPreflightArgs({
+        cfg: baseCfg,
+        discordConfig: {
+          dmPolicy: "open",
+        } as DiscordConfig,
+        data: {
+          channel_id: "dm-1",
+          author: message.author,
+          message,
+        } as DiscordMessageEvent,
+        client: createDmClient("dm-1"),
+        botUserId: "bot-1",
+      }),
+      allowFrom: ["*"],
+    });
+
+    expect(preflight).not.toBeNull();
+    expect(preflight?.boundSessionKey).toBe(binding.targetSessionKey);
+    expect(preflight?.route.sessionKey).toBe(binding.targetSessionKey);
+    expect(preflight?.route.agentId).toBe("codex");
+  });
+});

package/src/monitor/agent-components-auth.ts

@@ -0,0 +1,7 @@
+export { resolveInteractionContextWithDmAuth } from "./agent-components-dm-auth.js";
+export {
+  ensureAgentComponentInteractionAllowed,
+  ensureComponentUserAllowed,
+  resolveAuthorizedComponentInteraction,
+  resolveComponentCommandAuthorized,
+} from "./agent-components-guild-auth.js";

package/src/monitor/agent-components-context.ts

@@ -0,0 +1,144 @@
+import { ChannelType } from "discord-api-types/v10";
+import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { logError } from "openclaw/plugin-sdk/text-runtime";
+import {
+  type AgentComponentContext,
+  type AgentComponentInteraction,
+  type AgentComponentMessageInteraction,
+  type ComponentInteractionContext,
+  type DiscordChannelContext,
+} from "./agent-components.types.js";
+import { normalizeDiscordSlug } from "./allow-list.js";
+import { resolveDiscordChannelInfoSafe } from "./channel-access.js";
+
+function formatUsername(user: { username: string; discriminator?: string | null }): string {
+  if (user.discriminator && user.discriminator !== "0") {
+    return `${user.username}#${user.discriminator}`;
+  }
+  return user.username;
+}
+
+function isThreadChannelType(channelType: number | undefined): boolean {
+  return (
+    channelType === ChannelType.PublicThread ||
+    channelType === ChannelType.PrivateThread ||
+    channelType === ChannelType.AnnouncementThread
+  );
+}
+
+export function resolveAgentComponentRoute(params: {
+  ctx: AgentComponentContext;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  userId: string;
+  channelId: string;
+  parentId: string | undefined;
+}) {
+  return resolveAgentRoute({
+    cfg: params.ctx.cfg,
+    channel: "discord",
+    accountId: params.ctx.accountId,
+    guildId: params.rawGuildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
+      id: params.isDirectMessage ? params.userId : params.channelId,
+    },
+    parentPeer: params.parentId ? { kind: "channel", id: params.parentId } : undefined,
+  });
+}
+
+export async function ackComponentInteraction(params: {
+  interaction: AgentComponentInteraction;
+  replyOpts: { ephemeral?: boolean };
+  label: string;
+}) {
+  try {
+    await params.interaction.reply({
+      content: "✓",
+      ...params.replyOpts,
+    });
+  } catch (err) {
+    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
+  }
+}
+
+export function resolveDiscordChannelContext(
+  interaction: AgentComponentInteraction,
+): DiscordChannelContext {
+  const channel = interaction.channel;
+  const channelInfo = resolveDiscordChannelInfoSafe(channel);
+  const channelName = channelInfo.name;
+  const channelSlug = channelName ? normalizeDiscordSlug(channelName) : "";
+  const channelType = channelInfo.type;
+  const isThread = isThreadChannelType(channelType);
+
+  let parentId: string | undefined;
+  let parentName: string | undefined;
+  let parentSlug = "";
+  if (isThread) {
+    parentId = channelInfo.parentId;
+    parentName = channelInfo.parentName;
+    if (parentName) {
+      parentSlug = normalizeDiscordSlug(parentName);
+    }
+  }
+
+  return { channelName, channelSlug, channelType, isThread, parentId, parentName, parentSlug };
+}
+
+export async function resolveComponentInteractionContext(params: {
+  interaction: AgentComponentInteraction;
+  label: string;
+  defer?: boolean;
+}): Promise<ComponentInteractionContext | null> {
+  const { interaction, label } = params;
+  const channelId = interaction.rawData.channel_id;
+  if (!channelId) {
+    logError(`${label}: missing channel_id in interaction`);
+    return null;
+  }
+
+  const user = interaction.user;
+  if (!user) {
+    logError(`${label}: missing user in interaction`);
+    return null;
+  }
+
+  const shouldDefer = params.defer !== false && "defer" in interaction;
+  let didDefer = false;
+  if (shouldDefer) {
+    try {
+      await (interaction as AgentComponentMessageInteraction).defer({ ephemeral: true });
+      didDefer = true;
+    } catch (err) {
+      logError(`${label}: failed to defer interaction: ${String(err)}`);
+    }
+  }
+  const replyOpts = didDefer ? {} : { ephemeral: true };
+
+  const username = formatUsername(user);
+  const userId = user.id;
+  const rawGuildId = interaction.rawData.guild_id;
+  const channelType = resolveDiscordChannelContext(interaction).channelType;
+  const isGroupDm = channelType === ChannelType.GroupDM;
+  const isDirectMessage =
+    channelType === ChannelType.DM || (!rawGuildId && !isGroupDm && channelType == null);
+  const memberRoleIds = Array.isArray(interaction.rawData.member?.roles)
+    ? interaction.rawData.member.roles.map((roleId: string) => roleId)
+    : [];
+
+  return {
+    channelId,
+    user,
+    username,
+    userId,
+    replyOpts,
+    rawGuildId,
+    isDirectMessage,
+    isGroupDm,
+    memberRoleIds,
+  };
+}