@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/shared.test.ts

@@ -0,0 +1,165 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDiscordPluginBase, discordConfigAdapter } from "./shared.js";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("createDiscordPluginBase", () => {
+  it("owns Discord native command name overrides", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(
+      plugin.commands?.resolveNativeCommandName?.({
+        commandKey: "tts",
+        defaultName: "tts",
+      }),
+    ).toBe("voice");
+    expect(
+      plugin.commands?.resolveNativeCommandName?.({
+        commandKey: "status",
+        defaultName: "status",
+      }),
+    ).toBe("status");
+  });
+
+  it("exposes security checks on the setup surface", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(plugin.security?.resolveDmPolicy).toBeTypeOf("function");
+    expect(plugin.security?.collectWarnings).toBeTypeOf("function");
+    expect(plugin.security?.collectAuditFindings).toBeTypeOf("function");
+  });
+
+  it("hydrates announce delivery targets from stored session routing", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(plugin.meta.preferSessionLookupForAnnounceTarget).toBe(true);
+  });
+
+  it("reports duplicate-token accounts as disabled to gateway startup", () => {
+    vi.stubEnv("DISCORD_BOT_TOKEN", "same-token");
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            work: {
+              token: "same-token",
+            },
+          },
+        },
+      },
+    };
+
+    const defaultAccount = plugin.config.resolveAccount(cfg, "default");
+    const workAccount = plugin.config.resolveAccount(cfg, "work");
+
+    expect(plugin.config.isEnabled?.(defaultAccount, cfg)).toBe(false);
+    expect(plugin.config.disabledReason?.(defaultAccount, cfg)).toBe(
+      'duplicate bot token; using account "work"',
+    );
+    expect(plugin.config.isEnabled?.(workAccount, cfg)).toBe(true);
+  });
+});
+
+describe("discordConfigAdapter", () => {
+  it("resolves top-level allowFrom before legacy dm.allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: ["123"],
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual(["123"]);
+  });
+
+  it("falls back to legacy dm.allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual(["456"]);
+  });
+
+  it("prefers account legacy dm.allowFrom over inherited root allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          allowFrom: ["root"],
+          accounts: {
+            work: {
+              dm: { allowFrom: ["account-legacy"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "work" })).toEqual([
+      "account-legacy",
+    ]);
+  });
+
+  it("coerces numeric allowFrom entries at the config boundary", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: [123456789],
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "123456789",
+    ]);
+  });
+
+  it("keeps read-only accessors from resolving token SecretRefs", () => {
+    const cfg = {
+      secrets: {
+        providers: {
+          discord_token: {
+            source: "file",
+            path: "/tmp/openclaw-missing-discord-token",
+            mode: "singleValue",
+          },
+        },
+      },
+      channels: {
+        discord: {
+          token: { source: "file", provider: "discord_token", id: "value" },
+          allowFrom: ["1128540374256849009"],
+          defaultTo: "1498959610751750304",
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "1128540374256849009",
+    ]);
+    expect(discordConfigAdapter.resolveDefaultTo?.({ cfg, accountId: "default" })).toBe(
+      "1498959610751750304",
+    );
+  });
+});

package/src/shared.ts

@@ -0,0 +1,190 @@
+import { describeAccountSnapshot } from "openclaw/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { formatAllowFromLowercase } from "openclaw/plugin-sdk/allow-from";
+import { adaptScopedAccountAccessor } from "openclaw/plugin-sdk/channel-config-helpers";
+import { createScopedChannelConfigAdapter } from "openclaw/plugin-sdk/channel-config-helpers";
+import type { ChannelDoctorAdapter } from "openclaw/plugin-sdk/channel-contract";
+import { inspectDiscordAccount } from "./account-inspect.js";
+import {
+  isDiscordAccountEnabledForRuntime,
+  listDiscordAccountIds,
+  mergeDiscordAccountConfig,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordAccount,
+  resolveDiscordAccountAllowFrom,
+  resolveDiscordAccountDisabledReason,
+  type ResolvedDiscordAccount,
+} from "./accounts.js";
+import { getChatChannelMeta, type ChannelPlugin } from "./channel-api.js";
+import { DiscordChannelConfigSchema } from "./config-schema.js";
+import { normalizeCompatibilityConfig } from "./doctor-contract.js";
+import { DISCORD_LEGACY_CONFIG_RULES } from "./doctor-shared.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+import {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./secret-config-contract.js";
+import {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./security-contract.js";
+import { discordSecurityAdapter } from "./security.js";
+import { deriveLegacySessionChatType } from "./session-contract.js";
+
+const DISCORD_CHANNEL = "discord" as const;
+
+type DiscordDoctorModule = typeof import("./doctor.js");
+type DiscordConfigAccessorAccount = {
+  allowFrom: string[] | undefined;
+  defaultTo: string | undefined;
+};
+
+let discordDoctorModulePromise: Promise<DiscordDoctorModule> | undefined;
+
+async function loadDiscordDoctorModule(): Promise<DiscordDoctorModule> {
+  discordDoctorModulePromise ??= import("./doctor.js");
+  return await discordDoctorModulePromise;
+}
+
+const discordDoctor: ChannelDoctorAdapter = {
+  dmAllowFromMode: "topOnly",
+  groupModel: "route",
+  groupAllowFromFallbackToAllowFrom: false,
+  warnOnEmptyGroupSenderAllowlist: false,
+  legacyConfigRules: DISCORD_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig,
+  collectPreviewWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectPreviewWarnings?.(params) ?? [],
+  collectMutableAllowlistWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectMutableAllowlistWarnings?.(params) ?? [],
+  repairConfig: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.repairConfig?.(params) ?? {
+      config: params.cfg,
+      changes: [],
+    },
+};
+
+function resolveDiscordConfigAccessorAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): DiscordConfigAccessorAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultDiscordAccountId(params.cfg),
+  );
+  const config = mergeDiscordAccountConfig(params.cfg, accountId);
+  return {
+    allowFrom: resolveDiscordAccountAllowFrom({ cfg: params.cfg, accountId }),
+    defaultTo: config.defaultTo,
+  };
+}
+
+export const discordConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedDiscordAccount,
+  DiscordConfigAccessorAccount
+>({
+  sectionKey: DISCORD_CHANNEL,
+  listAccountIds: listDiscordAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveDiscordAccount),
+  resolveAccessorAccount: resolveDiscordConfigAccessorAccount,
+  inspectAccount: adaptScopedAccountAccessor(inspectDiscordAccount),
+  defaultAccountId: resolveDefaultDiscordAccountId,
+  clearBaseFields: ["token", "name"],
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: (allowFrom) => formatAllowFromLowercase({ allowFrom }),
+  resolveDefaultTo: (account) => account.defaultTo,
+});
+
+export function createDiscordPluginBase(params: {
+  setup: NonNullable<ChannelPlugin<ResolvedDiscordAccount>["setup"]>;
+  setupWizard?: ChannelPlugin<ResolvedDiscordAccount>["setupWizard"];
+}): Pick<
+  ChannelPlugin<ResolvedDiscordAccount>,
+  | "id"
+  | "meta"
+  | "setupWizard"
+  | "capabilities"
+  | "commands"
+  | "doctor"
+  | "streaming"
+  | "reload"
+  | "configSchema"
+  | "config"
+  | "setup"
+  | "messaging"
+  | "security"
+  | "secrets"
+> {
+  return {
+    id: DISCORD_CHANNEL,
+    ...(params.setupWizard ? { setupWizard: params.setupWizard } : {}),
+    meta: { ...getChatChannelMeta(DISCORD_CHANNEL) },
+    capabilities: {
+      chatTypes: ["direct", "channel", "thread"],
+      polls: true,
+      reactions: true,
+      threads: true,
+      media: true,
+      tts: {
+        voice: {
+          synthesisTarget: "voice-note",
+        },
+      },
+      nativeCommands: true,
+    },
+    commands: {
+      nativeCommandsAutoEnabled: true,
+      nativeSkillsAutoEnabled: true,
+      resolveNativeCommandName: ({ commandKey, defaultName }) =>
+        commandKey === "tts" ? "voice" : defaultName,
+    },
+    doctor: discordDoctor,
+    streaming: {
+      blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+    },
+    reload: { configPrefixes: ["channels.discord"] },
+    configSchema: DiscordChannelConfigSchema,
+    config: {
+      ...discordConfigAdapter,
+      hasConfiguredState: ({ env }) =>
+        typeof env?.DISCORD_BOT_TOKEN === "string" && env.DISCORD_BOT_TOKEN.trim().length > 0,
+      isEnabled: (account, cfg) => isDiscordAccountEnabledForRuntime(account, cfg),
+      disabledReason: (account, cfg) => resolveDiscordAccountDisabledReason(account, cfg),
+      isConfigured: (account) => Boolean(account.token?.trim()),
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured: Boolean(account.token?.trim()),
+          extra: {
+            tokenSource: account.tokenSource,
+          },
+        }),
+    },
+    messaging: {
+      deriveLegacySessionChatType,
+    },
+    security: discordSecurityAdapter,
+    secrets: {
+      secretTargetRegistryEntries,
+      unsupportedSecretRefSurfacePatterns,
+      collectUnsupportedSecretRefConfigCandidates,
+      collectRuntimeConfigAssignments,
+    },
+    setup: params.setup,
+  } as Pick<
+    ChannelPlugin<ResolvedDiscordAccount>,
+    | "id"
+    | "meta"
+    | "setupWizard"
+    | "capabilities"
+    | "commands"
+    | "doctor"
+    | "streaming"
+    | "reload"
+    | "configSchema"
+    | "config"
+    | "setup"
+    | "messaging"
+    | "security"
+    | "secrets"
+  >;
+}

package/src/status-issues.test.ts

@@ -0,0 +1,70 @@
+import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
+import { describe, expect, it } from "vitest";
+import { collectDiscordStatusIssues } from "./status-issues.js";
+
+describe("collectDiscordStatusIssues", () => {
+  it("reports disabled message content intent and unresolved channel ids", () => {
+    const issues = collectDiscordStatusIssues([
+      {
+        accountId: "ops",
+        enabled: true,
+        configured: true,
+        application: {
+          intents: {
+            messageContent: "disabled",
+          },
+        },
+        audit: {
+          unresolvedChannels: 2,
+        },
+      } as ChannelAccountSnapshot,
+    ]);
+
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          channel: "discord",
+          accountId: "ops",
+          kind: "intent",
+        }),
+        expect.objectContaining({
+          channel: "discord",
+          accountId: "ops",
+          kind: "config",
+        }),
+      ]),
+    );
+  });
+
+  it("reports channel permission failures with match metadata", () => {
+    const issues = collectDiscordStatusIssues([
+      {
+        accountId: "ops",
+        enabled: true,
+        configured: true,
+        audit: {
+          channels: [
+            {
+              channelId: "123",
+              ok: false,
+              missing: ["ViewChannel", "SendMessages"],
+              error: "403",
+              matchKey: "alerts",
+              matchSource: "guilds.ops.channels",
+            },
+          ],
+        },
+      } as ChannelAccountSnapshot,
+    ]);
+
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toMatchObject({
+      channel: "discord",
+      accountId: "ops",
+      kind: "permissions",
+    });
+    expect(issues[0]?.message).toContain("Channel 123 permission check failed");
+    expect(issues[0]?.message).toContain("alerts");
+    expect(issues[0]?.message).toContain("guilds.ops.channels");
+  });
+});

package/src/status-issues.ts

@@ -0,0 +1,169 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelStatusIssue,
+} from "openclaw/plugin-sdk/channel-contract";
+import {
+  appendMatchMetadata,
+  asString,
+  isRecord,
+  resolveEnabledConfiguredAccountId,
+} from "openclaw/plugin-sdk/status-helpers";
+
+type DiscordIntentSummary = {
+  messageContent?: "enabled" | "limited" | "disabled";
+};
+
+type DiscordApplicationSummary = {
+  intents?: DiscordIntentSummary;
+};
+
+type DiscordAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  application?: unknown;
+  audit?: unknown;
+};
+
+type DiscordPermissionsAuditSummary = {
+  unresolvedChannels?: number;
+  channels?: Array<{
+    channelId: string;
+    ok?: boolean;
+    missing?: string[];
+    error?: string | null;
+    matchKey?: string;
+    matchSource?: string;
+  }>;
+};
+
+function readDiscordAccountStatus(value: ChannelAccountSnapshot): DiscordAccountStatus | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    application: value.application,
+    audit: value.audit,
+  };
+}
+
+function readDiscordApplicationSummary(value: unknown): DiscordApplicationSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const intentsRaw = value.intents;
+  if (!isRecord(intentsRaw)) {
+    return {};
+  }
+  return {
+    intents: {
+      messageContent:
+        intentsRaw.messageContent === "enabled" ||
+        intentsRaw.messageContent === "limited" ||
+        intentsRaw.messageContent === "disabled"
+          ? intentsRaw.messageContent
+          : undefined,
+    },
+  };
+}
+
+function readDiscordPermissionsAuditSummary(value: unknown): DiscordPermissionsAuditSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const unresolvedChannels =
+    typeof value.unresolvedChannels === "number" && Number.isFinite(value.unresolvedChannels)
+      ? value.unresolvedChannels
+      : undefined;
+  const channelsRaw = value.channels;
+  const channels = Array.isArray(channelsRaw)
+    ? (channelsRaw
+        .map((entry) => {
+          if (!isRecord(entry)) {
+            return null;
+          }
+          const channelId = asString(entry.channelId);
+          if (!channelId) {
+            return null;
+          }
+          const ok = typeof entry.ok === "boolean" ? entry.ok : undefined;
+          const missing = Array.isArray(entry.missing)
+            ? entry.missing.map((v) => asString(v)).filter(Boolean)
+            : undefined;
+          const error = asString(entry.error) ?? null;
+          const matchKey = asString(entry.matchKey) ?? undefined;
+          const matchSource = asString(entry.matchSource) ?? undefined;
+          return {
+            channelId,
+            ok,
+            missing: missing?.length ? missing : undefined,
+            error,
+            matchKey,
+            matchSource,
+          };
+        })
+        .filter(Boolean) as DiscordPermissionsAuditSummary["channels"])
+    : undefined;
+  return { unresolvedChannels, channels };
+}
+
+export function collectDiscordStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readDiscordAccountStatus(entry);
+    if (!account) {
+      continue;
+    }
+    const accountId = resolveEnabledConfiguredAccountId(account);
+    if (!accountId) {
+      continue;
+    }
+
+    const app = readDiscordApplicationSummary(account.application);
+    const messageContent = app.intents?.messageContent;
+    if (messageContent === "disabled") {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "intent",
+        message: "Message Content Intent is disabled. Bot may not see normal channel messages.",
+        fix: "Enable Message Content Intent in Discord Dev Portal → Bot → Privileged Gateway Intents, or require mention-only operation.",
+      });
+    }
+
+    const audit = readDiscordPermissionsAuditSummary(account.audit);
+    if (audit.unresolvedChannels && audit.unresolvedChannels > 0) {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "config",
+        message: `Some configured guild channels are not numeric IDs (unresolvedChannels=${audit.unresolvedChannels}). Permission audit can only check numeric channel IDs.`,
+        fix: "Use numeric channel IDs as keys in channels.discord.guilds.*.channels (then rerun channels status --probe).",
+      });
+    }
+    for (const channel of audit.channels ?? []) {
+      if (channel.ok === true) {
+        continue;
+      }
+      const missing = channel.missing?.length ? ` missing ${channel.missing.join(", ")}` : "";
+      const error = channel.error ? `: ${channel.error}` : "";
+      const baseMessage = `Channel ${channel.channelId} permission check failed.${missing}${error}`;
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "permissions",
+        message: appendMatchMetadata(baseMessage, {
+          matchKey: channel.matchKey,
+          matchSource: channel.matchSource,
+        }),
+        fix: "Ensure the bot role can view + send in this channel (and that channel overrides don't deny it).",
+      });
+    }
+  }
+  return issues;
+}