@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/actions/runtime.moderation.authz.test.ts

@@ -0,0 +1,151 @@
+import { PermissionFlagsBits } from "discord-api-types/v10";
+import type { DiscordActionConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EMPTY_DISCORD_TEST_CONFIG } from "../test-support/config.js";
+import {
+  discordModerationActionRuntime,
+  handleDiscordModerationAction,
+} from "./runtime.moderation.js";
+
+const originalDiscordModerationActionRuntime = { ...discordModerationActionRuntime };
+const banMemberDiscord = vi.fn(async () => ({ ok: true }));
+const kickMemberDiscord = vi.fn(async () => ({ ok: true }));
+const timeoutMemberDiscord = vi.fn(async () => ({ id: "user-1" }));
+const hasAnyGuildPermissionDiscord = vi.fn(async () => false);
+
+const enableAllActions = (_key: keyof DiscordActionConfig, _defaultValue = true) => true;
+const DISCORD_TEST_CFG = EMPTY_DISCORD_TEST_CONFIG;
+
+function handleModerationAction(action: string, params: Record<string, unknown>) {
+  return handleDiscordModerationAction(action, params, enableAllActions, DISCORD_TEST_CFG);
+}
+
+describe("discord moderation sender authorization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    Object.assign(discordModerationActionRuntime, originalDiscordModerationActionRuntime, {
+      banMemberDiscord,
+      kickMemberDiscord,
+      timeoutMemberDiscord,
+      hasAnyGuildPermissionDiscord,
+    });
+  });
+
+  it("rejects ban when sender lacks BAN_MEMBERS", async () => {
+    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
+
+    await expect(
+      handleModerationAction("ban", {
+        guildId: "guild-1",
+        userId: "user-1",
+        senderUserId: "sender-1",
+      }),
+    ).rejects.toThrow("required permissions");
+
+    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
+      "guild-1",
+      "sender-1",
+      [PermissionFlagsBits.BanMembers],
+      { cfg: DISCORD_TEST_CFG },
+    );
+    expect(banMemberDiscord).not.toHaveBeenCalled();
+  });
+
+  it("rejects kick when sender lacks KICK_MEMBERS", async () => {
+    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
+
+    await expect(
+      handleModerationAction("kick", {
+        guildId: "guild-1",
+        userId: "user-1",
+        senderUserId: "sender-1",
+      }),
+    ).rejects.toThrow("required permissions");
+
+    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
+      "guild-1",
+      "sender-1",
+      [PermissionFlagsBits.KickMembers],
+      { cfg: DISCORD_TEST_CFG },
+    );
+    expect(kickMemberDiscord).not.toHaveBeenCalled();
+  });
+
+  it("rejects timeout when sender lacks MODERATE_MEMBERS", async () => {
+    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
+
+    await expect(
+      handleModerationAction("timeout", {
+        guildId: "guild-1",
+        userId: "user-1",
+        senderUserId: "sender-1",
+        durationMinutes: 60,
+      }),
+    ).rejects.toThrow("required permissions");
+
+    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
+      "guild-1",
+      "sender-1",
+      [PermissionFlagsBits.ModerateMembers],
+      { cfg: DISCORD_TEST_CFG },
+    );
+    expect(timeoutMemberDiscord).not.toHaveBeenCalled();
+  });
+
+  it("executes moderation action when sender has required permission", async () => {
+    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(true);
+    kickMemberDiscord.mockResolvedValueOnce({ ok: true });
+
+    await handleModerationAction("kick", {
+      guildId: "guild-1",
+      userId: "user-1",
+      senderUserId: "sender-1",
+      reason: "rule violation",
+    });
+
+    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
+      "guild-1",
+      "sender-1",
+      [PermissionFlagsBits.KickMembers],
+      { cfg: DISCORD_TEST_CFG },
+    );
+    expect(kickMemberDiscord).toHaveBeenCalledWith(
+      {
+        guildId: "guild-1",
+        userId: "user-1",
+        reason: "rule violation",
+      },
+      { cfg: DISCORD_TEST_CFG },
+    );
+  });
+
+  it("forwards accountId into permission check and moderation execution", async () => {
+    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(true);
+    timeoutMemberDiscord.mockResolvedValueOnce({ id: "user-1" });
+
+    await handleModerationAction("timeout", {
+      guildId: "guild-1",
+      userId: "user-1",
+      senderUserId: "sender-1",
+      accountId: "ops",
+      durationMinutes: 5,
+    });
+
+    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
+      "guild-1",
+      "sender-1",
+      [PermissionFlagsBits.ModerateMembers],
+      { cfg: DISCORD_TEST_CFG, accountId: "ops" },
+    );
+    expect(timeoutMemberDiscord).toHaveBeenCalledWith(
+      {
+        guildId: "guild-1",
+        userId: "user-1",
+        durationMinutes: 5,
+        until: undefined,
+        reason: undefined,
+      },
+      { cfg: DISCORD_TEST_CFG, accountId: "ops" },
+    );
+  });
+});

package/src/actions/runtime.moderation.ts

@@ -0,0 +1,116 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import {
+  type ActionGate,
+  jsonResult,
+  readStringParam,
+  type DiscordActionConfig,
+  type OpenClawConfig,
+} from "../runtime-api.js";
+import {
+  banMemberDiscord,
+  hasAnyGuildPermissionDiscord,
+  kickMemberDiscord,
+  timeoutMemberDiscord,
+} from "../send.js";
+import {
+  isDiscordModerationAction,
+  readDiscordModerationCommand,
+  requiredGuildPermissionForModerationAction,
+} from "./runtime.moderation-shared.js";
+import { createDiscordActionOptions } from "./runtime.shared.js";
+
+export const discordModerationActionRuntime = {
+  banMemberDiscord,
+  hasAnyGuildPermissionDiscord,
+  kickMemberDiscord,
+  timeoutMemberDiscord,
+};
+
+async function verifySenderModerationPermission(params: {
+  guildId: string;
+  senderUserId?: string;
+  requiredPermission: bigint;
+  accountId?: string;
+  cfg: OpenClawConfig;
+}) {
+  // CLI/manual flows may not have sender context; enforce only when present.
+  if (!params.senderUserId) {
+    return;
+  }
+  const hasPermission = await discordModerationActionRuntime.hasAnyGuildPermissionDiscord(
+    params.guildId,
+    params.senderUserId,
+    [params.requiredPermission],
+    createDiscordActionOptions({ cfg: params.cfg, accountId: params.accountId }),
+  );
+  if (!hasPermission) {
+    throw new Error("Sender does not have required permissions for this moderation action.");
+  }
+}
+
+export async function handleDiscordModerationAction(
+  action: string,
+  params: Record<string, unknown>,
+  isActionEnabled: ActionGate<DiscordActionConfig>,
+  cfg: OpenClawConfig,
+): Promise<AgentToolResult<unknown>> {
+  if (!isDiscordModerationAction(action)) {
+    throw new Error(`Unknown action: ${action}`);
+  }
+  if (!isActionEnabled("moderation", false)) {
+    throw new Error("Discord moderation is disabled.");
+  }
+  if (!cfg) {
+    throw new Error("Discord moderation actions require a resolved runtime config.");
+  }
+  const accountId = readStringParam(params, "accountId");
+  const command = readDiscordModerationCommand(action, params);
+  const senderUserId = readStringParam(params, "senderUserId");
+  const withOpts = () => createDiscordActionOptions({ cfg, accountId });
+  await verifySenderModerationPermission({
+    guildId: command.guildId,
+    senderUserId,
+    requiredPermission: requiredGuildPermissionForModerationAction(command.action),
+    accountId,
+    cfg,
+  });
+  switch (command.action) {
+    case "timeout": {
+      const member = await discordModerationActionRuntime.timeoutMemberDiscord(
+        {
+          guildId: command.guildId,
+          userId: command.userId,
+          durationMinutes: command.durationMinutes,
+          until: command.until,
+          reason: command.reason,
+        },
+        withOpts(),
+      );
+      return jsonResult({ ok: true, member });
+    }
+    case "kick": {
+      await discordModerationActionRuntime.kickMemberDiscord(
+        {
+          guildId: command.guildId,
+          userId: command.userId,
+          reason: command.reason,
+        },
+        withOpts(),
+      );
+      return jsonResult({ ok: true });
+    }
+    case "ban": {
+      await discordModerationActionRuntime.banMemberDiscord(
+        {
+          guildId: command.guildId,
+          userId: command.userId,
+          reason: command.reason,
+          deleteMessageDays: command.deleteMessageDays,
+        },
+        withOpts(),
+      );
+      return jsonResult({ ok: true });
+    }
+  }
+  throw new Error("Unsupported Discord moderation action");
+}

package/src/actions/runtime.presence.test.ts

@@ -0,0 +1,160 @@
+import type { DiscordActionConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { GatewayPlugin } from "../internal/gateway.js";
+import { clearGateways, registerGateway } from "../monitor/gateway-registry.js";
+import type { ActionGate } from "../runtime-api.js";
+import { handleDiscordPresenceAction } from "./runtime.presence.js";
+
+const mockUpdatePresence = vi.fn();
+
+function createMockGateway(connected = true): GatewayPlugin {
+  return { isConnected: connected, updatePresence: mockUpdatePresence } as unknown as GatewayPlugin;
+}
+
+const presenceEnabled: ActionGate<DiscordActionConfig> = (key) => key === "presence";
+const presenceDisabled: ActionGate<DiscordActionConfig> = () => false;
+
+describe("handleDiscordPresenceAction", () => {
+  async function setPresence(
+    params: Record<string, unknown>,
+    actionGate: ActionGate<DiscordActionConfig> = presenceEnabled,
+  ) {
+    return await handleDiscordPresenceAction("setPresence", params, actionGate);
+  }
+
+  beforeEach(() => {
+    mockUpdatePresence.mockClear();
+    clearGateways();
+    registerGateway(undefined, createMockGateway());
+  });
+
+  it("sets playing activity", async () => {
+    const result = await handleDiscordPresenceAction(
+      "setPresence",
+      { activityType: "playing", activityName: "with fire", status: "online" },
+      presenceEnabled,
+    );
+    expect(mockUpdatePresence).toHaveBeenCalledWith({
+      since: null,
+      activities: [{ name: "with fire", type: 0 }],
+      status: "online",
+      afk: false,
+    });
+    const textBlock = result.content.find((block) => block.type === "text");
+    const payload = JSON.parse(
+      (textBlock as { type: "text"; text: string } | undefined)?.text ?? "{}",
+    );
+    expect(payload.ok).toBe(true);
+    expect(payload.activities[0]).toEqual({ type: 0, name: "with fire" });
+  });
+
+  it.each([
+    {
+      name: "streaming activity with URL",
+      params: {
+        activityType: "streaming",
+        activityName: "My Stream",
+        activityUrl: "https://twitch.tv/example",
+      },
+      expectedActivities: [{ name: "My Stream", type: 1, url: "https://twitch.tv/example" }],
+    },
+    {
+      name: "streaming activity without URL",
+      params: { activityType: "streaming", activityName: "My Stream" },
+      expectedActivities: [{ name: "My Stream", type: 1 }],
+    },
+    {
+      name: "listening activity",
+      params: { activityType: "listening", activityName: "Spotify" },
+      expectedActivities: [{ name: "Spotify", type: 2 }],
+    },
+    {
+      name: "watching activity",
+      params: { activityType: "watching", activityName: "you" },
+      expectedActivities: [{ name: "you", type: 3 }],
+    },
+    {
+      name: "custom activity using state",
+      params: { activityType: "custom", activityState: "Vibing" },
+      expectedActivities: [{ name: "", type: 4, state: "Vibing" }],
+    },
+    {
+      name: "activity with state",
+      params: { activityType: "playing", activityName: "My Game", activityState: "In the lobby" },
+      expectedActivities: [{ name: "My Game", type: 0, state: "In the lobby" }],
+    },
+    {
+      name: "default empty activity name when only type provided",
+      params: { activityType: "playing" },
+      expectedActivities: [{ name: "", type: 0 }],
+    },
+  ])("sets $name", async ({ params, expectedActivities }) => {
+    await setPresence(params);
+    expect(mockUpdatePresence).toHaveBeenCalledWith({
+      since: null,
+      activities: expectedActivities,
+      status: "online",
+      afk: false,
+    });
+  });
+
+  it("sets status-only without activity", async () => {
+    await setPresence({ status: "idle" });
+    expect(mockUpdatePresence).toHaveBeenCalledWith({
+      since: null,
+      activities: [],
+      status: "idle",
+      afk: false,
+    });
+  });
+
+  it.each([
+    { name: "invalid status", params: { status: "offline" }, expectedMessage: /Invalid status/ },
+    {
+      name: "invalid activity type",
+      params: { activityType: "invalid" },
+      expectedMessage: /Invalid activityType/,
+    },
+  ])("rejects $name", async ({ params, expectedMessage }) => {
+    await expect(setPresence(params)).rejects.toThrow(expectedMessage);
+  });
+
+  it("defaults status to online", async () => {
+    await setPresence({ activityType: "playing", activityName: "test" });
+    expect(mockUpdatePresence).toHaveBeenCalledWith(expect.objectContaining({ status: "online" }));
+  });
+
+  it("respects presence gating", async () => {
+    await expect(setPresence({ status: "online" }, presenceDisabled)).rejects.toThrow(/disabled/);
+  });
+
+  it("errors when gateway is not registered", async () => {
+    clearGateways();
+    await expect(setPresence({ status: "dnd" })).rejects.toThrow(/not available/);
+  });
+
+  it("errors when gateway is not connected", async () => {
+    clearGateways();
+    registerGateway(undefined, createMockGateway(false));
+    await expect(setPresence({ status: "dnd" })).rejects.toThrow(/not connected/);
+  });
+
+  it("uses accountId to resolve gateway", async () => {
+    const accountGateway = createMockGateway();
+    registerGateway("my-account", accountGateway);
+    await setPresence({ accountId: "my-account", activityType: "playing", activityName: "test" });
+    expect(mockUpdatePresence).toHaveBeenCalled();
+  });
+
+  it("requires activityType when activityName is provided", async () => {
+    await expect(setPresence({ activityName: "My Game" })).rejects.toThrow(
+      /activityType is required/,
+    );
+  });
+
+  it("rejects unknown presence actions", async () => {
+    await expect(handleDiscordPresenceAction("unknownAction", {}, presenceEnabled)).rejects.toThrow(
+      /Unknown presence action/,
+    );
+  });
+});

package/src/actions/runtime.presence.ts

@@ -0,0 +1,117 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import type { Activity, UpdatePresenceData } from "../internal/gateway.js";
+import { getGateway } from "../monitor/gateway-registry.js";
+import {
+  type ActionGate,
+  jsonResult,
+  readStringParam,
+  type DiscordActionConfig,
+} from "../runtime-api.js";
+
+const ACTIVITY_TYPE_MAP: Record<string, number> = {
+  playing: 0,
+  streaming: 1,
+  listening: 2,
+  watching: 3,
+  custom: 4,
+  competing: 5,
+};
+
+const VALID_STATUSES = new Set(["online", "dnd", "idle", "invisible"]);
+
+export async function handleDiscordPresenceAction(
+  action: string,
+  params: Record<string, unknown>,
+  isActionEnabled: ActionGate<DiscordActionConfig>,
+): Promise<AgentToolResult<unknown>> {
+  if (action !== "setPresence") {
+    throw new Error(`Unknown presence action: ${action}`);
+  }
+
+  if (!isActionEnabled("presence", false)) {
+    throw new Error("Discord presence changes are disabled.");
+  }
+
+  const accountId = readStringParam(params, "accountId");
+  const gateway = getGateway(accountId);
+  if (!gateway) {
+    throw new Error(
+      `Discord gateway not available${accountId ? ` for account "${accountId}"` : ""}. The bot may not be connected.`,
+    );
+  }
+  if (!gateway.isConnected) {
+    throw new Error(
+      `Discord gateway is not connected${accountId ? ` for account "${accountId}"` : ""}.`,
+    );
+  }
+
+  const statusRaw = readStringParam(params, "status") ?? "online";
+  if (!VALID_STATUSES.has(statusRaw)) {
+    throw new Error(
+      `Invalid status "${statusRaw}". Must be one of: ${[...VALID_STATUSES].join(", ")}`,
+    );
+  }
+  const status = statusRaw as UpdatePresenceData["status"];
+
+  const activityTypeRaw = readStringParam(params, "activityType");
+  const activityName = readStringParam(params, "activityName");
+
+  const activities: Activity[] = [];
+
+  if (activityTypeRaw || activityName) {
+    if (!activityTypeRaw) {
+      throw new Error(
+        "activityType is required when activityName is provided. " +
+          `Valid types: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`,
+      );
+    }
+    const typeNum = ACTIVITY_TYPE_MAP[normalizeLowercaseStringOrEmpty(activityTypeRaw)];
+    if (typeNum === undefined) {
+      throw new Error(
+        `Invalid activityType "${activityTypeRaw}". Must be one of: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`,
+      );
+    }
+
+    const activity: Activity = {
+      name: activityName ?? "",
+      type: typeNum,
+    };
+
+    // Streaming URL (Twitch/YouTube). May not render for bots but is the correct payload shape.
+    if (typeNum === 1) {
+      const url = readStringParam(params, "activityUrl");
+      if (url) {
+        activity.url = url;
+      }
+    }
+
+    const state = readStringParam(params, "activityState");
+    if (state) {
+      activity.state = state;
+    }
+
+    activities.push(activity);
+  }
+
+  const presenceData: UpdatePresenceData = {
+    since: null,
+    activities,
+    status,
+    afk: false,
+  };
+
+  gateway.updatePresence(presenceData);
+
+  return jsonResult({
+    ok: true,
+    status,
+    activities: activities.map((a) =>
+      Object.assign(
+        { type: a.type, name: a.name },
+        a.url ? { url: a.url } : {},
+        a.state ? { state: a.state } : {},
+      ),
+    ),
+  });
+}

package/src/actions/runtime.shared.ts

@@ -0,0 +1,83 @@
+import { parseAvailableTags, readNumberParam, readStringParam } from "../runtime-api.js";
+import type { OpenClawConfig } from "../runtime-api.js";
+import type {
+  DiscordChannelCreate,
+  DiscordChannelEdit,
+  DiscordChannelMove,
+} from "../send.types.js";
+
+export function readDiscordParentIdParam(
+  params: Record<string, unknown>,
+): string | null | undefined {
+  if (params.clearParent === true) {
+    return null;
+  }
+  if (params.parentId === null) {
+    return null;
+  }
+  return readStringParam(params, "parentId");
+}
+
+function readDiscordBooleanParam(
+  params: Record<string, unknown>,
+  key: string,
+): boolean | undefined {
+  return typeof params[key] === "boolean" ? params[key] : undefined;
+}
+
+export function createDiscordActionOptions<
+  T extends Record<string, unknown> = Record<string, never>,
+>(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+  extra?: T;
+}): { cfg: OpenClawConfig; accountId?: string } & T {
+  return {
+    cfg: params.cfg,
+    ...(params.accountId ? { accountId: params.accountId } : {}),
+    ...(params.extra ?? ({} as T)),
+  };
+}
+
+export function readDiscordChannelCreateParams(
+  params: Record<string, unknown>,
+): DiscordChannelCreate {
+  const parentId = readDiscordParentIdParam(params);
+  return {
+    guildId: readStringParam(params, "guildId", { required: true }),
+    name: readStringParam(params, "name", { required: true }),
+    type: readNumberParam(params, "type", { integer: true }) ?? undefined,
+    parentId: parentId ?? undefined,
+    topic: readStringParam(params, "topic") ?? undefined,
+    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
+    nsfw: readDiscordBooleanParam(params, "nsfw"),
+  };
+}
+
+export function readDiscordChannelEditParams(params: Record<string, unknown>): DiscordChannelEdit {
+  const parentId = readDiscordParentIdParam(params);
+  return {
+    channelId: readStringParam(params, "channelId", { required: true }),
+    name: readStringParam(params, "name") ?? undefined,
+    topic: readStringParam(params, "topic") ?? undefined,
+    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
+    parentId: parentId === undefined ? undefined : parentId,
+    nsfw: readDiscordBooleanParam(params, "nsfw"),
+    rateLimitPerUser: readNumberParam(params, "rateLimitPerUser", { integer: true }) ?? undefined,
+    archived: readDiscordBooleanParam(params, "archived"),
+    locked: readDiscordBooleanParam(params, "locked"),
+    autoArchiveDuration:
+      readNumberParam(params, "autoArchiveDuration", { integer: true }) ?? undefined,
+    availableTags: parseAvailableTags(params.availableTags),
+  };
+}
+
+export function readDiscordChannelMoveParams(params: Record<string, unknown>): DiscordChannelMove {
+  const parentId = readDiscordParentIdParam(params);
+  return {
+    guildId: readStringParam(params, "guildId", { required: true }),
+    channelId: readStringParam(params, "channelId", { required: true }),
+    parentId: parentId === undefined ? undefined : parentId,
+    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
+  };
+}