@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/config-schema.test.ts

@@ -0,0 +1,325 @@
+import { describe, expect, it } from "vitest";
+import { DiscordConfigSchema } from "../config-api.js";
+
+function expectValidDiscordConfig(config: unknown) {
+  const res = DiscordConfigSchema.safeParse(config);
+  expect(res.success).toBe(true);
+  if (!res.success) {
+    throw new Error("expected Discord config to be valid");
+  }
+  return res.data;
+}
+
+function expectInvalidDiscordConfig(config: unknown) {
+  const res = DiscordConfigSchema.safeParse(config);
+  expect(res.success).toBe(false);
+  if (res.success) {
+    throw new Error("expected Discord config to be invalid");
+  }
+  return res.error.issues;
+}
+
+describe("discord config schema", () => {
+  it('rejects dmPolicy="open" without allowFrom "*"', () => {
+    const issues = expectInvalidDiscordConfig({
+      dmPolicy: "open",
+      allowFrom: ["123"],
+    });
+
+    expect(issues[0]?.path.join(".")).toBe("allowFrom");
+  });
+
+  it('rejects dmPolicy="open" with empty allowFrom', () => {
+    const issues = expectInvalidDiscordConfig({
+      dmPolicy: "open",
+      allowFrom: [],
+    });
+
+    expect(issues[0]?.path.join(".")).toBe("allowFrom");
+  });
+
+  it('rejects legacy dm.policy="open" with empty dm.allowFrom', () => {
+    const issues = expectInvalidDiscordConfig({
+      dm: { policy: "open", allowFrom: [] },
+    });
+
+    expect(issues[0]?.path.join(".")).toBe("dm.allowFrom");
+  });
+
+  it('accepts legacy dm.policy="open" with top-level allowFrom alias', () => {
+    expectValidDiscordConfig({
+      dm: { policy: "open", allowFrom: ["123"] },
+      allowFrom: ["*"],
+    });
+  });
+
+  it("accepts textChunkLimit without reviving legacy message limits", () => {
+    const cfg = expectValidDiscordConfig({
+      enabled: true,
+      textChunkLimit: 1999,
+      maxLinesPerMessage: 17,
+    });
+
+    expect(cfg.textChunkLimit).toBe(1999);
+    expect(cfg.maxLinesPerMessage).toBe(17);
+  });
+
+  it("defaults groupPolicy to allowlist", () => {
+    const cfg = expectValidDiscordConfig({});
+
+    expect(cfg.groupPolicy).toBe("allowlist");
+  });
+
+  it("accepts historyLimit", () => {
+    const cfg = expectValidDiscordConfig({ historyLimit: 3 });
+
+    expect(cfg.historyLimit).toBe(3);
+  });
+
+  it("accepts Discord application IDs at top-level and account scope", () => {
+    const cfg = expectValidDiscordConfig({
+      applicationId: "123456789012345678",
+      accounts: {
+        work: {
+          applicationId: 234567890123456,
+        },
+      },
+    });
+
+    expect(cfg.applicationId).toBe("123456789012345678");
+    expect(cfg.accounts?.work?.applicationId).toBe("234567890123456");
+  });
+
+  it("rejects unsafe numeric Discord application IDs", () => {
+    const issues = expectInvalidDiscordConfig({
+      applicationId: 106232522769186816,
+    });
+
+    expect(
+      issues.some((issue) => issue.message.includes("not a valid non-negative safe integer")),
+    ).toBe(true);
+  });
+
+  it("loads guild map and dm group settings", () => {
+    const cfg = expectValidDiscordConfig({
+      enabled: true,
+      dm: {
+        enabled: true,
+        allowFrom: ["steipete"],
+        groupEnabled: true,
+        groupChannels: ["openclaw-dm"],
+      },
+      actions: {
+        emojiUploads: true,
+        stickerUploads: false,
+        channels: true,
+      },
+      guilds: {
+        "123": {
+          slug: "friends-of-openclaw",
+          requireMention: false,
+          users: ["steipete"],
+          channels: {
+            general: { enabled: true, autoThread: true },
+          },
+        },
+      },
+    });
+
+    expect(cfg.enabled).toBe(true);
+    expect(cfg.dm?.groupEnabled).toBe(true);
+    expect(cfg.dm?.groupChannels).toEqual(["openclaw-dm"]);
+    expect(cfg.actions?.emojiUploads).toBe(true);
+    expect(cfg.actions?.stickerUploads).toBe(false);
+    expect(cfg.actions?.channels).toBe(true);
+    expect(cfg.guilds?.["123"]?.slug).toBe("friends-of-openclaw");
+    expect(cfg.guilds?.["123"]?.channels?.general?.enabled).toBe(true);
+    expect(cfg.guilds?.["123"]?.channels?.general?.autoThread).toBe(true);
+  });
+
+  it("accepts voice model override field", () => {
+    const cfg = expectValidDiscordConfig({
+      voice: {
+        model: "openai/gpt-5.4-mini",
+      },
+    });
+
+    expect(cfg.voice?.model).toBe("openai/gpt-5.4-mini");
+  });
+
+  it("accepts Discord voice timing overrides", () => {
+    const cfg = expectValidDiscordConfig({
+      voice: {
+        connectTimeoutMs: 45_000,
+        reconnectGraceMs: 20_000,
+      },
+    });
+
+    expect(cfg.voice?.connectTimeoutMs).toBe(45_000);
+    expect(cfg.voice?.reconnectGraceMs).toBe(20_000);
+  });
+
+  it("rejects invalid Discord voice timing overrides", () => {
+    for (const voice of [
+      { connectTimeoutMs: 0 },
+      { connectTimeoutMs: 120_001 },
+      { reconnectGraceMs: -1 },
+      { reconnectGraceMs: 1.5 },
+    ]) {
+      expectInvalidDiscordConfig({ voice });
+    }
+  });
+
+  it("coerces safe-integer numeric allowlist entries to strings", () => {
+    const cfg = expectValidDiscordConfig({
+      allowFrom: [123],
+      dm: { allowFrom: [456], groupChannels: [789] },
+      guilds: {
+        "123": {
+          users: [111],
+          roles: [222],
+          channels: {
+            general: { users: [333], roles: [444] },
+          },
+        },
+      },
+      execApprovals: { approvers: [555] },
+    });
+
+    expect(cfg.allowFrom).toEqual(["123"]);
+    expect(cfg.dm?.allowFrom).toEqual(["456"]);
+    expect(cfg.dm?.groupChannels).toEqual(["789"]);
+    expect(cfg.guilds?.["123"]?.users).toEqual(["111"]);
+    expect(cfg.guilds?.["123"]?.roles).toEqual(["222"]);
+    expect(cfg.guilds?.["123"]?.channels?.general?.users).toEqual(["333"]);
+    expect(cfg.guilds?.["123"]?.channels?.general?.roles).toEqual(["444"]);
+    expect(cfg.execApprovals?.approvers).toEqual(["555"]);
+  });
+
+  it("rejects numeric IDs that are not valid non-negative safe integers", () => {
+    const cases = [106232522769186816, -1, 123.45];
+    for (const id of cases) {
+      const issues = expectInvalidDiscordConfig({ allowFrom: [id] });
+
+      expect(
+        issues.some((issue) => issue.message.includes("not a valid non-negative safe integer")),
+      ).toBe(true);
+    }
+  });
+
+  it.each([
+    { name: "status-only presence", config: { status: "idle" } },
+    {
+      name: "custom activity when type is omitted",
+      config: { activity: "Focus time" },
+    },
+    {
+      name: "custom activity type",
+      config: { activity: "Chilling", activityType: 4 },
+    },
+    {
+      name: "auto presence config",
+      config: {
+        autoPresence: {
+          enabled: true,
+          intervalMs: 30000,
+          minUpdateIntervalMs: 15000,
+          exhaustedText: "token exhausted",
+        },
+      },
+    },
+  ] as const)("accepts $name", ({ config }) => {
+    expect(DiscordConfigSchema.safeParse(config).success).toBe(true);
+  });
+
+  it.each([
+    {
+      name: "streaming activity without url",
+      config: { activity: "Live", activityType: 1 },
+    },
+    {
+      name: "activityUrl without streaming type",
+      config: { activity: "Live", activityUrl: "https://twitch.tv/openclaw" },
+    },
+    {
+      name: "auto presence min update interval above check interval",
+      config: {
+        autoPresence: {
+          enabled: true,
+          intervalMs: 5000,
+          minUpdateIntervalMs: 6000,
+        },
+      },
+    },
+  ] as const)("rejects $name", ({ config }) => {
+    expect(DiscordConfigSchema.safeParse(config).success).toBe(false);
+  });
+
+  it("accepts agentComponents.enabled at channel scope", () => {
+    const res = DiscordConfigSchema.safeParse({
+      agentComponents: {
+        enabled: true,
+      },
+    });
+
+    expect(res.success).toBe(true);
+  });
+
+  it("accepts agentComponents.enabled at account scope", () => {
+    const res = DiscordConfigSchema.safeParse({
+      accounts: {
+        work: {
+          agentComponents: {
+            enabled: false,
+          },
+        },
+      },
+    });
+
+    expect(res.success).toBe(true);
+  });
+
+  it("accepts thread.inheritParent at top-level and account scope", () => {
+    const cases = [
+      {
+        thread: {
+          inheritParent: true,
+        },
+      },
+      {
+        accounts: {
+          work: {
+            thread: {
+              inheritParent: true,
+            },
+          },
+        },
+      },
+    ] as const;
+
+    for (const config of cases) {
+      const res = DiscordConfigSchema.safeParse(config);
+      expect(res.success).toBe(true);
+    }
+  });
+
+  it("rejects unknown fields under agentComponents", () => {
+    const res = DiscordConfigSchema.safeParse({
+      agentComponents: {
+        enabled: true,
+        invalidField: true,
+      },
+    });
+
+    expect(res.success).toBe(false);
+    if (!res.success) {
+      expect(
+        res.error.issues.some(
+          (issue) =>
+            issue.path.join(".") === "agentComponents" &&
+            issue.message.toLowerCase().includes("unrecognized"),
+        ),
+      ).toBe(true);
+    }
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,6 @@
+import { buildChannelConfigSchema, DiscordConfigSchema } from "../config-api.js";
+import { discordChannelConfigUiHints } from "./config-ui-hints.js";
+
+export const DiscordChannelConfigSchema = buildChannelConfigSchema(DiscordConfigSchema, {
+  uiHints: discordChannelConfigUiHints,
+});

package/src/config-ui-hints.ts

@@ -0,0 +1,249 @@
+import type { ChannelConfigUiHint } from "openclaw/plugin-sdk/channel-core";
+
+export const discordChannelConfigUiHints = {
+  "": {
+    label: "Discord",
+    help: "Discord channel provider configuration for bot auth, retry policy, streaming, thread bindings, and optional voice capabilities. Keep privileged intents and advanced features disabled unless needed.",
+  },
+  dmPolicy: {
+    label: "Discord DM Policy",
+    help: 'Direct message access control ("pairing" recommended). "open" requires channels.discord.allowFrom=["*"].',
+  },
+  "dm.policy": {
+    label: "Discord DM Policy",
+    help: 'Direct message access control ("pairing" recommended). "open" requires channels.discord.allowFrom=["*"] (legacy: channels.discord.dm.allowFrom).',
+  },
+  configWrites: {
+    label: "Discord Config Writes",
+    help: "Allow Discord to write config in response to channel events/commands (default: true).",
+  },
+  proxy: {
+    label: "Discord Proxy URL",
+    help: "Proxy URL for Discord gateway + API requests (app-id lookup and allowlist resolution). Set per account via channels.discord.accounts.<id>.proxy.",
+  },
+  "commands.native": {
+    label: "Discord Native Commands",
+    help: 'Override native commands for Discord (bool or "auto").',
+  },
+  "commands.nativeSkills": {
+    label: "Discord Native Skill Commands",
+    help: 'Override native skill commands for Discord (bool or "auto").',
+  },
+  streaming: {
+    label: "Discord Streaming Mode",
+    help: 'Unified Discord stream preview mode: "off" | "partial" | "block" | "progress". "progress" maps to "partial" on Discord. Legacy boolean/streamMode keys are auto-mapped.',
+  },
+  "streaming.mode": {
+    label: "Discord Streaming Mode",
+    help: 'Canonical Discord preview mode: "off" | "partial" | "block" | "progress". "progress" maps to "partial" on Discord.',
+  },
+  "streaming.chunkMode": {
+    label: "Discord Chunk Mode",
+    help: 'Chunking mode for outbound Discord text delivery: "length" (default) or "newline".',
+  },
+  "streaming.block.enabled": {
+    label: "Discord Block Streaming Enabled",
+    help: 'Enable chunked block-style Discord preview delivery when channels.discord.streaming.mode="block".',
+  },
+  "streaming.block.coalesce": {
+    label: "Discord Block Streaming Coalesce",
+    help: "Merge streamed Discord block replies before final delivery.",
+  },
+  "streaming.preview.chunk.minChars": {
+    label: "Discord Draft Chunk Min Chars",
+    help: 'Minimum chars before emitting a Discord stream preview update when channels.discord.streaming.mode="block" (default: 200).',
+  },
+  "streaming.preview.chunk.maxChars": {
+    label: "Discord Draft Chunk Max Chars",
+    help: 'Target max size for a Discord stream preview chunk when channels.discord.streaming.mode="block" (default: 800; clamped to channels.discord.textChunkLimit).',
+  },
+  "streaming.preview.chunk.breakPreference": {
+    label: "Discord Draft Chunk Break Preference",
+    help: "Preferred breakpoints for Discord draft chunks (paragraph | newline | sentence). Default: paragraph.",
+  },
+  "streaming.preview.toolProgress": {
+    label: "Discord Draft Tool Progress",
+    help: "Show tool/progress activity in the live draft preview message (default: true). Set false to keep tool updates as separate messages.",
+  },
+  "retry.attempts": {
+    label: "Discord Retry Attempts",
+    help: "Max retry attempts for outbound Discord API calls (default: 3).",
+  },
+  "retry.minDelayMs": {
+    label: "Discord Retry Min Delay (ms)",
+    help: "Minimum retry delay in ms for Discord outbound calls.",
+  },
+  "retry.maxDelayMs": {
+    label: "Discord Retry Max Delay (ms)",
+    help: "Maximum retry delay cap in ms for Discord outbound calls.",
+  },
+  "retry.jitter": {
+    label: "Discord Retry Jitter",
+    help: "Jitter factor (0-1) applied to Discord retry delays.",
+  },
+  maxLinesPerMessage: {
+    label: "Discord Max Lines Per Message",
+    help: "Soft max line count per Discord message (default: 17).",
+  },
+  "thread.inheritParent": {
+    label: "Discord Thread Parent Inheritance",
+    help: "If true, Discord thread sessions inherit the parent channel transcript (default: false).",
+  },
+  "eventQueue.listenerTimeout": {
+    label: "Discord EventQueue Listener Timeout (ms)",
+    help: "Canonical Discord listener timeout control in ms for gateway normalization/enqueue handlers. Default is 120000 in OpenClaw; set per account via channels.discord.accounts.<id>.eventQueue.listenerTimeout.",
+  },
+  "eventQueue.maxQueueSize": {
+    label: "Discord EventQueue Max Queue Size",
+    help: "Optional Discord EventQueue capacity override (max queued events before backpressure). Set per account via channels.discord.accounts.<id>.eventQueue.maxQueueSize.",
+  },
+  "eventQueue.maxConcurrency": {
+    label: "Discord EventQueue Max Concurrency",
+    help: "Optional Discord EventQueue concurrency override (max concurrent handler executions). Set per account via channels.discord.accounts.<id>.eventQueue.maxConcurrency.",
+  },
+  "threadBindings.enabled": {
+    label: "Discord Thread Binding Enabled",
+    help: "Enable Discord thread binding features (/focus, bound-thread routing/delivery, and thread-bound subagent sessions). Overrides session.threadBindings.enabled when set.",
+  },
+  "threadBindings.idleHours": {
+    label: "Discord Thread Binding Idle Timeout (hours)",
+    help: "Inactivity window in hours for Discord thread-bound sessions (/focus and spawned thread sessions). Set 0 to disable idle auto-unfocus (default: 24). Overrides session.threadBindings.idleHours when set.",
+  },
+  "threadBindings.maxAgeHours": {
+    label: "Discord Thread Binding Max Age (hours)",
+    help: "Optional hard max age in hours for Discord thread-bound sessions. Set 0 to disable hard cap (default: 0). Overrides session.threadBindings.maxAgeHours when set.",
+  },
+  "threadBindings.spawnSessions": {
+    label: "Discord Thread-Bound Session Spawn",
+    help: "Allow sessions_spawn(thread=true) and ACP thread spawns to auto-create and bind Discord threads (default: true). Set false to disable for this account/channel.",
+  },
+  "threadBindings.defaultSpawnContext": {
+    label: "Discord Thread Spawn Context",
+    help: 'Default native subagent context for thread-bound spawns. "fork" starts from the requester transcript; "isolated" starts clean. Default: "fork".',
+  },
+  "ui.components.accentColor": {
+    label: "Discord Component Accent Color",
+    help: "Accent color for Discord component containers (hex). Set per account via channels.discord.accounts.<id>.ui.components.accentColor.",
+  },
+  "intents.presence": {
+    label: "Discord Presence Intent",
+    help: "Enable the Guild Presences privileged intent. Must also be enabled in the Discord Developer Portal. Allows tracking user activities (e.g. Spotify). Default: false.",
+  },
+  "intents.guildMembers": {
+    label: "Discord Guild Members Intent",
+    help: "Enable the Guild Members privileged intent. Must also be enabled in the Discord Developer Portal. Default: false.",
+  },
+  "intents.voiceStates": {
+    label: "Discord Voice States Intent",
+    help: "Enable the Guild Voice States intent. Defaults to the effective Discord voice setting; set true only for Discord voice channel conversations.",
+  },
+  gatewayInfoTimeoutMs: {
+    label: "Discord Gateway Metadata Timeout (ms)",
+    help: "Timeout for Discord /gateway/bot metadata lookup before falling back to the default gateway URL. Default is 30000; OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS can override when config is unset.",
+  },
+  gatewayReadyTimeoutMs: {
+    label: "Discord Gateway READY Timeout (ms)",
+    help: "Startup wait for the Discord gateway READY event before restarting the socket. Default is 15000; OPENCLAW_DISCORD_READY_TIMEOUT_MS can override when config is unset.",
+  },
+  gatewayRuntimeReadyTimeoutMs: {
+    label: "Discord Gateway Runtime READY Timeout (ms)",
+    help: "Runtime reconnect wait for the Discord gateway READY event before force-stopping the lifecycle. Default is 30000; OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS can override when config is unset.",
+  },
+  "voice.enabled": {
+    label: "Discord Voice Enabled",
+    help: "Enable Discord voice channel conversations. Text-only Discord configs leave voice off by default; set true to enable /vc commands and the Guild Voice States intent.",
+  },
+  "voice.model": {
+    label: "Discord Voice Model",
+    help: "Optional LLM model override for Discord voice channel responses (for example openai/gpt-5.4-mini). Leave unset to inherit the routed agent model.",
+  },
+  "voice.autoJoin": {
+    label: "Discord Voice Auto-Join",
+    help: "Voice channels to auto-join on startup (list of guildId/channelId entries).",
+  },
+  "voice.daveEncryption": {
+    label: "Discord Voice DAVE Encryption",
+    help: "Toggle DAVE end-to-end encryption for Discord voice joins (default: true in @discordjs/voice; Discord may require this).",
+  },
+  "voice.decryptionFailureTolerance": {
+    label: "Discord Voice Decrypt Failure Tolerance",
+    help: "Consecutive decrypt failures before DAVE attempts session recovery (passed to @discordjs/voice; default: 24).",
+  },
+  "voice.connectTimeoutMs": {
+    label: "Discord Voice Connect Timeout (ms)",
+    help: "Initial @discordjs/voice Ready wait before a join is treated as failed. Default: 30000.",
+  },
+  "voice.reconnectGraceMs": {
+    label: "Discord Voice Reconnect Grace (ms)",
+    help: "Grace period for a disconnected Discord voice session to enter Signalling or Connecting before OpenClaw destroys it. Default: 15000.",
+  },
+  "voice.tts": {
+    label: "Discord Voice Text-to-Speech",
+    help: "Optional TTS overrides for Discord voice playback (merged with messages.tts).",
+  },
+  "pluralkit.enabled": {
+    label: "Discord PluralKit Enabled",
+    help: "Resolve PluralKit proxied messages and treat system members as distinct senders.",
+  },
+  "pluralkit.token": {
+    label: "Discord PluralKit Token",
+    help: "Optional PluralKit token for resolving private systems or members.",
+  },
+  activity: {
+    label: "Discord Presence Activity",
+    help: "Discord presence activity text (defaults to custom status).",
+  },
+  status: {
+    label: "Discord Presence Status",
+    help: "Discord presence status (online, dnd, idle, invisible).",
+  },
+  "autoPresence.enabled": {
+    label: "Discord Auto Presence Enabled",
+    help: "Enable automatic Discord bot presence updates based on runtime/model availability signals. When enabled: healthy=>online, degraded/unknown=>idle, exhausted/unavailable=>dnd.",
+  },
+  "autoPresence.intervalMs": {
+    label: "Discord Auto Presence Check Interval (ms)",
+    help: "How often to evaluate Discord auto-presence state in milliseconds (default: 30000).",
+  },
+  "autoPresence.minUpdateIntervalMs": {
+    label: "Discord Auto Presence Min Update Interval (ms)",
+    help: "Minimum time between actual Discord presence update calls in milliseconds (default: 15000). Prevents status spam on noisy state changes.",
+  },
+  "autoPresence.healthyText": {
+    label: "Discord Auto Presence Healthy Text",
+    help: "Optional custom status text while runtime is healthy (online). If omitted, falls back to static channels.discord.activity when set.",
+  },
+  "autoPresence.degradedText": {
+    label: "Discord Auto Presence Degraded Text",
+    help: "Optional custom status text while runtime/model availability is degraded or unknown (idle).",
+  },
+  "autoPresence.exhaustedText": {
+    label: "Discord Auto Presence Exhausted Text",
+    help: "Optional custom status text while runtime detects exhausted/unavailable model quota (dnd). Supports {reason} template placeholder.",
+  },
+  activityType: {
+    label: "Discord Presence Activity Type",
+    help: "Discord presence activity type (0=Playing,1=Streaming,2=Listening,3=Watching,4=Custom,5=Competing).",
+  },
+  activityUrl: {
+    label: "Discord Presence Activity URL",
+    help: "Discord presence streaming URL (required for activityType=1).",
+  },
+  allowBots: {
+    label: "Discord Allow Bot Messages",
+    help: 'Allow bot-authored messages to trigger Discord replies (default: false). Set "mentions" to only accept bot messages that mention the bot.',
+  },
+  mentionAliases: {
+    label: "Discord Mention Aliases",
+    help: "Map outbound @handle text to stable Discord user IDs before sending. Set per account via channels.discord.accounts.<id>.mentionAliases.",
+  },
+  token: {
+    label: "Discord Bot Token",
+    help: "Discord bot token used for gateway and REST API authentication for this provider account. Keep this secret out of committed config and rotate immediately after any leak.",
+    sensitive: true,
+  },
+  applicationId: {
+    label: "Discord Application ID",
+    help: "Optional Discord application/client ID. Set this when hosted environments cannot reach Discord's application lookup endpoint during startup.",
+  },
+} satisfies Record<string, ChannelConfigUiHint>;

package/src/conversation-identity.ts

@@ -0,0 +1,58 @@
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
+import { parseDiscordTarget } from "./target-parsing.js";
+
+function normalizeDiscordTarget(
+  raw: string | null | undefined,
+  defaultKind: "user" | "channel",
+): string | undefined {
+  const trimmed = normalizeOptionalString(raw);
+  if (!trimmed) {
+    return undefined;
+  }
+  return parseDiscordTarget(trimmed, { defaultKind })?.normalized;
+}
+
+function buildDiscordConversationIdentity(
+  kind: "user" | "channel",
+  rawId: string | null | undefined,
+): string | undefined {
+  const trimmed = normalizeOptionalString(rawId);
+  return trimmed ? `${kind}:${trimmed}` : undefined;
+}
+
+export function resolveDiscordConversationIdentity(params: {
+  isDirectMessage: boolean;
+  userId?: string | null;
+  channelId?: string | null;
+}): string | undefined {
+  return params.isDirectMessage
+    ? buildDiscordConversationIdentity("user", params.userId)
+    : buildDiscordConversationIdentity("channel", params.channelId);
+}
+
+export function resolveDiscordCurrentConversationIdentity(params: {
+  chatType?: string | null;
+  from?: string | null;
+  originatingTo?: string | null;
+  commandTo?: string | null;
+  fallbackTo?: string | null;
+}): string | undefined {
+  if (normalizeOptionalLowercaseString(params.chatType) === "direct") {
+    const senderTarget = normalizeDiscordTarget(params.from, "user");
+    if (senderTarget?.startsWith("user:")) {
+      return senderTarget;
+    }
+  }
+
+  for (const candidate of [params.originatingTo, params.commandTo, params.fallbackTo]) {
+    const target = normalizeDiscordTarget(candidate, "channel");
+    if (target) {
+      return target;
+    }
+  }
+
+  return undefined;
+}

package/src/delivery-retry.ts

@@ -0,0 +1,56 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  resolveRetryConfig,
+  retryAsync,
+  type RetryConfig,
+} from "openclaw/plugin-sdk/retry-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
+import { DiscordError } from "./internal/discord.js";
+
+const DISCORD_DELIVERY_RETRY_DEFAULTS = {
+  attempts: 3,
+  minDelayMs: 1000,
+  maxDelayMs: 30_000,
+  jitter: 0,
+} satisfies Required<RetryConfig>;
+
+export function isRetryableDiscordDeliveryError(err: unknown): boolean {
+  if (err instanceof DiscordError) {
+    return false;
+  }
+  const status = (err as { status?: number }).status ?? (err as { statusCode?: number }).statusCode;
+  return status === 429 || (status !== undefined && status >= 500);
+}
+
+function getDiscordDeliveryRetryAfterMs(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  if (
+    "retryAfter" in err &&
+    typeof err.retryAfter === "number" &&
+    Number.isFinite(err.retryAfter)
+  ) {
+    return err.retryAfter * 1000;
+  }
+  const retryAfterRaw = (err as { headers?: Record<string, string> }).headers?.["retry-after"];
+  if (!retryAfterRaw) {
+    return undefined;
+  }
+  const retryAfterMs = Number(retryAfterRaw) * 1000;
+  return Number.isFinite(retryAfterMs) ? retryAfterMs : undefined;
+}
+
+export async function withDiscordDeliveryRetry<T>(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  fn: () => Promise<T>;
+}): Promise<T> {
+  const account = resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId });
+  const retryConfig = resolveRetryConfig(DISCORD_DELIVERY_RETRY_DEFAULTS, account.config.retry);
+  return await retryAsync(params.fn, {
+    ...retryConfig,
+    shouldRetry: (err) => isRetryableDiscordDeliveryError(err),
+    retryAfterMs: getDiscordDeliveryRetryAfterMs,
+  });
+}