@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/monitor/timeouts.ts

@@ -0,0 +1,84 @@
+// Compatibility constants for existing imports. Discord no longer enforces
+// channel-owned listener or inbound run timeouts.
+export const DISCORD_DEFAULT_LISTENER_TIMEOUT_MS = 120_000;
+export const DISCORD_DEFAULT_INBOUND_WORKER_TIMEOUT_MS = 30 * 60_000;
+
+export const DISCORD_ATTACHMENT_IDLE_TIMEOUT_MS = 60_000;
+export const DISCORD_ATTACHMENT_TOTAL_TIMEOUT_MS = 120_000;
+
+export function mergeAbortSignals(
+  signals: Array<AbortSignal | undefined>,
+): AbortSignal | undefined {
+  const activeSignals = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+  if (activeSignals.length === 0) {
+    return undefined;
+  }
+  if (activeSignals.length === 1) {
+    return activeSignals[0];
+  }
+  if (typeof AbortSignal.any === "function") {
+    return AbortSignal.any(activeSignals);
+  }
+  const fallbackController = new AbortController();
+  for (const signal of activeSignals) {
+    if (signal.aborted) {
+      fallbackController.abort();
+      return fallbackController.signal;
+    }
+  }
+  const abortFallback = () => {
+    fallbackController.abort();
+    for (const signal of activeSignals) {
+      signal.removeEventListener("abort", abortFallback);
+    }
+  };
+  for (const signal of activeSignals) {
+    signal.addEventListener("abort", abortFallback, { once: true });
+  }
+  return fallbackController.signal;
+}
+
+export async function raceWithTimeout<T, U>(params: {
+  promise: Promise<T>;
+  timeoutMs: number;
+  onTimeout: () => U;
+}): Promise<T | U> {
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<U>((resolve) => {
+    timeoutTimer = setTimeout(() => resolve(params.onTimeout()), Math.max(1, params.timeoutMs));
+    timeoutTimer.unref?.();
+  });
+  try {
+    return await Promise.race([params.promise, timeoutPromise]);
+  } finally {
+    if (timeoutTimer) {
+      clearTimeout(timeoutTimer);
+    }
+  }
+}
+
+export async function withAbortTimeout<T>(params: {
+  timeoutMs: number;
+  createTimeoutError: () => Error;
+  run: (signal: AbortSignal) => Promise<T>;
+}): Promise<T> {
+  const controller = new AbortController();
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutTimer = setTimeout(
+      () => {
+        controller.abort();
+        reject(params.createTimeoutError());
+      },
+      Math.max(1, params.timeoutMs),
+    );
+    timeoutTimer.unref?.();
+  });
+  try {
+    return await Promise.race([params.run(controller.signal), timeoutPromise]);
+  } finally {
+    if (timeoutTimer) {
+      clearTimeout(timeoutTimer);
+    }
+  }
+}

package/src/monitor/typing.test.ts

@@ -0,0 +1,42 @@
+import { Routes } from "discord-api-types/v10";
+import { describe, expect, it, vi } from "vitest";
+import { sendTyping } from "./typing.js";
+
+describe("sendTyping", () => {
+  it("uses the direct Discord typing REST endpoint", async () => {
+    const rest = {
+      post: vi.fn(async () => {}),
+    };
+
+    await sendTyping({
+      // @ts-expect-error test stub only needs rest.post
+      rest,
+      channelId: "12345",
+    });
+
+    expect(rest.post).toHaveBeenCalledTimes(1);
+    expect(rest.post).toHaveBeenCalledWith(Routes.channelTyping("12345"));
+  });
+
+  it("times out when the typing endpoint hangs", async () => {
+    vi.useFakeTimers();
+    try {
+      const rest = {
+        post: vi.fn(() => new Promise(() => {})),
+      };
+
+      const promise = sendTyping({
+        // @ts-expect-error test stub only needs rest.post
+        rest,
+        channelId: "12345",
+      });
+      const rejection = expect(promise).rejects.toThrow("discord typing start timed out");
+
+      await vi.advanceTimersByTimeAsync(5_000);
+
+      await rejection;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/monitor/typing.ts

@@ -0,0 +1,17 @@
+import { sendChannelTyping, type RequestClient } from "../internal/discord.js";
+import { raceWithTimeout } from "./timeouts.js";
+
+const DISCORD_TYPING_START_TIMEOUT_MS = 5_000;
+
+export async function sendTyping(params: { rest: RequestClient; channelId: string }) {
+  const result = await raceWithTimeout({
+    promise: sendChannelTyping(params.rest, params.channelId).then(() => ({
+      kind: "sent" as const,
+    })),
+    timeoutMs: DISCORD_TYPING_START_TIMEOUT_MS,
+    onTimeout: () => ({ kind: "timeout" as const }),
+  });
+  if (result.kind === "timeout") {
+    throw new Error(`discord typing start timed out after ${DISCORD_TYPING_START_TIMEOUT_MS}ms`);
+  }
+}

package/src/monitor.gateway.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from "vitest";
+import { waitForDiscordGatewayStop } from "./monitor.gateway.js";
+import type { DiscordGatewayEvent } from "./monitor/gateway-supervisor.js";
+
+function createGatewayEvent(
+  type: DiscordGatewayEvent["type"],
+  message: string,
+): DiscordGatewayEvent {
+  const err = new Error(message);
+  return {
+    type,
+    err,
+    message: String(err),
+    shouldStopLifecycle: type !== "other",
+  };
+}
+
+function createGatewayWaitHarness() {
+  let lifecycleHandler: ((event: DiscordGatewayEvent) => void) | undefined;
+  const disconnect = vi.fn();
+  const abort = new AbortController();
+  const attachLifecycle = vi.fn((handler: (event: DiscordGatewayEvent) => void) => {
+    lifecycleHandler = handler;
+  });
+  const detachLifecycle = vi.fn(() => {
+    lifecycleHandler = undefined;
+  });
+  return {
+    abort,
+    attachLifecycle,
+    detachLifecycle,
+    disconnect,
+    emitGatewayEvent: (event: DiscordGatewayEvent) => {
+      lifecycleHandler?.(event);
+    },
+    gatewaySupervisor: {
+      attachLifecycle,
+      detachLifecycle,
+    },
+  };
+}
+
+function startGatewayWait(params?: {
+  disconnect?: () => void;
+  onGatewayEvent?: (event: DiscordGatewayEvent) => "continue" | "stop";
+  registerForceStop?: (fn: (error: unknown) => void) => void;
+}) {
+  const harness = createGatewayWaitHarness();
+  if (params?.disconnect) {
+    harness.disconnect.mockImplementation(params.disconnect);
+  }
+  const promise = waitForDiscordGatewayStop({
+    gateway: { disconnect: harness.disconnect },
+    abortSignal: harness.abort.signal,
+    gatewaySupervisor: harness.gatewaySupervisor,
+    ...(params?.onGatewayEvent ? { onGatewayEvent: params.onGatewayEvent } : {}),
+    ...(params?.registerForceStop ? { registerForceStop: params.registerForceStop } : {}),
+  });
+  return { ...harness, promise };
+}
+
+async function expectAbortToResolve(params: {
+  abort: AbortController;
+  attachLifecycle: ReturnType<typeof vi.fn>;
+  detachLifecycle: ReturnType<typeof vi.fn>;
+  disconnect: ReturnType<typeof vi.fn>;
+  promise: Promise<void>;
+  expectedDisconnectBeforeAbort?: number;
+}) {
+  if (params.expectedDisconnectBeforeAbort !== undefined) {
+    expect(params.disconnect).toHaveBeenCalledTimes(params.expectedDisconnectBeforeAbort);
+  }
+  expect(params.attachLifecycle).toHaveBeenCalledTimes(1);
+  params.abort.abort();
+  await expect(params.promise).resolves.toBeUndefined();
+  expect(params.disconnect).toHaveBeenCalledTimes(1);
+  expect(params.detachLifecycle).toHaveBeenCalledTimes(1);
+}
+
+describe("waitForDiscordGatewayStop", () => {
+  it("resolves on abort and disconnects gateway", async () => {
+    const { abort, attachLifecycle, detachLifecycle, disconnect, promise } = startGatewayWait();
+    await expectAbortToResolve({ abort, attachLifecycle, detachLifecycle, disconnect, promise });
+  });
+
+  it("rejects on lifecycle stop events and disconnects", async () => {
+    const fatalEvent = createGatewayEvent("fatal", "boom");
+    const { detachLifecycle, disconnect, emitGatewayEvent, promise } = startGatewayWait();
+
+    emitGatewayEvent(fatalEvent);
+
+    await expect(promise).rejects.toThrow("discord gateway fatal: Error: boom");
+    expect(disconnect).toHaveBeenCalledTimes(1);
+    expect(detachLifecycle).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores transient gateway events when instructed", async () => {
+    const transientEvent = createGatewayEvent("other", "transient");
+    const onGatewayEvent = vi.fn(() => "continue" as const);
+    const { abort, attachLifecycle, detachLifecycle, disconnect, emitGatewayEvent, promise } =
+      startGatewayWait({
+        onGatewayEvent,
+      });
+
+    emitGatewayEvent(transientEvent);
+    expect(onGatewayEvent).toHaveBeenCalledWith(transientEvent);
+    await expectAbortToResolve({
+      abort,
+      attachLifecycle,
+      detachLifecycle,
+      disconnect,
+      promise,
+      expectedDisconnectBeforeAbort: 0,
+    });
+  });
+
+  it("resolves on abort without a gateway", async () => {
+    const abort = new AbortController();
+    const promise = waitForDiscordGatewayStop({
+      abortSignal: abort.signal,
+    });
+
+    abort.abort();
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it("rejects via registerForceStop and disconnects gateway", async () => {
+    let forceStop: ((err: unknown) => void) | undefined;
+    const { detachLifecycle, disconnect, promise } = startGatewayWait({
+      registerForceStop: (handler) => {
+        forceStop = handler;
+      },
+    });
+
+    forceStop?.(new Error("runtime-not-ready"));
+
+    await expect(promise).rejects.toThrow("runtime-not-ready");
+    expect(disconnect).toHaveBeenCalledTimes(1);
+    expect(detachLifecycle).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the lifecycle handler active until disconnect returns on abort", async () => {
+    const onGatewayEvent = vi.fn(() => "stop" as const);
+    const fatalEvent = createGatewayEvent("fatal", "disconnect emitted error");
+    let emitFromDisconnect: ((event: DiscordGatewayEvent) => void) | undefined;
+    const { abort, detachLifecycle, disconnect, emitGatewayEvent, promise } = startGatewayWait({
+      onGatewayEvent,
+      disconnect: () => {
+        emitFromDisconnect?.(fatalEvent);
+      },
+    });
+    emitFromDisconnect = emitGatewayEvent;
+
+    abort.abort();
+
+    await expect(promise).resolves.toBeUndefined();
+    expect(onGatewayEvent).toHaveBeenCalledWith(fatalEvent);
+    expect(disconnect).toHaveBeenCalledTimes(1);
+    expect(detachLifecycle).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the original rejection when disconnect emits another stop event", async () => {
+    const firstEvent = createGatewayEvent("fatal", "first failure");
+    const secondEvent = createGatewayEvent("fatal", "second failure");
+    const seenEvents: DiscordGatewayEvent[] = [];
+    let emitFromDisconnect: ((event: DiscordGatewayEvent) => void) | undefined;
+    const { emitGatewayEvent, promise } = startGatewayWait({
+      onGatewayEvent: (event) => {
+        seenEvents.push(event);
+        return "stop";
+      },
+      disconnect: () => {
+        emitFromDisconnect?.(secondEvent);
+      },
+    });
+    emitFromDisconnect = emitGatewayEvent;
+
+    emitGatewayEvent(firstEvent);
+
+    await expect(promise).rejects.toThrow("discord gateway fatal: Error: first failure");
+    expect(seenEvents.map((event) => event.message)).toEqual([
+      firstEvent.message,
+      secondEvent.message,
+    ]);
+  });
+});

package/src/monitor.gateway.ts

@@ -0,0 +1,75 @@
+import type { DiscordGatewayHandle } from "./monitor/gateway-handle.js";
+import {
+  DiscordGatewayEvent,
+  DiscordGatewayLifecycleError,
+  DiscordGatewaySupervisor,
+} from "./monitor/gateway-supervisor.js";
+
+export { getDiscordGatewayEmitter } from "./monitor/gateway-supervisor.js";
+
+export type WaitForDiscordGatewayStopParams = {
+  gateway?: DiscordGatewayHandle;
+  abortSignal?: AbortSignal;
+  gatewaySupervisor?: Pick<DiscordGatewaySupervisor, "attachLifecycle" | "detachLifecycle">;
+  onGatewayEvent?: (event: DiscordGatewayEvent) => "continue" | "stop";
+  registerForceStop?: (forceStop: (err: unknown) => void) => void;
+};
+
+export async function waitForDiscordGatewayStop(
+  params: WaitForDiscordGatewayStopParams,
+): Promise<void> {
+  const { gateway, abortSignal } = params;
+  return await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      abortSignal?.removeEventListener("abort", onAbort);
+      params.gatewaySupervisor?.detachLifecycle();
+    };
+    const finishResolve = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      try {
+        gateway?.disconnect?.();
+      } finally {
+        // remove listeners after disconnect so late "error" events emitted
+        // during disconnect are still handled instead of becoming uncaught
+        cleanup();
+        resolve();
+      }
+    };
+    const finishReject = (err: unknown) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      try {
+        gateway?.disconnect?.();
+      } finally {
+        cleanup();
+        reject(err);
+      }
+    };
+    const onAbort = () => {
+      finishResolve();
+    };
+    const onGatewayEvent = (event: DiscordGatewayEvent) => {
+      const shouldStop = (params.onGatewayEvent?.(event) ?? "stop") === "stop";
+      if (shouldStop) {
+        finishReject(new DiscordGatewayLifecycleError(event));
+      }
+    };
+    const onForceStop = (err: unknown) => {
+      finishReject(err);
+    };
+    if (abortSignal?.aborted) {
+      onAbort();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+    params.gatewaySupervisor?.attachLifecycle(onGatewayEvent);
+    params.registerForceStop?.(onForceStop);
+  });
+}