@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/message-handler.context.ts

@@ -0,0 +1,492 @@
+import {
+  buildChannelInboundEventContext,
+  formatInboundEnvelope,
+  resolveEnvelopeFormatOptions,
+  toHistoryMediaEntries,
+  toInboundMediaFacts,
+} from "klaw/plugin-sdk/channel-inbound";
+import { resolveChannelContextVisibilityMode } from "klaw/plugin-sdk/context-visibility-runtime";
+import { resolvePinnedMainDmOwnerFromAllowlist } from "klaw/plugin-sdk/conversation-runtime";
+import { isDangerousNameMatchingEnabled } from "klaw/plugin-sdk/dangerous-name-runtime";
+import { createChannelHistoryWindow } from "klaw/plugin-sdk/reply-history";
+import { buildAgentSessionKey, resolveThreadSessionKeys } from "klaw/plugin-sdk/routing";
+import { danger, logVerbose, shouldLogVerbose } from "klaw/plugin-sdk/runtime-env";
+import { evaluateSupplementalContextVisibility } from "klaw/plugin-sdk/security-runtime";
+import { readSessionUpdatedAt, resolveStorePath } from "klaw/plugin-sdk/session-store-runtime";
+import { truncateUtf16Safe } from "klaw/plugin-sdk/text-utility-runtime";
+import { resolveDiscordConversationIdentity } from "../conversation-identity.js";
+import { ChannelType } from "../internal/discord.js";
+import { normalizeDiscordAllowList, normalizeDiscordSlug } from "./allow-list.js";
+import { resolveTimestampMs } from "./format.js";
+import {
+  buildDiscordInboundAccessContext,
+  createDiscordSupplementalContextAccessChecker,
+} from "./inbound-context.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.js";
+import {
+  resolveReferencedReplyMediaList,
+  resolveDiscordMessageText,
+  type DiscordMediaInfo,
+} from "./message-utils.js";
+import { buildDirectLabel, buildGuildLabel, resolveReplyContext } from "./reply-context.js";
+import { resolveDiscordAutoThreadReplyPlan, resolveDiscordThreadStarter } from "./threading.js";
+import {
+  DISCORD_ATTACHMENT_IDLE_TIMEOUT_MS,
+  DISCORD_ATTACHMENT_TOTAL_TIMEOUT_MS,
+} from "./timeouts.js";
+
+function normalizeDiscordDmOwnerEntry(entry: string): string | undefined {
+  const normalized = normalizeDiscordAllowList([entry], ["discord:", "user:", "pk:"]);
+  const candidate = normalized?.ids.values().next().value;
+  return typeof candidate === "string" && /^\d+$/.test(candidate) ? candidate : undefined;
+}
+
+function isContextAborted(abortSignal?: AbortSignal): boolean {
+  return Boolean(abortSignal?.aborted);
+}
+
+export async function buildDiscordMessageProcessContext(params: {
+  ctx: DiscordMessagePreflightContext;
+  text: string;
+  mediaList: DiscordMediaInfo[];
+}) {
+  const { ctx, text, mediaList } = params;
+  const {
+    cfg,
+    discordConfig,
+    accountId,
+    runtime,
+    mediaMaxBytes,
+    discordRestFetch,
+    abortSignal,
+    guildHistories,
+    historyLimit,
+    replyToMode,
+    message,
+    author,
+    sender,
+    canonicalMessageId,
+    data,
+    client,
+    channelInfo,
+    channelName,
+    messageChannelId,
+    isGuildMessage,
+    isDirectMessage,
+    baseText,
+    preflightAudioTranscript,
+    threadChannel,
+    threadParentId,
+    threadParentName,
+    threadParentType,
+    threadName,
+    displayChannelSlug,
+    guildInfo,
+    guildSlug,
+    memberRoleIds,
+    channelConfig,
+    baseSessionKey,
+    boundSessionKey,
+    route,
+    commandAuthorized,
+  } = ctx;
+
+  const fromLabel = isDirectMessage
+    ? buildDirectLabel(author)
+    : buildGuildLabel({
+        guild: data.guild ?? undefined,
+        channelName: channelName ?? messageChannelId,
+        channelId: messageChannelId,
+      });
+  const senderLabel = sender.label;
+  const isForumParent =
+    threadParentType === ChannelType.GuildForum || threadParentType === ChannelType.GuildMedia;
+  const forumParentSlug =
+    isForumParent && threadParentName ? normalizeDiscordSlug(threadParentName) : "";
+  const threadChannelId = threadChannel?.id;
+  const threadParentInheritanceEnabled = discordConfig?.thread?.inheritParent ?? false;
+  const isForumStarter =
+    Boolean(threadChannelId && isForumParent && forumParentSlug) && message.id === threadChannelId;
+  const forumContextLine = isForumStarter ? `[Forum parent: #${forumParentSlug}]` : null;
+  const groupChannel = isGuildMessage && displayChannelSlug ? `#${displayChannelSlug}` : undefined;
+  const groupSubject = isDirectMessage ? undefined : groupChannel;
+  const senderName = sender.isPluralKit
+    ? (sender.name ?? author.username)
+    : (data.member?.nickname ?? author.globalName ?? author.username);
+  const senderUsername = sender.isPluralKit
+    ? (sender.tag ?? sender.name ?? author.username)
+    : author.username;
+  const { groupSystemPrompt, ownerAllowFrom, untrustedContext } = buildDiscordInboundAccessContext({
+    channelConfig,
+    guildInfo,
+    sender: { id: sender.id, name: sender.name, tag: sender.tag },
+    allowNameMatching: isDangerousNameMatchingEnabled(discordConfig),
+    isGuild: isGuildMessage,
+    channelTopic: channelInfo?.topic,
+  });
+  const pinnedMainDmOwner = isDirectMessage
+    ? resolvePinnedMainDmOwnerFromAllowlist({
+        dmScope: cfg.session?.dmScope,
+        allowFrom: channelConfig?.users ?? guildInfo?.users,
+        normalizeEntry: normalizeDiscordDmOwnerEntry,
+      })
+    : null;
+  const contextVisibilityMode = resolveChannelContextVisibilityMode({
+    cfg,
+    channel: "discord",
+    accountId,
+  });
+  const allowNameMatching = isDangerousNameMatchingEnabled(discordConfig);
+  const isSupplementalContextSenderAllowed = createDiscordSupplementalContextAccessChecker({
+    channelConfig,
+    guildInfo,
+    allowNameMatching,
+    isGuild: isGuildMessage,
+  });
+  const storePath = resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
+  const previousTimestamp = readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const channelHistory = createChannelHistoryWindow({ historyMap: guildHistories });
+  const isRoomEvent = ctx.inboundEventKind === "room_event";
+  let combinedBody = formatInboundEnvelope({
+    channel: "Discord",
+    from: fromLabel,
+    timestamp: resolveTimestampMs(message.timestamp),
+    body: text,
+    chatType: isDirectMessage ? "direct" : "channel",
+    senderLabel,
+    previousTimestamp,
+    envelope: envelopeOptions,
+  });
+  const shouldIncludeChannelHistory =
+    !isDirectMessage &&
+    (isRoomEvent || !(isGuildMessage && channelConfig?.autoThread && !threadChannel));
+  if (shouldIncludeChannelHistory) {
+    combinedBody = channelHistory.buildPendingContext({
+      historyKey: messageChannelId,
+      limit: historyLimit,
+      currentMessage: combinedBody,
+      formatEntry: (entry) =>
+        formatInboundEnvelope({
+          channel: "Discord",
+          from: fromLabel,
+          timestamp: entry.timestamp,
+          body: `${entry.body} [id:${entry.messageId ?? "unknown"} channel:${messageChannelId}]`,
+          chatType: "channel",
+          senderLabel: entry.sender,
+          envelope: envelopeOptions,
+        }),
+    });
+  }
+  const replyContext = resolveReplyContext(message, resolveDiscordMessageText);
+  const replyVisibility = replyContext
+    ? evaluateSupplementalContextVisibility({
+        mode: contextVisibilityMode,
+        kind: "quote",
+        senderAllowed: isSupplementalContextSenderAllowed({
+          id: replyContext.senderId,
+          name: replyContext.senderName,
+          tag: replyContext.senderTag,
+          memberRoleIds: replyContext.memberRoleIds,
+        }),
+      })
+    : null;
+  const filteredReplyContext = replyContext && replyVisibility?.include ? replyContext : null;
+  if (replyContext && !filteredReplyContext && isGuildMessage) {
+    logVerbose(`discord: drop reply context (mode=${contextVisibilityMode})`);
+  }
+  const mediaListForContext = [...mediaList];
+  if (filteredReplyContext) {
+    const referencedReplyMediaList = await resolveReferencedReplyMediaList(message, mediaMaxBytes, {
+      fetchImpl: discordRestFetch,
+      ssrfPolicy: cfg.browser?.ssrfPolicy,
+      readIdleTimeoutMs: DISCORD_ATTACHMENT_IDLE_TIMEOUT_MS,
+      totalTimeoutMs: DISCORD_ATTACHMENT_TOTAL_TIMEOUT_MS,
+      abortSignal,
+    });
+    if (!isContextAborted(abortSignal)) {
+      mediaListForContext.push(...referencedReplyMediaList);
+    }
+  }
+  if (forumContextLine) {
+    combinedBody = `${combinedBody}\n${forumContextLine}`;
+  }
+
+  let threadStarterBody: string | undefined;
+  let threadLabel: string | undefined;
+  let parentSessionKey: string | undefined;
+  let modelParentSessionKey: string | undefined;
+  if (threadChannel) {
+    const includeThreadStarter = channelConfig?.includeThreadStarter !== false;
+    if (includeThreadStarter) {
+      const starter = await resolveDiscordThreadStarter({
+        channel: threadChannel,
+        client,
+        parentId: threadParentId,
+        parentType: threadParentType,
+        resolveTimestampMs,
+      });
+      if (starter?.text) {
+        const starterVisibility = evaluateSupplementalContextVisibility({
+          mode: contextVisibilityMode,
+          kind: "thread",
+          senderAllowed: isSupplementalContextSenderAllowed({
+            id: starter.authorId,
+            name: starter.authorName ?? starter.author,
+            tag: starter.authorTag,
+            memberRoleIds: starter.memberRoleIds,
+          }),
+        });
+        if (starterVisibility.include) {
+          threadStarterBody = starter.text;
+        } else {
+          logVerbose(`discord: drop thread starter context (mode=${contextVisibilityMode})`);
+        }
+      }
+    }
+    const parentName = threadParentName ?? "parent";
+    threadLabel = threadName
+      ? `Discord thread #${normalizeDiscordSlug(parentName)} › ${threadName}`
+      : `Discord thread #${normalizeDiscordSlug(parentName)}`;
+    if (threadParentId) {
+      parentSessionKey = buildAgentSessionKey({
+        agentId: route.agentId,
+        channel: route.channel,
+        peer: { kind: "channel", id: threadParentId },
+      });
+      modelParentSessionKey = parentSessionKey;
+    }
+    if (!threadParentInheritanceEnabled) {
+      parentSessionKey = undefined;
+    }
+  }
+  const preflightAudioIndex =
+    preflightAudioTranscript === undefined
+      ? -1
+      : mediaListForContext.findIndex((media) => media.contentType?.startsWith("audio/"));
+  const threadKeys = resolveThreadSessionKeys({
+    baseSessionKey,
+    threadId: threadChannel ? messageChannelId : undefined,
+    parentSessionKey,
+    useSuffix: false,
+  });
+  const replyPlan = await resolveDiscordAutoThreadReplyPlan({
+    client,
+    message,
+    messageChannelId,
+    isGuildMessage,
+    channelConfig: isRoomEvent ? null : channelConfig,
+    threadChannel,
+    channelType: channelInfo?.type,
+    channelName: channelInfo?.name,
+    channelDescription: channelInfo?.topic,
+    baseText: baseText ?? "",
+    combinedBody,
+    replyToMode,
+    agentId: route.agentId,
+    channel: route.channel,
+    cfg,
+    threadParentInheritanceEnabled,
+  });
+  const deliverTarget = replyPlan.deliverTarget;
+  const replyTarget = replyPlan.replyTarget;
+  const replyReference = replyPlan.replyReference;
+  const autoThreadContext = replyPlan.autoThreadContext;
+
+  const effectiveFrom = isDirectMessage
+    ? `discord:${author.id}`
+    : (autoThreadContext?.From ?? `discord:channel:${messageChannelId}`);
+  const dmConversationTarget = isDirectMessage
+    ? resolveDiscordConversationIdentity({
+        isDirectMessage,
+        userId: author.id,
+      })
+    : undefined;
+  const effectiveTo = autoThreadContext?.To ?? dmConversationTarget ?? replyTarget;
+  if (!effectiveTo) {
+    runtime.error?.(danger("discord: missing reply target"));
+    return null;
+  }
+  const lastRouteTo = dmConversationTarget ?? effectiveTo;
+  const inboundHistory = shouldIncludeChannelHistory
+    ? channelHistory.buildInboundHistory({
+        historyKey: messageChannelId,
+        limit: historyLimit,
+      })
+    : undefined;
+  const originatingTo = autoThreadContext?.OriginatingTo ?? dmConversationTarget ?? replyTarget;
+  const effectiveSessionKey =
+    boundSessionKey ?? autoThreadContext?.SessionKey ?? threadKeys.sessionKey;
+  const effectivePreviousTimestamp =
+    effectiveSessionKey === route.sessionKey
+      ? previousTimestamp
+      : readSessionUpdatedAt({
+          storePath,
+          sessionKey: effectiveSessionKey,
+        });
+
+  const ctxPayload = buildChannelInboundEventContext({
+    channel: "discord",
+    provider: "discord",
+    surface: "discord",
+    accountId: route.accountId,
+    messageId: canonicalMessageId ?? message.id,
+    messageIdFull: canonicalMessageId && canonicalMessageId !== message.id ? message.id : undefined,
+    timestamp: resolveTimestampMs(message.timestamp),
+    from: effectiveFrom,
+    sender: {
+      id: sender.id,
+      name: senderName,
+      username: senderUsername,
+      tag: sender.tag,
+      roles: memberRoleIds,
+      displayLabel: senderLabel,
+    },
+    conversation: {
+      kind: isDirectMessage ? "direct" : "channel",
+      id: messageChannelId,
+      label: fromLabel,
+      spaceId: isGuildMessage ? (guildInfo?.id ?? guildSlug) || undefined : undefined,
+      threadId: threadChannel?.id ?? autoThreadContext?.createdThreadId ?? undefined,
+      routePeer: {
+        kind: isDirectMessage ? "direct" : "channel",
+        id: isDirectMessage ? author.id : messageChannelId,
+      },
+    },
+    route: {
+      agentId: route.agentId,
+      accountId: route.accountId,
+      routeSessionKey: route.sessionKey,
+      dispatchSessionKey: effectiveSessionKey,
+      parentSessionKey: autoThreadContext?.ParentSessionKey ?? threadKeys.parentSessionKey,
+      modelParentSessionKey:
+        autoThreadContext?.ModelParentSessionKey ?? modelParentSessionKey ?? undefined,
+    },
+    reply: {
+      to: effectiveTo,
+      originatingTo,
+    },
+    message: {
+      inboundEventKind: ctx.inboundEventKind,
+      body: combinedBody,
+      rawBody: preflightAudioTranscript ?? baseText,
+      bodyForAgent: preflightAudioTranscript ?? baseText ?? text,
+      commandBody: preflightAudioTranscript ?? baseText,
+      envelopeFrom: fromLabel,
+      inboundHistory,
+    },
+    access: {
+      mentions: {
+        canDetectMention: ctx.canDetectMention,
+        wasMentioned: ctx.effectiveWasMentioned,
+        hasAnyMention: ctx.hasAnyMention,
+        requireMention: ctx.shouldRequireMention,
+        effectiveWasMentioned: ctx.effectiveWasMentioned,
+      },
+      commands: {
+        authorized: commandAuthorized,
+        allowTextCommands: ctx.allowTextCommands,
+        useAccessGroups: false,
+        authorizers: [],
+      },
+    },
+    commandTurn: {
+      kind: "text-slash" as const,
+      source: "text" as const,
+      authorized: commandAuthorized,
+      body: preflightAudioTranscript ?? baseText,
+    },
+    media: toInboundMediaFacts(mediaListForContext, {
+      transcribed: (_media, index) => index === preflightAudioIndex,
+    }),
+    supplemental: {
+      quote: filteredReplyContext
+        ? {
+            id: filteredReplyContext.id,
+            body: filteredReplyContext.body,
+            sender: filteredReplyContext.sender,
+          }
+        : undefined,
+      thread: {
+        starterBody: !effectivePreviousTimestamp ? threadStarterBody : undefined,
+        label: threadLabel,
+      },
+      groupSystemPrompt: isGuildMessage ? groupSystemPrompt : undefined,
+    },
+    extra: {
+      ...(preflightAudioTranscript !== undefined ? { Transcript: preflightAudioTranscript } : {}),
+      GroupSubject: groupSubject,
+      GroupChannel: groupChannel,
+      UntrustedStructuredContext: untrustedContext,
+      OwnerAllowFrom: ownerAllowFrom,
+    },
+  });
+  const persistedSessionKey = ctxPayload.SessionKey ?? route.sessionKey;
+  if (isRoomEvent && shouldIncludeChannelHistory) {
+    await channelHistory.recordWithMedia({
+      historyKey: messageChannelId,
+      limit: historyLimit,
+      entry: {
+        sender: senderName,
+        body: text,
+        timestamp: resolveTimestampMs(message.timestamp),
+        messageId: message.id,
+      },
+      media: toHistoryMediaEntries(mediaList, { messageId: message.id }),
+      messageId: message.id,
+    });
+  }
+
+  if (shouldLogVerbose()) {
+    const preview = truncateUtf16Safe(combinedBody, 200).replace(/\n/g, "\\n");
+    logVerbose(
+      `discord inbound: channel=${messageChannelId} deliver=${deliverTarget} from=${ctxPayload.From} preview="${preview}"`,
+    );
+  }
+
+  return {
+    ctxPayload,
+    persistedSessionKey,
+    turn: {
+      storePath,
+      record: {
+        updateLastRoute: {
+          sessionKey: persistedSessionKey,
+          channel: "discord",
+          to: lastRouteTo,
+          accountId: route.accountId,
+          mainDmOwnerPin:
+            isDirectMessage && persistedSessionKey === route.mainSessionKey && pinnedMainDmOwner
+              ? {
+                  ownerRecipient: pinnedMainDmOwner,
+                  senderRecipient: author.id,
+                  onSkip: ({
+                    ownerRecipient,
+                    senderRecipient,
+                  }: {
+                    ownerRecipient: string;
+                    senderRecipient: string;
+                  }) => {
+                    logVerbose(
+                      `discord: skip main-session last route for ${senderRecipient} (pinned owner ${ownerRecipient})`,
+                    );
+                  },
+                }
+              : undefined,
+        },
+        onRecordError: (err: unknown) => {
+          logVerbose(`discord: failed updating session meta: ${String(err)}`);
+        },
+      },
+    },
+    replyPlan,
+    deliverTarget,
+    replyTarget,
+    replyReference,
+  };
+}

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

@@ -0,0 +1,119 @@
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { resolveDiscordConversationIdentity } from "../conversation-identity.js";
+import type { User } from "../internal/discord.js";
+import { resolveDiscordDmCommandAccess, type DiscordDmPolicy } from "./dm-command-auth.js";
+import { handleDiscordDmCommandDecision } from "./dm-command-decision.js";
+import { formatDiscordUserTag } from "./format.js";
+import type {
+  DiscordMessagePreflightParams,
+  DiscordSenderIdentity,
+} from "./message-handler.preflight.types.js";
+
+let conversationRuntimePromise:
+  | Promise<typeof import("klaw/plugin-sdk/conversation-binding-runtime")>
+  | undefined;
+let discordSendRuntimePromise: Promise<typeof import("../send.js")> | undefined;
+
+async function loadConversationRuntime() {
+  conversationRuntimePromise ??= import("klaw/plugin-sdk/conversation-binding-runtime");
+  return await conversationRuntimePromise;
+}
+
+async function loadDiscordSendRuntime() {
+  discordSendRuntimePromise ??= import("../send.js");
+  return await discordSendRuntimePromise;
+}
+
+export async function resolveDiscordDmPreflightAccess(params: {
+  preflight: DiscordMessagePreflightParams;
+  author: User;
+  sender: DiscordSenderIdentity;
+  dmPolicy: DiscordDmPolicy;
+  resolvedAccountId: string;
+  allowNameMatching: boolean;
+}): Promise<{ commandAuthorized: boolean } | null> {
+  if (params.dmPolicy === "disabled") {
+    logVerbose("discord: drop dm (dmPolicy: disabled)");
+    return null;
+  }
+
+  const directBindingConversationId =
+    resolveDiscordConversationIdentity({
+      isDirectMessage: true,
+      userId: params.author.id,
+    }) ?? `user:${params.author.id}`;
+  const directBindingRecord = (await loadConversationRuntime())
+    .getSessionBindingService()
+    .resolveByConversation({
+      channel: "discord",
+      accountId: params.preflight.accountId,
+      conversationId: directBindingConversationId,
+    });
+  const dmAccess = await resolveDiscordDmCommandAccess({
+    accountId: params.resolvedAccountId,
+    dmPolicy: params.dmPolicy,
+    configuredAllowFrom: params.preflight.allowFrom ?? [],
+    sender: {
+      id: params.sender.id,
+      name: params.sender.name,
+      tag: params.sender.tag,
+    },
+    allowNameMatching: params.allowNameMatching,
+    cfg: params.preflight.cfg,
+    token: params.preflight.token,
+    rest: params.preflight.client.rest,
+  });
+  const commandAuthorized =
+    (dmAccess.senderAccess.allowed && dmAccess.commandAccess.authorized) ||
+    directBindingRecord != null;
+  if (dmAccess.senderAccess.decision === "allow") {
+    return { commandAuthorized };
+  }
+  if (directBindingRecord) {
+    logVerbose(
+      `discord: allow bound DM conversation ${directBindingConversationId} despite dmPolicy=${params.dmPolicy}`,
+    );
+    return { commandAuthorized };
+  }
+
+  await handleDiscordDmCommandDecision({
+    senderAccess: dmAccess.senderAccess,
+    accountId: params.resolvedAccountId,
+    sender: {
+      id: params.author.id,
+      tag: formatDiscordUserTag(params.author),
+      name: params.author.username ?? undefined,
+    },
+    onPairingCreated: async (code) => {
+      logVerbose(
+        `discord pairing request sender=${params.author.id} tag=${formatDiscordUserTag(params.author)} reason=${dmAccess.senderAccess.reasonCode}`,
+      );
+      try {
+        const conversationRuntime = await loadConversationRuntime();
+        const { sendMessageDiscord } = await loadDiscordSendRuntime();
+        await sendMessageDiscord(
+          `user:${params.author.id}`,
+          conversationRuntime.buildPairingReply({
+            channel: "discord",
+            idLine: `Your Discord user id: ${params.author.id}`,
+            code,
+          }),
+          {
+            cfg: params.preflight.cfg,
+            token: params.preflight.token,
+            rest: params.preflight.client.rest,
+            accountId: params.preflight.accountId,
+          },
+        );
+      } catch (err) {
+        logVerbose(`discord pairing reply failed for ${params.author.id}: ${String(err)}`);
+      }
+    },
+    onUnauthorized: async () => {
+      logVerbose(
+        `Blocked unauthorized discord sender ${params.sender.id} (dmPolicy=${params.dmPolicy}, reason=${dmAccess.senderAccess.reasonCode})`,
+      );
+    },
+  });
+  return null;
+}