@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/draft-stream.ts

@@ -0,0 +1,162 @@
+import { createFinalizableDraftLifecycle } from "klaw/plugin-sdk/channel-lifecycle";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import {
+  createChannelMessage,
+  deleteChannelMessage,
+  editChannelMessage,
+  type RequestClient,
+} from "./internal/discord.js";
+import { resolveDiscordMessageFlags } from "./send.shared.js";
+
+/** Discord messages cap at 2000 characters. */
+const DISCORD_STREAM_MAX_CHARS = 2000;
+const DEFAULT_THROTTLE_MS = 1200;
+const DISCORD_PREVIEW_ALLOWED_MENTIONS = { parse: [] };
+
+type DiscordDraftStream = {
+  update: (text: string) => void;
+  flush: () => Promise<void>;
+  messageId: () => string | undefined;
+  clear: () => Promise<void>;
+  discardPending: () => Promise<void>;
+  seal: () => Promise<void>;
+  stop: () => Promise<void>;
+  /** Reset internal state so the next update creates a new message instead of editing. */
+  forceNewMessage: () => void;
+};
+
+export function createDiscordDraftStream(params: {
+  rest: RequestClient;
+  channelId: string;
+  maxChars?: number;
+  replyToMessageId?: string | (() => string | undefined);
+  throttleMs?: number;
+  /** Minimum chars before sending first message (debounce for push notifications) */
+  minInitialChars?: number;
+  suppressEmbeds?: boolean;
+  log?: (message: string) => void;
+  warn?: (message: string) => void;
+}): DiscordDraftStream {
+  const maxChars = Math.min(params.maxChars ?? DISCORD_STREAM_MAX_CHARS, DISCORD_STREAM_MAX_CHARS);
+  const throttleMs = Math.max(250, params.throttleMs ?? DEFAULT_THROTTLE_MS);
+  const minInitialChars = params.minInitialChars;
+  const channelId = params.channelId;
+  const rest = params.rest;
+  const flags = resolveDiscordMessageFlags({ suppressEmbeds: params.suppressEmbeds });
+  const resolveReplyToMessageId = () =>
+    typeof params.replyToMessageId === "function"
+      ? params.replyToMessageId()
+      : params.replyToMessageId;
+
+  const streamState = { stopped: false, final: false };
+  let streamMessageId: string | undefined;
+  let lastSentText = "";
+
+  const sendOrEditStreamMessage = async (text: string): Promise<boolean> => {
+    // Allow final flush even if stopped (e.g., after clear()).
+    if (streamState.stopped && !streamState.final) {
+      return false;
+    }
+    const trimmed = text.trimEnd();
+    if (!trimmed) {
+      return false;
+    }
+    if (trimmed.length > maxChars) {
+      // Discord messages cap at 2000 chars.
+      // Stop streaming once we exceed the cap to avoid repeated API failures.
+      streamState.stopped = true;
+      params.warn?.(`discord stream preview stopped (text length ${trimmed.length} > ${maxChars})`);
+      return false;
+    }
+    if (trimmed === lastSentText) {
+      return true;
+    }
+
+    // Debounce first preview send for better push notification quality.
+    if (streamMessageId === undefined && minInitialChars != null && !streamState.final) {
+      if (trimmed.length < minInitialChars) {
+        return false;
+      }
+    }
+
+    lastSentText = trimmed;
+    try {
+      if (streamMessageId !== undefined) {
+        // Edit existing message
+        await editChannelMessage(rest, channelId, streamMessageId, {
+          body: {
+            content: trimmed,
+            allowed_mentions: DISCORD_PREVIEW_ALLOWED_MENTIONS,
+            ...(flags ? { flags } : {}),
+          },
+        });
+        return true;
+      }
+      // Send new message
+      const replyToMessageId = resolveReplyToMessageId()?.trim();
+      const messageReference = replyToMessageId
+        ? { message_id: replyToMessageId, fail_if_not_exists: false }
+        : undefined;
+      const sent = await createChannelMessage<{ id?: string }>(rest, channelId, {
+        body: {
+          content: trimmed,
+          allowed_mentions: DISCORD_PREVIEW_ALLOWED_MENTIONS,
+          ...(flags ? { flags } : {}),
+          ...(messageReference ? { message_reference: messageReference } : {}),
+        },
+      });
+      const sentMessageId = sent?.id;
+      if (typeof sentMessageId !== "string" || !sentMessageId) {
+        streamState.stopped = true;
+        params.warn?.("discord stream preview stopped (missing message id from send)");
+        return false;
+      }
+      streamMessageId = sentMessageId;
+      return true;
+    } catch (err) {
+      streamState.stopped = true;
+      params.warn?.(`discord stream preview failed: ${formatErrorMessage(err)}`);
+      return false;
+    }
+  };
+
+  const readMessageId = () => streamMessageId;
+  const clearMessageId = () => {
+    streamMessageId = undefined;
+  };
+  const isValidStreamMessageId = (value: unknown): value is string => typeof value === "string";
+  const deleteStreamMessage = async (messageId: string) => {
+    await deleteChannelMessage(rest, channelId, messageId);
+  };
+
+  const { loop, update, stop, clear, discardPending, seal } = createFinalizableDraftLifecycle({
+    throttleMs,
+    state: streamState,
+    sendOrEditStreamMessage,
+    readMessageId,
+    clearMessageId,
+    isValidMessageId: isValidStreamMessageId,
+    deleteMessage: deleteStreamMessage,
+    warn: params.warn,
+    warnPrefix: "discord stream preview cleanup failed",
+  });
+
+  const forceNewMessage = () => {
+    streamMessageId = undefined;
+    lastSentText = "";
+    loop.resetPending();
+  };
+
+  params.log?.(`discord stream preview ready (maxChars=${maxChars}, throttleMs=${throttleMs})`);
+
+  return {
+    update,
+    flush: loop.flush,
+    messageId: () => streamMessageId,
+    clear,
+    discardPending,
+    seal,
+    stop,
+    forceNewMessage,
+  };
+}

package/src/durable-delivery.test.ts

@@ -0,0 +1,103 @@
+import { sendDurableMessageBatch } from "klaw/plugin-sdk/channel-message";
+import {
+  createEmptyPluginRegistry,
+  createTestRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "klaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import {
+  createDiscordOutboundHoisted,
+  installDiscordOutboundModuleSpies,
+  resetDiscordOutboundMocks,
+} from "./outbound-adapter.test-harness.js";
+
+const hoisted = createDiscordOutboundHoisted();
+await installDiscordOutboundModuleSpies(hoisted);
+
+let discordPlugin: typeof import("./channel.js").discordPlugin;
+
+beforeAll(async () => {
+  ({ discordPlugin } = await import("./channel.js"));
+});
+
+describe("durable Discord delivery", () => {
+  beforeEach(() => {
+    resetDiscordOutboundMocks(hoisted);
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "discord",
+          source: "test",
+          plugin: discordPlugin,
+        },
+      ]),
+    );
+  });
+
+  afterEach(() => {
+    resetPluginRuntimeStateForTest();
+    setActivePluginRegistry(createEmptyPluginRegistry());
+  });
+
+  it("fans out planned text chunks and retries a transient failure on a later chunk", async () => {
+    hoisted.sendMessageDiscordMock
+      .mockResolvedValueOnce({
+        messageId: "msg-chunk-1",
+        channelId: "ch-1",
+      })
+      .mockRejectedValueOnce(Object.assign(new Error("discord 500"), { status: 500 }))
+      .mockResolvedValueOnce({
+        messageId: "msg-chunk-2",
+        channelId: "ch-1",
+      });
+
+    const result = await sendDurableMessageBatch({
+      cfg: {
+        channels: {
+          discord: {
+            token: "test-token",
+            retry: { attempts: 2, minDelayMs: 0, maxDelayMs: 0, jitter: 0 },
+          },
+        },
+      },
+      channel: "discord",
+      to: "channel:123456",
+      payloads: [{ text: "first chunk\nsecond chunk" }],
+      formatting: {
+        chunkMode: "newline",
+        maxLinesPerMessage: 1,
+        textLimit: 2000,
+      },
+      skipQueue: true,
+    });
+
+    expect(result.status).toBe("sent");
+    if (result.status !== "sent") {
+      throw new Error("expected durable Discord send to succeed");
+    }
+    expect(
+      result.results.map((entry) => ({
+        channel: entry.channel,
+        messageId: entry.messageId,
+      })),
+    ).toEqual([
+      { channel: "discord", messageId: "msg-chunk-1" },
+      { channel: "discord", messageId: "msg-chunk-2" },
+    ]);
+    expect(result.receipt.platformMessageIds).toEqual(["msg-chunk-1", "msg-chunk-2"]);
+    expect(result.payloadOutcomes).toEqual([
+      {
+        index: 0,
+        status: "sent",
+        results: result.results,
+      },
+    ]);
+    expect(hoisted.sendMessageDiscordMock).toHaveBeenCalledTimes(3);
+    expect(hoisted.sendMessageDiscordMock.mock.calls.map((call) => call[1])).toEqual([
+      "first chunk",
+      "second chunk",
+      "second chunk",
+    ]);
+  });
+});

package/src/error-body.ts

@@ -0,0 +1,38 @@
+const DISCORD_RESPONSE_BODY_SUMMARY_MAX_CHARS = 240;
+
+export function summarizeDiscordResponseBody(
+  body: string,
+  opts: { emptyText?: string } = {},
+): string | undefined {
+  const summary = body
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!summary) {
+    return opts.emptyText;
+  }
+  return summary.slice(0, DISCORD_RESPONSE_BODY_SUMMARY_MAX_CHARS);
+}
+
+export function isDiscordHtmlResponseBody(body: string, contentType?: string | null): boolean {
+  return (
+    /\bhtml\b/i.test(contentType ?? "") ||
+    /^\s*<!doctype\s+html\b/i.test(body) ||
+    /^\s*<html\b/i.test(body)
+  );
+}
+
+export function isDiscordRateLimitResponseBody(body: string): boolean {
+  const normalized = body.toLowerCase();
+  return (
+    normalized.includes("error 1015") ||
+    normalized.includes("cloudflare") ||
+    normalized.includes("rate limit")
+  );
+}

package/src/exec-approvals.test.ts

@@ -0,0 +1,88 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { describe, expect, it } from "vitest";
+import {
+  getDiscordExecApprovalApprovers,
+  isDiscordExecApprovalApprover,
+  isDiscordExecApprovalClientEnabled,
+} from "./exec-approvals.js";
+
+function buildConfig(
+  execApprovals?: NonNullable<NonNullable<KlawConfig["channels"]>["discord"]>["execApprovals"],
+  channelOverrides?: Partial<NonNullable<NonNullable<KlawConfig["channels"]>["discord"]>>,
+): KlawConfig {
+  return {
+    channels: {
+      discord: {
+        token: "discord-token",
+        ...channelOverrides,
+        execApprovals,
+      },
+    },
+  } as KlawConfig;
+}
+
+describe("discord exec approvals", () => {
+  it("requires explicit enablement even when owner approvers resolve", () => {
+    expect(isDiscordExecApprovalClientEnabled({ cfg: buildConfig() })).toBe(false);
+    expect(
+      isDiscordExecApprovalClientEnabled({
+        cfg: buildConfig({ enabled: true }),
+      }),
+    ).toBe(false);
+    expect(
+      isDiscordExecApprovalClientEnabled({
+        cfg: buildConfig({ approvers: ["123"] }),
+      }),
+    ).toBe(false);
+    expect(
+      isDiscordExecApprovalClientEnabled({
+        cfg: {
+          ...buildConfig(),
+          commands: { ownerAllowFrom: ["discord:789"] },
+        } as KlawConfig,
+      }),
+    ).toBe(false);
+    expect(
+      isDiscordExecApprovalClientEnabled({
+        cfg: buildConfig({ enabled: "auto", approvers: ["123"] }),
+      }),
+    ).toBe(true);
+    expect(
+      isDiscordExecApprovalClientEnabled({
+        cfg: buildConfig({ enabled: false, approvers: ["123"] }),
+      }),
+    ).toBe(false);
+  });
+
+  it("prefers explicit approvers when configured", () => {
+    const cfg = buildConfig({ approvers: ["456"] }, { allowFrom: ["123"], defaultTo: "user:789" });
+
+    expect(getDiscordExecApprovalApprovers({ cfg })).toEqual(["456"]);
+    expect(isDiscordExecApprovalApprover({ cfg, senderId: "456" })).toBe(true);
+    expect(isDiscordExecApprovalApprover({ cfg, senderId: "123" })).toBe(false);
+  });
+
+  it("does not infer approvers from allowFrom or default DM routes", () => {
+    const cfg = buildConfig(
+      { enabled: true },
+      {
+        allowFrom: ["123"],
+        dm: { allowFrom: ["456"] },
+        defaultTo: "user:789",
+      },
+    );
+
+    expect(getDiscordExecApprovalApprovers({ cfg })).toStrictEqual([]);
+    expect(isDiscordExecApprovalApprover({ cfg, senderId: "789" })).toBe(false);
+  });
+
+  it("falls back to commands.ownerAllowFrom for exec approvers", () => {
+    const cfg = {
+      ...buildConfig(),
+      commands: { ownerAllowFrom: ["discord:123", "user:456", "789"] },
+    } as KlawConfig;
+
+    expect(getDiscordExecApprovalApprovers({ cfg })).toEqual(["123", "456", "789"]);
+    expect(isDiscordExecApprovalApprover({ cfg, senderId: "456" })).toBe(true);
+  });
+});

package/src/exec-approvals.ts

@@ -0,0 +1,110 @@
+import type { ChannelOutboundPayloadHint } from "klaw/plugin-sdk/channel-contract";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { DiscordExecApprovalConfig } from "klaw/plugin-sdk/config-contracts";
+import type { ReplyPayload } from "klaw/plugin-sdk/reply-dispatch-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
+import {
+  getExecApprovalReplyMetadata,
+  isChannelExecApprovalClientEnabledFromConfig,
+  matchesApprovalRequestFilters,
+  resolveApprovalApprovers,
+} from "./approval-runtime.js";
+import { parseDiscordTarget } from "./target-parsing.js";
+
+function normalizeDiscordApproverId(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return trimmed;
+  }
+  try {
+    const target = parseDiscordTarget(trimmed);
+    return target?.kind === "user" ? target.id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveDiscordOwnerApprovers(cfg: KlawConfig): string[] {
+  const ownerAllowFrom = cfg.commands?.ownerAllowFrom;
+  if (!Array.isArray(ownerAllowFrom) || ownerAllowFrom.length === 0) {
+    return [];
+  }
+  return resolveApprovalApprovers({
+    explicit: ownerAllowFrom,
+    normalizeApprover: (value) => normalizeDiscordApproverId(String(value)),
+  });
+}
+
+export function getDiscordExecApprovalApprovers(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+  configOverride?: DiscordExecApprovalConfig | null;
+}): string[] {
+  return resolveApprovalApprovers({
+    explicit:
+      params.configOverride?.approvers ??
+      resolveDiscordAccount(params).config.execApprovals?.approvers ??
+      resolveDiscordOwnerApprovers(params.cfg),
+    normalizeApprover: (value) => normalizeDiscordApproverId(String(value)),
+  });
+}
+
+export function isDiscordExecApprovalClientEnabled(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+  configOverride?: DiscordExecApprovalConfig | null;
+}): boolean {
+  const config = params.configOverride ?? resolveDiscordAccount(params).config.execApprovals;
+  return isChannelExecApprovalClientEnabledFromConfig({
+    enabled: config?.enabled,
+    approverCount: getDiscordExecApprovalApprovers({
+      cfg: params.cfg,
+      accountId: params.accountId,
+      configOverride: params.configOverride,
+    }).length,
+  });
+}
+
+export function isDiscordExecApprovalApprover(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+  senderId?: string | null;
+  configOverride?: DiscordExecApprovalConfig | null;
+}): boolean {
+  const senderId = params.senderId?.trim();
+  if (!senderId) {
+    return false;
+  }
+  return getDiscordExecApprovalApprovers({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    configOverride: params.configOverride,
+  }).includes(senderId);
+}
+
+export function shouldSuppressLocalDiscordExecApprovalPrompt(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+  payload: ReplyPayload;
+  hint?: ChannelOutboundPayloadHint;
+}): boolean {
+  const metadata = getExecApprovalReplyMetadata(params.payload);
+  const config = resolveDiscordAccount(params).config.execApprovals;
+  return (
+    params.hint?.kind === "approval-pending" &&
+    params.hint.nativeRouteActive === true &&
+    isDiscordExecApprovalClientEnabled(params) &&
+    metadata !== null &&
+    matchesApprovalRequestFilters({
+      request: {
+        agentId: metadata.agentId,
+        sessionKey: metadata.sessionKey,
+      },
+      agentFilter: config?.agentFilter,
+      sessionFilter: config?.sessionFilter,
+    })
+  );
+}

package/src/gateway-logging.test.ts

@@ -0,0 +1,98 @@
+import { EventEmitter } from "node:events";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("klaw/plugin-sdk/runtime-env", () => ({
+  logVerbose: vi.fn(),
+}));
+
+let logVerbose: typeof import("klaw/plugin-sdk/runtime-env").logVerbose;
+let attachDiscordGatewayLogging: typeof import("./gateway-logging.js").attachDiscordGatewayLogging;
+
+const makeRuntime = () => ({
+  log: vi.fn(),
+  error: vi.fn(),
+  exit: vi.fn(),
+});
+
+describe("attachDiscordGatewayLogging", () => {
+  beforeAll(async () => {
+    ({ logVerbose } = await import("klaw/plugin-sdk/runtime-env"));
+    ({ attachDiscordGatewayLogging } = await import("./gateway-logging.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("logs debug events and promotes reconnect/close to info", () => {
+    const emitter = new EventEmitter();
+    const runtime = makeRuntime();
+
+    const cleanup = attachDiscordGatewayLogging({
+      emitter,
+      runtime,
+    });
+
+    emitter.emit("debug", "Gateway websocket opened");
+    emitter.emit("debug", "Gateway websocket closed: 1001");
+    emitter.emit("debug", "Gateway reconnect scheduled in 1000ms (close, resume=true)");
+    emitter.emit("debug", "Gateway forcing fresh IDENTIFY after 3 failed resume attempts");
+
+    const logVerboseMock = vi.mocked(logVerbose);
+    expect(logVerboseMock).toHaveBeenCalledTimes(4);
+    expect(runtime.log).toHaveBeenCalledTimes(3);
+    expect(runtime.log).toHaveBeenNthCalledWith(
+      1,
+      "discord gateway: Gateway websocket closed: 1001",
+    );
+    expect(runtime.log).toHaveBeenNthCalledWith(
+      2,
+      "discord gateway: Gateway reconnect scheduled in 1000ms (close, resume=true)",
+    );
+    expect(runtime.log).toHaveBeenNthCalledWith(
+      3,
+      "discord gateway: Gateway forcing fresh IDENTIFY after 3 failed resume attempts",
+    );
+
+    cleanup();
+  });
+
+  it("logs warnings and metrics only to verbose", () => {
+    const emitter = new EventEmitter();
+    const runtime = makeRuntime();
+
+    const cleanup = attachDiscordGatewayLogging({
+      emitter,
+      runtime,
+    });
+
+    emitter.emit("warning", "High latency detected: 1200ms");
+    emitter.emit("metrics", { latency: 42, errors: 1 });
+
+    const logVerboseMock = vi.mocked(logVerbose);
+    expect(logVerboseMock).toHaveBeenCalledTimes(2);
+    expect(runtime.log).not.toHaveBeenCalled();
+
+    cleanup();
+  });
+
+  it("removes listeners on cleanup", () => {
+    const emitter = new EventEmitter();
+    const runtime = makeRuntime();
+
+    const cleanup = attachDiscordGatewayLogging({
+      emitter,
+      runtime,
+    });
+    cleanup();
+
+    const logVerboseMock = vi.mocked(logVerbose);
+    logVerboseMock.mockClear();
+
+    emitter.emit("debug", "Gateway websocket closed: 1001");
+    emitter.emit("warning", "High latency detected: 1200ms");
+    emitter.emit("metrics", { latency: 42 });
+
+    expect(logVerboseMock).not.toHaveBeenCalled();
+    expect(runtime.log).not.toHaveBeenCalled();
+  });
+});

package/src/gateway-logging.ts

@@ -0,0 +1,67 @@
+import type { EventEmitter } from "node:events";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+
+type GatewayEmitter = Pick<EventEmitter, "on" | "removeListener">;
+
+const INFO_DEBUG_MARKERS = [
+  "Gateway websocket closed",
+  "Gateway reconnect scheduled in",
+  "Gateway forcing fresh IDENTIFY after",
+];
+
+const shouldPromoteGatewayDebug = (message: string) =>
+  INFO_DEBUG_MARKERS.some((marker) => message.includes(marker));
+
+const formatGatewayMetrics = (metrics: unknown) => {
+  if (metrics === null || metrics === undefined) {
+    return String(metrics);
+  }
+  if (typeof metrics === "string") {
+    return metrics;
+  }
+  if (typeof metrics === "number" || typeof metrics === "boolean" || typeof metrics === "bigint") {
+    return String(metrics);
+  }
+  try {
+    return JSON.stringify(metrics);
+  } catch {
+    return "[unserializable metrics]";
+  }
+};
+
+export function attachDiscordGatewayLogging(params: {
+  emitter?: GatewayEmitter;
+  runtime: RuntimeEnv;
+}) {
+  const { emitter, runtime } = params;
+  if (!emitter) {
+    return () => {};
+  }
+
+  const onGatewayDebug = (msg: unknown) => {
+    const message = String(msg);
+    logVerbose(`discord gateway: ${message}`);
+    if (shouldPromoteGatewayDebug(message)) {
+      runtime.log?.(`discord gateway: ${message}`);
+    }
+  };
+
+  const onGatewayWarning = (warning: unknown) => {
+    logVerbose(`discord gateway warning: ${String(warning)}`);
+  };
+
+  const onGatewayMetrics = (metrics: unknown) => {
+    logVerbose(`discord gateway metrics: ${formatGatewayMetrics(metrics)}`);
+  };
+
+  emitter.on("debug", onGatewayDebug);
+  emitter.on("warning", onGatewayWarning);
+  emitter.on("metrics", onGatewayMetrics);
+
+  return () => {
+    emitter.removeListener("debug", onGatewayDebug);
+    emitter.removeListener("warning", onGatewayWarning);
+    emitter.removeListener("metrics", onGatewayMetrics);
+  };
+}