@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/threading.starter.test.ts

@@ -0,0 +1,279 @@
+import { StickerFormatType } from "discord-api-types/v10";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ChannelType, type Client } from "../internal/discord.js";
+import { resetDiscordThreadStarterCacheForTest, resolveDiscordThreadStarter } from "./threading.js";
+
+type ResolvedThreadStarter = NonNullable<Awaited<ReturnType<typeof resolveDiscordThreadStarter>>>;
+
+type ThreadStarterRestMessage = {
+  content?: string | null;
+  embeds?: Array<{ title?: string | null; description?: string | null }>;
+  message_snapshots?: Array<{
+    message?: {
+      content?: string | null;
+      attachments?: unknown[];
+      embeds?: Array<{ title?: string | null; description?: string | null }>;
+      sticker_items?: unknown[];
+    };
+  }>;
+  author?: {
+    id?: string | null;
+    username?: string | null;
+    discriminator?: string | null;
+  };
+  member?: {
+    roles?: string[];
+  };
+  timestamp?: string | null;
+};
+
+function createStarterAuthor(
+  overrides: Record<string, unknown> = {},
+): NonNullable<ThreadStarterRestMessage["author"]> {
+  return {
+    id: "u1",
+    username: "Alice",
+    discriminator: "0",
+    ...overrides,
+  } as NonNullable<ThreadStarterRestMessage["author"]>;
+}
+
+function createForwardedSnapshotMessage(
+  overrides: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    content: "",
+    attachments: [],
+    embeds: [],
+    ...overrides,
+  };
+}
+
+function createForwardedSnapshot(overrides: Record<string, unknown> = {}) {
+  return {
+    message: createForwardedSnapshotMessage(overrides),
+  };
+}
+
+function createStarterMessage(overrides: ThreadStarterRestMessage = {}): ThreadStarterRestMessage {
+  return {
+    content: "",
+    embeds: [],
+    author: createStarterAuthor(),
+    ...overrides,
+  };
+}
+
+function requireThreadStarter(
+  result: Awaited<ReturnType<typeof resolveDiscordThreadStarter>>,
+): ResolvedThreadStarter {
+  if (!result) {
+    throw new Error("expected resolved Discord thread starter");
+  }
+  return result;
+}
+
+function firstRestGetPath(get: ReturnType<typeof vi.fn>): unknown {
+  const [call] = get.mock.calls;
+  if (!call) {
+    throw new Error("expected Discord REST GET call");
+  }
+  return call[0];
+}
+
+async function resolveStarter(params: {
+  message: ThreadStarterRestMessage;
+  parentId?: string;
+  parentType?: ChannelType;
+  resolveTimestampMs?: () => number | undefined;
+}) {
+  const get = vi.fn().mockResolvedValue(params.message);
+  const client = { rest: { get } } as unknown as Client;
+
+  const result = await resolveDiscordThreadStarter({
+    channel: { id: "thread-1" },
+    client,
+    parentId: params.parentId ?? "parent-1",
+    parentType: params.parentType ?? ChannelType.GuildText,
+    resolveTimestampMs: params.resolveTimestampMs ?? (() => undefined),
+  });
+
+  return { get, result };
+}
+
+describe("resolveDiscordThreadStarter", () => {
+  beforeEach(() => {
+    resetDiscordThreadStarterCacheForTest();
+  });
+
+  it("falls back to joined embed title and description when content is empty", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        content: "   ",
+        embeds: [{ title: "Alert", description: "Details" }],
+        timestamp: "2026-02-24T12:00:00.000Z",
+      }),
+      resolveTimestampMs: () => 123,
+    });
+
+    expect(requireThreadStarter(result)).toEqual({
+      text: "Alert\nDetails",
+      author: "Alice",
+      authorId: "u1",
+      authorName: "Alice",
+      authorTag: "Alice",
+      memberRoleIds: undefined,
+      timestamp: 123,
+    });
+  });
+
+  it("prefers starter content over embed fallback text", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        content: "starter content",
+        embeds: [{ title: "Alert", description: "Details" }],
+      }),
+    });
+
+    if (!result) {
+      throw new Error("starter content should have produced a resolved starter payload");
+    }
+    expect(result.text).toBe("starter content");
+  });
+
+  it("preserves username, tag, and role metadata for downstream visibility checks", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        content: "starter content",
+        author: createStarterAuthor({ discriminator: "1234" }),
+        member: {
+          roles: ["role-1", "role-2"],
+        },
+      }),
+    });
+
+    expect(requireThreadStarter(result)).toEqual({
+      text: "starter content",
+      author: "Alice#1234",
+      authorId: "u1",
+      authorName: "Alice",
+      authorTag: "Alice#1234",
+      memberRoleIds: ["role-1", "role-2"],
+      timestamp: undefined,
+    });
+  });
+
+  it("extracts text from forwarded message snapshots when content is empty", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        message_snapshots: [createForwardedSnapshot({ content: "forwarded task content" })],
+        author: createStarterAuthor({ id: "u2", username: "Bob" }),
+        timestamp: "2026-04-03T07:00:00.000Z",
+      }),
+      resolveTimestampMs: () => 456,
+    });
+
+    const starter = requireThreadStarter(result);
+    expect(starter.text).toContain("forwarded task content");
+    expect(starter.author).toBe("Bob");
+    expect(starter.timestamp).toBe(456);
+  });
+
+  it("prefers content over forwarded message snapshots", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        content: "direct content",
+        message_snapshots: [createForwardedSnapshot({ content: "forwarded content" })],
+        author: createStarterAuthor({ id: "u3", username: "Charlie" }),
+      }),
+    });
+
+    expect(requireThreadStarter(result).text).toBe("direct content");
+  });
+
+  it("joins multiple forwarded message snapshots", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        message_snapshots: [
+          createForwardedSnapshot({ content: "first forwarded message" }),
+          createForwardedSnapshot({ content: "second forwarded message" }),
+        ],
+        author: createStarterAuthor({ id: "u5", username: "Eve" }),
+      }),
+    });
+
+    const starter = requireThreadStarter(result);
+    expect(starter.text).toContain("first forwarded message");
+    expect(starter.text).toContain("second forwarded message");
+  });
+
+  it("preserves forwarded attachment placeholders in thread starter context", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        message_snapshots: [
+          createForwardedSnapshot({
+            attachments: [
+              {
+                id: "a1",
+                filename: "forwarded.png",
+                content_type: "image/png",
+                url: "https://cdn.discordapp.com/forwarded.png",
+              },
+            ],
+          }),
+        ],
+        author: createStarterAuthor({ id: "u6", username: "Frank" }),
+      }),
+    });
+
+    const starter = requireThreadStarter(result);
+    expect(starter.text).toContain("[Forwarded message]");
+    expect(starter.text).toContain("<media:image> (1 image)");
+  });
+
+  it("preserves forwarded sticker placeholders in thread starter context", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        message_snapshots: [
+          createForwardedSnapshot({
+            sticker_items: [
+              {
+                id: "s1",
+                name: "party",
+                format_type: StickerFormatType.PNG,
+              },
+            ],
+          }),
+        ],
+        author: createStarterAuthor({ id: "u7", username: "Grace" }),
+      }),
+    });
+
+    const starter = requireThreadStarter(result);
+    expect(starter.text).toContain("[Forwarded message]");
+    expect(starter.text).toContain("<media:sticker> (1 sticker)");
+  });
+
+  it("uses the thread id as the message channel id for forum parents", async () => {
+    const { get, result } = await resolveStarter({
+      message: createStarterMessage({ content: "starter content" }),
+      parentId: undefined,
+      parentType: ChannelType.GuildForum,
+    });
+
+    expect(requireThreadStarter(result).text).toBe("starter content");
+    expect(get).toHaveBeenCalledTimes(1);
+    expect(firstRestGetPath(get)).toBe("/channels/thread-1/messages/thread-1");
+  });
+
+  it("returns null when content, embeds, and snapshots are all empty", async () => {
+    const { result } = await resolveStarter({
+      message: createStarterMessage({
+        message_snapshots: [],
+        author: createStarterAuthor({ id: "u4", username: "Dave" }),
+      }),
+    });
+
+    expect(result).toBeNull();
+  });
+});

package/src/monitor/threading.starter.ts

@@ -0,0 +1,288 @@
+import type { ReplyToMode } from "klaw/plugin-sdk/config-contracts";
+import { createReplyReferencePlanner } from "klaw/plugin-sdk/reply-reference";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { truncateUtf16Safe } from "klaw/plugin-sdk/text-utility-runtime";
+import { ChannelType, getChannelMessage, type Client } from "../internal/discord.js";
+import {
+  resolveDiscordChannelIdSafe,
+  resolveDiscordChannelNameSafe,
+  resolveDiscordChannelParentIdSafe,
+  resolveDiscordChannelParentSafe,
+} from "./channel-access.js";
+import {
+  resolveDiscordChannelInfo,
+  resolveDiscordEmbedText,
+  resolveDiscordForwardedMessagesTextFromSnapshots,
+  resolveDiscordMessageChannelId,
+  type DiscordChannelInfo,
+  type DiscordChannelInfoClient,
+} from "./message-utils.js";
+import { getCachedThreadStarter, setCachedThreadStarter } from "./threading.cache.js";
+import type {
+  DiscordMessageEvent,
+  DiscordReplyDeliveryPlan,
+  DiscordThreadChannel,
+  DiscordThreadParentInfo,
+  DiscordThreadStarter,
+  DiscordThreadStarterRestAuthor,
+  DiscordThreadStarterRestMember,
+  DiscordThreadStarterRestMessage,
+} from "./threading.types.js";
+
+function isDiscordThreadType(type: ChannelType | undefined): boolean {
+  return (
+    type === ChannelType.PublicThread ||
+    type === ChannelType.PrivateThread ||
+    type === ChannelType.AnnouncementThread
+  );
+}
+
+function isDiscordForumParentType(parentType: ChannelType | undefined): boolean {
+  return parentType === ChannelType.GuildForum || parentType === ChannelType.GuildMedia;
+}
+
+export function resolveDiscordThreadChannel(params: {
+  isGuildMessage: boolean;
+  message: DiscordMessageEvent["message"];
+  channelInfo: DiscordChannelInfo | null;
+  messageChannelId?: string;
+}): DiscordThreadChannel | null {
+  if (!params.isGuildMessage) {
+    return null;
+  }
+  const { message, channelInfo } = params;
+  const channel = "channel" in message ? (message as { channel?: unknown }).channel : undefined;
+  const isThreadChannel =
+    channel &&
+    typeof channel === "object" &&
+    "isThread" in channel &&
+    typeof (channel as { isThread?: unknown }).isThread === "function" &&
+    (channel as { isThread: () => boolean }).isThread();
+  if (isThreadChannel) {
+    return channel as unknown as DiscordThreadChannel;
+  }
+  if (!isDiscordThreadType(channelInfo?.type)) {
+    return null;
+  }
+  const messageChannelId =
+    params.messageChannelId ||
+    resolveDiscordMessageChannelId({
+      message,
+    });
+  if (!messageChannelId) {
+    return null;
+  }
+  return {
+    id: messageChannelId,
+    name: channelInfo?.name ?? undefined,
+    parentId: channelInfo?.parentId ?? undefined,
+    parent: undefined,
+    ownerId: channelInfo?.ownerId ?? undefined,
+  };
+}
+
+export async function resolveDiscordThreadParentInfo(params: {
+  client: DiscordChannelInfoClient;
+  threadChannel: DiscordThreadChannel;
+  channelInfo: DiscordChannelInfo | null;
+}): Promise<DiscordThreadParentInfo> {
+  const { threadChannel, channelInfo, client } = params;
+  const parent = resolveDiscordChannelParentSafe(threadChannel);
+  let parentId =
+    resolveDiscordChannelParentIdSafe(threadChannel) ??
+    resolveDiscordChannelIdSafe(parent) ??
+    channelInfo?.parentId ??
+    undefined;
+  if (!parentId && threadChannel.id) {
+    const threadInfo = await resolveDiscordChannelInfo(client, threadChannel.id);
+    parentId = threadInfo?.parentId ?? undefined;
+  }
+  if (!parentId) {
+    return {};
+  }
+  let parentName = resolveDiscordChannelNameSafe(parent);
+  const parentInfo = await resolveDiscordChannelInfo(client, parentId);
+  parentName = parentName ?? parentInfo?.name;
+  const parentType = parentInfo?.type;
+  return { id: parentId, name: parentName, type: parentType };
+}
+
+export async function resolveDiscordThreadStarter(params: {
+  channel: DiscordThreadChannel;
+  client: Client;
+  parentId?: string;
+  parentType?: ChannelType;
+  resolveTimestampMs: (value?: string | null) => number | undefined;
+}): Promise<DiscordThreadStarter | null> {
+  const cacheKey = params.channel.id;
+  const now = Date.now();
+  const cached = getCachedThreadStarter(cacheKey, now);
+  if (cached) {
+    return cached;
+  }
+  try {
+    const messageChannelId = resolveDiscordThreadStarterMessageChannelId(params);
+    if (!messageChannelId) {
+      return null;
+    }
+    const starter = await fetchDiscordThreadStarterMessage({
+      client: params.client,
+      messageChannelId,
+      threadId: params.channel.id,
+    });
+    if (!starter) {
+      return null;
+    }
+    const payload = buildDiscordThreadStarterPayload({
+      starter,
+      resolveTimestampMs: params.resolveTimestampMs,
+    });
+    if (!payload) {
+      return null;
+    }
+    setCachedThreadStarter(cacheKey, payload, Date.now());
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+function resolveDiscordThreadStarterMessageChannelId(params: {
+  channel: DiscordThreadChannel;
+  parentId?: string;
+  parentType?: ChannelType;
+}): string | undefined {
+  return isDiscordForumParentType(params.parentType) ? params.channel.id : params.parentId;
+}
+
+async function fetchDiscordThreadStarterMessage(params: {
+  client: Client;
+  messageChannelId: string;
+  threadId: string;
+}): Promise<DiscordThreadStarterRestMessage | null> {
+  const starter = await getChannelMessage(
+    params.client.rest,
+    params.messageChannelId,
+    params.threadId,
+  );
+  return starter ? (starter as DiscordThreadStarterRestMessage) : null;
+}
+
+function buildDiscordThreadStarterPayload(params: {
+  starter: DiscordThreadStarterRestMessage;
+  resolveTimestampMs: (value?: string | null) => number | undefined;
+}): DiscordThreadStarter | null {
+  const text = resolveDiscordThreadStarterText(params.starter);
+  if (!text) {
+    return null;
+  }
+  return {
+    text,
+    ...resolveDiscordThreadStarterIdentity(params.starter),
+    timestamp: params.resolveTimestampMs(params.starter.timestamp) ?? undefined,
+  };
+}
+
+function resolveDiscordThreadStarterText(starter: DiscordThreadStarterRestMessage): string {
+  const content = normalizeOptionalString(starter.content) ?? "";
+  const embedText = resolveDiscordEmbedText(starter.embeds?.[0]);
+  const forwardedText = resolveDiscordForwardedMessagesTextFromSnapshots(starter.message_snapshots);
+  return content || embedText || forwardedText;
+}
+
+function resolveDiscordThreadStarterIdentity(
+  starter: DiscordThreadStarterRestMessage,
+): Omit<DiscordThreadStarter, "text" | "timestamp"> {
+  const author = resolveDiscordThreadStarterAuthor(starter);
+  return {
+    author,
+    authorId: starter.author?.id ?? undefined,
+    authorName: starter.author?.username ?? undefined,
+    authorTag: resolveDiscordThreadStarterAuthorTag(starter.author),
+    memberRoleIds: resolveDiscordThreadStarterRoleIds(starter.member),
+  };
+}
+
+function resolveDiscordThreadStarterAuthor(starter: DiscordThreadStarterRestMessage): string {
+  return (
+    starter.member?.nick ??
+    starter.member?.displayName ??
+    resolveDiscordThreadStarterAuthorTag(starter.author) ??
+    starter.author?.username ??
+    starter.author?.id ??
+    "Unknown"
+  );
+}
+
+function resolveDiscordThreadStarterAuthorTag(
+  author: DiscordThreadStarterRestAuthor | null | undefined,
+): string | undefined {
+  if (!author?.username || !author.discriminator) {
+    return undefined;
+  }
+  if (author.discriminator !== "0") {
+    return `${author.username}#${author.discriminator}`;
+  }
+  return author.username;
+}
+
+function resolveDiscordThreadStarterRoleIds(
+  member: DiscordThreadStarterRestMember | null | undefined,
+): string[] | undefined {
+  return Array.isArray(member?.roles) ? member.roles : undefined;
+}
+
+export function resolveDiscordReplyTarget(opts: {
+  replyToMode: ReplyToMode;
+  replyToId?: string;
+  hasReplied: boolean;
+}): string | undefined {
+  if (opts.replyToMode === "off") {
+    return undefined;
+  }
+  const replyToId = normalizeOptionalString(opts.replyToId);
+  if (!replyToId) {
+    return undefined;
+  }
+  if (opts.replyToMode === "all") {
+    return replyToId;
+  }
+  return opts.hasReplied ? undefined : replyToId;
+}
+
+export function sanitizeDiscordThreadName(rawName: string, fallbackId: string): string {
+  const cleanedName = rawName
+    .replace(/<@!?\d+>/g, "")
+    .replace(/<@&\d+>/g, "")
+    .replace(/<#\d+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const baseSource = cleanedName || `Thread ${fallbackId}`;
+  const base = truncateUtf16Safe(baseSource, 80);
+  return truncateUtf16Safe(base, 100) || `Thread ${fallbackId}`;
+}
+
+export function resolveDiscordReplyDeliveryPlan(params: {
+  replyTarget: string;
+  replyToMode: ReplyToMode;
+  messageId: string;
+  threadChannel?: DiscordThreadChannel | null;
+  createdThreadId?: string | null;
+}): DiscordReplyDeliveryPlan {
+  const originalReplyTarget = params.replyTarget;
+  let deliverTarget = originalReplyTarget;
+  let replyTarget = originalReplyTarget;
+
+  if (params.createdThreadId) {
+    deliverTarget = `channel:${params.createdThreadId}`;
+    replyTarget = deliverTarget;
+  }
+  const allowReference = deliverTarget === originalReplyTarget;
+  const replyReference = createReplyReferencePlanner({
+    replyToMode: allowReference ? params.replyToMode : "off",
+    existingId: params.threadChannel ? params.messageId : undefined,
+    startId: params.messageId,
+    allowReference,
+  });
+  return { deliverTarget, replyTarget, replyReference };
+}

package/src/monitor/threading.ts

@@ -0,0 +1,20 @@
+export {
+  maybeCreateDiscordAutoThread,
+  resolveDiscordAutoThreadContext,
+  resolveDiscordAutoThreadReplyPlan,
+} from "./threading.auto-thread.js";
+export { resetDiscordThreadStarterCacheForTest } from "./threading.cache.js";
+export {
+  resolveDiscordReplyDeliveryPlan,
+  resolveDiscordReplyTarget,
+  resolveDiscordThreadChannel,
+  resolveDiscordThreadParentInfo,
+  resolveDiscordThreadStarter,
+  sanitizeDiscordThreadName,
+} from "./threading.starter.js";
+export type {
+  DiscordAutoThreadContext,
+  DiscordAutoThreadReplyPlan,
+  DiscordThreadChannel,
+  DiscordThreadStarter,
+} from "./threading.types.js";

package/src/monitor/threading.types.ts

@@ -0,0 +1,102 @@
+import type { APIAttachment, APIStickerItem } from "discord-api-types/v10";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { createReplyReferencePlanner } from "klaw/plugin-sdk/reply-reference";
+import type { ChannelType, Client, MessageCreateListener } from "../internal/discord.js";
+import type { DiscordChannelConfigResolved } from "./allow-list.js";
+
+export type DiscordThreadChannel = {
+  id: string;
+  name?: string | null;
+  parentId?: string | null;
+  parent?: { id?: string; name?: string };
+  ownerId?: string | null;
+};
+
+export type DiscordThreadStarter = {
+  text: string;
+  author: string;
+  authorId?: string;
+  authorName?: string;
+  authorTag?: string;
+  memberRoleIds?: string[];
+  timestamp?: number;
+};
+
+export type DiscordThreadParentInfo = {
+  id?: string;
+  name?: string;
+  type?: ChannelType;
+};
+
+type DiscordThreadStarterRestEmbed = {
+  title?: string | null;
+  description?: string | null;
+};
+
+type DiscordThreadStarterRestSnapshotMessage = {
+  content?: string | null;
+  attachments?: APIAttachment[] | null;
+  embeds?: DiscordThreadStarterRestEmbed[] | null;
+  sticker_items?: APIStickerItem[] | null;
+};
+
+export type DiscordThreadStarterRestAuthor = {
+  id?: string | null;
+  username?: string | null;
+  discriminator?: string | null;
+};
+
+export type DiscordThreadStarterRestMember = {
+  nick?: string | null;
+  displayName?: string | null;
+  roles?: string[];
+};
+
+export type DiscordThreadStarterRestMessage = {
+  content?: string | null;
+  embeds?: DiscordThreadStarterRestEmbed[] | null;
+  message_snapshots?: Array<{ message?: DiscordThreadStarterRestSnapshotMessage | null }> | null;
+  member?: DiscordThreadStarterRestMember | null;
+  author?: DiscordThreadStarterRestAuthor | null;
+  timestamp?: string | null;
+};
+
+export type DiscordMessageEvent = Parameters<MessageCreateListener["handle"]>[0];
+
+export type DiscordReplyDeliveryPlan = {
+  deliverTarget: string;
+  replyTarget: string;
+  replyReference: ReturnType<typeof createReplyReferencePlanner>;
+};
+
+export type DiscordAutoThreadContext = {
+  createdThreadId: string;
+  From: string;
+  To: string;
+  OriginatingTo: string;
+  SessionKey: string;
+  ModelParentSessionKey?: string;
+  ParentSessionKey?: string;
+};
+
+export type DiscordAutoThreadReplyPlan = DiscordReplyDeliveryPlan & {
+  createdThreadId?: string;
+  autoThreadContext: DiscordAutoThreadContext | null;
+};
+
+export type MaybeCreateDiscordAutoThreadParams = {
+  client: Client;
+  message: DiscordMessageEvent["message"];
+  messageChannelId?: string;
+  channel?: string;
+  isGuildMessage: boolean;
+  channelConfig?: DiscordChannelConfigResolved | null;
+  threadChannel?: DiscordThreadChannel | null;
+  channelType?: ChannelType;
+  channelName?: string;
+  channelDescription?: string;
+  baseText: string;
+  combinedBody: string;
+  cfg: KlawConfig;
+  agentId?: string;
+};