@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/targets.test.ts

@@ -0,0 +1,367 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetDiscordDirectoryCacheForTest,
+  resolveDiscordDirectoryUserId,
+} from "./directory-cache.js";
+import * as directoryLive from "./directory-live.js";
+import {
+  resolveDiscordGroupRequireMention,
+  resolveDiscordGroupToolPolicy,
+} from "./group-policy.js";
+import { normalizeDiscordMessagingTarget } from "./normalize.js";
+import { parseDiscordTarget, resolveDiscordChannelId, resolveDiscordTarget } from "./targets.js";
+
+describe("parseDiscordTarget", () => {
+  it("parses user mention and prefixes", () => {
+    const cases = [
+      { input: "<@123>", id: "123", normalized: "user:123" },
+      { input: "<@!456>", id: "456", normalized: "user:456" },
+      { input: "user:789", id: "789", normalized: "user:789" },
+      { input: "discord:987", id: "987", normalized: "user:987" },
+    ] as const;
+    for (const testCase of cases) {
+      expect(parseDiscordTarget(testCase.input), testCase.input).toMatchObject({
+        kind: "user",
+        id: testCase.id,
+        normalized: testCase.normalized,
+      });
+    }
+  });
+
+  it("parses channel targets", () => {
+    const cases = [
+      { input: "channel:555", id: "555", normalized: "channel:555" },
+      { input: "general", id: "general", normalized: "channel:general" },
+    ] as const;
+    for (const testCase of cases) {
+      expect(parseDiscordTarget(testCase.input), testCase.input).toMatchObject({
+        kind: "channel",
+        id: testCase.id,
+        normalized: testCase.normalized,
+      });
+    }
+  });
+
+  it("accepts numeric ids when a default kind is provided", () => {
+    expect(parseDiscordTarget("123", { defaultKind: "channel" })).toMatchObject({
+      kind: "channel",
+      id: "123",
+      normalized: "channel:123",
+    });
+  });
+
+  it("rejects invalid parse targets", () => {
+    const cases = [
+      { input: "123", expectedMessage: /Ambiguous Discord recipient/ },
+      { input: "@bob", expectedMessage: /Discord DMs require a user id/ },
+    ] as const;
+    for (const testCase of cases) {
+      expect(() => parseDiscordTarget(testCase.input), testCase.input).toThrow(
+        testCase.expectedMessage,
+      );
+    }
+  });
+
+  it("guides ambiguous numeric recipients with all supported explicit formats", () => {
+    expect(() => parseDiscordTarget("123456789")).toThrow(
+      'Ambiguous Discord recipient "123456789". For DMs use "user:123456789" or "<@123456789>"; for channels use "channel:123456789".',
+    );
+  });
+});
+
+describe("resolveDiscordChannelId", () => {
+  it("strips channel: prefix and accepts raw ids", () => {
+    expect(resolveDiscordChannelId("channel:123")).toBe("123");
+    expect(resolveDiscordChannelId("123")).toBe("123");
+  });
+
+  it("rejects user targets", () => {
+    expect(() => resolveDiscordChannelId("user:123")).toThrow(/channel id is required/i);
+  });
+});
+
+describe("resolveDiscordTarget", () => {
+  const cfg = { channels: { discord: {} } } as OpenClawConfig;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    __resetDiscordDirectoryCacheForTest();
+  });
+
+  it("returns a resolved user for usernames", async () => {
+    vi.spyOn(directoryLive, "listDiscordDirectoryPeersLive").mockResolvedValueOnce([
+      { kind: "user", id: "user:999", name: "Jane" } as const,
+    ]);
+
+    await expect(
+      resolveDiscordTarget("jane", { cfg, accountId: "default" }),
+    ).resolves.toMatchObject({ kind: "user", id: "999", normalized: "user:999" });
+  });
+
+  it("falls back to parsing when lookup misses", async () => {
+    vi.spyOn(directoryLive, "listDiscordDirectoryPeersLive").mockResolvedValueOnce([]);
+    await expect(
+      resolveDiscordTarget("general", { cfg, accountId: "default" }),
+    ).resolves.toMatchObject({ kind: "channel", id: "general" });
+  });
+
+  it("does not call directory lookup for explicit user ids", async () => {
+    const listPeers = vi.spyOn(directoryLive, "listDiscordDirectoryPeersLive");
+    await expect(
+      resolveDiscordTarget("user:123", { cfg, accountId: "default" }),
+    ).resolves.toMatchObject({ kind: "user", id: "123" });
+    expect(listPeers).not.toHaveBeenCalled();
+  });
+
+  it("treats bare numeric ids in allowFrom as users even when channels are the default", async () => {
+    const listPeers = vi.spyOn(directoryLive, "listDiscordDirectoryPeersLive");
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: ["123"],
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      resolveDiscordTarget("123", { cfg, accountId: "default" }, { defaultKind: "channel" }),
+    ).resolves.toMatchObject({ kind: "user", id: "123", normalized: "user:123" });
+    expect(listPeers).not.toHaveBeenCalled();
+  });
+
+  it("uses legacy dm.allowFrom when disambiguating bare numeric ids", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      resolveDiscordTarget("456", { cfg, accountId: "default" }, { defaultKind: "channel" }),
+    ).resolves.toMatchObject({ kind: "user", id: "456", normalized: "user:456" });
+  });
+
+  it("prefers top-level allowFrom over legacy dm.allowFrom for bare numeric ids", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: ["123"],
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      resolveDiscordTarget("456", { cfg, accountId: "default" }, { defaultKind: "channel" }),
+    ).resolves.toMatchObject({ kind: "channel", id: "456", normalized: "channel:456" });
+  });
+
+  it("uses account legacy dm.allowFrom before inherited root allowFrom for bare numeric ids", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          allowFrom: ["123"],
+          accounts: {
+            work: {
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      resolveDiscordTarget("456", { cfg, accountId: "work" }, { defaultKind: "channel" }),
+    ).resolves.toMatchObject({ kind: "user", id: "456", normalized: "user:456" });
+    await expect(
+      resolveDiscordTarget("123", { cfg, accountId: "work" }, { defaultKind: "channel" }),
+    ).resolves.toMatchObject({ kind: "channel", id: "123", normalized: "channel:123" });
+  });
+
+  it("caches username lookups under the configured default account when accountId is omitted", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          defaultAccount: "work",
+          accounts: {
+            work: {
+              token: "discord-work",
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    vi.spyOn(directoryLive, "listDiscordDirectoryPeersLive").mockResolvedValueOnce([
+      { kind: "user", id: "user:999", name: "Jane" } as const,
+    ]);
+
+    await expect(resolveDiscordTarget("jane", { cfg })).resolves.toMatchObject({
+      kind: "user",
+      id: "999",
+      normalized: "user:999",
+    });
+    expect(resolveDiscordDirectoryUserId({ accountId: "work", handle: "jane" })).toBe("999");
+    expect(resolveDiscordDirectoryUserId({ accountId: "default", handle: "jane" })).toBeUndefined();
+  });
+});
+
+describe("normalizeDiscordMessagingTarget", () => {
+  it("defaults raw numeric ids to channels", () => {
+    expect(normalizeDiscordMessagingTarget("123")).toBe("channel:123");
+  });
+});
+
+describe("discord group policy", () => {
+  it("prefers channel policy, then guild policy, with sender-specific overrides", () => {
+    const discordCfg = {
+      channels: {
+        discord: {
+          token: "discord-test",
+          guilds: {
+            guild1: {
+              requireMention: false,
+              tools: { allow: ["message.guild"] },
+              toolsBySender: {
+                "id:user:guild-admin": { allow: ["sessions.list"] },
+              },
+              channels: {
+                "123": {
+                  requireMention: true,
+                  tools: { allow: ["message.channel"] },
+                  toolsBySender: {
+                    "id:user:channel-admin": { deny: ["exec"] },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    } as any;
+
+    expect(
+      resolveDiscordGroupRequireMention({ cfg: discordCfg, groupSpace: "guild1", groupId: "123" }),
+    ).toBe(true);
+    expect(
+      resolveDiscordGroupRequireMention({
+        cfg: discordCfg,
+        groupSpace: "guild1",
+        groupId: "missing",
+      }),
+    ).toBe(false);
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        groupSpace: "guild1",
+        groupId: "123",
+        senderId: "user:channel-admin",
+      }),
+    ).toEqual({ deny: ["exec"] });
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        groupSpace: "guild1",
+        groupId: "123",
+        senderId: "user:someone",
+      }),
+    ).toEqual({ allow: ["message.channel"] });
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        groupSpace: "guild1",
+        groupId: "missing",
+        senderId: "user:guild-admin",
+      }),
+    ).toEqual({ allow: ["sessions.list"] });
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        groupSpace: "guild1",
+        groupId: "missing",
+        senderId: "user:someone",
+      }),
+    ).toEqual({ allow: ["message.guild"] });
+  });
+
+  it("honors account-scoped guild and channel overrides", () => {
+    const discordCfg = {
+      channels: {
+        discord: {
+          token: "discord-test",
+          guilds: {
+            guild1: {
+              requireMention: true,
+              tools: { allow: ["message.root"] },
+            },
+          },
+          accounts: {
+            work: {
+              token: "discord-work",
+              guilds: {
+                guild1: {
+                  requireMention: false,
+                  tools: { allow: ["message.account"] },
+                  channels: {
+                    "123": {
+                      requireMention: true,
+                      tools: { allow: ["message.account-channel"] },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    } as any;
+
+    expect(
+      resolveDiscordGroupRequireMention({
+        cfg: discordCfg,
+        accountId: "work",
+        groupSpace: "guild1",
+        groupId: "missing",
+      }),
+    ).toBe(false);
+    expect(
+      resolveDiscordGroupRequireMention({
+        cfg: discordCfg,
+        accountId: "work",
+        groupSpace: "guild1",
+        groupId: "123",
+      }),
+    ).toBe(true);
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        accountId: "work",
+        groupSpace: "guild1",
+        groupId: "missing",
+      }),
+    ).toEqual({ allow: ["message.account"] });
+    expect(
+      resolveDiscordGroupToolPolicy({
+        cfg: discordCfg,
+        accountId: "work",
+        groupSpace: "guild1",
+        groupId: "123",
+      }),
+    ).toEqual({ allow: ["message.account-channel"] });
+  });
+});

package/src/targets.ts

@@ -0,0 +1,12 @@
+import {
+  parseDiscordTarget,
+  type DiscordTarget,
+  type DiscordTargetKind,
+  type DiscordTargetParseOptions,
+  resolveDiscordChannelId,
+} from "./target-parsing.js";
+import { resolveDiscordTarget } from "./target-resolver.js";
+
+export { parseDiscordTarget, resolveDiscordChannelId };
+export type { DiscordTarget, DiscordTargetKind, DiscordTargetParseOptions };
+export { resolveDiscordTarget };

package/src/test-http-helpers.ts

@@ -0,0 +1,10 @@
+export function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status });
+}
+
+export function urlToString(url: Request | URL | string): string {
+  if (typeof url === "string") {
+    return url;
+  }
+  return "url" in url ? url.url : String(url);
+}

package/src/test-support/component-runtime.ts

@@ -0,0 +1,190 @@
+import {
+  parsePluginBindingApprovalCustomId,
+  resolvePinnedMainDmOwnerFromAllowlist,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import { isSingleUseReplyToMode } from "openclaw/plugin-sdk/reply-reference";
+import { vi, type Mock } from "vitest";
+
+type UnknownMock = Mock<(...args: unknown[]) => unknown>;
+type AsyncUnknownMock = Mock<(...args: unknown[]) => Promise<unknown>>;
+type DispatchReplyWithBufferedBlockDispatcherFn =
+  typeof import("openclaw/plugin-sdk/reply-dispatch-runtime").dispatchReplyWithBufferedBlockDispatcher;
+type DispatchReplyMock = Mock<DispatchReplyWithBufferedBlockDispatcherFn>;
+
+type DiscordComponentRuntimeMocks = {
+  buildPluginBindingResolvedTextMock: UnknownMock;
+  dispatchPluginInteractiveHandlerMock: AsyncUnknownMock;
+  dispatchReplyMock: DispatchReplyMock;
+  enqueueSystemEventMock: UnknownMock;
+  readAllowFromStoreMock: AsyncUnknownMock;
+  readSessionUpdatedAtMock: UnknownMock;
+  recordInboundSessionMock: AsyncUnknownMock;
+  resolveStorePathMock: UnknownMock;
+  resolvePluginConversationBindingApprovalMock: AsyncUnknownMock;
+  upsertPairingRequestMock: AsyncUnknownMock;
+};
+
+const runtimeMocks = vi.hoisted(
+  (): DiscordComponentRuntimeMocks => ({
+    buildPluginBindingResolvedTextMock: vi.fn(),
+    dispatchPluginInteractiveHandlerMock: vi.fn(),
+    dispatchReplyMock: vi.fn<DispatchReplyWithBufferedBlockDispatcherFn>(),
+    enqueueSystemEventMock: vi.fn(),
+    readAllowFromStoreMock: vi.fn(),
+    readSessionUpdatedAtMock: vi.fn(),
+    recordInboundSessionMock: vi.fn(),
+    resolveStorePathMock: vi.fn(),
+    resolvePluginConversationBindingApprovalMock: vi.fn(),
+    upsertPairingRequestMock: vi.fn(),
+  }),
+);
+
+export const readAllowFromStoreMock: AsyncUnknownMock = runtimeMocks.readAllowFromStoreMock;
+export const dispatchPluginInteractiveHandlerMock: AsyncUnknownMock =
+  runtimeMocks.dispatchPluginInteractiveHandlerMock;
+export const dispatchReplyMock: DispatchReplyMock = runtimeMocks.dispatchReplyMock;
+export const enqueueSystemEventMock: UnknownMock = runtimeMocks.enqueueSystemEventMock;
+export const upsertPairingRequestMock: AsyncUnknownMock = runtimeMocks.upsertPairingRequestMock;
+export const recordInboundSessionMock: AsyncUnknownMock = runtimeMocks.recordInboundSessionMock;
+export const readSessionUpdatedAtMock: UnknownMock = runtimeMocks.readSessionUpdatedAtMock;
+export const resolveStorePathMock: UnknownMock = runtimeMocks.resolveStorePathMock;
+const resolvePluginConversationBindingApprovalMock: AsyncUnknownMock =
+  runtimeMocks.resolvePluginConversationBindingApprovalMock;
+const buildPluginBindingResolvedTextMock: UnknownMock =
+  runtimeMocks.buildPluginBindingResolvedTextMock;
+
+async function readStoreAllowFromForDmPolicy(params: {
+  provider: string;
+  accountId: string;
+  dmPolicy?: string | null;
+  shouldRead?: boolean | null;
+}) {
+  if (params.shouldRead === false || params.dmPolicy === "allowlist") {
+    return [];
+  }
+  return await readAllowFromStoreMock(params.provider, params.accountId);
+}
+
+vi.mock("../monitor/agent-components-helpers.runtime.js", () => {
+  return {
+    readStoreAllowFromForDmPolicy,
+    resolvePinnedMainDmOwnerFromAllowlist,
+    upsertChannelPairingRequest: (...args: unknown[]) => upsertPairingRequestMock(...args),
+  };
+});
+
+vi.mock("../monitor/agent-components.runtime.js", () => {
+  return {
+    buildPluginBindingResolvedText: (...args: unknown[]) =>
+      buildPluginBindingResolvedTextMock(...args),
+    createReplyReferencePlanner: vi.fn(
+      (params: {
+        existingId?: string;
+        hasReplied?: boolean;
+        replyToMode?: "off" | "first" | "all" | "batched";
+        startId?: string;
+      }) => {
+        let hasReplied = params.hasReplied ?? false;
+        let nextId = params.existingId ?? params.startId;
+        return {
+          hasReplied() {
+            return hasReplied;
+          },
+          markSent() {
+            hasReplied = true;
+          },
+          use() {
+            if (params.replyToMode === "off") {
+              return undefined;
+            }
+            if (isSingleUseReplyToMode(params.replyToMode ?? "off") && hasReplied) {
+              return undefined;
+            }
+            const value = nextId;
+            hasReplied = true;
+            nextId = undefined;
+            return value;
+          },
+        };
+      },
+    ),
+    dispatchPluginInteractiveHandler: (...args: unknown[]) =>
+      dispatchPluginInteractiveHandlerMock(...args),
+    dispatchReplyWithBufferedBlockDispatcher: dispatchReplyMock,
+    finalizeInboundContext: vi.fn((ctx) => ctx),
+    parsePluginBindingApprovalCustomId,
+    recordInboundSession: (...args: unknown[]) => recordInboundSessionMock(...args),
+    resolveChunkMode: vi.fn(() => "sentences"),
+    resolvePluginConversationBindingApproval: (...args: unknown[]) =>
+      resolvePluginConversationBindingApprovalMock(...args),
+    resolveTextChunkLimit: vi.fn(() => 2000),
+  };
+});
+
+vi.mock("../interactive-dispatch.js", () => {
+  return {
+    dispatchDiscordPluginInteractiveHandler: (...args: unknown[]) =>
+      dispatchPluginInteractiveHandlerMock(...args),
+  };
+});
+
+vi.mock("../monitor/agent-components.deps.runtime.js", () => {
+  return {
+    enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
+    readSessionUpdatedAt: (...args: unknown[]) => readSessionUpdatedAtMock(...args),
+    resolveStorePath: (...args: unknown[]) => resolveStorePathMock(...args),
+  };
+});
+
+vi.mock("../interactive-dispatch.js", async () => {
+  const actual = await vi.importActual<typeof import("../interactive-dispatch.js")>(
+    "../interactive-dispatch.js",
+  );
+  return {
+    ...actual,
+    dispatchDiscordPluginInteractiveHandler: (...args: unknown[]) =>
+      dispatchPluginInteractiveHandlerMock(...args),
+  };
+});
+
+export function resetDiscordComponentRuntimeMocks() {
+  dispatchPluginInteractiveHandlerMock.mockReset().mockResolvedValue({
+    matched: false,
+    handled: false,
+    duplicate: false,
+  });
+  dispatchReplyMock.mockClear();
+  enqueueSystemEventMock.mockClear();
+  readAllowFromStoreMock.mockClear().mockResolvedValue([]);
+  readSessionUpdatedAtMock.mockClear().mockReturnValue(undefined);
+  upsertPairingRequestMock.mockClear().mockResolvedValue({ code: "PAIRCODE", created: true });
+  recordInboundSessionMock.mockClear().mockResolvedValue(undefined);
+  resolveStorePathMock.mockClear().mockReturnValue("/tmp/openclaw-sessions-test.json");
+  resolvePluginConversationBindingApprovalMock.mockReset().mockResolvedValue({
+    status: "approved",
+    binding: {
+      bindingId: "binding-1",
+      pluginId: "openclaw-codex-app-server",
+      pluginName: "OpenClaw App Server",
+      pluginRoot: "/plugins/codex",
+      channel: "discord",
+      accountId: "default",
+      conversationId: "user:123456789",
+      boundAt: Date.now(),
+    },
+    request: {
+      id: "approval-1",
+      pluginId: "openclaw-codex-app-server",
+      pluginName: "OpenClaw App Server",
+      pluginRoot: "/plugins/codex",
+      requestedAt: Date.now(),
+      conversation: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: "user:123456789",
+      },
+    },
+    decision: "allow-once",
+  });
+  buildPluginBindingResolvedTextMock.mockReset().mockReturnValue("Binding approved.");
+}

package/src/test-support/config.ts

@@ -0,0 +1,7 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export const EMPTY_DISCORD_TEST_CONFIG = {} as OpenClawConfig;
+
+export const EMPTY_DISCORD_TEST_OPTS = {
+  cfg: EMPTY_DISCORD_TEST_CONFIG,
+};

package/src/test-support/configured-binding-runtime.ts

@@ -0,0 +1,29 @@
+type ConfiguredBindingConversationRuntimeModule = {
+  ensureConfiguredBindingRouteReady: (...args: never[]) => unknown;
+  resolveConfiguredBindingRoute: (...args: never[]) => unknown;
+};
+
+export async function createConfiguredBindingConversationRuntimeModuleMock<
+  TModule extends ConfiguredBindingConversationRuntimeModule,
+>(
+  params: {
+    ensureConfiguredBindingRouteReadyMock: (
+      ...args: Parameters<TModule["ensureConfiguredBindingRouteReady"]>
+    ) => ReturnType<TModule["ensureConfiguredBindingRouteReady"]>;
+    resolveConfiguredBindingRouteMock: (
+      ...args: Parameters<TModule["resolveConfiguredBindingRoute"]>
+    ) => ReturnType<TModule["resolveConfiguredBindingRoute"]>;
+  },
+  loadActual: () => Promise<TModule>,
+) {
+  const actual = await loadActual();
+  return {
+    ...actual,
+    ensureConfiguredBindingRouteReady: (
+      ...args: Parameters<TModule["ensureConfiguredBindingRouteReady"]>
+    ) => params.ensureConfiguredBindingRouteReadyMock(...args),
+    resolveConfiguredBindingRoute: (
+      ...args: Parameters<TModule["resolveConfiguredBindingRoute"]>
+    ) => params.resolveConfiguredBindingRouteMock(...args),
+  } satisfies TModule;
+}

package/src/test-support/partial-channel.ts

@@ -0,0 +1,26 @@
+const DISCORD_PARTIAL_CHANNEL_RAW_DATA_ERROR =
+  "Cannot access rawData on partial Channel. Use fetch() to populate data.";
+
+export function defineThrowingDiscordChannelGetter(
+  channel: object,
+  key: string,
+  message = DISCORD_PARTIAL_CHANNEL_RAW_DATA_ERROR,
+) {
+  Object.defineProperty(channel, key, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      throw new Error(message);
+    },
+  });
+}
+
+export function createPartialDiscordChannelWithThrowingGetters<T extends object>(
+  channel: T,
+  keys: readonly string[],
+): T {
+  for (const key of keys) {
+    defineThrowingDiscordChannelGetter(channel, key);
+  }
+  return channel;
+}