@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/audit-core.ts

@@ -0,0 +1,141 @@
+import type {
+  DiscordGuildChannelConfig,
+  DiscordGuildEntry,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk/config-types";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { isRecord, normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+
+type DiscordChannelPermissionsAuditEntry = {
+  channelId: string;
+  ok: boolean;
+  missing?: string[];
+  error?: string | null;
+  matchKey?: string;
+  matchSource?: "id";
+};
+
+export type DiscordChannelPermissionsAudit = {
+  ok: boolean;
+  checkedChannels: number;
+  unresolvedChannels: number;
+  channels: DiscordChannelPermissionsAuditEntry[];
+  elapsedMs: number;
+};
+
+const REQUIRED_CHANNEL_PERMISSIONS = ["ViewChannel", "SendMessages"] as const;
+
+function shouldAuditChannelConfig(config: DiscordGuildChannelConfig | undefined) {
+  if (!config) {
+    return true;
+  }
+  if (config.enabled === false) {
+    return false;
+  }
+  return true;
+}
+
+function listConfiguredGuildChannelKeys(
+  guilds: Record<string, DiscordGuildEntry> | undefined,
+): string[] {
+  if (!guilds) {
+    return [];
+  }
+  const ids = new Set<string>();
+  for (const entry of Object.values(guilds)) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const channelsRaw = (entry as { channels?: unknown }).channels;
+    if (!isRecord(channelsRaw)) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(channelsRaw)) {
+      const channelId = normalizeOptionalString(key) ?? "";
+      if (!channelId) {
+        continue;
+      }
+      if (channelId === "*") {
+        continue;
+      }
+      if (!shouldAuditChannelConfig(value as DiscordGuildChannelConfig | undefined)) {
+        continue;
+      }
+      ids.add(channelId);
+    }
+  }
+  return [...ids].toSorted((a, b) => a.localeCompare(b));
+}
+
+export function collectDiscordAuditChannelIdsForGuilds(
+  guilds: Record<string, DiscordGuildEntry> | undefined,
+) {
+  const keys = listConfiguredGuildChannelKeys(guilds);
+  const channelIds = keys.filter((key) => /^\d+$/.test(key));
+  const unresolvedChannels = keys.length - channelIds.length;
+  return { channelIds, unresolvedChannels };
+}
+
+export async function auditDiscordChannelPermissionsWithFetcher(params: {
+  cfg: OpenClawConfig;
+  token: string;
+  accountId?: string | null;
+  channelIds: string[];
+  timeoutMs: number;
+  fetchChannelPermissions: (
+    channelId: string,
+    params: { cfg: OpenClawConfig; token: string; accountId?: string },
+  ) => Promise<{
+    permissions: string[];
+  }>;
+}): Promise<DiscordChannelPermissionsAudit> {
+  const started = Date.now();
+  const token = normalizeOptionalString(params.token) ?? "";
+  if (!token || params.channelIds.length === 0) {
+    return {
+      ok: true,
+      checkedChannels: 0,
+      unresolvedChannels: 0,
+      channels: [],
+      elapsedMs: Date.now() - started,
+    };
+  }
+
+  const required = [...REQUIRED_CHANNEL_PERMISSIONS];
+  const channels: DiscordChannelPermissionsAuditEntry[] = [];
+
+  for (const channelId of params.channelIds) {
+    try {
+      const perms = await params.fetchChannelPermissions(channelId, {
+        cfg: params.cfg,
+        token,
+        accountId: params.accountId ?? undefined,
+      });
+      const missing = required.filter((p) => !perms.permissions.includes(p));
+      channels.push({
+        channelId,
+        ok: missing.length === 0,
+        missing: missing.length ? missing : undefined,
+        error: null,
+        matchKey: channelId,
+        matchSource: "id",
+      });
+    } catch (err) {
+      channels.push({
+        channelId,
+        ok: false,
+        error: formatErrorMessage(err),
+        matchKey: channelId,
+        matchSource: "id",
+      });
+    }
+  }
+
+  return {
+    ok: channels.every((c) => c.ok),
+    checkedChannels: channels.length,
+    unresolvedChannels: 0,
+    channels,
+    elapsedMs: Date.now() - started,
+  };
+}

package/src/audit.test.ts

@@ -0,0 +1,145 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  auditDiscordChannelPermissionsWithFetcher,
+  collectDiscordAuditChannelIdsForGuilds,
+} from "./audit-core.js";
+
+const fetchChannelPermissionsDiscordMock = vi.fn();
+
+function readDiscordGuilds(cfg: OpenClawConfig) {
+  const guilds = cfg.channels?.discord?.guilds;
+  expect(guilds).toBeDefined();
+  return guilds ?? {};
+}
+
+describe("discord audit", () => {
+  beforeEach(() => {
+    fetchChannelPermissionsDiscordMock.mockReset();
+  });
+
+  it("collects numeric channel ids even when config uses allow=false and counts unresolved keys", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                general: { allow: true },
+                "222": { allow: false },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111", "222"]);
+    expect(collected.unresolvedChannels).toBe(1);
+
+    fetchChannelPermissionsDiscordMock.mockResolvedValueOnce({
+      channelId: "111",
+      permissions: ["ViewChannel"],
+      raw: "0",
+      isDm: false,
+    });
+    fetchChannelPermissionsDiscordMock.mockResolvedValueOnce({
+      channelId: "222",
+      permissions: ["ViewChannel", "SendMessages"],
+      raw: "0",
+      isDm: false,
+    });
+
+    const audit = await auditDiscordChannelPermissionsWithFetcher({
+      cfg,
+      token: "t",
+      accountId: "default",
+      channelIds: collected.channelIds,
+      timeoutMs: 1000,
+      fetchChannelPermissions: fetchChannelPermissionsDiscordMock,
+    });
+    expect(audit.ok).toBe(false);
+    expect(audit.channels).toHaveLength(2);
+    expect(audit.channels[0]?.channelId).toBe("111");
+    expect(audit.channels[0]?.missing).toContain("SendMessages");
+  });
+
+  it("does not count '*' wildcard key as unresolved channel", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                "*": { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111"]);
+    expect(collected.unresolvedChannels).toBe(0);
+  });
+
+  it("handles guild with only '*' wildcard and no numeric channel ids", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "*": { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual([]);
+    expect(collected.unresolvedChannels).toBe(0);
+  });
+
+  it("collects audit channel ids without resolving SecretRef-backed Discord tokens", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: {
+            source: "env",
+            provider: "default",
+            id: "DISCORD_BOT_TOKEN",
+          },
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                general: { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111"]);
+    expect(collected.unresolvedChannels).toBe(1);
+  });
+});

package/src/audit.ts

@@ -0,0 +1,32 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { inspectDiscordAccount } from "./account-inspect.js";
+import {
+  auditDiscordChannelPermissionsWithFetcher,
+  collectDiscordAuditChannelIdsForGuilds,
+  type DiscordChannelPermissionsAudit,
+} from "./audit-core.js";
+import { fetchChannelPermissionsDiscord } from "./send.js";
+
+export function collectDiscordAuditChannelIds(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}) {
+  const account = inspectDiscordAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  return collectDiscordAuditChannelIdsForGuilds(account.config.guilds);
+}
+
+export async function auditDiscordChannelPermissions(params: {
+  cfg: OpenClawConfig;
+  token: string;
+  accountId?: string | null;
+  channelIds: string[];
+  timeoutMs: number;
+}): Promise<DiscordChannelPermissionsAudit> {
+  return await auditDiscordChannelPermissionsWithFetcher({
+    ...params,
+    fetchChannelPermissions: fetchChannelPermissionsDiscord,
+  });
+}

package/src/channel-actions.contract.test.ts

@@ -0,0 +1,45 @@
+import { installChannelActionsContractSuite } from "openclaw/plugin-sdk/channel-test-helpers";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { describe } from "vitest";
+import { discordPlugin } from "../api.js";
+
+describe("discord actions contract", () => {
+  installChannelActionsContractSuite({
+    plugin: discordPlugin,
+    cases: [
+      {
+        name: "describes configured Discord actions and capabilities",
+        cfg: {
+          channels: {
+            discord: {
+              token: "Bot token-main",
+              actions: {
+                polls: true,
+                reactions: true,
+                permissions: false,
+                messages: false,
+                pins: false,
+                threads: false,
+                search: false,
+                stickers: false,
+                memberInfo: false,
+                roleInfo: false,
+                emojiUploads: false,
+                stickerUploads: false,
+                channelInfo: false,
+                channels: false,
+                voiceStatus: false,
+                events: false,
+                roles: false,
+                moderation: false,
+                presence: false,
+              },
+            },
+          },
+        } as OpenClawConfig,
+        expectedActions: ["send", "poll", "react", "reactions", "emoji-list"],
+        expectedCapabilities: ["presentation"],
+      },
+    ],
+  });
+});

package/src/channel-actions.runtime.ts

@@ -0,0 +1 @@
+export { handleDiscordMessageAction } from "./actions/handle-action.js";

package/src/channel-actions.test.ts

@@ -0,0 +1,236 @@
+import type { ChannelMessageActionContext } from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { withEnv } from "openclaw/plugin-sdk/test-env";
+import { describe, expect, it, vi } from "vitest";
+
+const handleDiscordMessageActionMock = vi.hoisted(() =>
+  vi.fn(async () => ({ content: [], details: { ok: true } })),
+);
+
+const handleActionModule = await import("./actions/handle-action.js");
+vi.spyOn(handleActionModule, "handleDiscordMessageAction").mockImplementation(
+  handleDiscordMessageActionMock,
+);
+const { discordMessageActions } = await import("./channel-actions.js");
+
+describe("discordMessageActions", () => {
+  it("returns no tool actions when no token-sourced Discord accounts are enabled", () => {
+    withEnv({ DISCORD_BOT_TOKEN: undefined }, () => {
+      const discovery = discordMessageActions.describeMessageTool?.({
+        cfg: {
+          channels: {
+            discord: {
+              enabled: true,
+            },
+          },
+        } as OpenClawConfig,
+      });
+
+      expect(discovery).toEqual({
+        actions: [],
+        capabilities: [],
+        schema: null,
+      });
+    });
+  });
+
+  it("describes enabled Discord actions for token-backed accounts", () => {
+    const discovery = discordMessageActions.describeMessageTool?.({
+      cfg: {
+        channels: {
+          discord: {
+            token: "Bot token-main",
+            actions: {
+              polls: true,
+              reactions: true,
+              permissions: true,
+              channels: false,
+              roles: false,
+            },
+          },
+        },
+      } as OpenClawConfig,
+    });
+
+    expect(discovery?.capabilities).toEqual(["presentation"]);
+    expect(discovery?.schema).toBeUndefined();
+    expect(discovery?.actions).toEqual(
+      expect.arrayContaining(["send", "poll", "react", "reactions", "emoji-list", "permissions"]),
+    );
+    expect(discovery?.actions).not.toContain("channel-create");
+    expect(discovery?.actions).not.toContain("role-add");
+  });
+
+  it("describes actions when the Discord token is an unresolved SecretRef", () => {
+    const discovery = discordMessageActions.describeMessageTool?.({
+      cfg: {
+        channels: {
+          discord: {
+            token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
+            actions: {
+              polls: true,
+              reactions: true,
+            },
+          },
+        },
+      } as unknown as OpenClawConfig,
+    });
+
+    expect(discovery?.capabilities).toEqual(["presentation"]);
+    expect(discovery?.actions).toEqual(
+      expect.arrayContaining(["send", "poll", "react", "reactions", "emoji-list"]),
+    );
+  });
+
+  it("describes scoped account actions when only the account token is an unresolved SecretRef", () => {
+    const discovery = discordMessageActions.describeMessageTool?.({
+      cfg: {
+        channels: {
+          discord: {
+            actions: {
+              polls: true,
+              reactions: false,
+            },
+            accounts: {
+              ops: {
+                token: { source: "file", provider: "filemain", id: "/DISCORD_BOT_TOKEN" },
+                actions: {
+                  polls: false,
+                  reactions: true,
+                },
+              },
+            },
+          },
+        },
+      } as unknown as OpenClawConfig,
+      accountId: "ops",
+    });
+
+    expect(discovery?.actions).toEqual(
+      expect.arrayContaining(["send", "react", "reactions", "emoji-list"]),
+    );
+    expect(discovery?.actions).not.toContain("poll");
+  });
+
+  it("honors account-scoped action gates during discovery", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot token-main",
+          actions: {
+            reactions: false,
+            polls: true,
+          },
+          accounts: {
+            work: {
+              token: "Bot token-work",
+              actions: {
+                reactions: true,
+                polls: false,
+              },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const defaultDiscovery = discordMessageActions.describeMessageTool?.({
+      cfg,
+      accountId: "default",
+    });
+    const workDiscovery = discordMessageActions.describeMessageTool?.({
+      cfg,
+      accountId: "work",
+    });
+
+    expect(defaultDiscovery?.actions).toEqual(expect.arrayContaining(["send", "poll"]));
+    expect(defaultDiscovery?.actions).not.toContain("react");
+    expect(workDiscovery?.actions).toEqual(
+      expect.arrayContaining(["send", "react", "reactions", "emoji-list"]),
+    );
+    expect(workDiscovery?.actions).not.toContain("poll");
+  });
+
+  it("does not expose Discord-native message tool schema", () => {
+    const discovery = discordMessageActions.describeMessageTool?.({
+      cfg: {
+        channels: {
+          discord: {
+            token: "Bot token-main",
+          },
+        },
+      } as OpenClawConfig,
+    });
+    expect(discovery?.schema).toBeUndefined();
+  });
+
+  it.each(["read", "search"])("routes %s actions through gateway execution mode", (action) => {
+    expect(discordMessageActions.resolveExecutionMode?.({ action: action as never })).toBe(
+      "gateway",
+    );
+  });
+
+  it.each(["send", "edit", "delete", "react", "pin", "poll"])(
+    "routes %s actions through local execution mode",
+    (action) => {
+      expect(discordMessageActions.resolveExecutionMode?.({ action: action as never })).toBe(
+        "local",
+      );
+    },
+  );
+
+  it("extracts send targets for message and thread reply actions", () => {
+    expect(
+      discordMessageActions.extractToolSend?.({
+        args: { action: "sendMessage", to: "channel:123" },
+      }),
+    ).toEqual({ to: "channel:123" });
+
+    expect(
+      discordMessageActions.extractToolSend?.({
+        args: { action: "threadReply", channelId: "987" },
+      }),
+    ).toEqual({ to: "channel:987" });
+
+    expect(
+      discordMessageActions.extractToolSend?.({
+        args: { action: "threadReply", channelId: "   " },
+      }),
+    ).toBeNull();
+  });
+
+  it("delegates action handling to the Discord action handler", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot token-main",
+        },
+      },
+    } as OpenClawConfig;
+    const toolContext: ChannelMessageActionContext["toolContext"] = {
+      currentChannelProvider: "discord",
+    };
+    const mediaLocalRoots = ["/tmp/media"];
+
+    await discordMessageActions.handleAction?.({
+      channel: "discord",
+      action: "send",
+      params: { to: "channel:123", message: "hello" },
+      cfg,
+      accountId: "ops",
+      requesterSenderId: "user-1",
+      toolContext,
+      mediaLocalRoots,
+    });
+
+    expect(handleDiscordMessageActionMock).toHaveBeenCalledWith({
+      action: "send",
+      params: { to: "channel:123", message: "hello" },
+      cfg,
+      accountId: "ops",
+      requesterSenderId: "user-1",
+      toolContext,
+      mediaLocalRoots,
+    });
+  });
+});