@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/actions/runtime.ts

@@ -0,0 +1,81 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { createDiscordActionGate } from "../accounts.js";
+import { readStringParam, type OpenClawConfig } from "../runtime-api.js";
+import { handleDiscordGuildAction } from "./runtime.guild.js";
+import { handleDiscordMessagingAction } from "./runtime.messaging.js";
+import { handleDiscordModerationAction } from "./runtime.moderation.js";
+import { handleDiscordPresenceAction } from "./runtime.presence.js";
+
+const messagingActions = new Set([
+  "react",
+  "reactions",
+  "sticker",
+  "poll",
+  "permissions",
+  "fetchMessage",
+  "readMessages",
+  "sendMessage",
+  "editMessage",
+  "deleteMessage",
+  "threadCreate",
+  "threadList",
+  "threadReply",
+  "pinMessage",
+  "unpinMessage",
+  "listPins",
+  "searchMessages",
+]);
+
+const guildActions = new Set([
+  "memberInfo",
+  "roleInfo",
+  "emojiList",
+  "emojiUpload",
+  "stickerUpload",
+  "roleAdd",
+  "roleRemove",
+  "channelInfo",
+  "channelList",
+  "voiceStatus",
+  "eventList",
+  "eventCreate",
+  "channelCreate",
+  "channelEdit",
+  "channelDelete",
+  "channelMove",
+  "categoryCreate",
+  "categoryEdit",
+  "categoryDelete",
+  "channelPermissionSet",
+  "channelPermissionRemove",
+]);
+
+const moderationActions = new Set(["timeout", "kick", "ban"]);
+
+const presenceActions = new Set(["setPresence"]);
+
+export async function handleDiscordAction(
+  params: Record<string, unknown>,
+  cfg: OpenClawConfig,
+  options?: {
+    mediaLocalRoots?: readonly string[];
+  },
+): Promise<AgentToolResult<unknown>> {
+  const action = readStringParam(params, "action", { required: true });
+  const accountId = readStringParam(params, "accountId");
+  const isActionEnabled = createDiscordActionGate({ cfg, accountId });
+
+  if (messagingActions.has(action)) {
+    return await handleDiscordMessagingAction(action, params, isActionEnabled, cfg, options);
+  }
+  if (guildActions.has(action)) {
+    return await handleDiscordGuildAction(action, params, isActionEnabled, cfg, options);
+  }
+  if (moderationActions.has(action)) {
+    return await handleDiscordModerationAction(action, params, isActionEnabled, cfg);
+  }
+  if (presenceActions.has(action)) {
+    return await handleDiscordPresenceAction(action, params, isActionEnabled);
+  }
+  throw new Error(`Unknown action: ${action}`);
+}

package/src/api-barrel.test.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+const API_SOURCE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), "../api.ts");
+const itOnSupportedNode = Number(process.versions.node.split(".")[0]) >= 22 ? it : it.skip;
+
+function collectExportedNames(): Set<string> {
+  const source = ts.createSourceFile(
+    API_SOURCE_PATH,
+    readFileSync(API_SOURCE_PATH, "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  const names = new Set<string>();
+  for (const statement of source.statements) {
+    if (
+      ts.isVariableStatement(statement) &&
+      statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) {
+          names.add(declaration.name.text);
+        }
+      }
+      continue;
+    }
+    if (!ts.isExportDeclaration(statement) || !statement.exportClause) {
+      continue;
+    }
+    if (ts.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements) {
+        names.add(element.name.text);
+      }
+    }
+  }
+  return names;
+}
+
+describe("discord API barrel", () => {
+  it("exports current internal entrypoints", () => {
+    const exportedNames = collectExportedNames();
+
+    for (const exportName of [
+      "discordPlugin",
+      "discordSetupPlugin",
+      "buildDiscordComponentCustomId",
+      "handleDiscordMessageAction",
+      "parseDiscordComponentCustomIdForCarbon",
+      "parseDiscordComponentCustomIdForInteraction",
+      "parseDiscordModalCustomIdForCarbon",
+      "parseDiscordModalCustomIdForInteraction",
+      "fetchDiscordApplicationSummary",
+      "DiscordSendResult",
+    ]) {
+      expect(exportedNames).toContain(exportName);
+    }
+  });
+
+  itOnSupportedNode("links runtime exports used by bundled Discord wiring", async () => {
+    const api = await import("../api.js");
+
+    for (const exportName of [
+      "DISCORD_COMPONENT_CUSTOM_ID_KEY",
+      "buildDiscordComponentMessageFlags",
+      "createDiscordFormModal",
+      "handleDiscordMessageAction",
+      "handleDiscordSubagentSpawning",
+      "listEnabledDiscordAccounts",
+      "parseDiscordComponentCustomIdForCarbon",
+      "parseDiscordModalCustomIdForCarbon",
+      "resolveDiscordRuntimeGroupPolicy",
+      "tryHandleDiscordMessageActionGuildAdmin",
+    ]) {
+      expect(api).toHaveProperty(exportName);
+    }
+  });
+});

package/src/api.test.ts

@@ -0,0 +1,130 @@
+import { withFetchPreconnect } from "openclaw/plugin-sdk/test-env";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { DiscordApiError, fetchDiscord } from "./api.js";
+import { jsonResponse } from "./test-http-helpers.js";
+
+describe("fetchDiscord", () => {
+  beforeEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("formats rate limit payloads without raw JSON", async () => {
+    const fetcher = withFetchPreconnect(async () =>
+      jsonResponse(
+        {
+          message: "You are being rate limited.",
+          retry_after: 0.631,
+          global: false,
+        },
+        429,
+      ),
+    );
+
+    let error: unknown;
+    try {
+      await fetchDiscord("/users/@me/guilds", "test", fetcher, {
+        retry: { attempts: 1 },
+      });
+    } catch (err) {
+      error = err;
+    }
+
+    const message = String(error);
+    expect(message).toContain("Discord API /users/@me/guilds failed (429)");
+    expect(message).toContain("You are being rate limited.");
+    expect(message).toContain("retry after 0.6s");
+    expect(message).not.toContain("{");
+    expect(message).not.toContain("retry_after");
+  });
+
+  it("preserves non-JSON error text", async () => {
+    const fetcher = withFetchPreconnect(async () => new Response("Not Found", { status: 404 }));
+    await expect(
+      fetchDiscord("/users/@me/guilds", "test", fetcher, {
+        retry: { attempts: 1 },
+      }),
+    ).rejects.toThrow("Discord API /users/@me/guilds failed (404): Not Found");
+  });
+
+  it("sanitizes Cloudflare HTML rate limits and applies a fallback cooldown", async () => {
+    const fetcher = withFetchPreconnect(
+      async () =>
+        new Response(
+          "<!doctype html><html><head><title>Error 1015</title></head><body><h1>You are being rate limited</h1><script>raw()</script></body></html>",
+          { status: 429, headers: { "content-type": "text/html" } },
+        ),
+    );
+
+    let error: unknown;
+    try {
+      await fetchDiscord("/users/@me/guilds", "test", fetcher, {
+        retry: { attempts: 1 },
+      });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).toBeInstanceOf(DiscordApiError);
+    expect((error as DiscordApiError).retryAfter).toBe(60);
+    const message = String(error);
+    expect(message).toContain("Discord API /users/@me/guilds failed (429)");
+    expect(message).toContain("rate limited by Discord upstream");
+    expect(message).toContain("Error 1015");
+    expect(message).not.toContain("<html");
+    expect(message).not.toContain("<script");
+  });
+
+  it("honors Retry-After for Cloudflare HTML application lookup rate limits", async () => {
+    const fetcher = withFetchPreconnect(
+      async () =>
+        new Response("<html><title>Error 1015</title><body>rate limited</body></html>", {
+          status: 429,
+          headers: { "content-type": "text/html", "retry-after": "7" },
+        }),
+    );
+
+    let error: unknown;
+    try {
+      await fetchDiscord("/oauth2/applications/@me", "test", fetcher, {
+        retry: { attempts: 1 },
+      });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).toBeInstanceOf(DiscordApiError);
+    expect((error as DiscordApiError).retryAfter).toBe(7);
+    const message = String(error);
+    expect(message).toContain("Discord API /oauth2/applications/@me failed (429)");
+    expect(message).toContain("Error 1015");
+    expect(message).not.toContain("<html");
+  });
+
+  it("retries rate limits before succeeding", async () => {
+    let calls = 0;
+    const fetcher = withFetchPreconnect(async () => {
+      calls += 1;
+      if (calls === 1) {
+        return jsonResponse(
+          {
+            message: "You are being rate limited.",
+            retry_after: 0,
+            global: false,
+          },
+          429,
+        );
+      }
+      return jsonResponse([{ id: "1", name: "Guild" }], 200);
+    });
+
+    const result = await fetchDiscord<Array<{ id: string; name: string }>>(
+      "/users/@me/guilds",
+      "test",
+      fetcher,
+      { retry: { attempts: 2, minDelayMs: 0, maxDelayMs: 0, jitter: 0 } },
+    );
+
+    expect(result).toHaveLength(1);
+    expect(calls).toBe(2);
+  });
+});

package/src/api.ts

@@ -0,0 +1,169 @@
+import { resolveFetch } from "openclaw/plugin-sdk/fetch-runtime";
+import {
+  resolveRetryConfig,
+  retryAsync,
+  type RetryConfig,
+} from "openclaw/plugin-sdk/retry-runtime";
+import { isDiscordHtmlResponseBody, summarizeDiscordResponseBody } from "./error-body.js";
+
+const DISCORD_API_BASE = "https://discord.com/api/v10";
+const DISCORD_API_RETRY_DEFAULTS = {
+  attempts: 3,
+  minDelayMs: 500,
+  maxDelayMs: 5 * 60_000,
+  jitter: 0.1,
+};
+const DISCORD_API_429_FALLBACK_RETRY_AFTER_SECONDS = 60;
+
+type DiscordApiErrorPayload = {
+  message?: string;
+  retry_after?: number;
+  code?: number;
+  global?: boolean;
+};
+
+function parseDiscordApiErrorPayload(text: string): DiscordApiErrorPayload | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(trimmed);
+    if (payload && typeof payload === "object") {
+      return payload as DiscordApiErrorPayload;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function parseRetryAfterSeconds(text: string, response: Response): number | undefined {
+  const payload = parseDiscordApiErrorPayload(text);
+  const retryAfter =
+    payload && typeof payload.retry_after === "number" && Number.isFinite(payload.retry_after)
+      ? payload.retry_after
+      : undefined;
+  if (retryAfter !== undefined) {
+    return retryAfter;
+  }
+  const header = response.headers.get("Retry-After");
+  if (!header) {
+    return undefined;
+  }
+  const parsed = Number(header);
+  if (Number.isFinite(parsed) && parsed >= 0) {
+    return parsed;
+  }
+  const retryAt = Date.parse(header);
+  if (!Number.isFinite(retryAt)) {
+    return undefined;
+  }
+  return Math.max(0, (retryAt - Date.now()) / 1000);
+}
+
+function formatRetryAfterSeconds(value: number | undefined): string | undefined {
+  if (value === undefined || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  const rounded = value < 10 ? value.toFixed(1) : Math.round(value).toString();
+  return `${rounded}s`;
+}
+
+function formatDiscordApiErrorText(text: string, response: Response): string | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const payload = parseDiscordApiErrorPayload(trimmed);
+  if (!payload) {
+    const looksJson = trimmed.startsWith("{") && trimmed.endsWith("}");
+    if (looksJson) {
+      return "unknown error";
+    }
+    const summary = summarizeDiscordResponseBody(trimmed);
+    if (isDiscordHtmlResponseBody(trimmed, response.headers.get("content-type"))) {
+      if (!summary) {
+        return response.status === 429 ? "rate limited by Discord upstream" : undefined;
+      }
+      return response.status === 429 ? `rate limited by Discord upstream: ${summary}` : summary;
+    }
+    return summary;
+  }
+  const message =
+    typeof payload.message === "string" && payload.message.trim()
+      ? payload.message.trim()
+      : "unknown error";
+  const retryAfter = formatRetryAfterSeconds(
+    typeof payload.retry_after === "number" ? payload.retry_after : undefined,
+  );
+  return retryAfter ? `${message} (retry after ${retryAfter})` : message;
+}
+
+export class DiscordApiError extends Error {
+  status: number;
+  retryAfter?: number;
+
+  constructor(message: string, status: number, retryAfter?: number) {
+    super(message);
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+function getDiscordApiRetryAfterMs(
+  err: unknown,
+  retryConfig: Required<RetryConfig>,
+): number | undefined {
+  if (!(err instanceof DiscordApiError) || typeof err.retryAfter !== "number") {
+    return undefined;
+  }
+  return Math.min(Math.max(0, err.retryAfter * 1000), retryConfig.maxDelayMs);
+}
+
+type DiscordFetchOptions = {
+  retry?: RetryConfig;
+  label?: string;
+};
+
+export async function fetchDiscord<T>(
+  path: string,
+  token: string,
+  fetcher: typeof fetch = fetch,
+  options?: DiscordFetchOptions,
+): Promise<T> {
+  const fetchImpl = resolveFetch(fetcher);
+  if (!fetchImpl) {
+    throw new Error("fetch is not available");
+  }
+
+  const retryConfig = resolveRetryConfig(DISCORD_API_RETRY_DEFAULTS, options?.retry);
+  return retryAsync(
+    async () => {
+      const res = await fetchImpl(`${DISCORD_API_BASE}${path}`, {
+        headers: { Authorization: `Bot ${token}` },
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const detail = formatDiscordApiErrorText(text, res);
+        const suffix = detail ? `: ${detail}` : "";
+        const retryAfter =
+          res.status === 429
+            ? (parseRetryAfterSeconds(text, res) ?? DISCORD_API_429_FALLBACK_RETRY_AFTER_SECONDS)
+            : undefined;
+        throw new DiscordApiError(
+          `Discord API ${path} failed (${res.status})${suffix}`,
+          res.status,
+          retryAfter,
+        );
+      }
+      return (await res.json()) as T;
+    },
+    {
+      ...retryConfig,
+      label: options?.label ?? path,
+      shouldRetry: (err) => err instanceof DiscordApiError && err.status === 429,
+      retryAfterMs: (err) => getDiscordApiRetryAfterMs(err, retryConfig),
+    },
+  );
+}

package/src/approval-handler.runtime.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { discordApprovalNativeRuntime } from "./approval-handler.runtime.js";
+
+describe("discordApprovalNativeRuntime", () => {
+  it("routes origin approval updates to the Discord thread channel when threadId is present", async () => {
+    const prepared = await discordApprovalNativeRuntime.transport.prepareTarget({
+      cfg: {} as never,
+      accountId: "main",
+      context: {
+        token: "discord-token",
+        config: {} as never,
+      },
+      plannedTarget: {
+        surface: "origin",
+        reason: "preferred",
+        target: {
+          to: "123456789",
+          threadId: "777888999",
+        },
+      },
+      request: {
+        id: "req-1",
+        request: {
+          command: "hostname",
+        },
+        createdAtMs: 0,
+        expiresAtMs: 1_000,
+      },
+      approvalKind: "exec",
+      view: {} as never,
+      pendingPayload: {} as never,
+    });
+
+    expect(prepared).toEqual({
+      dedupeKey: "777888999",
+      target: {
+        discordChannelId: "777888999",
+      },
+    });
+  });
+});