@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/message-handler.routing-preflight.ts

@@ -0,0 +1,112 @@
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { resolveDiscordConversationIdentity } from "../conversation-identity.js";
+import type { User } from "../internal/discord.js";
+import type { DiscordMessagePreflightParams } from "./message-handler.preflight.types.js";
+import {
+  buildDiscordRoutePeer,
+  resolveDiscordConversationRoute,
+  resolveDiscordEffectiveRoute,
+  shouldIgnoreStaleDiscordRouteBinding,
+} from "./route-resolution.js";
+
+let conversationRuntimePromise:
+  | Promise<typeof import("klaw/plugin-sdk/conversation-binding-runtime")>
+  | undefined;
+
+async function loadConversationRuntime() {
+  conversationRuntimePromise ??= import("klaw/plugin-sdk/conversation-binding-runtime");
+  return await conversationRuntimePromise;
+}
+
+export async function resolveDiscordPreflightRoute(params: {
+  preflight: DiscordMessagePreflightParams;
+  author: User;
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  messageChannelId: string;
+  memberRoleIds: string[];
+  earlyThreadParentId?: string;
+}) {
+  const conversationRuntime = await loadConversationRuntime();
+  const route = resolveDiscordConversationRoute({
+    cfg: params.preflight.cfg,
+    accountId: params.preflight.accountId,
+    guildId: params.preflight.data.guild_id ?? undefined,
+    memberRoleIds: params.memberRoleIds,
+    peer: buildDiscordRoutePeer({
+      isDirectMessage: params.isDirectMessage,
+      isGroupDm: params.isGroupDm,
+      directUserId: params.author.id,
+      conversationId: params.messageChannelId,
+    }),
+    parentConversationId: params.earlyThreadParentId,
+  });
+  const bindingConversationId = params.isDirectMessage
+    ? (resolveDiscordConversationIdentity({
+        isDirectMessage: true,
+        userId: params.author.id,
+      }) ?? `user:${params.author.id}`)
+    : params.messageChannelId;
+  let runtimeRoute = conversationRuntime.resolveRuntimeConversationBindingRoute({
+    route,
+    conversation: {
+      channel: "discord",
+      accountId: params.preflight.accountId,
+      conversationId: bindingConversationId,
+      parentConversationId: params.earlyThreadParentId,
+    },
+  });
+  if (
+    shouldIgnoreStaleDiscordRouteBinding({
+      bindingRecord: runtimeRoute.bindingRecord,
+      route,
+    })
+  ) {
+    logVerbose(
+      `discord: ignoring stale route binding for conversation ${bindingConversationId} (${runtimeRoute.bindingRecord?.targetSessionKey} -> ${route.sessionKey})`,
+    );
+    runtimeRoute = {
+      bindingRecord: null,
+      route,
+    };
+  }
+  let threadBinding = runtimeRoute.bindingRecord ?? undefined;
+  const configuredRoute =
+    threadBinding == null
+      ? conversationRuntime.resolveConfiguredBindingRoute({
+          cfg: params.preflight.cfg,
+          route,
+          conversation: {
+            channel: "discord",
+            accountId: params.preflight.accountId,
+            conversationId: params.messageChannelId,
+            parentConversationId: params.earlyThreadParentId,
+          },
+        })
+      : null;
+  const configuredBinding = configuredRoute?.bindingResolution ?? null;
+  if (!threadBinding && configuredBinding) {
+    threadBinding = configuredBinding.record;
+  }
+  const boundSessionKey = conversationRuntime.isPluginOwnedSessionBindingRecord(threadBinding)
+    ? ""
+    : (runtimeRoute.boundSessionKey ?? threadBinding?.targetSessionKey?.trim());
+  const effectiveRoute = runtimeRoute.boundSessionKey
+    ? runtimeRoute.route
+    : resolveDiscordEffectiveRoute({
+        route,
+        boundSessionKey,
+        configuredRoute,
+        matchedBy: "binding.channel",
+      });
+
+  return {
+    conversationRuntime,
+    threadBinding,
+    configuredBinding,
+    boundSessionKey,
+    effectiveRoute,
+    boundAgentId: boundSessionKey ? effectiveRoute.agentId : undefined,
+    baseSessionKey: effectiveRoute.sessionKey,
+  };
+}

package/src/monitor/message-handler.test-harness.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.js";
+import { createNoopThreadBindingManager } from "./thread-bindings.js";
+
+export async function createBaseDiscordMessageContext(
+  overrides: Record<string, unknown> = {},
+): Promise<DiscordMessagePreflightContext> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "klaw-discord-"));
+  const storePath = path.join(dir, "sessions.json");
+  return {
+    cfg: { messages: { ackReaction: "👀" }, session: { store: storePath } },
+    discordConfig: {},
+    accountId: "default",
+    token: "token",
+    runtime: { log: () => {}, error: () => {} },
+    guildHistories: new Map(),
+    historyLimit: 0,
+    mediaMaxBytes: 1024,
+    textLimit: 4000,
+    sender: { label: "user" },
+    replyToMode: "off",
+    ackReactionScope: "group-mentions",
+    groupPolicy: "open",
+    data: { guild: { id: "g1", name: "Guild" } },
+    client: { rest: {} },
+    message: {
+      id: "m1",
+      channelId: "c1",
+      timestamp: new Date().toISOString(),
+      attachments: [],
+    },
+    messageChannelId: "c1",
+    author: {
+      id: "U1",
+      username: "alice",
+      discriminator: "0",
+      globalName: "Alice",
+    },
+    channelInfo: { name: "general" },
+    channelName: "general",
+    isGuildMessage: true,
+    isDirectMessage: false,
+    isGroupDm: false,
+    commandAuthorized: true,
+    baseText: "hi",
+    messageText: "hi",
+    wasMentioned: false,
+    shouldRequireMention: true,
+    canDetectMention: true,
+    effectiveWasMentioned: true,
+    shouldBypassMention: false,
+    threadChannel: null,
+    threadParentId: undefined,
+    threadParentName: undefined,
+    threadParentType: undefined,
+    threadName: undefined,
+    displayChannelSlug: "general",
+    guildInfo: null,
+    guildSlug: "guild",
+    channelConfig: null,
+    baseSessionKey: "agent:main:discord:guild:g1",
+    route: {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:guild:g1",
+      mainSessionKey: "agent:main:main",
+    },
+    threadBindings: createNoopThreadBindingManager("default"),
+    ...overrides,
+  } as unknown as DiscordMessagePreflightContext;
+}
+
+export function createDiscordDirectMessageContextOverrides(): Record<string, unknown> {
+  return {
+    data: { guild: null },
+    channelInfo: null,
+    channelName: undefined,
+    isGuildMessage: false,
+    isDirectMessage: true,
+    isGroupDm: false,
+    shouldRequireMention: false,
+    canDetectMention: false,
+    effectiveWasMentioned: false,
+    displayChannelSlug: "",
+    guildInfo: null,
+    guildSlug: "",
+    baseSessionKey: "agent:main:discord:direct:u1",
+    route: {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:direct:u1",
+      mainSessionKey: "agent:main:main",
+    },
+  };
+}

package/src/monitor/message-handler.test-helpers.ts

@@ -0,0 +1,75 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { vi } from "vitest";
+import type { createDiscordMessageHandler } from "./message-handler.js";
+import { createNoopThreadBindingManager } from "./thread-bindings.js";
+
+export const DEFAULT_DISCORD_BOT_USER_ID = "bot-123";
+
+export function createDiscordHandlerParams(overrides?: {
+  botUserId?: string;
+  setStatus?: (patch: Record<string, unknown>) => void;
+  abortSignal?: AbortSignal;
+}): Parameters<typeof createDiscordMessageHandler>[0] {
+  const cfg: KlawConfig = {
+    channels: {
+      discord: {
+        enabled: true,
+        token: "test-token",
+        groupPolicy: "allowlist",
+      },
+    },
+    messages: {
+      inbound: {
+        debounceMs: 0,
+      },
+    },
+  };
+  return {
+    cfg,
+    discordConfig: cfg.channels?.discord,
+    accountId: "default",
+    token: "test-token",
+    runtime: {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: (code: number): never => {
+        throw new Error(`exit ${code}`);
+      },
+    },
+    botUserId: overrides?.botUserId ?? DEFAULT_DISCORD_BOT_USER_ID,
+    guildHistories: new Map(),
+    historyLimit: 0,
+    mediaMaxBytes: 10_000,
+    textLimit: 2_000,
+    replyToMode: "off" as const,
+    dmEnabled: true,
+    dmPolicy: "pairing",
+    groupDmEnabled: false,
+    threadBindings: createNoopThreadBindingManager("default"),
+    setStatus: overrides?.setStatus,
+    abortSignal: overrides?.abortSignal,
+  };
+}
+
+export function createDiscordPreflightContext(channelId = "ch-1") {
+  return {
+    data: {
+      channel_id: channelId,
+      message: {
+        id: `msg-${channelId}`,
+        channel_id: channelId,
+        attachments: [],
+      },
+    },
+    message: {
+      id: `msg-${channelId}`,
+      channel_id: channelId,
+      attachments: [],
+    },
+    route: {
+      sessionKey: `agent:main:discord:channel:${channelId}`,
+    },
+    baseSessionKey: `agent:main:discord:channel:${channelId}`,
+    messageChannelId: channelId,
+  };
+}

package/src/monitor/message-handler.ts

@@ -0,0 +1,309 @@
+import {
+  createChannelInboundDebouncer,
+  shouldDebounceTextInbound,
+} from "klaw/plugin-sdk/channel-inbound";
+import { danger, logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { resolveOpenProviderRuntimeGroupPolicy } from "klaw/plugin-sdk/runtime-group-policy";
+import { createDiscordRestClient } from "../client.js";
+import type { Client } from "../internal/discord.js";
+import {
+  buildDiscordInboundReplayKey,
+  claimDiscordInboundReplay,
+  commitDiscordInboundReplay,
+  createDiscordInboundReplayGuard,
+  DiscordRetryableInboundError,
+  releaseDiscordInboundReplay,
+} from "./inbound-dedupe.js";
+import { buildDiscordInboundJob } from "./inbound-job.js";
+import type { DiscordMessageEvent, DiscordMessageHandler } from "./listeners.js";
+import { applyImplicitReplyBatchGate } from "./message-handler.batch-gate.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.js";
+import type { DiscordMessagePreflightParams } from "./message-handler.preflight.types.js";
+import {
+  createDiscordMessageRunQueue,
+  type DiscordMessageRunQueueTestingHooks,
+} from "./message-run-queue.js";
+import {
+  hasDiscordMessageStickers,
+  resolveDiscordMessageChannelId,
+  resolveDiscordMessageText,
+} from "./message-utils.js";
+import type { DiscordMonitorStatusSink } from "./status.js";
+import { sendTyping } from "./typing.js";
+
+type PreflightDiscordMessage =
+  typeof import("./message-handler.preflight.js").preflightDiscordMessage;
+
+type DiscordMessageHandlerParams = Omit<
+  DiscordMessagePreflightParams,
+  "ackReactionScope" | "groupPolicy" | "data" | "client"
+> & {
+  setStatus?: DiscordMonitorStatusSink;
+  abortSignal?: AbortSignal;
+  testing?: DiscordMessageHandlerTestingHooks;
+};
+
+type DiscordMessageHandlerTestingHooks = DiscordMessageRunQueueTestingHooks & {
+  preflightDiscordMessage?: PreflightDiscordMessage;
+};
+
+let messagePreflightRuntimePromise:
+  | Promise<typeof import("./message-handler.preflight.js")>
+  | undefined;
+
+async function loadMessagePreflightRuntime() {
+  messagePreflightRuntimePromise ??= import("./message-handler.preflight.js");
+  return await messagePreflightRuntimePromise;
+}
+
+export type DiscordMessageHandlerWithLifecycle = DiscordMessageHandler & {
+  deactivate: () => void;
+};
+
+function isNonEmptyString(value: string | undefined): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function shouldSendAcceptedDiscordTypingCue(ctx: DiscordMessagePreflightContext): boolean {
+  if (ctx.abortSignal?.aborted) {
+    return false;
+  }
+  if (!ctx.isDirectMessage || ctx.isGuildMessage || ctx.isGroupDm) {
+    return false;
+  }
+  if (!ctx.messageText.trim()) {
+    return false;
+  }
+  const configuredTypingMode = ctx.cfg.session?.typingMode ?? ctx.cfg.agents?.defaults?.typingMode;
+  return configuredTypingMode === undefined || configuredTypingMode === "instant";
+}
+
+function queueAcceptedDiscordTypingCue(ctx: DiscordMessagePreflightContext): void {
+  if (!shouldSendAcceptedDiscordTypingCue(ctx)) {
+    return;
+  }
+  const { rest } = createDiscordRestClient({
+    cfg: ctx.cfg,
+    token: ctx.token,
+    accountId: ctx.accountId,
+  });
+  void sendTyping({ rest, channelId: ctx.messageChannelId }).catch((err) => {
+    logVerbose(
+      `discord early typing cue failed for channel ${ctx.messageChannelId}: ${String(err)}`,
+    );
+  });
+}
+
+export function createDiscordMessageHandler(
+  params: DiscordMessageHandlerParams,
+): DiscordMessageHandlerWithLifecycle {
+  const { groupPolicy } = resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: params.cfg.channels?.discord !== undefined,
+    groupPolicy: params.discordConfig?.groupPolicy,
+    defaultGroupPolicy: params.cfg.channels?.defaults?.groupPolicy,
+  });
+  const ackReactionScope =
+    params.discordConfig?.ackReactionScope ??
+    params.cfg.messages?.ackReactionScope ??
+    "group-mentions";
+  const preflightDiscordMessageImpl = params.testing?.preflightDiscordMessage;
+  const replayGuard = createDiscordInboundReplayGuard();
+  const messageRunQueue = createDiscordMessageRunQueue({
+    runtime: params.runtime,
+    setStatus: params.setStatus,
+    abortSignal: params.abortSignal,
+    replayGuard,
+    testing: params.testing,
+  });
+
+  const { debouncer } = createChannelInboundDebouncer<{
+    data: DiscordMessageEvent;
+    client: Client;
+    abortSignal?: AbortSignal;
+    replayKey?: string;
+  }>({
+    cfg: params.cfg,
+    channel: "discord",
+    buildKey: (entry) => {
+      const message = entry.data.message;
+      const authorId = entry.data.author?.id;
+      if (!message || !authorId) {
+        return null;
+      }
+      const channelId = resolveDiscordMessageChannelId({
+        message,
+        eventChannelId: entry.data.channel_id,
+      });
+      if (!channelId) {
+        return null;
+      }
+      return `discord:${params.accountId}:${channelId}:${authorId}`;
+    },
+    shouldDebounce: (entry) => {
+      const message = entry.data.message;
+      if (!message) {
+        return false;
+      }
+      const baseText = resolveDiscordMessageText(message, { includeForwarded: false });
+      return shouldDebounceTextInbound({
+        text: baseText,
+        cfg: params.cfg,
+        hasMedia:
+          (message.attachments && message.attachments.length > 0) ||
+          hasDiscordMessageStickers(message),
+      });
+    },
+    onFlush: async (entries) => {
+      const last = entries.at(-1);
+      if (!last) {
+        return;
+      }
+      const replayKeys = entries.map((entry) => entry.replayKey).filter(isNonEmptyString);
+      const abortSignal = last.abortSignal;
+      if (abortSignal?.aborted) {
+        releaseDiscordInboundReplay({
+          replayKeys,
+          error: abortSignal.reason,
+          replayGuard,
+        });
+        return;
+      }
+      try {
+        if (entries.length === 1) {
+          const preflight =
+            preflightDiscordMessageImpl ??
+            (await loadMessagePreflightRuntime()).preflightDiscordMessage;
+          const ctx = await preflight({
+            ...params,
+            ackReactionScope,
+            groupPolicy,
+            abortSignal,
+            data: last.data,
+            client: last.client,
+          });
+          if (!ctx) {
+            await commitDiscordInboundReplay({ replayKeys, replayGuard });
+            return;
+          }
+          applyImplicitReplyBatchGate(ctx, params.replyToMode, false);
+          queueAcceptedDiscordTypingCue(ctx);
+          messageRunQueue.enqueue(buildDiscordInboundJob(ctx, { replayKeys }));
+          return;
+        }
+        const combinedBaseText = entries
+          .map((entry) =>
+            resolveDiscordMessageText(entry.data.message, { includeForwarded: false }),
+          )
+          .filter(Boolean)
+          .join("\n");
+        const syntheticMessage = Object.create(Object.getPrototypeOf(last.data.message), {
+          ...Object.getOwnPropertyDescriptors(last.data.message),
+          content: { value: combinedBaseText, enumerable: true, configurable: true },
+          attachments: { value: [], enumerable: true, configurable: true },
+          message_snapshots: {
+            value: (last.data.message as { message_snapshots?: unknown }).message_snapshots,
+            enumerable: true,
+            configurable: true,
+          },
+          messageSnapshots: {
+            value: (last.data.message as { messageSnapshots?: unknown }).messageSnapshots,
+            enumerable: true,
+            configurable: true,
+          },
+          rawData: {
+            value: { ...(last.data.message as { rawData?: Record<string, unknown> }).rawData },
+            enumerable: true,
+            configurable: true,
+          },
+        }) as DiscordMessageEvent["message"];
+        const syntheticData: DiscordMessageEvent = {
+          ...last.data,
+          message: syntheticMessage,
+        };
+        const preflight =
+          preflightDiscordMessageImpl ??
+          (await loadMessagePreflightRuntime()).preflightDiscordMessage;
+        const ctx = await preflight({
+          ...params,
+          ackReactionScope,
+          groupPolicy,
+          abortSignal,
+          data: syntheticData,
+          client: last.client,
+        });
+        if (!ctx) {
+          await commitDiscordInboundReplay({ replayKeys, replayGuard });
+          return;
+        }
+        applyImplicitReplyBatchGate(ctx, params.replyToMode, true);
+        if (entries.length > 1) {
+          const ids = entries.map((entry) => entry.data.message?.id).filter(isNonEmptyString);
+          if (ids.length > 0) {
+            const ctxBatch = ctx as typeof ctx & {
+              MessageSids?: string[];
+              MessageSidFirst?: string;
+              MessageSidLast?: string;
+            };
+            ctxBatch.MessageSids = ids;
+            ctxBatch.MessageSidFirst = ids[0];
+            ctxBatch.MessageSidLast = ids[ids.length - 1];
+          }
+        }
+        queueAcceptedDiscordTypingCue(ctx);
+        messageRunQueue.enqueue(buildDiscordInboundJob(ctx, { replayKeys }));
+      } catch (error) {
+        if (error instanceof DiscordRetryableInboundError) {
+          releaseDiscordInboundReplay({ replayKeys, error, replayGuard });
+        } else {
+          await commitDiscordInboundReplay({ replayKeys, replayGuard });
+        }
+        throw error;
+      }
+    },
+    onError: (err) => {
+      params.runtime.error?.(danger(`discord debounce flush failed: ${String(err)}`));
+    },
+  });
+
+  const handler: DiscordMessageHandlerWithLifecycle = async (data, client, options) => {
+    try {
+      if (options?.abortSignal?.aborted) {
+        return;
+      }
+      // Filter bot-own messages before they enter the debounce queue.
+      // The same check exists in preflightDiscordMessage(), but by that point
+      // the message has already consumed debounce capacity and blocked
+      // legitimate user messages. On active servers this causes cumulative
+      // slowdown (see #15874).
+      const msgAuthorId = data.message?.author?.id ?? data.author?.id;
+      if (params.botUserId && msgAuthorId === params.botUserId) {
+        return;
+      }
+      const replayKey = buildDiscordInboundReplayKey({
+        accountId: params.accountId,
+        data,
+      });
+      if (
+        !(await claimDiscordInboundReplay({
+          replayKey,
+          replayGuard,
+        }))
+      ) {
+        return;
+      }
+
+      await debouncer.enqueue({
+        data,
+        client,
+        abortSignal: options?.abortSignal,
+        replayKey: replayKey ?? undefined,
+      });
+    } catch (err) {
+      params.runtime.error?.(danger(`handler failed: ${String(err)}`));
+    }
+  };
+
+  handler.deactivate = messageRunQueue.deactivate;
+
+  return handler;
+}