@gakr-gakr/discord 0.1.0

package/src/monitor/reply-context.ts

@@ -0,0 +1,64 @@
+import type { Guild, Message, User } from "../internal/discord.js";
+import { resolveTimestampMs } from "./format.js";
+import { resolveDiscordSenderIdentity } from "./sender-identity.js";
+
+type DiscordReplyContext = {
+  id: string;
+  channelId: string;
+  sender: string;
+  senderId?: string;
+  senderName?: string;
+  senderTag?: string;
+  memberRoleIds?: string[];
+  body: string;
+  timestamp?: number;
+};
+
+export function resolveReplyContext(
+  message: Message,
+  resolveDiscordMessageText: (message: Message, options?: { includeForwarded?: boolean }) => string,
+): DiscordReplyContext | null {
+  const referenced = message.referencedMessage;
+  if (!referenced?.author) {
+    return null;
+  }
+  const referencedText = resolveDiscordMessageText(referenced, {
+    includeForwarded: true,
+  });
+  if (!referencedText) {
+    return null;
+  }
+  const sender = resolveDiscordSenderIdentity({
+    author: referenced.author,
+    pluralkitInfo: null,
+  });
+  return {
+    id: referenced.id,
+    channelId: referenced.channelId,
+    sender: sender.tag ?? sender.label ?? "unknown",
+    senderId: referenced.author.id,
+    senderName: referenced.author.username ?? undefined,
+    senderTag: sender.tag ?? undefined,
+    memberRoleIds: (() => {
+      const roles = (referenced as { member?: { roles?: string[] } }).member?.roles;
+      return Array.isArray(roles) ? roles.map((roleId) => roleId) : undefined;
+    })(),
+    body: referencedText,
+    timestamp: resolveTimestampMs(referenced.timestamp),
+  };
+}
+
+export function buildDirectLabel(author: User, tagOverride?: string) {
+  const username =
+    tagOverride?.trim() || resolveDiscordSenderIdentity({ author, pluralkitInfo: null }).tag;
+  return `${username ?? "unknown"} user id:${author.id}`;
+}
+
+export function buildGuildLabel(params: {
+  guild?: Guild<true> | Guild;
+  channelName: string;
+  channelId: string;
+}) {
+  const { guild, channelName, channelId } = params;
+  return `${guild?.name ?? "Guild"} #${channelName} channel id:${channelId}`;
+}

package/src/monitor/reply-delivery.ts

@@ -0,0 +1,216 @@
+import { resolveAgentAvatar } from "autobot/plugin-sdk/agent-runtime";
+import { sendDurableMessageBatch } from "autobot/plugin-sdk/channel-message";
+import type {
+  MarkdownTableMode,
+  AutoBotConfig,
+  ReplyToMode,
+} from "autobot/plugin-sdk/config-contracts";
+import type { OutboundMediaAccess } from "autobot/plugin-sdk/media-runtime";
+import {
+  buildOutboundSessionContext,
+  type OutboundDeliveryFormattingOptions,
+  type OutboundIdentity,
+  type OutboundSendDeps,
+} from "autobot/plugin-sdk/outbound-runtime";
+import type { ChunkMode } from "autobot/plugin-sdk/reply-chunking";
+import type { ReplyPayload } from "autobot/plugin-sdk/reply-dispatch-runtime";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { RequestClient } from "../internal/discord.js";
+import { sendMessageDiscord, sendVoiceMessageDiscord } from "../send.js";
+import { sanitizeDiscordFrontChannelReplyPayloads } from "./reply-safety.js";
+
+export type DiscordThreadBindingLookupRecord = {
+  accountId: string;
+  channelId: string;
+  threadId: string;
+  agentId: string;
+  label?: string;
+  webhookId?: string;
+  webhookToken?: string;
+};
+
+export type DiscordThreadBindingLookup = {
+  listBySessionKey: (targetSessionKey: string) => DiscordThreadBindingLookupRecord[];
+  touchThread?: (params: { threadId: string; at?: number; persist?: boolean }) => unknown;
+};
+
+function resolveTargetChannelId(target: string): string | undefined {
+  if (!target.startsWith("channel:")) {
+    return undefined;
+  }
+  const channelId = target.slice("channel:".length).trim();
+  return channelId || undefined;
+}
+
+function resolveBoundThreadBinding(params: {
+  threadBindings?: DiscordThreadBindingLookup;
+  sessionKey?: string;
+  target: string;
+}): DiscordThreadBindingLookupRecord | undefined {
+  const sessionKey = params.sessionKey?.trim();
+  if (!params.threadBindings || !sessionKey) {
+    return undefined;
+  }
+  const targetChannelId = resolveTargetChannelId(params.target);
+  if (!targetChannelId) {
+    return undefined;
+  }
+  return params.threadBindings
+    .listBySessionKey(sessionKey)
+    .find((entry) => entry.threadId === targetChannelId);
+}
+
+function resolveBindingIdentity(
+  cfg: AutoBotConfig,
+  binding: DiscordThreadBindingLookupRecord | undefined,
+): OutboundIdentity | undefined {
+  if (!binding) {
+    return undefined;
+  }
+  const baseLabel = binding.label?.trim() || binding.agentId;
+  const identity: OutboundIdentity = {
+    name: (`🤖 ${baseLabel}`.trim() || "🤖 agent").slice(0, 80),
+  };
+  try {
+    const avatar = resolveAgentAvatar(cfg, binding.agentId);
+    if (avatar.kind === "remote") {
+      identity.avatarUrl = avatar.url;
+    }
+  } catch {
+    // Avatar is cosmetic; delivery should not depend on local identity config.
+  }
+  return identity;
+}
+
+function createDiscordDeliveryDeps(params: {
+  cfg: AutoBotConfig;
+  token: string;
+  rest?: RequestClient;
+}): OutboundSendDeps {
+  return {
+    discord: (to: string, text: string, opts?: Parameters<typeof sendMessageDiscord>[2]) =>
+      sendMessageDiscord(to, text, {
+        ...opts,
+        cfg: opts?.cfg ?? params.cfg,
+        token: params.token,
+        rest: params.rest,
+      }),
+    discordVoice: (
+      to: string,
+      audioPath: string,
+      opts?: Parameters<typeof sendVoiceMessageDiscord>[2],
+    ) =>
+      sendVoiceMessageDiscord(to, audioPath, {
+        ...opts,
+        cfg: opts?.cfg ?? params.cfg,
+        token: params.token,
+        rest: params.rest,
+      }),
+  };
+}
+
+type DiscordDeliveryOptions = {
+  to: string;
+  threadId?: string;
+  agentId?: string;
+  identity?: OutboundIdentity;
+  mediaAccess?: OutboundMediaAccess;
+  replyToMode: ReplyToMode;
+  formatting: OutboundDeliveryFormattingOptions;
+};
+
+function resolveDiscordDeliveryOptions(params: {
+  cfg: AutoBotConfig;
+  target: string;
+  sessionKey?: string;
+  threadBindings?: DiscordThreadBindingLookup;
+  textLimit: number;
+  maxLinesPerMessage?: number;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  replyToMode?: ReplyToMode;
+  mediaLocalRoots?: readonly string[];
+}): DiscordDeliveryOptions {
+  const binding = resolveBoundThreadBinding({
+    threadBindings: params.threadBindings,
+    sessionKey: params.sessionKey,
+    target: params.target,
+  });
+  return {
+    to: binding ? `channel:${binding.channelId}` : params.target,
+    threadId: binding?.threadId,
+    agentId: binding?.agentId,
+    identity: resolveBindingIdentity(params.cfg, binding),
+    mediaAccess: params.mediaLocalRoots?.length
+      ? { localRoots: params.mediaLocalRoots }
+      : undefined,
+    replyToMode: params.replyToMode ?? "all",
+    formatting: {
+      textLimit: params.textLimit,
+      maxLinesPerMessage: params.maxLinesPerMessage,
+      tableMode: params.tableMode,
+      chunkMode: params.chunkMode,
+    },
+  };
+}
+
+export async function deliverDiscordReply(params: {
+  cfg: AutoBotConfig;
+  replies: ReplyPayload[];
+  target: string;
+  token: string;
+  accountId?: string;
+  rest?: RequestClient;
+  runtime: RuntimeEnv;
+  textLimit: number;
+  maxLinesPerMessage?: number;
+  replyToId?: string;
+  replyToMode?: ReplyToMode;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  sessionKey?: string;
+  threadBindings?: DiscordThreadBindingLookup;
+  mediaLocalRoots?: readonly string[];
+  kind: "tool" | "block" | "final";
+}) {
+  void params.runtime;
+
+  const delivery = resolveDiscordDeliveryOptions(params);
+  const payloads = sanitizeDiscordFrontChannelReplyPayloads(params.replies, { kind: params.kind });
+  if (payloads.length === 0) {
+    return;
+  }
+
+  const send = await sendDurableMessageBatch({
+    cfg: params.cfg,
+    channel: "discord",
+    to: delivery.to,
+    accountId: params.accountId,
+    payloads,
+    replyToId: normalizeOptionalString(params.replyToId),
+    replyToMode: delivery.replyToMode,
+    formatting: delivery.formatting,
+    threadId: delivery.threadId,
+    identity: delivery.identity,
+    deps: createDiscordDeliveryDeps({
+      cfg: params.cfg,
+      token: params.token,
+      rest: params.rest,
+    }),
+    mediaAccess: delivery.mediaAccess,
+    session: buildOutboundSessionContext({
+      cfg: params.cfg,
+      sessionKey: params.sessionKey,
+      agentId: delivery.agentId,
+      requesterAccountId: params.accountId,
+    }),
+  });
+  if (send.status === "failed" || send.status === "partial_failed") {
+    throw send.error;
+  }
+  const results = send.status === "sent" ? send.results : [];
+  if (results.length === 0) {
+    throw new Error(`discord final reply produced no delivered message for ${delivery.to}`);
+  }
+}

package/src/monitor/reply-safety.ts

@@ -0,0 +1,96 @@
+import type { ReplyPayload } from "autobot/plugin-sdk/reply-dispatch-runtime";
+import { resolveSendableOutboundReplyParts } from "autobot/plugin-sdk/reply-payload";
+import { sanitizeAssistantVisibleText } from "autobot/plugin-sdk/text-chunking";
+
+const DISCORD_INTERNAL_TRACE_LINE_RE =
+  /^(?:>\s*)?(?:📊|🛠️|📖|📝|🔍|🔎|⚙️)\s*(?:Session Status|Exec|Read|Edit|Write|Patch|Search|Open|Click|Find|Screenshot|Update Plan|Tool Call|Tool Result|Function Call|Shell|Command)\s*:/i;
+const DISCORD_INTERNAL_COMPACT_COMMAND_TRACE_LINE_RE =
+  /^(?:>\s*)?🛠️\s*(?:(?:(?:elevated|pty)\b\s*(?:·|,)\s*)+)?(?:`{1,2}\s*\S|(?:run|check|fetch|pull|push|view|show|list|switch|create|merge|rebase|stage|restore|reset|stash|search|find|print|copy|move|remove|install|start|cd|git|pnpm|npm|yarn|bun|node|python|python3|bash|sh)\b)/i;
+const DISCORD_INTERNAL_CHANNEL_LINE_RE =
+  /^(?:>\s*)?(?:analysis|commentary|tool[-_ ]?call|tool[-_ ]?result|function[-_ ]?call|thinking|reasoning)\s*[:=]/i;
+
+function hasNonEmptyRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0,
+  );
+}
+
+function hasInteractiveOrPresentationBlocks(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.title === "string" && record.title.trim().length > 0) {
+    return true;
+  }
+  return Array.isArray(record.blocks) && record.blocks.length > 0;
+}
+
+function hasNonTextReplyPayloadContent(payload: ReplyPayload): boolean {
+  return (
+    payload.audioAsVoice === true ||
+    hasNonEmptyRecord(payload.channelData) ||
+    hasInteractiveOrPresentationBlocks(payload.interactive) ||
+    hasInteractiveOrPresentationBlocks(payload.presentation)
+  );
+}
+
+function stripDiscordInternalTraceLines(text: string): string {
+  let inFence = false;
+  const kept: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      kept.push(line);
+      continue;
+    }
+    if (!inFence) {
+      const trimmed = line.trim();
+      if (
+        DISCORD_INTERNAL_TRACE_LINE_RE.test(trimmed) ||
+        DISCORD_INTERNAL_COMPACT_COMMAND_TRACE_LINE_RE.test(trimmed) ||
+        DISCORD_INTERNAL_CHANNEL_LINE_RE.test(trimmed)
+      ) {
+        continue;
+      }
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+function collapseExcessBlankLines(text: string): string {
+  return text.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export function sanitizeDiscordFrontChannelText(text: string): string {
+  const withoutAssistantScaffolding = sanitizeAssistantVisibleText(text);
+  const withoutTraceLines = stripDiscordInternalTraceLines(withoutAssistantScaffolding);
+  return collapseExcessBlankLines(withoutTraceLines).trim();
+}
+
+export function sanitizeDiscordFrontChannelReplyPayloads(
+  payloads: readonly ReplyPayload[],
+  options: { kind?: "tool" | "block" | "final" } = {},
+): ReplyPayload[] {
+  const preserveVerboseToolProgress = options.kind === "tool";
+  const safePayloads: ReplyPayload[] = [];
+  for (const payload of payloads) {
+    const safeText =
+      typeof payload.text === "string"
+        ? preserveVerboseToolProgress
+          ? collapseExcessBlankLines(sanitizeAssistantVisibleText(payload.text)).trim()
+          : sanitizeDiscordFrontChannelText(payload.text)
+        : payload.text;
+    const nextPayload =
+      safeText === payload.text
+        ? payload
+        : ({ ...payload, text: safeText || undefined } as ReplyPayload);
+    const nextParts = resolveSendableOutboundReplyParts(nextPayload);
+    if (!nextParts.hasContent && !hasNonTextReplyPayloadContent(nextPayload)) {
+      continue;
+    }
+    safePayloads.push(nextPayload);
+  }
+  return safePayloads;
+}

package/src/monitor/rest-fetch.ts

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import {
+  createHttp1EnvHttpProxyAgent,
+  createHttp1ProxyAgent,
+  resolveEnvHttpProxyAgentOptions,
+  wrapFetchWithAbortSignal,
+} from "autobot/plugin-sdk/fetch-runtime";
+import {
+  captureHttpExchange,
+  resolveEffectiveDebugProxyUrl,
+} from "autobot/plugin-sdk/proxy-capture";
+import { resolveRequestUrl } from "autobot/plugin-sdk/request-url";
+import { danger } from "autobot/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+import { Agent, fetch as undiciFetch } from "undici";
+import { createDiscordDnsLookup } from "../network-config.js";
+import { withValidatedDiscordProxy } from "../proxy-fetch.js";
+
+const discordDnsLookup = createDiscordDnsLookup();
+
+type DiscordRestDispatcher =
+  | InstanceType<typeof Agent>
+  | ReturnType<typeof createHttp1EnvHttpProxyAgent>
+  | ReturnType<typeof createHttp1ProxyAgent>;
+
+function createDirectDiscordRestDispatcher(): InstanceType<typeof Agent> {
+  return new Agent({
+    allowH2: false,
+    connect: { lookup: discordDnsLookup },
+  });
+}
+
+function createEnvProxyDiscordRestDispatcher(
+  runtime: RuntimeEnv,
+): ReturnType<typeof createHttp1EnvHttpProxyAgent> | undefined {
+  const envProxyOptions = resolveEnvHttpProxyAgentOptions();
+  if (!envProxyOptions) {
+    return undefined;
+  }
+  try {
+    return createHttp1EnvHttpProxyAgent({
+      ...envProxyOptions,
+      connect: { lookup: discordDnsLookup },
+    });
+  } catch (err) {
+    runtime.error?.(
+      danger(
+        `discord: env proxy unavailable for REST fetch; using direct dispatcher: ${formatErrorMessage(err)}`,
+      ),
+    );
+    return undefined;
+  }
+}
+
+function createDiscordRestFetchWithDispatcher(dispatcher: DiscordRestDispatcher): typeof fetch {
+  return wrapFetchWithAbortSignal(((input: RequestInfo | URL, init?: RequestInit) =>
+    (
+      undiciFetch(input as string | URL, {
+        ...(init as Record<string, unknown>),
+        dispatcher,
+      }) as unknown as Promise<Response>
+    ).then((response) => {
+      captureHttpExchange({
+        url: resolveRequestUrl(input),
+        method: init?.method ?? "GET",
+        requestHeaders: init?.headers as Headers | Record<string, string> | undefined,
+        requestBody: (init as RequestInit & { body?: BodyInit | null })?.body ?? null,
+        response,
+        flowId: randomUUID(),
+        meta: { subsystem: "discord-rest" },
+      });
+      return response;
+    })) as typeof fetch);
+}
+
+export function resolveDiscordRestFetch(
+  proxyUrl: string | undefined,
+  runtime: RuntimeEnv,
+): typeof fetch {
+  const effectiveProxyUrl = resolveEffectiveDebugProxyUrl(proxyUrl);
+  if (effectiveProxyUrl) {
+    const fetcher = withValidatedDiscordProxy(effectiveProxyUrl, runtime, (proxy) =>
+      createDiscordRestFetchWithDispatcher(createHttp1ProxyAgent({ uri: proxy })),
+    );
+    if (!fetcher) {
+      return fetch;
+    }
+    runtime.log?.("discord: rest proxy enabled");
+    return fetcher;
+  }
+
+  const fetcher = createDiscordRestFetchWithDispatcher(
+    createEnvProxyDiscordRestDispatcher(runtime) ?? createDirectDiscordRestDispatcher(),
+  );
+  return fetcher;
+}

package/src/monitor/route-resolution.ts

@@ -0,0 +1,140 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { SessionBindingRecord } from "autobot/plugin-sdk/conversation-runtime";
+import {
+  deriveLastRoutePolicy,
+  isAcpSessionKey,
+  isSubagentSessionKey,
+  parseAgentSessionKey,
+  resolveAgentRoute,
+  type ResolvedAgentRoute,
+  type RoutePeer,
+} from "autobot/plugin-sdk/routing";
+import { resolveAgentIdFromSessionKey } from "autobot/plugin-sdk/routing";
+
+export function buildDiscordRoutePeer(params: {
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  directUserId?: string | null;
+  conversationId: string;
+}): RoutePeer {
+  return {
+    kind: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
+    id: params.isDirectMessage
+      ? params.directUserId?.trim() || params.conversationId
+      : params.conversationId,
+  };
+}
+
+export function resolveDiscordConversationRoute(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  guildId?: string | null;
+  memberRoleIds?: string[];
+  peer: RoutePeer;
+  parentConversationId?: string | null;
+}): ResolvedAgentRoute {
+  return resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "discord",
+    accountId: params.accountId,
+    guildId: params.guildId ?? undefined,
+    memberRoleIds: params.memberRoleIds,
+    peer: params.peer,
+    parentPeer: params.parentConversationId
+      ? { kind: "channel", id: params.parentConversationId }
+      : undefined,
+  });
+}
+
+export function resolveDiscordBoundConversationRoute(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  guildId?: string | null;
+  memberRoleIds?: string[];
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  directUserId?: string | null;
+  conversationId: string;
+  parentConversationId?: string | null;
+  boundSessionKey?: string | null;
+  configuredRoute?: { route: ResolvedAgentRoute } | null;
+  matchedBy?: ResolvedAgentRoute["matchedBy"];
+}): ResolvedAgentRoute {
+  const route = resolveDiscordConversationRoute({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    guildId: params.guildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: buildDiscordRoutePeer({
+      isDirectMessage: params.isDirectMessage,
+      isGroupDm: params.isGroupDm,
+      directUserId: params.directUserId,
+      conversationId: params.conversationId,
+    }),
+    parentConversationId: params.parentConversationId,
+  });
+  return resolveDiscordEffectiveRoute({
+    route,
+    boundSessionKey: params.boundSessionKey,
+    configuredRoute: params.configuredRoute,
+    matchedBy: params.matchedBy,
+  });
+}
+
+export function resolveDiscordEffectiveRoute(params: {
+  route: ResolvedAgentRoute;
+  boundSessionKey?: string | null;
+  configuredRoute?: { route: ResolvedAgentRoute } | null;
+  matchedBy?: ResolvedAgentRoute["matchedBy"];
+}): ResolvedAgentRoute {
+  const boundSessionKey = params.boundSessionKey?.trim();
+  if (!boundSessionKey) {
+    return params.configuredRoute?.route ?? params.route;
+  }
+  return {
+    ...params.route,
+    sessionKey: boundSessionKey,
+    agentId: resolveAgentIdFromSessionKey(boundSessionKey),
+    lastRoutePolicy: deriveLastRoutePolicy({
+      sessionKey: boundSessionKey,
+      mainSessionKey: params.route.mainSessionKey,
+    }),
+    ...(params.matchedBy ? { matchedBy: params.matchedBy } : {}),
+  };
+}
+
+function hasExplicitRuntimeBindingIntent(record: SessionBindingRecord): boolean {
+  if (record.targetKind === "subagent") {
+    return true;
+  }
+  if (isAcpSessionKey(record.targetSessionKey) || isSubagentSessionKey(record.targetSessionKey)) {
+    return true;
+  }
+  const metadata = record.metadata;
+  if (!metadata || typeof metadata !== "object") {
+    return false;
+  }
+  return (
+    typeof metadata.boundBy === "string" ||
+    typeof metadata.label === "string" ||
+    typeof metadata.threadName === "string" ||
+    metadata.pluginBindingOwner === "plugin"
+  );
+}
+
+export function shouldIgnoreStaleDiscordRouteBinding(params: {
+  bindingRecord?: SessionBindingRecord | null;
+  route: ResolvedAgentRoute;
+}): boolean {
+  const bindingRecord = params.bindingRecord;
+  const boundSessionKey = bindingRecord?.targetSessionKey?.trim();
+  if (!bindingRecord || !boundSessionKey || hasExplicitRuntimeBindingIntent(bindingRecord)) {
+    return false;
+  }
+  const bound = parseAgentSessionKey(boundSessionKey);
+  const routed = parseAgentSessionKey(params.route.sessionKey);
+  if (!bound || !routed || bound.rest !== routed.rest) {
+    return false;
+  }
+  return bound.agentId !== params.route.agentId;
+}

package/src/monitor/sender-identity.ts

@@ -0,0 +1,81 @@
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { User } from "../internal/discord.js";
+import type { PluralKitMessageInfo } from "../pluralkit.js";
+import { formatDiscordUserTag } from "./format.js";
+
+export type DiscordSenderIdentity = {
+  id: string;
+  name?: string;
+  tag?: string;
+  label: string;
+  isPluralKit: boolean;
+  pluralkit?: {
+    memberId: string;
+    memberName?: string;
+    systemId?: string;
+    systemName?: string;
+  };
+};
+
+type DiscordWebhookMessageLike = {
+  webhookId?: string | null;
+  webhook_id?: string | null;
+};
+
+type DiscordMemberLike = {
+  nickname?: string | null;
+  nick?: string | null;
+};
+
+export function resolveDiscordWebhookId(message: DiscordWebhookMessageLike): string | null {
+  const candidate = message.webhookId ?? message.webhook_id;
+  return typeof candidate === "string" && candidate.trim() ? candidate.trim() : null;
+}
+
+export function resolveDiscordSenderIdentity(params: {
+  author: User;
+  member?: DiscordMemberLike | null;
+  pluralkitInfo?: PluralKitMessageInfo | null;
+}): DiscordSenderIdentity {
+  const pkInfo = params.pluralkitInfo ?? null;
+  const pkMember = pkInfo?.member ?? undefined;
+  const pkSystem = pkInfo?.system ?? undefined;
+  const memberId = pkMember?.id?.trim();
+  const memberNameRaw = pkMember?.display_name ?? pkMember?.name ?? "";
+  const memberName = memberNameRaw?.trim();
+  if (memberId && memberName) {
+    const systemName = pkSystem?.name?.trim();
+    const label = systemName ? `${memberName} (PK:${systemName})` : `${memberName} (PK)`;
+    return {
+      id: memberId,
+      name: memberName,
+      tag: normalizeOptionalString(pkMember?.name),
+      label,
+      isPluralKit: true,
+      pluralkit: {
+        memberId,
+        memberName,
+        systemId: normalizeOptionalString(pkSystem?.id),
+        systemName,
+      },
+    };
+  }
+
+  const senderTag = formatDiscordUserTag(params.author);
+  const senderDisplay =
+    params.member?.nickname ??
+    params.member?.nick ??
+    params.author.globalName ??
+    params.author.username;
+  const senderLabel =
+    senderDisplay && senderTag && senderDisplay !== senderTag
+      ? `${senderDisplay} (${senderTag})`
+      : (senderDisplay ?? senderTag ?? params.author.id);
+  return {
+    id: params.author.id,
+    name: params.author.username ?? undefined,
+    tag: senderTag,
+    label: senderLabel,
+    isPluralKit: false,
+  };
+}