@openclaw/discord 2026.2.19 → 2026.2.22

package/index.ts

@@ -2,6 +2,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { discordPlugin } from "./src/channel.js";
 import { setDiscordRuntime } from "./src/runtime.js";
+import { registerDiscordSubagentHooks } from "./src/subagent-hooks.js";
 
 const plugin = {
   id: "discord",
@@ -11,6 +12,7 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setDiscordRuntime(api.runtime);
     api.registerChannel({ plugin: discordPlugin });
+    registerDiscordSubagentHooks(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/discord",
-  "version": "2026.2.19",
+  "version": "2026.2.22",
   "description": "OpenClaw Discord channel plugin",
   "type": "module",
   "devDependencies": {

package/src/channel.test.ts

@@ -0,0 +1,36 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { discordPlugin } from "./channel.js";
+import { setDiscordRuntime } from "./runtime.js";
+
+describe("discordPlugin outbound", () => {
+  it("forwards mediaLocalRoots to sendMessageDiscord", async () => {
+    const sendMessageDiscord = vi.fn(async () => ({ messageId: "m1" }));
+    setDiscordRuntime({
+      channel: {
+        discord: {
+          sendMessageDiscord,
+        },
+      },
+    } as unknown as PluginRuntime);
+
+    const result = await discordPlugin.outbound!.sendMedia!({
+      cfg: {} as OpenClawConfig,
+      to: "channel:123",
+      text: "hi",
+      mediaUrl: "/tmp/image.png",
+      mediaLocalRoots: ["/tmp/agent-root"],
+      accountId: "work",
+    });
+
+    expect(sendMessageDiscord).toHaveBeenCalledWith(
+      "channel:123",
+      "hi",
+      expect.objectContaining({
+        mediaUrl: "/tmp/image.png",
+        mediaLocalRoots: ["/tmp/agent-root"],
+      }),
+    );
+    expect(result).toMatchObject({ channel: "discord", messageId: "m1" });
+  });
+});

package/src/channel.ts

@@ -22,6 +22,8 @@ import {
   resolveDefaultDiscordAccountId,
   resolveDiscordGroupRequireMention,
   resolveDiscordGroupToolPolicy,
+  resolveOpenProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
   setAccountEnabledInConfigSection,
   type ChannelMessageActionAdapter,
   type ChannelPlugin,
@@ -110,6 +112,8 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
         .map((entry) => String(entry).trim())
         .filter(Boolean)
         .map((entry) => entry.toLowerCase()),
+    resolveDefaultTo: ({ cfg, accountId }) =>
+      resolveDiscordAccount({ cfg, accountId }).config.defaultTo?.trim() || undefined,
   },
   security: {
     resolveDmPolicy: ({ cfg, accountId, account }) => {
@@ -128,8 +132,12 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
     },
     collectWarnings: ({ account, cfg }) => {
       const warnings: string[] = [];
-      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+      const defaultGroupPolicy = resolveDefaultGroupPolicy(cfg);
+      const { groupPolicy } = resolveOpenProviderRuntimeGroupPolicy({
+        providerConfigPresent: cfg.channels?.discord !== undefined,
+        groupPolicy: account.config.groupPolicy,
+        defaultGroupPolicy,
+      });
       const guildEntries = account.config.guilds ?? {};
       const guildsConfigured = Object.keys(guildEntries).length > 0;
       const channelAllowlistConfigured = guildsConfigured;
@@ -303,11 +311,21 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
       });
       return { channel: "discord", ...result };
     },
-    sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId, silent }) => {
+    sendMedia: async ({
+      to,
+      text,
+      mediaUrl,
+      mediaLocalRoots,
+      accountId,
+      deps,
+      replyToId,
+      silent,
+    }) => {
       const send = deps?.sendDiscord ?? getDiscordRuntime().channel.discord.sendMessageDiscord;
       const result = await send(to, text, {
         verbose: false,
         mediaUrl,
+        mediaLocalRoots,
         replyTo: replyToId ?? undefined,
         accountId: accountId ?? undefined,
         silent: silent ?? undefined,

package/src/subagent-hooks.test.ts

@@ -0,0 +1,388 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { registerDiscordSubagentHooks } from "./subagent-hooks.js";
+
+type ThreadBindingRecord = {
+  accountId: string;
+  threadId: string;
+};
+
+type MockResolvedDiscordAccount = {
+  accountId: string;
+  config: {
+    threadBindings?: {
+      enabled?: boolean;
+      spawnSubagentSessions?: boolean;
+    };
+  };
+};
+
+const hookMocks = vi.hoisted(() => ({
+  resolveDiscordAccount: vi.fn(
+    (params?: { accountId?: string }): MockResolvedDiscordAccount => ({
+      accountId: params?.accountId?.trim() || "default",
+      config: {
+        threadBindings: {
+          spawnSubagentSessions: true,
+        },
+      },
+    }),
+  ),
+  autoBindSpawnedDiscordSubagent: vi.fn(
+    async (): Promise<{ threadId: string } | null> => ({ threadId: "thread-1" }),
+  ),
+  listThreadBindingsBySessionKey: vi.fn((_params?: unknown): ThreadBindingRecord[] => []),
+  unbindThreadBindingsBySessionKey: vi.fn(() => []),
+}));
+
+vi.mock("openclaw/plugin-sdk", () => ({
+  resolveDiscordAccount: hookMocks.resolveDiscordAccount,
+  autoBindSpawnedDiscordSubagent: hookMocks.autoBindSpawnedDiscordSubagent,
+  listThreadBindingsBySessionKey: hookMocks.listThreadBindingsBySessionKey,
+  unbindThreadBindingsBySessionKey: hookMocks.unbindThreadBindingsBySessionKey,
+}));
+
+function registerHandlersForTest(
+  config: Record<string, unknown> = {
+    channels: {
+      discord: {
+        threadBindings: {
+          spawnSubagentSessions: true,
+        },
+      },
+    },
+  },
+) {
+  const handlers = new Map<string, (event: unknown, ctx: unknown) => unknown>();
+  const api = {
+    config,
+    on: (hookName: string, handler: (event: unknown, ctx: unknown) => unknown) => {
+      handlers.set(hookName, handler);
+    },
+  } as unknown as OpenClawPluginApi;
+  registerDiscordSubagentHooks(api);
+  return handlers;
+}
+
+function getRequiredHandler(
+  handlers: Map<string, (event: unknown, ctx: unknown) => unknown>,
+  hookName: string,
+): (event: unknown, ctx: unknown) => unknown {
+  const handler = handlers.get(hookName);
+  if (!handler) {
+    throw new Error(`expected ${hookName} hook handler`);
+  }
+  return handler;
+}
+
+function createSpawnEvent(overrides?: {
+  childSessionKey?: string;
+  agentId?: string;
+  label?: string;
+  mode?: string;
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string;
+  };
+  threadRequested?: boolean;
+}): {
+  childSessionKey: string;
+  agentId: string;
+  label: string;
+  mode: string;
+  requester: {
+    channel: string;
+    accountId: string;
+    to: string;
+    threadId?: string;
+  };
+  threadRequested: boolean;
+} {
+  const base = {
+    childSessionKey: "agent:main:subagent:child",
+    agentId: "main",
+    label: "banana",
+    mode: "session",
+    requester: {
+      channel: "discord",
+      accountId: "work",
+      to: "channel:123",
+      threadId: "456",
+    },
+    threadRequested: true,
+  };
+  return {
+    ...base,
+    ...overrides,
+    requester: {
+      ...base.requester,
+      ...(overrides?.requester ?? {}),
+    },
+  };
+}
+
+function createSpawnEventWithoutThread() {
+  return createSpawnEvent({
+    label: "",
+    requester: { threadId: undefined },
+  });
+}
+
+async function runSubagentSpawning(
+  config?: Record<string, unknown>,
+  event = createSpawnEventWithoutThread(),
+) {
+  const handlers = registerHandlersForTest(config);
+  const handler = getRequiredHandler(handlers, "subagent_spawning");
+  return await handler(event, {});
+}
+
+async function expectSubagentSpawningError(params?: {
+  config?: Record<string, unknown>;
+  errorContains?: string;
+  event?: ReturnType<typeof createSpawnEvent>;
+}) {
+  const result = await runSubagentSpawning(params?.config, params?.event);
+  expect(hookMocks.autoBindSpawnedDiscordSubagent).not.toHaveBeenCalled();
+  expect(result).toMatchObject({ status: "error" });
+  if (params?.errorContains) {
+    const errorText = (result as { error?: string }).error ?? "";
+    expect(errorText).toContain(params.errorContains);
+  }
+}
+
+describe("discord subagent hook handlers", () => {
+  beforeEach(() => {
+    hookMocks.resolveDiscordAccount.mockClear();
+    hookMocks.resolveDiscordAccount.mockImplementation((params?: { accountId?: string }) => ({
+      accountId: params?.accountId?.trim() || "default",
+      config: {
+        threadBindings: {
+          spawnSubagentSessions: true,
+        },
+      },
+    }));
+    hookMocks.autoBindSpawnedDiscordSubagent.mockClear();
+    hookMocks.listThreadBindingsBySessionKey.mockClear();
+    hookMocks.unbindThreadBindingsBySessionKey.mockClear();
+  });
+
+  it("registers subagent hooks", () => {
+    const handlers = registerHandlersForTest();
+    expect(handlers.has("subagent_spawning")).toBe(true);
+    expect(handlers.has("subagent_delivery_target")).toBe(true);
+    expect(handlers.has("subagent_spawned")).toBe(false);
+    expect(handlers.has("subagent_ended")).toBe(true);
+  });
+
+  it("binds thread routing on subagent_spawning", async () => {
+    const handlers = registerHandlersForTest();
+    const handler = getRequiredHandler(handlers, "subagent_spawning");
+
+    const result = await handler(createSpawnEvent(), {});
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledTimes(1);
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledWith({
+      accountId: "work",
+      channel: "discord",
+      to: "channel:123",
+      threadId: "456",
+      childSessionKey: "agent:main:subagent:child",
+      agentId: "main",
+      label: "banana",
+      boundBy: "system",
+    });
+    expect(result).toMatchObject({ status: "ok", threadBindingReady: true });
+  });
+
+  it("returns error when thread-bound subagent spawn is disabled", async () => {
+    await expectSubagentSpawningError({
+      config: {
+        channels: {
+          discord: {
+            threadBindings: {
+              spawnSubagentSessions: false,
+            },
+          },
+        },
+      },
+      errorContains: "spawnSubagentSessions=true",
+    });
+  });
+
+  it("returns error when global thread bindings are disabled", async () => {
+    await expectSubagentSpawningError({
+      config: {
+        session: {
+          threadBindings: {
+            enabled: false,
+          },
+        },
+        channels: {
+          discord: {
+            threadBindings: {
+              spawnSubagentSessions: true,
+            },
+          },
+        },
+      },
+      errorContains: "threadBindings.enabled=true",
+    });
+  });
+
+  it("allows account-level threadBindings.enabled to override global disable", async () => {
+    const result = await runSubagentSpawning({
+      session: {
+        threadBindings: {
+          enabled: false,
+        },
+      },
+      channels: {
+        discord: {
+          accounts: {
+            work: {
+              threadBindings: {
+                enabled: true,
+                spawnSubagentSessions: true,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({ status: "ok", threadBindingReady: true });
+  });
+
+  it("defaults thread-bound subagent spawn to disabled when unset", async () => {
+    await expectSubagentSpawningError({
+      config: {
+        channels: {
+          discord: {
+            threadBindings: {},
+          },
+        },
+      },
+    });
+  });
+
+  it("no-ops when thread binding is requested on non-discord channel", async () => {
+    const result = await runSubagentSpawning(
+      undefined,
+      createSpawnEvent({
+        requester: {
+          channel: "signal",
+          accountId: "",
+          to: "+123",
+          threadId: undefined,
+        },
+      }),
+    );
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).not.toHaveBeenCalled();
+    expect(result).toBeUndefined();
+  });
+
+  it("returns error when thread bind fails", async () => {
+    hookMocks.autoBindSpawnedDiscordSubagent.mockResolvedValueOnce(null);
+    const result = await runSubagentSpawning();
+
+    expect(result).toMatchObject({ status: "error" });
+    const errorText = (result as { error?: string }).error ?? "";
+    expect(errorText).toMatch(/unable to create or bind/i);
+  });
+
+  it("unbinds thread routing on subagent_ended", () => {
+    const handlers = registerHandlersForTest();
+    const handler = getRequiredHandler(handlers, "subagent_ended");
+
+    handler(
+      {
+        targetSessionKey: "agent:main:subagent:child",
+        targetKind: "subagent",
+        reason: "subagent-complete",
+        sendFarewell: true,
+        accountId: "work",
+      },
+      {},
+    );
+
+    expect(hookMocks.unbindThreadBindingsBySessionKey).toHaveBeenCalledTimes(1);
+    expect(hookMocks.unbindThreadBindingsBySessionKey).toHaveBeenCalledWith({
+      targetSessionKey: "agent:main:subagent:child",
+      accountId: "work",
+      targetKind: "subagent",
+      reason: "subagent-complete",
+      sendFarewell: true,
+    });
+  });
+
+  it("resolves delivery target from matching bound thread", () => {
+    hookMocks.listThreadBindingsBySessionKey.mockReturnValueOnce([
+      { accountId: "work", threadId: "777" },
+    ]);
+    const handlers = registerHandlersForTest();
+    const handler = getRequiredHandler(handlers, "subagent_delivery_target");
+
+    const result = handler(
+      {
+        childSessionKey: "agent:main:subagent:child",
+        requesterSessionKey: "agent:main:main",
+        requesterOrigin: {
+          channel: "discord",
+          accountId: "work",
+          to: "channel:123",
+          threadId: "777",
+        },
+        childRunId: "run-1",
+        spawnMode: "session",
+        expectsCompletionMessage: true,
+      },
+      {},
+    );
+
+    expect(hookMocks.listThreadBindingsBySessionKey).toHaveBeenCalledWith({
+      targetSessionKey: "agent:main:subagent:child",
+      accountId: "work",
+      targetKind: "subagent",
+    });
+    expect(result).toEqual({
+      origin: {
+        channel: "discord",
+        accountId: "work",
+        to: "channel:777",
+        threadId: "777",
+      },
+    });
+  });
+
+  it("keeps original routing when delivery target is ambiguous", () => {
+    hookMocks.listThreadBindingsBySessionKey.mockReturnValueOnce([
+      { accountId: "work", threadId: "777" },
+      { accountId: "work", threadId: "888" },
+    ]);
+    const handlers = registerHandlersForTest();
+    const handler = getRequiredHandler(handlers, "subagent_delivery_target");
+
+    const result = handler(
+      {
+        childSessionKey: "agent:main:subagent:child",
+        requesterSessionKey: "agent:main:main",
+        requesterOrigin: {
+          channel: "discord",
+          accountId: "work",
+          to: "channel:123",
+        },
+        childRunId: "run-1",
+        spawnMode: "session",
+        expectsCompletionMessage: true,
+      },
+      {},
+    );
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/subagent-hooks.ts

@@ -0,0 +1,152 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  autoBindSpawnedDiscordSubagent,
+  listThreadBindingsBySessionKey,
+  resolveDiscordAccount,
+  unbindThreadBindingsBySessionKey,
+} from "openclaw/plugin-sdk";
+
+function summarizeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  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,
+    };
+  };
+
+  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).",
+      };
+    }
+    if (!threadBindingFlags.spawnSubagentSessions) {
+      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)}`,
+      };
+    }
+  });
+
+  api.on("subagent_ended", (event) => {
+    unbindThreadBindingsBySessionKey({
+      targetSessionKey: event.targetSessionKey,
+      accountId: event.accountId,
+      targetKind: event.targetKind,
+      reason: event.reason,
+      sendFarewell: event.sendFarewell,
+    });
+  });
+
+  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",
+    });
+    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,
+      },
+    };
+  });
+}