@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/monitor/gateway-plugin.ts

@@ -0,0 +1,294 @@
+import { randomUUID } from "node:crypto";
+import * as httpsProxyAgent from "https-proxy-agent";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  captureWsEvent,
+  resolveEffectiveDebugProxyUrl,
+  resolveDebugProxySettings,
+} from "openclaw/plugin-sdk/proxy-capture";
+import { danger } from "openclaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import * as ws from "ws";
+import * as discordGateway from "../internal/gateway.js";
+import { validateDiscordProxyUrl } from "../proxy-fetch.js";
+import { resolveDiscordVoiceEnabled } from "../voice/config.js";
+import { DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT } from "./gateway-handle.js";
+import {
+  fetchDiscordGatewayInfoWithTimeout,
+  fetchDiscordGatewayMetadataDirect,
+  resolveDiscordGatewayInfoTimeoutMs,
+  resolveGatewayInfoWithFallback,
+  type DiscordGatewayFetch,
+  type DiscordGatewayFetchInit,
+} from "./gateway-metadata.js";
+
+export {
+  parseDiscordGatewayInfoBody,
+  resolveDiscordGatewayInfoTimeoutMs,
+} from "./gateway-metadata.js";
+
+const DISCORD_GATEWAY_HANDSHAKE_TIMEOUT_MS = 30_000;
+
+type DiscordGatewayWebSocketCtor = new (
+  url: string,
+  options?: { agent?: unknown; handshakeTimeout?: number },
+) => ws.WebSocket;
+const registrationPromises = new WeakMap<discordGateway.GatewayPlugin, Promise<void>>();
+type DiscordGatewayClient = Parameters<discordGateway.GatewayPlugin["registerClient"]>[0];
+type GatewayPluginTestingOptions = {
+  registerClient?: (
+    plugin: discordGateway.GatewayPlugin,
+    client: DiscordGatewayClient,
+  ) => Promise<void>;
+  webSocketCtor?: DiscordGatewayWebSocketCtor;
+};
+type CreateDiscordGatewayPluginTestingOptions = GatewayPluginTestingOptions & {
+  HttpsProxyAgentCtor?: typeof httpsProxyAgent.HttpsProxyAgent;
+};
+type DiscordGatewayRegistrationState = {
+  client?: DiscordGatewayClient;
+  ws?: unknown;
+  isConnecting?: boolean;
+};
+
+function assignGatewayClient(
+  plugin: discordGateway.GatewayPlugin,
+  client: DiscordGatewayClient,
+): void {
+  (plugin as unknown as DiscordGatewayRegistrationState).client = client;
+}
+
+function hasGatewaySocketStarted(plugin: discordGateway.GatewayPlugin): boolean {
+  const state = plugin as unknown as DiscordGatewayRegistrationState;
+  return state.ws != null || state.isConnecting === true;
+}
+
+type ResolveDiscordGatewayIntentsParams = {
+  intentsConfig?: import("openclaw/plugin-sdk/config-types").DiscordIntentsConfig;
+  voiceEnabled?: boolean;
+};
+
+export function resolveDiscordGatewayIntents(params?: ResolveDiscordGatewayIntentsParams): number {
+  const intentsConfig = params?.intentsConfig;
+  const voiceEnabled = params?.voiceEnabled;
+  const voiceStatesEnabled = intentsConfig?.voiceStates ?? voiceEnabled ?? false;
+  let intents =
+    discordGateway.GatewayIntents.Guilds |
+    discordGateway.GatewayIntents.GuildMessages |
+    discordGateway.GatewayIntents.MessageContent |
+    discordGateway.GatewayIntents.DirectMessages |
+    discordGateway.GatewayIntents.GuildMessageReactions |
+    discordGateway.GatewayIntents.DirectMessageReactions;
+  if (voiceStatesEnabled) {
+    intents |= discordGateway.GatewayIntents.GuildVoiceStates;
+  }
+  if (intentsConfig?.presence) {
+    intents |= discordGateway.GatewayIntents.GuildPresences;
+  }
+  if (intentsConfig?.guildMembers) {
+    intents |= discordGateway.GatewayIntents.GuildMembers;
+  }
+  return intents;
+}
+
+function createGatewayPlugin(params: {
+  options: {
+    reconnect: { maxAttempts: number };
+    intents: number;
+    autoInteractions: boolean;
+  };
+  gatewayInfoTimeoutMs: number;
+  fetchImpl: DiscordGatewayFetch;
+  fetchInit?: DiscordGatewayFetchInit;
+  wsAgent?: InstanceType<typeof httpsProxyAgent.HttpsProxyAgent<string>>;
+  runtime?: RuntimeEnv;
+  testing?: GatewayPluginTestingOptions;
+}): discordGateway.GatewayPlugin {
+  class OpenClawGatewayPlugin extends discordGateway.GatewayPlugin {
+    private gatewayInfoUsedFallback = false;
+
+    constructor() {
+      super(params.options);
+    }
+
+    override registerClient(client: DiscordGatewayClient) {
+      const registration = this.registerClientInternal(client);
+      // Client construction starts plugin hooks without awaiting them. Mark the
+      // promise handled immediately, then let startup await the original promise.
+      registration.catch(() => {});
+      registrationPromises.set(this, registration);
+      return registration;
+    }
+
+    private async registerClientInternal(client: DiscordGatewayClient) {
+      // Publish the client reference before the metadata fetch can yield, so an external
+      // connect()->identify() cannot silently drop IDENTIFY (#52372).
+      assignGatewayClient(this, client);
+
+      if (!this.gatewayInfo || this.gatewayInfoUsedFallback) {
+        const resolved = await fetchDiscordGatewayInfoWithTimeout({
+          token: client.options.token,
+          fetchImpl: params.fetchImpl,
+          fetchInit: params.fetchInit,
+          timeoutMs: params.gatewayInfoTimeoutMs,
+        })
+          .then((info) => ({
+            info,
+            usedFallback: false,
+          }))
+          .catch((error) => resolveGatewayInfoWithFallback({ runtime: params.runtime, error }));
+        this.gatewayInfo = resolved.info;
+        this.gatewayInfoUsedFallback = resolved.usedFallback;
+      }
+      if (params.testing?.registerClient) {
+        await params.testing.registerClient(this, client);
+        return;
+      }
+      // If the lifecycle timeout already started a socket while metadata was
+      // loading, do not register again; it would close that socket and open another one.
+      if (hasGatewaySocketStarted(this)) {
+        return;
+      }
+      return super.registerClient(client);
+    }
+
+    override createWebSocket(url: string) {
+      if (!url) {
+        throw new Error("Gateway URL is required");
+      }
+      const wsFlowId = randomUUID();
+      // Avoid Node's undici-backed global WebSocket here. We have seen late
+      // close-path crashes during Discord gateway teardown; the ws transport is
+      // already our proxy path and behaves predictably for lifecycle cleanup.
+      const WebSocketCtor = params.testing?.webSocketCtor ?? ws.default;
+      const socket = new WebSocketCtor(url, {
+        handshakeTimeout: DISCORD_GATEWAY_HANDSHAKE_TIMEOUT_MS,
+        ...(params.wsAgent ? { agent: params.wsAgent } : {}),
+      });
+      const emitTransportActivity = () => {
+        if ((this as unknown as { ws?: unknown }).ws !== socket) {
+          return;
+        }
+        this.emitter.emit(DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT, { at: Date.now() });
+      };
+      captureWsEvent({
+        url,
+        direction: "local",
+        kind: "ws-open",
+        flowId: wsFlowId,
+        meta: { subsystem: "discord-gateway" },
+      });
+      socket.on?.("message", (data: unknown) => {
+        emitTransportActivity();
+        captureWsEvent({
+          url,
+          direction: "inbound",
+          kind: "ws-frame",
+          flowId: wsFlowId,
+          payload: Buffer.isBuffer(data) ? data : Buffer.from(String(data)),
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      socket.on?.("close", (code: number, reason: Buffer) => {
+        captureWsEvent({
+          url,
+          direction: "local",
+          kind: "ws-close",
+          flowId: wsFlowId,
+          closeCode: code,
+          payload: reason,
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      socket.on?.("error", (error: Error) => {
+        captureWsEvent({
+          url,
+          direction: "local",
+          kind: "error",
+          flowId: wsFlowId,
+          errorText: error.message,
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      if ("binaryType" in socket) {
+        try {
+          socket.binaryType = "arraybuffer";
+        } catch {
+          // Ignore runtimes that expose a readonly binaryType.
+        }
+      }
+      return socket;
+    }
+  }
+
+  return new OpenClawGatewayPlugin();
+}
+
+function createDiscordGatewayMetadataFetch(debugCaptureEnabled: boolean): DiscordGatewayFetch {
+  return (input, init) =>
+    fetchDiscordGatewayMetadataDirect(
+      input,
+      init,
+      debugCaptureEnabled
+        ? false
+        : {
+            flowId: randomUUID(),
+            meta: { subsystem: "discord-gateway-metadata" },
+          },
+    );
+}
+
+export function waitForDiscordGatewayPluginRegistration(
+  plugin: unknown,
+): Promise<void> | undefined {
+  if (typeof plugin !== "object" || plugin === null) {
+    return undefined;
+  }
+  return registrationPromises.get(plugin as discordGateway.GatewayPlugin);
+}
+
+export function createDiscordGatewayPlugin(params: {
+  discordConfig: DiscordAccountConfig;
+  runtime: RuntimeEnv;
+  __testing?: CreateDiscordGatewayPluginTestingOptions;
+}): discordGateway.GatewayPlugin {
+  const intents = resolveDiscordGatewayIntents({
+    intentsConfig: params.discordConfig?.intents,
+    voiceEnabled: resolveDiscordVoiceEnabled(params.discordConfig?.voice),
+  });
+  const proxy = resolveEffectiveDebugProxyUrl(params.discordConfig?.proxy);
+  const debugProxySettings = resolveDebugProxySettings();
+  const gatewayInfoTimeoutMs = resolveDiscordGatewayInfoTimeoutMs({
+    configuredTimeoutMs: params.discordConfig?.gatewayInfoTimeoutMs,
+    env: process.env,
+  });
+  let fetchImpl = createDiscordGatewayMetadataFetch(debugProxySettings.enabled);
+  let wsAgent: InstanceType<typeof httpsProxyAgent.HttpsProxyAgent<string>> | undefined;
+
+  if (proxy) {
+    try {
+      validateDiscordProxyUrl(proxy);
+      const HttpsProxyAgentCtor =
+        params.__testing?.HttpsProxyAgentCtor ?? httpsProxyAgent.HttpsProxyAgent;
+      wsAgent = new HttpsProxyAgentCtor<string>(proxy);
+      params.runtime.log?.("discord: gateway proxy enabled");
+    } catch (err) {
+      params.runtime.error?.(danger(`discord: invalid gateway proxy: ${String(err)}`));
+      fetchImpl = (input, init) => fetchDiscordGatewayMetadataDirect(input, init, false);
+    }
+  }
+
+  return createGatewayPlugin({
+    options: {
+      reconnect: { maxAttempts: 50 },
+      intents,
+      // OpenClaw registers its own async interaction listener.
+      autoInteractions: false,
+    },
+    gatewayInfoTimeoutMs,
+    fetchImpl,
+    runtime: params.runtime,
+    testing: params.__testing,
+    ...(wsAgent ? { wsAgent } : {}),
+  });
+}

package/src/monitor/gateway-registry.ts

@@ -0,0 +1,37 @@
+import type { GatewayPlugin } from "../internal/gateway.js";
+
+/**
+ * Module-level registry of active Discord GatewayPlugin instances.
+ * Bridges the gap between agent tool handlers (which only have REST access)
+ * and the gateway WebSocket (needed for operations like updatePresence).
+ * Follows the same pattern as presence-cache.ts.
+ */
+const gatewayRegistry = new Map<string, GatewayPlugin>();
+
+// Sentinel key for the default (unnamed) account. Uses a prefix that cannot
+// collide with user-configured account IDs.
+const DEFAULT_ACCOUNT_KEY = "\0__default__";
+
+function resolveAccountKey(accountId?: string): string {
+  return accountId ?? DEFAULT_ACCOUNT_KEY;
+}
+
+/** Register a GatewayPlugin instance for an account. */
+export function registerGateway(accountId: string | undefined, gateway: GatewayPlugin): void {
+  gatewayRegistry.set(resolveAccountKey(accountId), gateway);
+}
+
+/** Unregister a GatewayPlugin instance for an account. */
+export function unregisterGateway(accountId?: string): void {
+  gatewayRegistry.delete(resolveAccountKey(accountId));
+}
+
+/** Get the GatewayPlugin for an account. Returns undefined if not registered. */
+export function getGateway(accountId?: string): GatewayPlugin | undefined {
+  return gatewayRegistry.get(resolveAccountKey(accountId));
+}
+
+/** Clear all registered gateways (for testing). */
+export function clearGateways(): void {
+  gatewayRegistry.clear();
+}

package/src/monitor/gateway-supervisor.test.ts

@@ -0,0 +1,150 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+import {
+  classifyDiscordGatewayEvent,
+  DiscordGatewayLifecycleError,
+  createDiscordGatewaySupervisor,
+} from "./gateway-supervisor.js";
+
+describe("classifyDiscordGatewayEvent", () => {
+  it("maps current gateway errors onto domain events", () => {
+    const transientTypeError = new TypeError();
+    transientTypeError.stack = "TypeError\n    at gatewayCrash (discord-gateway.js:12:34)";
+    const reconnectEvent = classifyDiscordGatewayEvent({
+      err: new Error("Max reconnect attempts (0) reached after close code 1006"),
+      isDisallowedIntentsError: () => false,
+    });
+    const fatalEvent = classifyDiscordGatewayEvent({
+      err: new Error("Fatal gateway close code: 4000"),
+      isDisallowedIntentsError: () => false,
+    });
+    const disallowedEvent = classifyDiscordGatewayEvent({
+      err: new Error("Fatal gateway close code: 4014"),
+      isDisallowedIntentsError: (err) => String(err).includes("4014"),
+    });
+    const transientEvent = classifyDiscordGatewayEvent({
+      err: transientTypeError,
+      isDisallowedIntentsError: () => false,
+    });
+
+    expect(reconnectEvent.type).toBe("reconnect-exhausted");
+    expect(reconnectEvent.shouldStopLifecycle).toBe(true);
+    expect(fatalEvent.type).toBe("fatal");
+    expect(disallowedEvent.type).toBe("disallowed-intents");
+    expect(transientEvent.type).toBe("fatal");
+    expect(transientEvent.message).toBe("TypeError @ gatewayCrash (discord-gateway.js:12:34)");
+    expect(transientEvent.shouldStopLifecycle).toBe(true);
+  });
+
+  it("wraps fatal lifecycle stops with discord-specific context", () => {
+    const transientTypeError = new TypeError();
+    transientTypeError.stack = "TypeError\n    at gatewayCrash (discord-gateway.js:12:34)";
+    const event = classifyDiscordGatewayEvent({
+      err: transientTypeError,
+      isDisallowedIntentsError: () => false,
+    });
+
+    const wrapped = new DiscordGatewayLifecycleError(event);
+
+    expect(wrapped.name).toBe("DiscordGatewayLifecycleError");
+    expect(wrapped.message).toBe(
+      "discord gateway fatal: TypeError @ gatewayCrash (discord-gateway.js:12:34)",
+    );
+    expect(wrapped.eventType).toBe("fatal");
+    expect(wrapped.cause).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("createDiscordGatewaySupervisor", () => {
+  it("buffers early errors, routes active ones, and logs late teardown errors", () => {
+    const emitter = new EventEmitter();
+    const runtime = {
+      error: vi.fn(),
+    };
+    const supervisor = createDiscordGatewaySupervisor({
+      gateway: { emitter },
+      isDisallowedIntentsError: (err) => String(err).includes("4014"),
+      runtime: runtime as never,
+    });
+    const seen: string[] = [];
+
+    emitter.emit("error", new Error("Fatal gateway close code: 4014"));
+    expect(
+      supervisor.drainPending((event) => {
+        seen.push(event.type);
+        return "continue";
+      }),
+    ).toBe("continue");
+
+    supervisor.attachLifecycle((event) => {
+      seen.push(event.type);
+    });
+    emitter.emit("error", new Error("Fatal gateway close code: 4000"));
+
+    supervisor.detachLifecycle();
+    emitter.emit("error", new Error("Max reconnect attempts (0) reached after close code 1006"));
+
+    expect(seen).toEqual(["disallowed-intents", "fatal"]);
+    expect(runtime.error).toHaveBeenCalledWith(
+      expect.stringContaining("suppressed late gateway reconnect-exhausted error during teardown"),
+    );
+  });
+
+  it("is idempotent on dispose and noops without an emitter", () => {
+    const supervisor = createDiscordGatewaySupervisor({
+      gateway: undefined,
+      isDisallowedIntentsError: () => false,
+      runtime: { error: vi.fn() } as never,
+    });
+
+    expect(supervisor.drainPending(() => "continue")).toBe("continue");
+    expect(() => supervisor.attachLifecycle(() => {})).not.toThrow();
+    expect(() => supervisor.detachLifecycle()).not.toThrow();
+    expect(() => supervisor.dispose()).not.toThrow();
+    expect(() => supervisor.dispose()).not.toThrow();
+  });
+
+  it("keeps suppressing late gateway errors after dispose", () => {
+    const emitter = new EventEmitter();
+    const runtime = { error: vi.fn() };
+    const supervisor = createDiscordGatewaySupervisor({
+      gateway: { emitter },
+      isDisallowedIntentsError: () => false,
+      runtime: runtime as never,
+    });
+
+    supervisor.dispose();
+
+    expect(() =>
+      emitter.emit("error", new Error("Max reconnect attempts (0) reached after close code 1005")),
+    ).not.toThrow();
+    expect(runtime.error).toHaveBeenCalledWith(
+      expect.stringContaining("suppressed late gateway reconnect-exhausted error after dispose"),
+    );
+  });
+
+  it("dedupes identical late gateway errors after dispose", () => {
+    const emitter = new EventEmitter();
+    const runtime = { error: vi.fn() };
+    const supervisor = createDiscordGatewaySupervisor({
+      gateway: { emitter },
+      isDisallowedIntentsError: () => false,
+      runtime: runtime as never,
+    });
+
+    supervisor.dispose();
+    const first = new TypeError();
+    first.stack = "TypeError\n    at gatewayCrash (discord-gateway.js:12:34)";
+    const second = new TypeError();
+    second.stack = "TypeError\n    at gatewayCrash (discord-gateway.js:12:34)";
+    emitter.emit("error", first);
+    emitter.emit("error", second);
+
+    expect(runtime.error).toHaveBeenCalledTimes(1);
+    expect(runtime.error).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "suppressed late gateway fatal error after dispose: TypeError @ gatewayCrash (discord-gateway.js:12:34)",
+      ),
+    );
+  });
+});

package/src/monitor/gateway-supervisor.ts

@@ -0,0 +1,206 @@
+import type { EventEmitter } from "node:events";
+import { danger } from "openclaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "openclaw/plugin-sdk/ssrf-runtime";
+
+type DiscordGatewayEventType = "disallowed-intents" | "fatal" | "other" | "reconnect-exhausted";
+
+export type DiscordGatewayEvent = {
+  type: DiscordGatewayEventType;
+  err: unknown;
+  message: string;
+  shouldStopLifecycle: boolean;
+};
+
+export class DiscordGatewayLifecycleError extends Error {
+  readonly eventType: DiscordGatewayEventType;
+
+  constructor(event: Pick<DiscordGatewayEvent, "type" | "message" | "err">) {
+    super(`discord gateway ${event.type}: ${event.message}`, {
+      cause: event.err instanceof Error ? event.err : undefined,
+    });
+    this.name = "DiscordGatewayLifecycleError";
+    this.eventType = event.type;
+  }
+}
+
+export function getDiscordGatewayEmitter(gateway?: unknown): EventEmitter | undefined {
+  return (gateway as { emitter?: EventEmitter } | undefined)?.emitter;
+}
+
+export type DiscordGatewaySupervisor = {
+  emitter?: EventEmitter;
+  attachLifecycle: (handler: (event: DiscordGatewayEvent) => void) => void;
+  detachLifecycle: () => void;
+  drainPending: (
+    handler: (event: DiscordGatewayEvent) => "continue" | "stop",
+  ) => "continue" | "stop";
+  dispose: () => void;
+};
+
+type GatewaySupervisorPhase = "active" | "buffering" | "disposed" | "teardown";
+
+function readFirstStackFrame(err: Error): string | undefined {
+  const stack = err.stack;
+  if (!stack) {
+    return undefined;
+  }
+  const frame = stack
+    .split("\n")
+    .slice(1)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return frame ? frame.replace(/^at\s+/, "") : undefined;
+}
+
+function formatDiscordGatewayErrorMessage(err: unknown): string {
+  if (!(err instanceof Error)) {
+    return formatErrorMessage(err);
+  }
+  if (err.message) {
+    const detail = formatErrorMessage(err);
+    return err.name ? `${err.name}: ${detail}` : detail;
+  }
+  const detail = formatErrorMessage(err);
+  const firstFrame = readFirstStackFrame(err);
+  if (firstFrame && detail === (err.name || "Error")) {
+    return `${detail} @ ${firstFrame}`;
+  }
+  return detail;
+}
+
+export function classifyDiscordGatewayEvent(params: {
+  err: unknown;
+  isDisallowedIntentsError: (err: unknown) => boolean;
+}): DiscordGatewayEvent {
+  const message = formatDiscordGatewayErrorMessage(params.err);
+  if (params.isDisallowedIntentsError(params.err)) {
+    return {
+      type: "disallowed-intents",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  if (message.includes("Max reconnect attempts")) {
+    return {
+      type: "reconnect-exhausted",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  if (
+    params.err instanceof TypeError ||
+    message.includes("Fatal Gateway error") ||
+    message.includes("Fatal gateway close code") ||
+    message.includes("Gateway HELLO missing heartbeat") ||
+    message.includes("Invalid gateway payload") ||
+    message.includes("Gateway socket emitted an unknown error")
+  ) {
+    return {
+      type: "fatal",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  return {
+    type: "other",
+    err: params.err,
+    message,
+    shouldStopLifecycle: false,
+  };
+}
+
+export function createDiscordGatewaySupervisor(params: {
+  gateway?: unknown;
+  isDisallowedIntentsError: (err: unknown) => boolean;
+  runtime: RuntimeEnv;
+}): DiscordGatewaySupervisor {
+  const emitter = getDiscordGatewayEmitter(params.gateway);
+  const pending: DiscordGatewayEvent[] = [];
+  if (!emitter) {
+    return {
+      attachLifecycle: () => {},
+      detachLifecycle: () => {},
+      drainPending: () => "continue",
+      dispose: () => {},
+      emitter,
+    };
+  }
+
+  let lifecycleHandler: ((event: DiscordGatewayEvent) => void) | undefined;
+  let phase: GatewaySupervisorPhase = "buffering";
+  const seenLateEventKeys = new Set<string>();
+  const logLateEvent =
+    (state: Extract<GatewaySupervisorPhase, "disposed" | "teardown">) =>
+    (event: DiscordGatewayEvent) => {
+      const key = `${state}:${event.type}:${event.message}`;
+      if (seenLateEventKeys.has(key)) {
+        return;
+      }
+      seenLateEventKeys.add(key);
+      params.runtime.error?.(
+        danger(
+          `discord: suppressed late gateway ${event.type} error ${
+            state === "disposed" ? "after dispose" : "during teardown"
+          }: ${event.message}`,
+        ),
+      );
+    };
+  const onGatewayError = (err: unknown) => {
+    const event = classifyDiscordGatewayEvent({
+      err,
+      isDisallowedIntentsError: params.isDisallowedIntentsError,
+    });
+    switch (phase) {
+      case "disposed":
+        logLateEvent("disposed")(event);
+        return;
+      case "active":
+        lifecycleHandler?.(event);
+        return;
+      case "teardown":
+        logLateEvent("teardown")(event);
+        return;
+      case "buffering":
+        pending.push(event);
+        return;
+    }
+  };
+  emitter.on("error", onGatewayError);
+
+  return {
+    emitter,
+    attachLifecycle: (handler) => {
+      lifecycleHandler = handler;
+      phase = "active";
+    },
+    detachLifecycle: () => {
+      lifecycleHandler = undefined;
+      phase = "teardown";
+    },
+    drainPending: (handler) => {
+      if (pending.length === 0) {
+        return "continue";
+      }
+      const queued = [...pending];
+      pending.length = 0;
+      for (const event of queued) {
+        if (handler(event) === "stop") {
+          return "stop";
+        }
+      }
+      return "continue";
+    },
+    dispose: () => {
+      if (phase === "disposed") {
+        return;
+      }
+      lifecycleHandler = undefined;
+      phase = "disposed";
+      pending.length = 0;
+    },
+  };
+}