@gakr-gakr/discord 0.1.0

package/src/monitor/gateway-supervisor.ts

@@ -0,0 +1,206 @@
+import type { EventEmitter } from "node:events";
+import { danger } from "autobot/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "autobot/plugin-sdk/ssrf-runtime";
+
+type DiscordGatewayEventType = "disallowed-intents" | "fatal" | "other" | "reconnect-exhausted";
+
+export type DiscordGatewayEvent = {
+  type: DiscordGatewayEventType;
+  err: unknown;
+  message: string;
+  shouldStopLifecycle: boolean;
+};
+
+export class DiscordGatewayLifecycleError extends Error {
+  readonly eventType: DiscordGatewayEventType;
+
+  constructor(event: Pick<DiscordGatewayEvent, "type" | "message" | "err">) {
+    super(`discord gateway ${event.type}: ${event.message}`, {
+      cause: event.err instanceof Error ? event.err : undefined,
+    });
+    this.name = "DiscordGatewayLifecycleError";
+    this.eventType = event.type;
+  }
+}
+
+export function getDiscordGatewayEmitter(gateway?: unknown): EventEmitter | undefined {
+  return (gateway as { emitter?: EventEmitter } | undefined)?.emitter;
+}
+
+export type DiscordGatewaySupervisor = {
+  emitter?: EventEmitter;
+  attachLifecycle: (handler: (event: DiscordGatewayEvent) => void) => void;
+  detachLifecycle: () => void;
+  drainPending: (
+    handler: (event: DiscordGatewayEvent) => "continue" | "stop",
+  ) => "continue" | "stop";
+  dispose: () => void;
+};
+
+type GatewaySupervisorPhase = "active" | "buffering" | "disposed" | "teardown";
+
+function readFirstStackFrame(err: Error): string | undefined {
+  const stack = err.stack;
+  if (!stack) {
+    return undefined;
+  }
+  const frame = stack
+    .split("\n")
+    .slice(1)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return frame ? frame.replace(/^at\s+/, "") : undefined;
+}
+
+function formatDiscordGatewayErrorMessage(err: unknown): string {
+  if (!(err instanceof Error)) {
+    return formatErrorMessage(err);
+  }
+  if (err.message) {
+    const detail = formatErrorMessage(err);
+    return err.name ? `${err.name}: ${detail}` : detail;
+  }
+  const detail = formatErrorMessage(err);
+  const firstFrame = readFirstStackFrame(err);
+  if (firstFrame && detail === (err.name || "Error")) {
+    return `${detail} @ ${firstFrame}`;
+  }
+  return detail;
+}
+
+export function classifyDiscordGatewayEvent(params: {
+  err: unknown;
+  isDisallowedIntentsError: (err: unknown) => boolean;
+}): DiscordGatewayEvent {
+  const message = formatDiscordGatewayErrorMessage(params.err);
+  if (params.isDisallowedIntentsError(params.err)) {
+    return {
+      type: "disallowed-intents",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  if (message.includes("Max reconnect attempts")) {
+    return {
+      type: "reconnect-exhausted",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  if (
+    params.err instanceof TypeError ||
+    message.includes("Fatal Gateway error") ||
+    message.includes("Fatal gateway close code") ||
+    message.includes("Gateway HELLO missing heartbeat") ||
+    message.includes("Invalid gateway payload") ||
+    message.includes("Gateway socket emitted an unknown error")
+  ) {
+    return {
+      type: "fatal",
+      err: params.err,
+      message,
+      shouldStopLifecycle: true,
+    };
+  }
+  return {
+    type: "other",
+    err: params.err,
+    message,
+    shouldStopLifecycle: false,
+  };
+}
+
+export function createDiscordGatewaySupervisor(params: {
+  gateway?: unknown;
+  isDisallowedIntentsError: (err: unknown) => boolean;
+  runtime: RuntimeEnv;
+}): DiscordGatewaySupervisor {
+  const emitter = getDiscordGatewayEmitter(params.gateway);
+  const pending: DiscordGatewayEvent[] = [];
+  if (!emitter) {
+    return {
+      attachLifecycle: () => {},
+      detachLifecycle: () => {},
+      drainPending: () => "continue",
+      dispose: () => {},
+      emitter,
+    };
+  }
+
+  let lifecycleHandler: ((event: DiscordGatewayEvent) => void) | undefined;
+  let phase: GatewaySupervisorPhase = "buffering";
+  const seenLateEventKeys = new Set<string>();
+  const logLateEvent =
+    (state: Extract<GatewaySupervisorPhase, "disposed" | "teardown">) =>
+    (event: DiscordGatewayEvent) => {
+      const key = `${state}:${event.type}:${event.message}`;
+      if (seenLateEventKeys.has(key)) {
+        return;
+      }
+      seenLateEventKeys.add(key);
+      params.runtime.error?.(
+        danger(
+          `discord: suppressed late gateway ${event.type} error ${
+            state === "disposed" ? "after dispose" : "during teardown"
+          }: ${event.message}`,
+        ),
+      );
+    };
+  const onGatewayError = (err: unknown) => {
+    const event = classifyDiscordGatewayEvent({
+      err,
+      isDisallowedIntentsError: params.isDisallowedIntentsError,
+    });
+    switch (phase) {
+      case "disposed":
+        logLateEvent("disposed")(event);
+        return;
+      case "active":
+        lifecycleHandler?.(event);
+        return;
+      case "teardown":
+        logLateEvent("teardown")(event);
+        return;
+      case "buffering":
+        pending.push(event);
+        return;
+    }
+  };
+  emitter.on("error", onGatewayError);
+
+  return {
+    emitter,
+    attachLifecycle: (handler) => {
+      lifecycleHandler = handler;
+      phase = "active";
+    },
+    detachLifecycle: () => {
+      lifecycleHandler = undefined;
+      phase = "teardown";
+    },
+    drainPending: (handler) => {
+      if (pending.length === 0) {
+        return "continue";
+      }
+      const queued = [...pending];
+      pending.length = 0;
+      for (const event of queued) {
+        if (handler(event) === "stop") {
+          return "stop";
+        }
+      }
+      return "continue";
+    },
+    dispose: () => {
+      if (phase === "disposed") {
+        return;
+      }
+      lifecycleHandler = undefined;
+      phase = "disposed";
+      pending.length = 0;
+    },
+  };
+}

package/src/monitor/inbound-context.ts

@@ -0,0 +1,95 @@
+import type { MsgContext } from "autobot/plugin-sdk/reply-runtime";
+import {
+  resolveDiscordMemberAllowed,
+  resolveDiscordOwnerAllowFrom,
+  type DiscordChannelConfigResolved,
+  type DiscordGuildEntryResolved,
+} from "./allow-list.js";
+
+type DiscordSupplementalContextSender = {
+  id?: string;
+  name?: string;
+  tag?: string;
+  memberRoleIds?: string[];
+};
+
+export function createDiscordSupplementalContextAccessChecker(params: {
+  channelConfig?: DiscordChannelConfigResolved | null;
+  guildInfo?: DiscordGuildEntryResolved | null;
+  allowNameMatching?: boolean;
+  isGuild: boolean;
+}) {
+  return (sender: DiscordSupplementalContextSender): boolean => {
+    if (!params.isGuild) {
+      return true;
+    }
+    return resolveDiscordMemberAllowed({
+      userAllowList: params.channelConfig?.users ?? params.guildInfo?.users,
+      roleAllowList: params.channelConfig?.roles ?? params.guildInfo?.roles,
+      memberRoleIds: sender.memberRoleIds ?? [],
+      userId: sender.id ?? "",
+      userName: sender.name,
+      userTag: sender.tag,
+      allowNameMatching: params.allowNameMatching,
+    });
+  };
+}
+
+export function buildDiscordGroupSystemPrompt(
+  channelConfig?: DiscordChannelConfigResolved | null,
+): string | undefined {
+  const systemPromptParts = [channelConfig?.systemPrompt?.trim() || null].filter(
+    (entry): entry is string => Boolean(entry),
+  );
+  return systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : undefined;
+}
+
+export function buildDiscordUntrustedContext(params: {
+  isGuild: boolean;
+  channelTopic?: string;
+}): MsgContext["UntrustedStructuredContext"] | undefined {
+  if (!params.isGuild) {
+    return undefined;
+  }
+  const entries: NonNullable<MsgContext["UntrustedStructuredContext"]> = [];
+  if (typeof params.channelTopic === "string" && params.channelTopic.trim().length > 0) {
+    entries.push({
+      label: "Discord channel metadata",
+      source: "discord",
+      type: "channel_metadata",
+      payload: {
+        topic: params.channelTopic.trim(),
+      },
+    });
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
+export function buildDiscordInboundAccessContext(params: {
+  channelConfig?: DiscordChannelConfigResolved | null;
+  guildInfo?: DiscordGuildEntryResolved | null;
+  sender: {
+    id: string;
+    name?: string;
+    tag?: string;
+  };
+  allowNameMatching?: boolean;
+  isGuild: boolean;
+  channelTopic?: string;
+}) {
+  return {
+    groupSystemPrompt: params.isGuild
+      ? buildDiscordGroupSystemPrompt(params.channelConfig)
+      : undefined,
+    untrustedContext: buildDiscordUntrustedContext({
+      isGuild: params.isGuild,
+      channelTopic: params.channelTopic,
+    }),
+    ownerAllowFrom: resolveDiscordOwnerAllowFrom({
+      channelConfig: params.channelConfig,
+      guildInfo: params.guildInfo,
+      sender: params.sender,
+      allowNameMatching: params.allowNameMatching,
+    }),
+  };
+}

package/src/monitor/inbound-dedupe.ts

@@ -0,0 +1,79 @@
+import { createClaimableDedupe, type ClaimableDedupe } from "autobot/plugin-sdk/persistent-dedupe";
+import type { DiscordMessageEvent } from "./listeners.js";
+import { resolveDiscordMessageChannelId } from "./message-utils.js";
+
+const RECENT_DISCORD_MESSAGE_TTL_MS = 5 * 60_000;
+const RECENT_DISCORD_MESSAGE_MAX = 5000;
+
+export function createDiscordInboundReplayGuard(): ClaimableDedupe {
+  return createClaimableDedupe({
+    ttlMs: RECENT_DISCORD_MESSAGE_TTL_MS,
+    memoryMaxSize: RECENT_DISCORD_MESSAGE_MAX,
+  });
+}
+
+export class DiscordRetryableInboundError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "DiscordRetryableInboundError";
+  }
+}
+
+export function buildDiscordInboundReplayKey(params: {
+  accountId: string;
+  data: DiscordMessageEvent;
+}): string | null {
+  const messageId = params.data.message?.id?.trim();
+  if (!messageId) {
+    return null;
+  }
+  const channelId = resolveDiscordMessageChannelId({
+    message: params.data.message,
+    eventChannelId: params.data.channel_id,
+  });
+  if (!channelId) {
+    return null;
+  }
+  return `${params.accountId}:${channelId}:${messageId}`;
+}
+
+export async function claimDiscordInboundReplay(params: {
+  replayKey?: string | null;
+  replayGuard: ClaimableDedupe;
+}): Promise<boolean> {
+  const replayKey = params.replayKey?.trim();
+  if (!replayKey) {
+    return true;
+  }
+  const claim = await params.replayGuard.claim(replayKey);
+  return claim.kind === "claimed";
+}
+
+export async function commitDiscordInboundReplay(params: {
+  replayKeys?: readonly (string | null | undefined)[];
+  replayGuard: ClaimableDedupe;
+}): Promise<void> {
+  const replayKeys = normalizeDiscordInboundReplayKeys(params.replayKeys);
+  await Promise.all(replayKeys.map((replayKey) => params.replayGuard.commit(replayKey)));
+}
+
+export function releaseDiscordInboundReplay(params: {
+  replayKeys?: readonly (string | null | undefined)[];
+  replayGuard: ClaimableDedupe;
+  error?: unknown;
+}): void {
+  const replayKeys = normalizeDiscordInboundReplayKeys(params.replayKeys);
+  replayKeys.forEach((replayKey) => params.replayGuard.release(replayKey, { error: params.error }));
+}
+
+function normalizeDiscordInboundReplayKeys(
+  replayKeys?: readonly (string | null | undefined)[],
+): string[] {
+  return [
+    ...new Set(
+      (replayKeys ?? [])
+        .map((replayKey) => replayKey?.trim())
+        .filter((replayKey): replayKey is string => Boolean(replayKey)),
+    ),
+  ];
+}

package/src/monitor/inbound-job.ts

@@ -0,0 +1,118 @@
+import {
+  resolveDiscordChannelIdSafe,
+  resolveDiscordChannelInfoSafe,
+  resolveDiscordChannelNameSafe,
+  resolveDiscordChannelParentSafe,
+} from "./channel-access.js";
+import type { DiscordMessagePreflightContext } from "./message-handler.preflight.types.js";
+
+type DiscordInboundJobRuntimeField =
+  | "runtime"
+  | "abortSignal"
+  | "guildHistories"
+  | "client"
+  | "threadBindings"
+  | "discordRestFetch";
+
+type DiscordInboundJobRuntime = Pick<DiscordMessagePreflightContext, DiscordInboundJobRuntimeField>;
+
+type DiscordInboundJobPayload = Omit<DiscordMessagePreflightContext, DiscordInboundJobRuntimeField>;
+
+export type DiscordInboundJob = {
+  queueKey: string;
+  payload: DiscordInboundJobPayload;
+  runtime: DiscordInboundJobRuntime;
+  replayKeys?: string[];
+};
+
+export function resolveDiscordInboundJobQueueKey(ctx: DiscordMessagePreflightContext): string {
+  const sessionKey = ctx.route.sessionKey?.trim();
+  if (sessionKey) {
+    return sessionKey;
+  }
+  const baseSessionKey = ctx.baseSessionKey?.trim();
+  if (baseSessionKey) {
+    return baseSessionKey;
+  }
+  return ctx.messageChannelId;
+}
+
+export function buildDiscordInboundJob(
+  ctx: DiscordMessagePreflightContext,
+  options?: { replayKeys?: readonly string[] },
+): DiscordInboundJob {
+  const {
+    runtime,
+    abortSignal,
+    guildHistories,
+    client,
+    threadBindings,
+    discordRestFetch,
+    message,
+    data,
+    threadChannel,
+    ...payload
+  } = ctx;
+
+  const sanitizedMessage = sanitizeDiscordInboundMessage(message);
+  return {
+    queueKey: resolveDiscordInboundJobQueueKey(ctx),
+    payload: {
+      ...payload,
+      message: sanitizedMessage,
+      data: {
+        ...data,
+        message: sanitizedMessage,
+      },
+      threadChannel: normalizeDiscordThreadChannel(threadChannel),
+    },
+    runtime: {
+      runtime,
+      abortSignal,
+      guildHistories,
+      client,
+      threadBindings,
+      discordRestFetch,
+    },
+    replayKeys: options?.replayKeys ? [...options.replayKeys] : undefined,
+  };
+}
+
+export function materializeDiscordInboundJob(
+  job: DiscordInboundJob,
+  abortSignal?: AbortSignal,
+): DiscordMessagePreflightContext {
+  return {
+    ...job.payload,
+    ...job.runtime,
+    abortSignal: abortSignal ?? job.runtime.abortSignal,
+  };
+}
+
+function sanitizeDiscordInboundMessage<T extends object>(message: T): T {
+  const descriptors = Object.getOwnPropertyDescriptors(message);
+  delete descriptors.channel;
+  return Object.create(Object.getPrototypeOf(message), descriptors) as T;
+}
+
+function normalizeDiscordThreadChannel(
+  threadChannel: DiscordMessagePreflightContext["threadChannel"],
+): DiscordMessagePreflightContext["threadChannel"] {
+  if (!threadChannel) {
+    return null;
+  }
+  const channelInfo = resolveDiscordChannelInfoSafe(threadChannel);
+  const parent = resolveDiscordChannelParentSafe(threadChannel);
+  return {
+    id: threadChannel.id,
+    name: channelInfo.name,
+    parentId: channelInfo.parentId,
+    parent: parent
+      ? {
+          id: resolveDiscordChannelIdSafe(parent),
+          name: resolveDiscordChannelNameSafe(parent),
+        }
+      : undefined,
+    ownerId: channelInfo.ownerId,
+  };
+}

package/src/monitor/listeners.queue.ts

@@ -0,0 +1,91 @@
+import { createSubsystemLogger, formatDurationSeconds } from "autobot/plugin-sdk/runtime-env";
+
+export type DiscordListenerLogger = ReturnType<
+  typeof import("autobot/plugin-sdk/runtime-env").createSubsystemLogger
+>;
+
+const DISCORD_SLOW_LISTENER_THRESHOLD_MS = 30_000;
+
+export const discordEventQueueLog = createSubsystemLogger("discord/event-queue");
+
+function formatListenerContextValue(value: unknown): string | null {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return null;
+}
+
+function formatListenerContextSuffix(context?: Record<string, unknown>): string {
+  if (!context) {
+    return "";
+  }
+  const entries = Object.entries(context).flatMap(([key, value]) => {
+    const formatted = formatListenerContextValue(value);
+    return formatted ? [`${key}=${formatted}`] : [];
+  });
+  if (entries.length === 0) {
+    return "";
+  }
+  return ` (${entries.join(" ")})`;
+}
+
+function logSlowDiscordListener(params: {
+  logger: DiscordListenerLogger | undefined;
+  listener: string;
+  event: string;
+  durationMs: number;
+  context?: Record<string, unknown>;
+}) {
+  if (params.durationMs < DISCORD_SLOW_LISTENER_THRESHOLD_MS) {
+    return;
+  }
+  const duration = formatDurationSeconds(params.durationMs, {
+    decimals: 1,
+    unit: "seconds",
+  });
+  const message = `Slow listener detected: ${params.listener} took ${duration} for event ${params.event}`;
+  const logger = params.logger ?? discordEventQueueLog;
+  logger.warn("Slow listener detected", {
+    listener: params.listener,
+    event: params.event,
+    durationMs: params.durationMs,
+    duration,
+    ...params.context,
+    consoleMessage: `${message}${formatListenerContextSuffix(params.context)}`,
+  });
+}
+
+export async function runDiscordListenerWithSlowLog(params: {
+  logger: DiscordListenerLogger | undefined;
+  listener: string;
+  event: string;
+  run: () => Promise<void>;
+  context?: Record<string, unknown>;
+  onError?: (err: unknown) => void;
+}) {
+  const startedAt = Date.now();
+  try {
+    await params.run();
+  } catch (err) {
+    if (params.onError) {
+      params.onError(err);
+      return;
+    }
+    throw err;
+  } finally {
+    logSlowDiscordListener({
+      logger: params.logger,
+      listener: params.listener,
+      event: params.event,
+      durationMs: Date.now() - startedAt,
+      context: params.context,
+    });
+  }
+}