@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/monitor/native-interaction-channel-context.ts

@@ -0,0 +1,50 @@
+import { ChannelType } from "../internal/discord.js";
+import type { DiscordChannelInfoClient } from "./message-utils.js";
+import { resolveDiscordThreadLikeChannelContext } from "./thread-channel-context.js";
+
+type DiscordInteractionChannel = {
+  id?: string;
+  type?: ChannelType;
+};
+
+type DiscordNativeInteractionChannelContext = {
+  channelType?: ChannelType;
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  isThreadChannel: boolean;
+  channelName?: string;
+  channelSlug: string;
+  rawChannelId: string;
+  threadParentId?: string;
+  threadParentName?: string;
+  threadParentSlug: string;
+};
+
+export async function resolveDiscordNativeInteractionChannelContext(params: {
+  channel: DiscordInteractionChannel | null | undefined;
+  client: DiscordChannelInfoClient;
+  hasGuild: boolean;
+  channelIdFallback: string;
+}): Promise<DiscordNativeInteractionChannelContext> {
+  const channelContext = await resolveDiscordThreadLikeChannelContext({
+    client: params.client,
+    channel: params.channel,
+    channelIdFallback: params.channelIdFallback,
+  });
+  const channelType = channelContext.channelType;
+  const isDirectMessage = channelType === ChannelType.DM;
+  const isGroupDm = channelType === ChannelType.GroupDM;
+
+  return {
+    channelType,
+    isDirectMessage,
+    isGroupDm,
+    isThreadChannel: channelContext.isThreadChannel,
+    channelName: channelContext.channelName,
+    channelSlug: channelContext.channelSlug,
+    rawChannelId: channelContext.channelId,
+    threadParentId: params.hasGuild ? channelContext.threadParentId : undefined,
+    threadParentName: params.hasGuild ? channelContext.threadParentName : undefined,
+    threadParentSlug: params.hasGuild ? channelContext.threadParentSlug : "",
+  };
+}

package/src/monitor/preflight-audio.runtime.ts

@@ -0,0 +1,9 @@
+import { transcribeFirstAudio as transcribeFirstAudioImpl } from "openclaw/plugin-sdk/media-runtime";
+
+type TranscribeFirstAudio = typeof import("openclaw/plugin-sdk/media-runtime").transcribeFirstAudio;
+
+export async function transcribeFirstAudio(
+  ...args: Parameters<TranscribeFirstAudio>
+): ReturnType<TranscribeFirstAudio> {
+  return await transcribeFirstAudioImpl(...args);
+}

package/src/monitor/preflight-audio.test.ts

@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const transcribeFirstAudioMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./preflight-audio.runtime.js", () => ({
+  transcribeFirstAudio: transcribeFirstAudioMock,
+}));
+
+import { resolveDiscordPreflightAudioMentionContext } from "./preflight-audio.js";
+
+const cfg = {} as import("openclaw/plugin-sdk/config-types").OpenClawConfig;
+
+describe("resolveDiscordPreflightAudioMentionContext", () => {
+  beforeEach(() => {
+    transcribeFirstAudioMock.mockReset();
+  });
+
+  it("preflights direct-message audio without requiring a mention", async () => {
+    transcribeFirstAudioMock.mockResolvedValue("hello from dm");
+
+    const result = await resolveDiscordPreflightAudioMentionContext({
+      message: {
+        attachments: [
+          {
+            url: "https://cdn.discordapp.com/attachments/voice.ogg",
+            content_type: "audio/ogg",
+            filename: "voice.ogg",
+          },
+        ],
+      },
+      isDirectMessage: true,
+      shouldRequireMention: false,
+      mentionRegexes: [],
+      cfg,
+    });
+
+    expect(transcribeFirstAudioMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          MediaUrls: ["https://cdn.discordapp.com/attachments/voice.ogg"],
+          MediaTypes: ["audio/ogg"],
+        }),
+      }),
+    );
+    expect(result).toEqual({
+      hasAudioAttachment: true,
+      hasTypedText: false,
+      transcript: "hello from dm",
+    });
+  });
+
+  it("preflights audio by filename when Discord omits content type", async () => {
+    transcribeFirstAudioMock.mockResolvedValue("filename transcript");
+
+    await resolveDiscordPreflightAudioMentionContext({
+      message: {
+        attachments: [
+          {
+            url: "https://cdn.discordapp.com/attachments/voice.opus",
+            filename: "voice.opus",
+          },
+        ],
+      },
+      isDirectMessage: true,
+      shouldRequireMention: false,
+      mentionRegexes: [],
+      cfg,
+    });
+
+    expect(transcribeFirstAudioMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          MediaUrls: ["https://cdn.discordapp.com/attachments/voice.opus"],
+          MediaTypes: ["audio/opus"],
+        }),
+      }),
+    );
+  });
+
+  it("preflights Discord voice attachments by waveform metadata", async () => {
+    transcribeFirstAudioMock.mockResolvedValue("metadata transcript");
+
+    await resolveDiscordPreflightAudioMentionContext({
+      message: {
+        attachments: [
+          {
+            url: " https://cdn.discordapp.com/attachments/voice ",
+            filename: "voice",
+            duration_secs: 1.5,
+            waveform: "AAAA",
+          },
+        ],
+      },
+      isDirectMessage: true,
+      shouldRequireMention: false,
+      mentionRegexes: [],
+      cfg,
+    });
+
+    expect(transcribeFirstAudioMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          MediaUrls: ["https://cdn.discordapp.com/attachments/voice"],
+          MediaTypes: ["audio/ogg"],
+        }),
+      }),
+    );
+  });
+
+  it("does not preflight typed direct-message audio", async () => {
+    const result = await resolveDiscordPreflightAudioMentionContext({
+      message: {
+        content: "typed caption",
+        attachments: [
+          {
+            url: "https://cdn.discordapp.com/attachments/voice.ogg",
+            content_type: "audio/ogg",
+            filename: "voice.ogg",
+          },
+        ],
+      },
+      isDirectMessage: true,
+      shouldRequireMention: false,
+      mentionRegexes: [],
+      cfg,
+    });
+
+    expect(transcribeFirstAudioMock).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      hasAudioAttachment: true,
+      hasTypedText: true,
+    });
+  });
+
+  it("ignores URL-less audio attachments", async () => {
+    const result = await resolveDiscordPreflightAudioMentionContext({
+      message: {
+        attachments: [
+          {
+            content_type: "audio/ogg",
+            filename: "voice.ogg",
+          },
+        ],
+      },
+      isDirectMessage: true,
+      shouldRequireMention: false,
+      mentionRegexes: [],
+      cfg,
+    });
+
+    expect(transcribeFirstAudioMock).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      hasAudioAttachment: false,
+      hasTypedText: false,
+    });
+  });
+});

package/src/monitor/preflight-audio.ts

@@ -0,0 +1,130 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { getFileExtension } from "openclaw/plugin-sdk/media-mime";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+
+type DiscordPreflightAudioRuntime = typeof import("./preflight-audio.runtime.js");
+
+let discordPreflightAudioRuntimePromise: Promise<DiscordPreflightAudioRuntime> | undefined;
+
+function loadDiscordPreflightAudioRuntime(): Promise<DiscordPreflightAudioRuntime> {
+  discordPreflightAudioRuntimePromise ??= import("./preflight-audio.runtime.js");
+  return discordPreflightAudioRuntimePromise;
+}
+
+type DiscordAudioAttachment = {
+  content_type?: string;
+  duration_secs?: number;
+  filename?: string;
+  url?: string;
+  waveform?: string;
+};
+
+const AUDIO_ATTACHMENT_MIME_BY_EXT = new Map([
+  [".aac", "audio/aac"],
+  [".caf", "audio/x-caf"],
+  [".flac", "audio/flac"],
+  [".m4a", "audio/mp4"],
+  [".mp3", "audio/mpeg"],
+  [".oga", "audio/ogg"],
+  [".ogg", "audio/ogg"],
+  [".opus", "audio/opus"],
+  [".wav", "audio/wav"],
+]);
+
+function inferAudioAttachmentMime(attachment: DiscordAudioAttachment): string | undefined {
+  const contentType = normalizeOptionalString(attachment.content_type);
+  if (contentType?.startsWith("audio/")) {
+    return contentType;
+  }
+  if (
+    typeof attachment.duration_secs === "number" ||
+    typeof normalizeOptionalString(attachment.waveform) === "string"
+  ) {
+    return "audio/ogg";
+  }
+  const ext = getFileExtension(attachment.filename ?? attachment.url);
+  return ext ? AUDIO_ATTACHMENT_MIME_BY_EXT.get(ext) : undefined;
+}
+
+function collectAudioAttachments(
+  attachments: DiscordAudioAttachment[] | undefined,
+): DiscordAudioAttachment[] {
+  if (!Array.isArray(attachments)) {
+    return [];
+  }
+  return attachments.filter(
+    (att) => normalizeOptionalString(att.url) && inferAudioAttachmentMime(att),
+  );
+}
+
+export async function resolveDiscordPreflightAudioMentionContext(params: {
+  message: {
+    attachments?: DiscordAudioAttachment[];
+    content?: string;
+  };
+  isDirectMessage: boolean;
+  shouldRequireMention: boolean;
+  mentionRegexes: RegExp[];
+  cfg: OpenClawConfig;
+  abortSignal?: AbortSignal;
+}): Promise<{
+  hasAudioAttachment: boolean;
+  hasTypedText: boolean;
+  transcript?: string;
+}> {
+  const audioAttachments = collectAudioAttachments(params.message.attachments);
+  const hasAudioAttachment = audioAttachments.length > 0;
+  const hasTypedText = Boolean(params.message.content?.trim());
+  const needsPreflightTranscription =
+    hasAudioAttachment &&
+    // `baseText` includes media placeholders; gate on typed text only.
+    !hasTypedText &&
+    (params.isDirectMessage || (params.shouldRequireMention && params.mentionRegexes.length > 0));
+
+  let transcript: string | undefined;
+  if (needsPreflightTranscription) {
+    if (params.abortSignal?.aborted) {
+      return {
+        hasAudioAttachment,
+        hasTypedText,
+      };
+    }
+    try {
+      const { transcribeFirstAudio } = await loadDiscordPreflightAudioRuntime();
+      if (params.abortSignal?.aborted) {
+        return {
+          hasAudioAttachment,
+          hasTypedText,
+        };
+      }
+      const audioUrls = audioAttachments
+        .map((att) => att.url)
+        .map((url) => normalizeOptionalString(url))
+        .filter((url): url is string => Boolean(url));
+      if (audioUrls.length > 0) {
+        transcript = await transcribeFirstAudio({
+          ctx: {
+            MediaUrls: audioUrls,
+            MediaTypes: audioAttachments
+              .map((att) => inferAudioAttachmentMime(att))
+              .filter((contentType): contentType is string => Boolean(contentType)),
+          },
+          cfg: params.cfg,
+          agentDir: undefined,
+        });
+        if (params.abortSignal?.aborted) {
+          transcript = undefined;
+        }
+      }
+    } catch (err) {
+      logVerbose(`discord: audio preflight transcription failed: ${String(err)}`);
+    }
+  }
+
+  return {
+    hasAudioAttachment,
+    hasTypedText,
+    transcript,
+  };
+}

package/src/monitor/presence-cache.ts

@@ -0,0 +1,61 @@
+import type { GatewayPresenceUpdate } from "discord-api-types/v10";
+
+/**
+ * In-memory cache of Discord user presence data.
+ * Populated by PRESENCE_UPDATE gateway events when the GuildPresences intent is enabled.
+ * Per-account maps are capped to prevent unbounded growth (#4948).
+ */
+const MAX_PRESENCE_PER_ACCOUNT = 5000;
+const presenceCache = new Map<string, Map<string, GatewayPresenceUpdate>>();
+
+function resolveAccountKey(accountId?: string): string {
+  return accountId ?? "default";
+}
+
+/** Update cached presence for a user. */
+export function setPresence(
+  accountId: string | undefined,
+  userId: string,
+  data: GatewayPresenceUpdate,
+): void {
+  const accountKey = resolveAccountKey(accountId);
+  let accountCache = presenceCache.get(accountKey);
+  if (!accountCache) {
+    accountCache = new Map();
+    presenceCache.set(accountKey, accountCache);
+  }
+  accountCache.set(userId, data);
+  // Evict oldest entries if cache exceeds limit
+  if (accountCache.size > MAX_PRESENCE_PER_ACCOUNT) {
+    const oldest = accountCache.keys().next().value;
+    if (oldest !== undefined) {
+      accountCache.delete(oldest);
+    }
+  }
+}
+
+/** Get cached presence for a user. Returns undefined if not cached. */
+export function getPresence(
+  accountId: string | undefined,
+  userId: string,
+): GatewayPresenceUpdate | undefined {
+  return presenceCache.get(resolveAccountKey(accountId))?.get(userId);
+}
+
+/** Clear cached presence data. */
+export function clearPresences(accountId?: string): void {
+  if (accountId) {
+    presenceCache.delete(resolveAccountKey(accountId));
+    return;
+  }
+  presenceCache.clear();
+}
+
+/** Get the number of cached presence entries. */
+export function presenceCacheSize(): number {
+  let total = 0;
+  for (const accountCache of presenceCache.values()) {
+    total += accountCache.size;
+  }
+  return total;
+}

package/src/monitor/presence.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { resolveDiscordPresenceUpdate } from "./presence.js";
+
+describe("resolveDiscordPresenceUpdate", () => {
+  it("returns online presence when no config is provided", () => {
+    const result = resolveDiscordPresenceUpdate({});
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe("online");
+    expect(result!.activities).toEqual([]);
+  });
+
+  it("uses configured status", () => {
+    const result = resolveDiscordPresenceUpdate({ status: "dnd" });
+    expect(result!.status).toBe("dnd");
+  });
+
+  it("includes activity when configured", () => {
+    const result = resolveDiscordPresenceUpdate({ activity: "Helping humans" });
+    expect(result!.status).toBe("online");
+    expect(result!.activities).toHaveLength(1);
+    expect(result!.activities[0].state).toBe("Helping humans");
+  });
+
+  it("uses custom activity type by default", () => {
+    const result = resolveDiscordPresenceUpdate({ activity: "test" });
+    expect(result!.activities[0].type).toBe(4);
+    expect(result!.activities[0].name).toBe("Custom Status");
+  });
+
+  it("respects explicit activityType", () => {
+    const result = resolveDiscordPresenceUpdate({ activity: "test", activityType: 3 });
+    expect(result!.activities[0].type).toBe(3);
+    expect(result!.activities[0].name).toBe("test");
+  });
+
+  it("sets streaming URL for type 1", () => {
+    const result = resolveDiscordPresenceUpdate({
+      activity: "Live",
+      activityType: 1,
+      activityUrl: "https://twitch.tv/test",
+    });
+    expect(result!.activities[0].url).toBe("https://twitch.tv/test");
+  });
+});

package/src/monitor/presence.ts

@@ -0,0 +1,50 @@
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import type { Activity, UpdatePresenceData } from "../internal/gateway.js";
+
+const DEFAULT_CUSTOM_ACTIVITY_TYPE = 4;
+const CUSTOM_STATUS_NAME = "Custom Status";
+
+type DiscordPresenceConfig = Pick<
+  DiscordAccountConfig,
+  "activity" | "status" | "activityType" | "activityUrl"
+>;
+
+export function resolveDiscordPresenceUpdate(
+  config: DiscordPresenceConfig,
+): UpdatePresenceData | null {
+  const activityText = normalizeOptionalString(config.activity) ?? "";
+  const status = normalizeOptionalString(config.status) ?? "";
+  const activityType = config.activityType;
+  const activityUrl = normalizeOptionalString(config.activityUrl) ?? "";
+
+  const hasActivity = Boolean(activityText);
+  const hasStatus = Boolean(status);
+
+  if (!hasActivity && !hasStatus) {
+    return { since: null, activities: [], status: "online", afk: false };
+  }
+
+  const activities: Activity[] = [];
+
+  if (hasActivity) {
+    const resolvedType = activityType ?? DEFAULT_CUSTOM_ACTIVITY_TYPE;
+    const activity: Activity =
+      resolvedType === DEFAULT_CUSTOM_ACTIVITY_TYPE
+        ? { name: CUSTOM_STATUS_NAME, type: resolvedType, state: activityText }
+        : { name: activityText, type: resolvedType };
+
+    if (resolvedType === 1 && activityUrl) {
+      activity.url = activityUrl;
+    }
+
+    activities.push(activity);
+  }
+
+  return {
+    since: null,
+    activities,
+    status: (status || "online") as UpdatePresenceData["status"],
+    afk: false,
+  };
+}

package/src/monitor/provider-session.runtime.ts

@@ -0,0 +1,12 @@
+export { getAcpSessionManager, isAcpRuntimeError } from "openclaw/plugin-sdk/acp-runtime";
+export {
+  resolveThreadBindingIdleTimeoutMs,
+  resolveThreadBindingMaxAgeMs,
+  resolveThreadBindingsEnabled,
+} from "openclaw/plugin-sdk/conversation-runtime";
+export { createDiscordMessageHandler } from "./message-handler.js";
+export {
+  createNoopThreadBindingManager,
+  createThreadBindingManager,
+  reconcileAcpThreadBindingsOnStartup,
+} from "./thread-bindings.js";

package/src/monitor/provider.acp.ts

@@ -0,0 +1,89 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { formatErrorMessage } from "openclaw/plugin-sdk/ssrf-runtime";
+import { raceWithTimeout } from "./timeouts.js";
+
+type DiscordProviderSessionRuntimeModule = typeof import("./provider-session.runtime.js");
+
+const DISCORD_ACP_STATUS_PROBE_TIMEOUT_MS = 8_000;
+const DISCORD_ACP_STALE_RUNNING_ACTIVITY_MS = 2 * 60 * 1000;
+
+function isLegacyMissingSessionError(message: string): boolean {
+  return (
+    message.includes("Session is not ACP-enabled") ||
+    message.includes("ACP session metadata missing")
+  );
+}
+
+function classifyAcpStatusProbeError(params: {
+  error: unknown;
+  isStaleRunning: boolean;
+  isAcpRuntimeError: DiscordProviderSessionRuntimeModule["isAcpRuntimeError"];
+}): {
+  status: "stale" | "uncertain";
+  reason: string;
+} {
+  if (params.isAcpRuntimeError(params.error) && params.error.code === "ACP_SESSION_INIT_FAILED") {
+    return { status: "stale", reason: "session-init-failed" };
+  }
+
+  const message = formatErrorMessage(params.error);
+  if (isLegacyMissingSessionError(message)) {
+    return { status: "stale", reason: "session-missing" };
+  }
+
+  return params.isStaleRunning
+    ? { status: "stale", reason: "status-error-running-stale" }
+    : { status: "uncertain", reason: "status-error" };
+}
+
+export async function probeDiscordAcpBindingHealth(params: {
+  cfg: OpenClawConfig;
+  sessionKey: string;
+  storedState?: "idle" | "running" | "error";
+  lastActivityAt?: number;
+  providerSessionRuntime: DiscordProviderSessionRuntimeModule;
+}): Promise<{ status: "healthy" | "stale" | "uncertain"; reason?: string }> {
+  const { getAcpSessionManager, isAcpRuntimeError } = params.providerSessionRuntime;
+  const manager = getAcpSessionManager();
+  const statusProbeAbortController = new AbortController();
+  const statusPromise = manager
+    .getSessionStatus({
+      cfg: params.cfg,
+      sessionKey: params.sessionKey,
+      signal: statusProbeAbortController.signal,
+    })
+    .then((status) => ({ kind: "status" as const, status }))
+    .catch((error: unknown) => ({ kind: "error" as const, error }));
+
+  const result = await raceWithTimeout({
+    promise: statusPromise,
+    timeoutMs: DISCORD_ACP_STATUS_PROBE_TIMEOUT_MS,
+    onTimeout: () => ({ kind: "timeout" as const }),
+  });
+  if (result.kind === "timeout") {
+    statusProbeAbortController.abort();
+  }
+  const runningForMs =
+    params.storedState === "running" && Number.isFinite(params.lastActivityAt)
+      ? Date.now() - Math.max(0, Math.floor(params.lastActivityAt ?? 0))
+      : 0;
+  const isStaleRunning =
+    params.storedState === "running" && runningForMs >= DISCORD_ACP_STALE_RUNNING_ACTIVITY_MS;
+
+  if (result.kind === "timeout") {
+    return isStaleRunning
+      ? { status: "stale", reason: "status-timeout-running-stale" }
+      : { status: "uncertain", reason: "status-timeout" };
+  }
+  if (result.kind === "error") {
+    return classifyAcpStatusProbeError({
+      error: result.error,
+      isStaleRunning,
+      isAcpRuntimeError,
+    });
+  }
+  if (result.status.state === "error") {
+    return { status: "uncertain", reason: "status-error-state" };
+  }
+  return { status: "healthy" };
+}