@openclaw/discord 2026.5.1-beta.1 → 2026.5.2-beta.2

package/src/internal/client.test.ts

@@ -150,6 +150,117 @@ describe("Client.deployCommands", () => {
     expect(deleteRequest).not.toHaveBeenCalled();
   });
 
+  it("does not patch live-only command metadata or reordered unordered arrays", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({
+        name: "one",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            description: "Value",
+            required: false,
+            autocomplete: false,
+            channel_types: [1, 0],
+          },
+        ],
+      }),
+    ]);
+    const get = vi.fn(async () => [
+      {
+        id: "cmd1",
+        application_id: "app1",
+        type: ApplicationCommandType.ChatInput,
+        name: "one",
+        name_localized: "one",
+        description: "one command",
+        description_localized: "one command",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            description: "Value",
+            description_localized: "Value",
+            channel_types: [0, 1],
+          },
+        ],
+        default_member_permissions: null,
+        dm_permission: true,
+        integration_types: [1, 0],
+        contexts: [2, 1, 0],
+        guild_id: undefined,
+        version: "1",
+      },
+    ]);
+    const patch = vi.fn(async () => undefined);
+    const post = vi.fn(async () => undefined);
+    const deleteRequest = vi.fn(async () => undefined);
+    attachRestMock(client, { get, patch, post, delete: deleteRequest });
+
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(patch).not.toHaveBeenCalled();
+    expect(post).not.toHaveBeenCalled();
+    expect(deleteRequest).not.toHaveBeenCalled();
+  });
+
+  it("patches changed option localization maps", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({
+        name: "one",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            name_localizations: { de: "wert" },
+            description: "Value",
+            description_localizations: { de: "Wert" },
+          },
+        ],
+      }),
+    ]);
+    const get = vi.fn(async () => [
+      {
+        id: "cmd1",
+        application_id: "app1",
+        type: ApplicationCommandType.ChatInput,
+        name: "one",
+        description: "one command",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            name_localizations: { de: "alter-wert" },
+            description: "Value",
+            description_localizations: { de: "Alter Wert" },
+          },
+        ],
+      },
+    ]);
+    const patch = vi.fn(async () => undefined);
+    const post = vi.fn(async () => undefined);
+    const deleteRequest = vi.fn(async () => undefined);
+    attachRestMock(client, { get, patch, post, delete: deleteRequest });
+
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(patch).toHaveBeenCalledWith(
+      Routes.applicationCommand("app1", "cmd1"),
+      expect.objectContaining({
+        body: expect.objectContaining({
+          options: [
+            expect.objectContaining({
+              name_localizations: { de: "wert" },
+              description_localizations: { de: "Wert" },
+            }),
+          ],
+        }),
+      }),
+    );
+    expect(post).not.toHaveBeenCalled();
+    expect(deleteRequest).not.toHaveBeenCalled();
+  });
+
   it("skips command deploy when the serialized command set is unchanged", async () => {
     const client = createInternalTestClient([createTestCommand({ name: "one" })]);
     const get = vi.fn(async () => []);

package/src/internal/client.ts

@@ -6,7 +6,7 @@ import { DiscordEntityCache } from "./entity-cache.js";
 import { DiscordEventQueue, type DiscordEventQueueOptions } from "./event-queue.js";
 import { dispatchInteraction } from "./interaction-dispatch.js";
 import { RequestClient, type RequestClientOptions } from "./rest.js";
-import type { Guild, GuildMember, User } from "./structures.js";
+import type { Guild, GuildMember, Message, User } from "./structures.js";
 
 export interface Route {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -49,10 +49,18 @@ export interface ClientOptions {
   restCacheTtlMs?: number;
 }
 
+type OneOffComponentResult =
+  | { success: true; customId: string; message: Message; values?: string[] }
+  | { success: false; message: Message; reason: "timed out" };
+
 export class ComponentRegistry<
   T extends { customId: string; customIdParser?: typeof parseCustomId; type?: number },
 > {
   private entries = new Map<string, T[]>();
+  private oneOffComponents = new Map<
+    string,
+    { message: Message; resolve(result: OneOffComponentResult): void; timer: NodeJS.Timeout }
+  >();
   private wildcardEntries: T[] = [];
 
   register(entry: T): void {
@@ -90,12 +98,66 @@ export class ComponentRegistry<
       return true;
     });
   }
+
+  waitForMessageComponent(message: Message, timeoutMs: number): Promise<OneOffComponentResult> {
+    const key = createOneOffComponentKey(message.id, message.channelId);
+    return new Promise((resolve) => {
+      const existing = this.oneOffComponents.get(key);
+      if (existing) {
+        clearTimeout(existing.timer);
+        existing.resolve({ success: false, message, reason: "timed out" });
+      }
+      const timer = setTimeout(
+        () => {
+          this.oneOffComponents.delete(key);
+          resolve({ success: false, message, reason: "timed out" });
+        },
+        Math.max(0, timeoutMs),
+      );
+      timer.unref?.();
+      this.oneOffComponents.set(key, {
+        message,
+        timer,
+        resolve,
+      });
+    });
+  }
+
+  resolveOneOffComponent(params: {
+    channelId?: string;
+    customId: string;
+    messageId?: string;
+    values?: string[];
+  }): boolean {
+    if (!params.messageId || !params.channelId) {
+      return false;
+    }
+    const entry = this.oneOffComponents.get(
+      createOneOffComponentKey(params.messageId, params.channelId),
+    );
+    if (!entry) {
+      return false;
+    }
+    clearTimeout(entry.timer);
+    this.oneOffComponents.delete(createOneOffComponentKey(params.messageId, params.channelId));
+    entry.resolve({
+      success: true,
+      customId: params.customId,
+      message: entry.message,
+      values: params.values,
+    });
+    return true;
+  }
 }
 
 function parseRegistryKey(customId: string, parser: typeof parseCustomId = parseCustomId): string {
   return parser(customId).key;
 }
 
+function createOneOffComponentKey(messageId: string, channelId: string): string {
+  return `${messageId}:${channelId}`;
+}
+
 export class Client {
   routes: Route[] = [];
   plugins: Array<{ id: string; plugin: Plugin }> = [];

package/src/internal/command-deploy.ts

@@ -157,12 +157,15 @@ function comparableCommand(value: unknown): unknown {
     return value;
   }
   const omit = new Set([
-    "id",
     "application_id",
+    "description_localized",
+    "dm_permission",
     "guild_id",
+    "id",
+    "name_localized",
+    "nsfw",
     "version",
     "default_permission",
-    "nsfw",
   ]);
   return stableComparableObject(
     Object.fromEntries(
@@ -171,18 +174,50 @@ function comparableCommand(value: unknown): unknown {
   );
 }
 
-function stableComparableObject(value: unknown): unknown {
+const unorderedCommandArrayFields = new Set(["channel_types", "contexts", "integration_types"]);
+const optionComparisonOmittedFields = new Set([
+  "contexts",
+  "default_member_permissions",
+  "description_localized",
+  "integration_types",
+  "name_localized",
+]);
+
+function stableComparableObject(value: unknown, path: string[] = []): unknown {
   if (Array.isArray(value)) {
-    return value.map((entry) => stableComparableObject(entry));
+    const normalized = value.map((entry) => stableComparableObject(entry, path));
+    const key = path.at(-1);
+    if (
+      key &&
+      unorderedCommandArrayFields.has(key) &&
+      normalized.every(
+        (entry) =>
+          typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean",
+      )
+    ) {
+      return normalized.toSorted((left, right) => String(left).localeCompare(String(right)));
+    }
+    return normalized;
   }
   if (!value || typeof value !== "object") {
     return value;
   }
   return Object.fromEntries(
     Object.entries(value as Record<string, unknown>)
-      .filter(([, entry]) => entry !== undefined)
+      .filter(([key, entry]) => {
+        if (entry === undefined) {
+          return false;
+        }
+        if (path.includes("options") && optionComparisonOmittedFields.has(key)) {
+          return false;
+        }
+        if ((key === "required" || key === "autocomplete") && entry === false) {
+          return false;
+        }
+        return true;
+      })
       .toSorted(([a], [b]) => a.localeCompare(b))
-      .map(([key, entry]) => [key, stableComparableObject(entry)]),
+      .map(([key, entry]) => [key, stableComparableObject(entry, [...path, key])]),
   );
 }
 

package/src/internal/gateway.test.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import {
   GatewayCloseCodes,
   GatewayDispatchEvents,
+  GatewayIntentBits,
   GatewayOpcodes,
   InteractionType,
   PresenceUpdateStatus,
@@ -127,6 +128,42 @@ describe("GatewayPlugin", () => {
     await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(error));
   });
 
+  it("reconnects when the socket closes while waiting for identify concurrency", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    await sharedGatewayIdentifyLimiter.wait({ shardId: 0, maxConcurrency: 1 });
+    const gateway = new TestGatewayPlugin({
+      autoInteractions: false,
+      url: "wss://gateway.example.test",
+    });
+    const errorSpy = vi.fn();
+    gateway.emitter.on("error", errorSpy);
+
+    gateway.connect(false);
+    const socket = gateway.sockets[0];
+    socket?.emit("open");
+    socket?.emit(
+      "message",
+      JSON.stringify({
+        op: GatewayOpcodes.Hello,
+        d: { heartbeat_interval: 45_000 },
+        s: null,
+      }),
+    );
+    if (socket) {
+      socket.readyState = 3;
+    }
+
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(errorSpy).toHaveBeenCalledWith(
+      new Error("Discord gateway socket closed before IDENTIFY could be sent"),
+    );
+    await vi.advanceTimersByTimeAsync(2_000);
+
+    expect(gateway.connectCalls).toEqual([false, false]);
+    expect(gateway.sockets).toHaveLength(2);
+  });
+
   it("preserves MESSAGE_CREATE author payloads for inbound dispatch", async () => {
     const gateway = new GatewayPlugin({ autoInteractions: false });
     const dispatchGatewayEvent = vi.fn(async (_event: string, _data: unknown) => {});
@@ -234,6 +271,29 @@ describe("GatewayPlugin", () => {
     );
   });
 
+  it("rejects gateway payloads that exceed Discord's size limit", () => {
+    const gateway = new GatewayPlugin({ autoInteractions: false });
+    const send = attachOpenSocket(gateway);
+
+    expect(() =>
+      gateway.send({
+        op: GatewayOpcodes.PresenceUpdate,
+        d: {
+          since: null,
+          activities: [
+            {
+              name: "x".repeat(4_100),
+              type: 0,
+            },
+          ],
+          status: PresenceUpdateStatus.Online,
+          afk: false,
+        },
+      } as GatewaySendPayload),
+    ).toThrow(/4096-byte limit/);
+    expect(send).not.toHaveBeenCalled();
+  });
+
   it("ignores stale socket close events after reconnecting", () => {
     const gateway = new TestGatewayPlugin({
       autoInteractions: false,
@@ -294,6 +354,7 @@ describe("GatewayPlugin", () => {
 
   it("clears resume state after invalid session false", async () => {
     vi.useFakeTimers();
+    vi.spyOn(Math, "random").mockReturnValue(0);
     const gateway = new TestGatewayPlugin({
       autoInteractions: false,
       url: "wss://gateway.example.test",
@@ -318,6 +379,29 @@ describe("GatewayPlugin", () => {
     expect(sessionState.sequence).toBeNull();
   });
 
+  it("delays invalid-session reconnects by Discord's randomized cooldown floor", async () => {
+    vi.useFakeTimers();
+    vi.spyOn(Math, "random").mockReturnValue(0.75);
+    const gateway = new TestGatewayPlugin({
+      autoInteractions: false,
+      url: "wss://gateway.example.test",
+    });
+
+    gateway.connect(false);
+    gateway.sockets[0]?.emit("open");
+    (
+      gateway as unknown as {
+        handlePayload(payload: { op: number; d: unknown }, resume: boolean): void;
+      }
+    ).handlePayload({ op: GatewayOpcodes.InvalidSession, d: true }, true);
+
+    await vi.advanceTimersByTimeAsync(3_999);
+    expect(gateway.connectCalls).toEqual([false]);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(gateway.connectCalls).toEqual([false, true]);
+  });
+
   it("includes close code details when reconnect attempts are exhausted", async () => {
     vi.useFakeTimers();
     const gateway = new TestGatewayPlugin({
@@ -472,4 +556,48 @@ describe("GatewayPlugin", () => {
       expect.stringContaining(`"op":${GatewayOpcodes.Identify}`),
     );
   });
+
+  it("validates requestGuildMembers before sending", () => {
+    const withoutMembersIntent = new GatewayPlugin({ autoInteractions: false });
+    attachOpenSocket(withoutMembersIntent);
+
+    expect(() =>
+      withoutMembersIntent.requestGuildMembers({ guild_id: "guild1", query: "", limit: 0 }),
+    ).toThrow(/GUILD_MEMBERS intent/);
+
+    const withoutPresenceIntent = new GatewayPlugin({
+      autoInteractions: false,
+      intents: GatewayIntentBits.GuildMembers,
+    });
+    attachOpenSocket(withoutPresenceIntent);
+
+    expect(() =>
+      withoutPresenceIntent.requestGuildMembers({
+        guild_id: "guild1",
+        query: "",
+        limit: 0,
+        presences: true,
+      }),
+    ).toThrow(/GUILD_PRESENCES intent/);
+
+    const valid = new GatewayPlugin({
+      autoInteractions: false,
+      intents: GatewayIntentBits.GuildMembers | GatewayIntentBits.GuildPresences,
+    });
+    const send = attachOpenSocket(valid);
+
+    expect(() =>
+      valid.requestGuildMembers({
+        guild_id: "guild1",
+        limit: 1,
+      }),
+    ).toThrow(/query or user_ids/);
+
+    valid.requestGuildMembers({ guild_id: "guild1", query: "", limit: 0, presences: true });
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(send.mock.calls[0]?.[0] as string)).toEqual({
+      op: GatewayOpcodes.RequestGuildMembers,
+      d: { guild_id: "guild1", query: "", limit: 0, presences: true },
+    });
+  });
 });

package/src/internal/gateway.ts

@@ -46,6 +46,9 @@ type GatewayPluginOptions = {
 
 const READY_STATE_OPEN = 1;
 const DEFAULT_GATEWAY_URL = "wss://gateway.discord.gg/";
+const DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES = 4096;
+const INVALID_SESSION_MIN_DELAY_MS = 1_000;
+const INVALID_SESSION_JITTER_MS = 4_000;
 
 function ensureGatewayParams(url: string): string {
   const parsed = new URL(url);
@@ -248,7 +251,12 @@ export class GatewayPlugin extends Plugin {
             true,
           );
         } else {
-          void this.identifyWithConcurrency();
+          void this.identifyWithConcurrency().catch((error: unknown) => {
+            this.emitter.emit(
+              "error",
+              error instanceof Error ? error : new Error(String(error), { cause: error }),
+            );
+          });
         }
         break;
       case GatewayOpcodes.HeartbeatAck:
@@ -269,7 +277,11 @@ export class GatewayPlugin extends Plugin {
         if (!payload.d) {
           this.resetSessionState();
         }
-        this.scheduleReconnect(payload.d);
+        this.scheduleReconnect(
+          payload.d,
+          undefined,
+          INVALID_SESSION_MIN_DELAY_MS + Math.floor(Math.random() * INVALID_SESSION_JITTER_MS),
+        );
         break;
       case GatewayOpcodes.Reconnect:
         this.scheduleReconnect(true);
@@ -325,7 +337,13 @@ export class GatewayPlugin extends Plugin {
       shardId: this.shardId,
       maxConcurrency: this.gatewayInfo?.session_start_limit.max_concurrency,
     });
-    if (!this.ws || this.ws.readyState !== READY_STATE_OPEN) {
+    const socket = this.ws;
+    if (!socket || socket.readyState !== READY_STATE_OPEN) {
+      const error = new Error("Discord gateway socket closed before IDENTIFY could be sent");
+      this.emitter.emit("error", error);
+      if (socket) {
+        this.scheduleReconnect(false);
+      }
       return;
     }
     this.identify();
@@ -336,6 +354,15 @@ export class GatewayPlugin extends Plugin {
       throw new Error("Discord gateway socket is not open");
     }
     const serialized = JSON.stringify(payload);
+    const payloadSize =
+      typeof Buffer !== "undefined"
+        ? Buffer.byteLength(serialized, "utf8")
+        : new TextEncoder().encode(serialized).byteLength;
+    if (payloadSize > DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES) {
+      throw new Error(
+        `Discord gateway payload exceeds ${DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES}-byte limit`,
+      );
+    }
     this.outboundLimiter.send(serialized, { critical: skipRateLimit });
   }
 
@@ -375,7 +402,7 @@ export class GatewayPlugin extends Plugin {
     this.sequence = null;
   }
 
-  private scheduleReconnect(resume: boolean, closeCode?: number): void {
+  private scheduleReconnect(resume: boolean, closeCode?: number, minDelayMs = 0): void {
     if (!this.shouldReconnect) {
       return;
     }
@@ -397,7 +424,10 @@ export class GatewayPlugin extends Plugin {
       );
       return;
     }
-    const delay = Math.min(30_000, 1_000 * 2 ** Math.min(this.reconnectAttempts, 5));
+    const delay = Math.max(
+      minDelayMs,
+      Math.min(30_000, 1_000 * 2 ** Math.min(this.reconnectAttempts, 5)),
+    );
     this.reconnectTimer.schedule(delay, () => {
       this.connect(resume);
     });
@@ -412,6 +442,15 @@ export class GatewayPlugin extends Plugin {
   }
 
   requestGuildMembers(data: RequestGuildMembersData): void {
+    if (!this.hasIntent(GatewayIntentBits.GuildMembers)) {
+      throw new Error("GUILD_MEMBERS intent is required for requestGuildMembers");
+    }
+    if (data.presences && !this.hasIntent(GatewayIntentBits.GuildPresences)) {
+      throw new Error("GUILD_PRESENCES intent is required when requesting presences");
+    }
+    if (!data.query && data.query !== "" && !data.user_ids) {
+      throw new Error("Either query or user_ids is required for requestGuildMembers");
+    }
     this.send({ op: GatewayOpcodes.RequestGuildMembers, d: data } as GatewaySendPayload);
   }
 

package/src/internal/interaction-dispatch.ts

@@ -30,6 +30,12 @@ type DispatchClient = Parameters<typeof createInteraction>[0] & {
   commands: BaseCommand[];
   componentHandler: {
     resolve(customId: string, options?: { componentType?: number }): DispatchComponent | undefined;
+    resolveOneOffComponent(params: {
+      channelId?: string;
+      customId: string;
+      messageId?: string;
+      values?: string[];
+    }): boolean;
   };
   modalHandler: { resolve(customId: string): DispatchModal | undefined };
 };
@@ -75,11 +81,22 @@ export async function dispatchInteraction(
     if (!customId) {
       return;
     }
+    const componentInteraction = interaction as BaseComponentInteraction;
+    if (
+      client.componentHandler.resolveOneOffComponent({
+        channelId: readMessageChannelId(rawData),
+        customId,
+        messageId: readMessageId(rawData),
+        values: readComponentValues(rawData),
+      })
+    ) {
+      await componentInteraction.acknowledge();
+      return;
+    }
     const component = client.componentHandler.resolve(customId, {
       componentType: (rawData as { data?: { component_type?: number } }).data?.component_type,
     });
     if (component) {
-      const componentInteraction = interaction as BaseComponentInteraction;
       await deferComponentInteractionIfNeeded(component, componentInteraction);
       await component.run(componentInteraction, parseComponentInteractionData(component, customId));
     }
@@ -128,3 +145,18 @@ function readInteractionName(rawData: APIInteraction): string | undefined {
 function readCustomId(rawData: APIInteraction): string | undefined {
   return (rawData as { data?: { custom_id?: string } }).data?.custom_id;
 }
+
+function readComponentValues(rawData: APIInteraction): string[] | undefined {
+  const values = (rawData as { data?: { values?: unknown } }).data?.values;
+  return Array.isArray(values) ? values.map(String) : undefined;
+}
+
+function readMessageId(rawData: APIInteraction): string | undefined {
+  const messageId = (rawData as { message?: { id?: unknown } }).message?.id;
+  return typeof messageId === "string" ? messageId : undefined;
+}
+
+function readMessageChannelId(rawData: APIInteraction): string | undefined {
+  const channelId = (rawData as { message?: { channel_id?: unknown } }).message?.channel_id;
+  return typeof channelId === "string" ? channelId : undefined;
+}

package/src/internal/interactions.test.ts

@@ -179,6 +179,78 @@ describe("BaseInteraction", () => {
     expect(interaction.user?.globalName).toBe("Alice Cooper");
     expect(interaction.user?.discriminator).toBe("1234");
   });
+
+  it("waits for a one-off component reply without invoking registered handlers", async () => {
+    const get = vi.fn(async () => ({
+      id: "message1",
+      channel_id: "channel1",
+      author: {
+        id: "bot1",
+        username: "bot",
+        discriminator: "0000",
+        global_name: null,
+        avatar: null,
+      },
+      content: "pick",
+      timestamp: "2026-05-01T00:00:00.000Z",
+    }));
+    const post = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { get, post });
+    const interaction = new BaseInteraction(
+      client,
+      createInternalInteractionPayload({ id: "interaction1", token: "token1" }),
+    );
+
+    const wait = interaction.replyAndWaitForComponent({ content: "pick" }, 1_000);
+    await vi.waitFor(() =>
+      expect(get).toHaveBeenCalledWith("/webhooks/app1/token1/messages/%40original"),
+    );
+
+    await client.handleInteraction(
+      createInternalComponentInteractionPayload({
+        id: "component-interaction1",
+        token: "component-token1",
+        data: { custom_id: "button1" },
+        message: {
+          id: "message1",
+          channel_id: "channel1",
+          author: {
+            id: "bot1",
+            username: "bot",
+            discriminator: "0000",
+            global_name: null,
+            avatar: null,
+          },
+          content: "pick",
+          timestamp: "2026-05-01T00:00:00.000Z",
+          edited_timestamp: null,
+          tts: false,
+          mention_everyone: false,
+          mentions: [],
+          mention_roles: [],
+          attachments: [],
+          embeds: [],
+          pinned: false,
+          type: 0,
+        },
+      }),
+    );
+
+    await expect(wait).resolves.toEqual({
+      success: true,
+      customId: "button1",
+      message: expect.objectContaining({ id: "message1", channelId: "channel1" }),
+      values: undefined,
+    });
+    expect(post).toHaveBeenNthCalledWith(
+      2,
+      "/interactions/component-interaction1/component-token1/callback",
+      {
+        body: { type: InteractionResponseType.DeferredMessageUpdate },
+      },
+    );
+  });
 });
 
 describe("ModalInteraction", () => {