@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/monitor/route-resolution.test.ts

@@ -0,0 +1,204 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing";
+import { describe, expect, it } from "vitest";
+import {
+  buildDiscordRoutePeer,
+  resolveDiscordBoundConversationRoute,
+  resolveDiscordConversationRoute,
+  resolveDiscordEffectiveRoute,
+  shouldIgnoreStaleDiscordRouteBinding,
+} from "./route-resolution.js";
+
+function buildWorkerBindingConfig(peer: {
+  kind: "channel" | "direct";
+  id: string;
+}): OpenClawConfig {
+  return {
+    agents: {
+      list: [{ id: "worker" }],
+    },
+    bindings: [
+      {
+        agentId: "worker",
+        match: {
+          channel: "discord",
+          accountId: "default",
+          peer,
+        },
+      },
+    ],
+  };
+}
+
+describe("discord route resolution helpers", () => {
+  it("builds a direct peer from DM metadata", () => {
+    expect(
+      buildDiscordRoutePeer({
+        isDirectMessage: true,
+        isGroupDm: false,
+        directUserId: "user-1",
+        conversationId: "channel-1",
+      }),
+    ).toEqual({
+      kind: "direct",
+      id: "user-1",
+    });
+  });
+
+  it("resolves bound session keys on top of the routed session", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:channel:c1",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    };
+
+    expect(
+      resolveDiscordEffectiveRoute({
+        route,
+        boundSessionKey: "agent:worker:discord:channel:c1",
+        matchedBy: "binding.channel",
+      }),
+    ).toEqual({
+      ...route,
+      agentId: "worker",
+      sessionKey: "agent:worker:discord:channel:c1",
+      matchedBy: "binding.channel",
+    });
+  });
+
+  it("falls back to configured route when no bound session exists", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:channel:c1",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    };
+    const configuredRoute = {
+      route: {
+        ...route,
+        agentId: "worker",
+        sessionKey: "agent:worker:discord:channel:c1",
+        mainSessionKey: "agent:worker:main",
+        lastRoutePolicy: "session" as const,
+        matchedBy: "binding.peer" as const,
+      },
+    };
+
+    expect(
+      resolveDiscordEffectiveRoute({
+        route,
+        configuredRoute,
+      }),
+    ).toEqual(configuredRoute.route);
+  });
+
+  it("resolves the same route shape as the inline Discord route inputs", () => {
+    const cfg = buildWorkerBindingConfig({ kind: "channel", id: "c1" });
+
+    expect(
+      resolveDiscordConversationRoute({
+        cfg,
+        accountId: "default",
+        guildId: "g1",
+        memberRoleIds: [],
+        peer: { kind: "channel", id: "c1" },
+      }),
+    ).toMatchObject({
+      agentId: "worker",
+      sessionKey: "agent:worker:discord:channel:c1",
+      matchedBy: "binding.peer",
+    });
+  });
+
+  it("composes route building with effective-route overrides", () => {
+    const cfg = buildWorkerBindingConfig({ kind: "direct", id: "user-1" });
+
+    expect(
+      resolveDiscordBoundConversationRoute({
+        cfg,
+        accountId: "default",
+        isDirectMessage: true,
+        isGroupDm: false,
+        directUserId: "user-1",
+        conversationId: "dm-1",
+        boundSessionKey: "agent:worker:discord:direct:user-1",
+        matchedBy: "binding.channel",
+      }),
+    ).toMatchObject({
+      agentId: "worker",
+      sessionKey: "agent:worker:discord:direct:user-1",
+      matchedBy: "binding.channel",
+    });
+  });
+
+  it("ignores stale route-shaped bindings after the configured agent changes", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "newagent",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:newagent:discord:channel:c1",
+      mainSessionKey: "agent:newagent:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.peer",
+    };
+
+    expect(
+      shouldIgnoreStaleDiscordRouteBinding({
+        route,
+        bindingRecord: {
+          bindingId: "binding-1",
+          targetSessionKey: "agent:oldagent:discord:channel:c1",
+          targetKind: "session",
+          conversation: {
+            channel: "discord",
+            accountId: "default",
+            conversationId: "c1",
+          },
+          status: "active",
+          boundAt: 1,
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps explicit focus bindings even when their agent differs from routing", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "newagent",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:newagent:discord:channel:c1",
+      mainSessionKey: "agent:newagent:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.peer",
+    };
+
+    expect(
+      shouldIgnoreStaleDiscordRouteBinding({
+        route,
+        bindingRecord: {
+          bindingId: "focus-binding",
+          targetSessionKey: "agent:oldagent:discord:channel:c1",
+          targetKind: "session",
+          conversation: {
+            channel: "discord",
+            accountId: "default",
+            conversationId: "c1",
+          },
+          status: "active",
+          boundAt: 1,
+          metadata: {
+            boundBy: "user-1",
+            label: "oldagent",
+          },
+        },
+      }),
+    ).toBe(false);
+  });
+});

package/src/monitor/route-resolution.ts

@@ -0,0 +1,140 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { SessionBindingRecord } from "openclaw/plugin-sdk/conversation-runtime";
+import {
+  deriveLastRoutePolicy,
+  isAcpSessionKey,
+  isSubagentSessionKey,
+  parseAgentSessionKey,
+  resolveAgentRoute,
+  type ResolvedAgentRoute,
+  type RoutePeer,
+} from "openclaw/plugin-sdk/routing";
+import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
+
+export function buildDiscordRoutePeer(params: {
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  directUserId?: string | null;
+  conversationId: string;
+}): RoutePeer {
+  return {
+    kind: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
+    id: params.isDirectMessage
+      ? params.directUserId?.trim() || params.conversationId
+      : params.conversationId,
+  };
+}
+
+export function resolveDiscordConversationRoute(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  guildId?: string | null;
+  memberRoleIds?: string[];
+  peer: RoutePeer;
+  parentConversationId?: string | null;
+}): ResolvedAgentRoute {
+  return resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "discord",
+    accountId: params.accountId,
+    guildId: params.guildId ?? undefined,
+    memberRoleIds: params.memberRoleIds,
+    peer: params.peer,
+    parentPeer: params.parentConversationId
+      ? { kind: "channel", id: params.parentConversationId }
+      : undefined,
+  });
+}
+
+export function resolveDiscordBoundConversationRoute(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  guildId?: string | null;
+  memberRoleIds?: string[];
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  directUserId?: string | null;
+  conversationId: string;
+  parentConversationId?: string | null;
+  boundSessionKey?: string | null;
+  configuredRoute?: { route: ResolvedAgentRoute } | null;
+  matchedBy?: ResolvedAgentRoute["matchedBy"];
+}): ResolvedAgentRoute {
+  const route = resolveDiscordConversationRoute({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    guildId: params.guildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: buildDiscordRoutePeer({
+      isDirectMessage: params.isDirectMessage,
+      isGroupDm: params.isGroupDm,
+      directUserId: params.directUserId,
+      conversationId: params.conversationId,
+    }),
+    parentConversationId: params.parentConversationId,
+  });
+  return resolveDiscordEffectiveRoute({
+    route,
+    boundSessionKey: params.boundSessionKey,
+    configuredRoute: params.configuredRoute,
+    matchedBy: params.matchedBy,
+  });
+}
+
+export function resolveDiscordEffectiveRoute(params: {
+  route: ResolvedAgentRoute;
+  boundSessionKey?: string | null;
+  configuredRoute?: { route: ResolvedAgentRoute } | null;
+  matchedBy?: ResolvedAgentRoute["matchedBy"];
+}): ResolvedAgentRoute {
+  const boundSessionKey = params.boundSessionKey?.trim();
+  if (!boundSessionKey) {
+    return params.configuredRoute?.route ?? params.route;
+  }
+  return {
+    ...params.route,
+    sessionKey: boundSessionKey,
+    agentId: resolveAgentIdFromSessionKey(boundSessionKey),
+    lastRoutePolicy: deriveLastRoutePolicy({
+      sessionKey: boundSessionKey,
+      mainSessionKey: params.route.mainSessionKey,
+    }),
+    ...(params.matchedBy ? { matchedBy: params.matchedBy } : {}),
+  };
+}
+
+function hasExplicitRuntimeBindingIntent(record: SessionBindingRecord): boolean {
+  if (record.targetKind === "subagent") {
+    return true;
+  }
+  if (isAcpSessionKey(record.targetSessionKey) || isSubagentSessionKey(record.targetSessionKey)) {
+    return true;
+  }
+  const metadata = record.metadata;
+  if (!metadata || typeof metadata !== "object") {
+    return false;
+  }
+  return (
+    typeof metadata.boundBy === "string" ||
+    typeof metadata.label === "string" ||
+    typeof metadata.threadName === "string" ||
+    metadata.pluginBindingOwner === "plugin"
+  );
+}
+
+export function shouldIgnoreStaleDiscordRouteBinding(params: {
+  bindingRecord?: SessionBindingRecord | null;
+  route: ResolvedAgentRoute;
+}): boolean {
+  const bindingRecord = params.bindingRecord;
+  const boundSessionKey = bindingRecord?.targetSessionKey?.trim();
+  if (!bindingRecord || !boundSessionKey || hasExplicitRuntimeBindingIntent(bindingRecord)) {
+    return false;
+  }
+  const bound = parseAgentSessionKey(boundSessionKey);
+  const routed = parseAgentSessionKey(params.route.sessionKey);
+  if (!bound || !routed || bound.rest !== routed.rest) {
+    return false;
+  }
+  return bound.agentId !== params.route.agentId;
+}

package/src/monitor/sender-identity.ts

@@ -0,0 +1,81 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import type { User } from "../internal/discord.js";
+import type { PluralKitMessageInfo } from "../pluralkit.js";
+import { formatDiscordUserTag } from "./format.js";
+
+export type DiscordSenderIdentity = {
+  id: string;
+  name?: string;
+  tag?: string;
+  label: string;
+  isPluralKit: boolean;
+  pluralkit?: {
+    memberId: string;
+    memberName?: string;
+    systemId?: string;
+    systemName?: string;
+  };
+};
+
+type DiscordWebhookMessageLike = {
+  webhookId?: string | null;
+  webhook_id?: string | null;
+};
+
+type DiscordMemberLike = {
+  nickname?: string | null;
+  nick?: string | null;
+};
+
+export function resolveDiscordWebhookId(message: DiscordWebhookMessageLike): string | null {
+  const candidate = message.webhookId ?? message.webhook_id;
+  return typeof candidate === "string" && candidate.trim() ? candidate.trim() : null;
+}
+
+export function resolveDiscordSenderIdentity(params: {
+  author: User;
+  member?: DiscordMemberLike | null;
+  pluralkitInfo?: PluralKitMessageInfo | null;
+}): DiscordSenderIdentity {
+  const pkInfo = params.pluralkitInfo ?? null;
+  const pkMember = pkInfo?.member ?? undefined;
+  const pkSystem = pkInfo?.system ?? undefined;
+  const memberId = pkMember?.id?.trim();
+  const memberNameRaw = pkMember?.display_name ?? pkMember?.name ?? "";
+  const memberName = memberNameRaw?.trim();
+  if (memberId && memberName) {
+    const systemName = pkSystem?.name?.trim();
+    const label = systemName ? `${memberName} (PK:${systemName})` : `${memberName} (PK)`;
+    return {
+      id: memberId,
+      name: memberName,
+      tag: normalizeOptionalString(pkMember?.name),
+      label,
+      isPluralKit: true,
+      pluralkit: {
+        memberId,
+        memberName,
+        systemId: normalizeOptionalString(pkSystem?.id),
+        systemName,
+      },
+    };
+  }
+
+  const senderTag = formatDiscordUserTag(params.author);
+  const senderDisplay =
+    params.member?.nickname ??
+    params.member?.nick ??
+    params.author.globalName ??
+    params.author.username;
+  const senderLabel =
+    senderDisplay && senderTag && senderDisplay !== senderTag
+      ? `${senderDisplay} (${senderTag})`
+      : (senderDisplay ?? senderTag ?? params.author.id);
+  return {
+    id: params.author.id,
+    name: params.author.username ?? undefined,
+    tag: senderTag,
+    label: senderLabel,
+    isPluralKit: false,
+  };
+}

package/src/monitor/startup-status.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { formatDiscordStartupStatusMessage } from "./startup-status.js";
+
+describe("formatDiscordStartupStatusMessage", () => {
+  it("reports logged-in status only after the gateway is ready", () => {
+    expect(
+      formatDiscordStartupStatusMessage({
+        gatewayReady: true,
+        botIdentity: "bot-1 (Molty)",
+      }),
+    ).toBe("logged in to discord as bot-1 (Molty)");
+  });
+
+  it("reports client initialization while gateway readiness is still pending", () => {
+    expect(
+      formatDiscordStartupStatusMessage({
+        gatewayReady: false,
+        botIdentity: "bot-1 (Molty)",
+      }),
+    ).toBe("discord client initialized as bot-1 (Molty); awaiting gateway readiness");
+  });
+
+  it("handles missing identity without awkward punctuation", () => {
+    expect(
+      formatDiscordStartupStatusMessage({
+        gatewayReady: false,
+      }),
+    ).toBe("discord client initialized; awaiting gateway readiness");
+  });
+});

package/src/monitor/startup-status.ts

@@ -0,0 +1,10 @@
+export function formatDiscordStartupStatusMessage(params: {
+  gatewayReady: boolean;
+  botIdentity?: string;
+}): string {
+  const identitySuffix = params.botIdentity ? ` as ${params.botIdentity}` : "";
+  if (params.gatewayReady) {
+    return `logged in to discord${identitySuffix}`;
+  }
+  return `discord client initialized${identitySuffix}; awaiting gateway readiness`;
+}

package/src/monitor/status.ts

@@ -0,0 +1,22 @@
+type DiscordMonitorStatusPatch = {
+  connected?: boolean;
+  lastEventAt?: number | null;
+  lastTransportActivityAt?: number | null;
+  lastConnectedAt?: number | null;
+  lastDisconnect?:
+    | string
+    | {
+        at: number;
+        status?: number;
+        error?: string;
+        loggedOut?: boolean;
+      }
+    | null;
+  lastInboundAt?: number | null;
+  lastError?: string | null;
+  busy?: boolean;
+  activeRuns?: number;
+  lastRunActivityAt?: number | null;
+};
+
+export type DiscordMonitorStatusSink = (patch: DiscordMonitorStatusPatch) => void;

package/src/monitor/system-events.ts

@@ -0,0 +1,55 @@
+import { type Message, MessageType } from "../internal/discord.js";
+import { formatDiscordUserTag } from "./format.js";
+
+export function resolveDiscordSystemEvent(message: Message, location: string): string | null {
+  switch (message.type) {
+    case MessageType.ChannelPinnedMessage:
+      return buildDiscordSystemEvent(message, location, "pinned a message");
+    case MessageType.RecipientAdd:
+      return buildDiscordSystemEvent(message, location, "added a recipient");
+    case MessageType.RecipientRemove:
+      return buildDiscordSystemEvent(message, location, "removed a recipient");
+    case MessageType.UserJoin:
+      return buildDiscordSystemEvent(message, location, "user joined");
+    case MessageType.GuildBoost:
+      return buildDiscordSystemEvent(message, location, "boosted the server");
+    case MessageType.GuildBoostTier1:
+      return buildDiscordSystemEvent(message, location, "boosted the server (Tier 1 reached)");
+    case MessageType.GuildBoostTier2:
+      return buildDiscordSystemEvent(message, location, "boosted the server (Tier 2 reached)");
+    case MessageType.GuildBoostTier3:
+      return buildDiscordSystemEvent(message, location, "boosted the server (Tier 3 reached)");
+    case MessageType.ThreadCreated:
+      return buildDiscordSystemEvent(message, location, "created a thread");
+    case MessageType.AutoModerationAction:
+      return buildDiscordSystemEvent(message, location, "auto moderation action");
+    case MessageType.GuildIncidentAlertModeEnabled:
+      return buildDiscordSystemEvent(message, location, "raid protection enabled");
+    case MessageType.GuildIncidentAlertModeDisabled:
+      return buildDiscordSystemEvent(message, location, "raid protection disabled");
+    case MessageType.GuildIncidentReportRaid:
+      return buildDiscordSystemEvent(message, location, "raid reported");
+    case MessageType.GuildIncidentReportFalseAlarm:
+      return buildDiscordSystemEvent(message, location, "raid report marked false alarm");
+    case MessageType.StageStart:
+      return buildDiscordSystemEvent(message, location, "stage started");
+    case MessageType.StageEnd:
+      return buildDiscordSystemEvent(message, location, "stage ended");
+    case MessageType.StageSpeaker:
+      return buildDiscordSystemEvent(message, location, "stage speaker updated");
+    case MessageType.StageTopic:
+      return buildDiscordSystemEvent(message, location, "stage topic updated");
+    case MessageType.PollResult:
+      return buildDiscordSystemEvent(message, location, "poll results posted");
+    case MessageType.PurchaseNotification:
+      return buildDiscordSystemEvent(message, location, "purchase notification");
+    default:
+      return null;
+  }
+}
+
+function buildDiscordSystemEvent(message: Message, location: string, action: string) {
+  const authorLabel = message.author ? formatDiscordUserTag(message.author) : "";
+  const actor = authorLabel ? `${authorLabel} ` : "";
+  return `Discord system: ${actor}${action} in ${location}`;
+}

package/src/monitor/thread-bindings.config.ts

@@ -0,0 +1,35 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  resolveThreadBindingIdleTimeoutMs,
+  resolveThreadBindingMaxAgeMs,
+  resolveThreadBindingsEnabled,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import { normalizeAccountId } from "openclaw/plugin-sdk/routing";
+
+export { resolveThreadBindingsEnabled };
+
+export function resolveDiscordThreadBindingIdleTimeoutMs(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): number {
+  const accountId = normalizeAccountId(params.accountId);
+  const root = params.cfg.channels?.discord?.threadBindings;
+  const account = params.cfg.channels?.discord?.accounts?.[accountId]?.threadBindings;
+  return resolveThreadBindingIdleTimeoutMs({
+    channelIdleHoursRaw: account?.idleHours ?? root?.idleHours,
+    sessionIdleHoursRaw: params.cfg.session?.threadBindings?.idleHours,
+  });
+}
+
+export function resolveDiscordThreadBindingMaxAgeMs(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): number {
+  const accountId = normalizeAccountId(params.accountId);
+  const root = params.cfg.channels?.discord?.threadBindings;
+  const account = params.cfg.channels?.discord?.accounts?.[accountId]?.threadBindings;
+  return resolveThreadBindingMaxAgeMs({
+    channelMaxAgeHoursRaw: account?.maxAgeHours ?? root?.maxAgeHours,
+    sessionMaxAgeHoursRaw: params.cfg.session?.threadBindings?.maxAgeHours,
+  });
+}