@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/subagent-hooks.ts

@@ -1,10 +1,20 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/discord";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/channel-plugin-common";
+import {
+  formatThreadBindingDisabledError,
+  formatThreadBindingSpawnDisabledError,
+  resolveThreadBindingSpawnPolicy,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalStringifiedId,
+} from "openclaw/plugin-sdk/text-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
 import {
   autoBindSpawnedDiscordSubagent,
   listThreadBindingsBySessionKey,
-  resolveDiscordAccount,
+  type ThreadBindingTargetKind,
   unbindThreadBindingsBySessionKey,
-} from "openclaw/plugin-sdk/discord";
+} from "./monitor/thread-bindings.js";
 
 function summarizeError(err: unknown): string {
   if (err instanceof Error) {
@@ -16,137 +26,189 @@ function summarizeError(err: unknown): string {
   return "error";
 }
 
-export function registerDiscordSubagentHooks(api: OpenClawPluginApi) {
-  const resolveThreadBindingFlags = (accountId?: string) => {
-    const account = resolveDiscordAccount({
-      cfg: api.config,
-      accountId,
-    });
-    const baseThreadBindings = api.config.channels?.discord?.threadBindings;
-    const accountThreadBindings =
-      api.config.channels?.discord?.accounts?.[account.accountId]?.threadBindings;
-    return {
-      enabled:
-        accountThreadBindings?.enabled ??
-        baseThreadBindings?.enabled ??
-        api.config.session?.threadBindings?.enabled ??
-        true,
-      spawnSubagentSessions:
-        accountThreadBindings?.spawnSubagentSessions ??
-        baseThreadBindings?.spawnSubagentSessions ??
-        false,
-    };
+type DiscordSubagentSpawningEvent = {
+  threadRequested?: boolean;
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
   };
+  childSessionKey: string;
+  agentId: string;
+  label?: string;
+};
 
-  api.on("subagent_spawning", async (event) => {
-    if (!event.threadRequested) {
-      return;
-    }
-    const channel = event.requester?.channel?.trim().toLowerCase();
-    if (channel !== "discord") {
-      // Ignore non-Discord channels so channel-specific plugins can handle
-      // their own thread/session provisioning without Discord blocking them.
-      return;
-    }
-    const threadBindingFlags = resolveThreadBindingFlags(event.requester?.accountId);
-    if (!threadBindingFlags.enabled) {
-      return {
-        status: "error" as const,
-        error:
-          "Discord thread bindings are disabled (set channels.discord.threadBindings.enabled=true to override for this account, or session.threadBindings.enabled=true globally).",
+type DiscordSubagentEndedEvent = {
+  targetSessionKey: string;
+  accountId?: string;
+  targetKind?: ThreadBindingTargetKind;
+  reason?: string;
+  sendFarewell?: boolean;
+};
+
+type DiscordSubagentDeliveryTargetEvent = {
+  expectsCompletionMessage?: boolean;
+  childSessionKey: string;
+  requesterOrigin?: {
+    channel?: string;
+    accountId?: string;
+    threadId?: string | number;
+  };
+};
+
+type DiscordSubagentSpawningResult =
+  | { status: "ok"; threadBindingReady?: boolean }
+  | { status: "error"; error: string }
+  | undefined;
+
+type DiscordSubagentDeliveryTargetResult =
+  | {
+      origin: {
+        channel: "discord";
+        accountId?: string;
+        to: string;
+        threadId?: string | number;
       };
     }
-    if (!threadBindingFlags.spawnSubagentSessions) {
+  | undefined;
+
+function normalizeThreadBindingTargetKind(raw?: string): ThreadBindingTargetKind | undefined {
+  const normalized = normalizeOptionalLowercaseString(raw);
+  if (normalized === "subagent" || normalized === "acp") {
+    return normalized;
+  }
+  return undefined;
+}
+
+export async function handleDiscordSubagentSpawning(
+  api: OpenClawPluginApi,
+  event: DiscordSubagentSpawningEvent,
+): Promise<DiscordSubagentSpawningResult> {
+  if (!event.threadRequested) {
+    return undefined;
+  }
+  const channel = normalizeOptionalLowercaseString(event.requester?.channel);
+  if (channel !== "discord") {
+    return undefined;
+  }
+  const account = resolveDiscordAccount({
+    cfg: api.config,
+    accountId: event.requester?.accountId,
+  });
+  const threadBindingPolicy = resolveThreadBindingSpawnPolicy({
+    cfg: api.config,
+    channel: "discord",
+    accountId: account.accountId,
+    kind: "subagent",
+  });
+  if (!threadBindingPolicy.enabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  if (!threadBindingPolicy.spawnEnabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingSpawnDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  try {
+    const agentId = event.agentId?.trim() || "subagent";
+    const binding = await autoBindSpawnedDiscordSubagent({
+      cfg: api.config,
+      accountId: account.accountId,
+      channel: event.requester?.channel,
+      to: event.requester?.to,
+      threadId: event.requester?.threadId,
+      childSessionKey: event.childSessionKey,
+      agentId,
+      label: event.label,
+      boundBy: "system",
+    });
+    if (!binding) {
       return {
         status: "error" as const,
         error:
-          "Discord thread-bound subagent spawns are disabled for this account (set channels.discord.threadBindings.spawnSubagentSessions=true to enable).",
-      };
-    }
-    try {
-      const binding = await autoBindSpawnedDiscordSubagent({
-        accountId: event.requester?.accountId,
-        channel: event.requester?.channel,
-        to: event.requester?.to,
-        threadId: event.requester?.threadId,
-        childSessionKey: event.childSessionKey,
-        agentId: event.agentId,
-        label: event.label,
-        boundBy: "system",
-      });
-      if (!binding) {
-        return {
-          status: "error" as const,
-          error:
-            "Unable to create or bind a Discord thread for this subagent session. Session mode is unavailable for this target.",
-        };
-      }
-      return { status: "ok" as const, threadBindingReady: true };
-    } catch (err) {
-      return {
-        status: "error" as const,
-        error: `Discord thread bind failed: ${summarizeError(err)}`,
+          "Unable to create or bind a Discord thread for this subagent session. Session mode is unavailable for this target.",
       };
     }
+    return { status: "ok" as const, threadBindingReady: true };
+  } catch (err) {
+    return {
+      status: "error" as const,
+      error: `Discord thread bind failed: ${summarizeError(err)}`,
+    };
+  }
+}
+
+export function handleDiscordSubagentEnded(event: DiscordSubagentEndedEvent) {
+  unbindThreadBindingsBySessionKey({
+    targetSessionKey: event.targetSessionKey,
+    accountId: event.accountId,
+    targetKind: normalizeThreadBindingTargetKind(event.targetKind),
+    reason: event.reason,
+    sendFarewell: event.sendFarewell,
   });
+}
 
-  api.on("subagent_ended", (event) => {
-    unbindThreadBindingsBySessionKey({
-      targetSessionKey: event.targetSessionKey,
-      accountId: event.accountId,
-      targetKind: event.targetKind,
-      reason: event.reason,
-      sendFarewell: event.sendFarewell,
-    });
+export function handleDiscordSubagentDeliveryTarget(
+  event: DiscordSubagentDeliveryTargetEvent,
+): DiscordSubagentDeliveryTargetResult {
+  if (!event.expectsCompletionMessage) {
+    return undefined;
+  }
+  const requesterChannel = normalizeOptionalLowercaseString(event.requesterOrigin?.channel);
+  if (requesterChannel !== "discord") {
+    return undefined;
+  }
+  const requesterAccountId = event.requesterOrigin?.accountId?.trim();
+  const requesterThreadId =
+    event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== ""
+      ? (normalizeOptionalStringifiedId(event.requesterOrigin.threadId) ?? "")
+      : "";
+  const bindings = listThreadBindingsBySessionKey({
+    targetSessionKey: event.childSessionKey,
+    ...(requesterAccountId ? { accountId: requesterAccountId } : {}),
+    targetKind: "subagent",
   });
+  if (bindings.length === 0) {
+    return undefined;
+  }
 
-  api.on("subagent_delivery_target", (event) => {
-    if (!event.expectsCompletionMessage) {
-      return;
-    }
-    const requesterChannel = event.requesterOrigin?.channel?.trim().toLowerCase();
-    if (requesterChannel !== "discord") {
-      return;
-    }
-    const requesterAccountId = event.requesterOrigin?.accountId?.trim();
-    const requesterThreadId =
-      event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== ""
-        ? String(event.requesterOrigin.threadId).trim()
-        : "";
-    const bindings = listThreadBindingsBySessionKey({
-      targetSessionKey: event.childSessionKey,
-      ...(requesterAccountId ? { accountId: requesterAccountId } : {}),
-      targetKind: "subagent",
+  let binding: (typeof bindings)[number] | undefined;
+  if (requesterThreadId) {
+    binding = bindings.find((entry) => {
+      if (entry.threadId !== requesterThreadId) {
+        return false;
+      }
+      if (requesterAccountId && entry.accountId !== requesterAccountId) {
+        return false;
+      }
+      return true;
     });
-    if (bindings.length === 0) {
-      return;
-    }
-
-    let binding: (typeof bindings)[number] | undefined;
-    if (requesterThreadId) {
-      binding = bindings.find((entry) => {
-        if (entry.threadId !== requesterThreadId) {
-          return false;
-        }
-        if (requesterAccountId && entry.accountId !== requesterAccountId) {
-          return false;
-        }
-        return true;
-      });
-    }
-    if (!binding && bindings.length === 1) {
-      binding = bindings[0];
-    }
-    if (!binding) {
-      return;
-    }
-    return {
-      origin: {
-        channel: "discord",
-        accountId: binding.accountId,
-        to: `channel:${binding.threadId}`,
-        threadId: binding.threadId,
-      },
-    };
-  });
+  }
+  if (!binding && bindings.length === 1) {
+    binding = bindings[0];
+  }
+  if (!binding) {
+    return undefined;
+  }
+  return {
+    origin: {
+      channel: "discord" as const,
+      accountId: binding.accountId,
+      to: `channel:${binding.threadId}`,
+      threadId: binding.threadId,
+    },
+  };
 }

package/src/target-parsing.ts

@@ -0,0 +1,53 @@
+import {
+  buildMessagingTarget,
+  parseMentionPrefixOrAtUserTarget,
+  requireTargetKind,
+  type MessagingTarget,
+  type MessagingTargetKind,
+  type MessagingTargetParseOptions,
+} from "openclaw/plugin-sdk/messaging-targets";
+
+export type DiscordTargetKind = MessagingTargetKind;
+
+export type DiscordTarget = MessagingTarget;
+
+export type DiscordTargetParseOptions = MessagingTargetParseOptions;
+
+export function parseDiscordTarget(
+  raw: string,
+  options: DiscordTargetParseOptions = {},
+): DiscordTarget | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const userTarget = parseMentionPrefixOrAtUserTarget({
+    raw: trimmed,
+    mentionPattern: /^<@!?(\d+)>$/,
+    prefixes: [
+      { prefix: "user:", kind: "user" },
+      { prefix: "channel:", kind: "channel" },
+      { prefix: "discord:", kind: "user" },
+    ],
+    atUserPattern: /^\d+$/,
+    atUserErrorMessage: "Discord DMs require a user id (use user:<id> or a <@id> mention)",
+  });
+  if (userTarget) {
+    return userTarget;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    if (options.defaultKind) {
+      return buildMessagingTarget(options.defaultKind, trimmed, trimmed);
+    }
+    throw new Error(
+      options.ambiguousMessage ??
+        `Ambiguous Discord recipient "${trimmed}". For DMs use "user:${trimmed}" or "<@${trimmed}>"; for channels use "channel:${trimmed}".`,
+    );
+  }
+  return buildMessagingTarget("channel", trimmed, trimmed);
+}
+
+export function resolveDiscordChannelId(raw: string): string {
+  const target = parseDiscordTarget(raw, { defaultKind: "channel" });
+  return requireTargetKind({ platform: "Discord", target, kind: "channel" });
+}

package/src/target-resolver.ts

@@ -0,0 +1,129 @@
+import type { DirectoryConfigParams } from "openclaw/plugin-sdk/directory-runtime";
+import { buildMessagingTarget, type MessagingTarget } from "openclaw/plugin-sdk/messaging-targets";
+import { resolveDiscordAccount, resolveDiscordAccountAllowFrom } from "./accounts.js";
+import { rememberDiscordDirectoryUser } from "./directory-cache.js";
+import { listDiscordDirectoryPeersLive } from "./directory-live.js";
+import { allowFromContainsDiscordUserId } from "./normalize.js";
+import { parseDiscordSendTarget } from "./send-target-parsing.js";
+import { type DiscordTargetParseOptions } from "./target-parsing.js";
+
+/**
+ * Resolve a Discord username to user ID using the directory lookup.
+ * This enables sending DMs by username instead of requiring explicit user IDs.
+ */
+export async function resolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget | undefined> {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const likelyUsername = isLikelyUsername(trimmed);
+  const shouldLookup = isExplicitUserLookup(trimmed, parseOptions) || likelyUsername;
+
+  if (
+    /^\d+$/.test(trimmed) &&
+    parseOptions.defaultKind !== "user" &&
+    isConfiguredAllowedDiscordDmUser(trimmed, options)
+  ) {
+    return buildMessagingTarget("user", trimmed, trimmed);
+  }
+
+  // Parse directly if it's already a known format. Use a safe parse so ambiguous
+  // numeric targets don't throw when we still want to attempt username lookup.
+  const directParse = safeParseDiscordTarget(trimmed, parseOptions);
+  if (directParse && directParse.kind !== "channel" && !likelyUsername) {
+    return directParse;
+  }
+
+  if (!shouldLookup) {
+    return directParse ?? parseDiscordSendTarget(trimmed, parseOptions);
+  }
+
+  try {
+    const directoryEntries = await listDiscordDirectoryPeersLive({
+      ...options,
+      query: trimmed,
+      limit: 1,
+    });
+
+    const match = directoryEntries[0];
+    if (match && match.kind === "user") {
+      const userId = match.id.replace(/^user:/, "");
+      const resolvedAccountId = resolveDiscordAccount({
+        cfg: options.cfg,
+        accountId: options.accountId,
+      }).accountId;
+      rememberDiscordDirectoryUser({
+        accountId: resolvedAccountId,
+        userId,
+        handles: [trimmed, match.name, match.handle],
+      });
+      return buildMessagingTarget("user", userId, trimmed);
+    }
+  } catch {
+    // Preserve legacy fallback behavior for channel names and direct ids.
+  }
+
+  return parseDiscordSendTarget(trimmed, parseOptions);
+}
+
+export async function parseAndResolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget> {
+  const resolved =
+    (await resolveDiscordTarget(raw, options, parseOptions)) ??
+    parseDiscordSendTarget(raw, parseOptions);
+  if (!resolved) {
+    throw new Error("Recipient is required for Discord sends");
+  }
+  return resolved;
+}
+
+function safeParseDiscordTarget(
+  input: string,
+  options: DiscordTargetParseOptions,
+): MessagingTarget | undefined {
+  try {
+    return parseDiscordSendTarget(input, options);
+  } catch {
+    return undefined;
+  }
+}
+
+function isConfiguredAllowedDiscordDmUser(input: string, options: DirectoryConfigParams): boolean {
+  const allowFrom =
+    resolveDiscordAccountAllowFrom({
+      cfg: options.cfg,
+      accountId: options.accountId,
+    }) ?? [];
+  return allowFromContainsDiscordUserId(allowFrom, input);
+}
+
+function isExplicitUserLookup(input: string, options: DiscordTargetParseOptions): boolean {
+  if (/^<@!?(\d+)>$/.test(input)) {
+    return true;
+  }
+  if (/^(user:|discord:)/.test(input)) {
+    return true;
+  }
+  if (input.startsWith("@")) {
+    return true;
+  }
+  if (/^\d+$/.test(input)) {
+    return options.defaultKind === "user";
+  }
+  return false;
+}
+
+function isLikelyUsername(input: string): boolean {
+  if (/^(user:|channel:|discord:|@|<@!?)|[\d]+$/.test(input)) {
+    return false;
+  }
+  return true;
+}