Add automod event logging to user mod threads

vcarl · claude · vcarl · commit 2ca7045cfa5b · 2026-01-13T19:24:19.000-05:00
- Add AutoModerationExecution intent to Discord client
- Handle AutoModerationActionExecution events in automod.ts
- Create reportAutomod() function for cases where message isn't available
- Modify escalationControls() to accept userId string directly
- Add automod enum value to ReportReasons

When automod triggers, the bot now logs the action to the user's mod
thread. If the message is still available, it uses the full reportUser()
flow. If blocked/deleted by automod, it uses a fallback that logs
available context (rule name, matched content, action type).

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/app/discord/automod.ts b/app/discord/automod.ts
@@ -1,9 +1,15 @@
-import { Events, type Client } from "discord.js";
+import {
+  AutoModerationActionType,
+  Events,
+  type AutoModerationActionExecution,
+  type Client,
+} from "discord.js";
 
 import { isStaff } from "#~/helpers/discord";
 import { isSpam } from "#~/helpers/isSpam";
 import { featureStats } from "#~/helpers/metrics";
-import { reportUser } from "#~/helpers/modLog";
+import { reportAutomod, reportUser } from "#~/helpers/modLog";
+import { log } from "#~/helpers/observability";
 import {
   markMessageAsDeleted,
   ReportReasons,
@@ -13,7 +19,99 @@ import { client } from "./client.server";
 
 const AUTO_SPAM_THRESHOLD = 3;
 
+async function handleAutomodAction(execution: AutoModerationActionExecution) {
+  const {
+    guild,
+    userId,
+    channelId,
+    messageId,
+    content,
+    action,
+    matchedContent,
+    matchedKeyword,
+    autoModerationRule,
+  } = execution;
+
+  // Only log actions that actually affected a message (BlockMessage, SendAlertMessage)
+  // Skip Timeout actions as they don't have associated message content
+  if (action.type === AutoModerationActionType.Timeout) {
+    log("debug", "Automod", "Skipping timeout action (no message to log)", {
+      userId,
+      guildId: guild.id,
+      ruleId: autoModerationRule?.name,
+    });
+    return;
+  }
+
+  log("info", "Automod", "Automod action executed", {
+    userId,
+    guildId: guild.id,
+    channelId,
+    messageId,
+    actionType: action.type,
+    ruleName: autoModerationRule?.name,
+    matchedKeyword,
+  });
+
+  // Try to fetch the message if we have a messageId
+  // The message may have been deleted by automod before we can fetch it
+  if (messageId && channelId) {
+    try {
+      const channel = await guild.channels.fetch(channelId);
+      if (channel?.isTextBased() && "messages" in channel) {
+        const message = await channel.messages.fetch(messageId);
+        // We have the full message, use reportUser
+        await reportUser({
+          reason: ReportReasons.automod,
+          message,
+          staff: client.user ?? false,
+          extra: `Rule: ${autoModerationRule?.name ?? "Unknown"}\nMatched: ${matchedKeyword ?? matchedContent ?? "Unknown"}`,
+        });
+        return;
+      }
+    } catch (e) {
+      log(
+        "debug",
+        "Automod",
+        "Could not fetch message, using fallback logging",
+        {
+          messageId,
+          error: e instanceof Error ? e.message : String(e),
+        },
+      );
+    }
+  }
+
+  // Fallback: message was blocked/deleted or we couldn't fetch it
+  // Use reportAutomod which doesn't require a Message object
+  const user = await guild.client.users.fetch(userId);
+  await reportAutomod({
+    guild,
+    user,
+    content: content ?? matchedContent ?? "[Content not available]",
+    channelId: channelId ?? undefined,
+    messageId: messageId ?? undefined,
+    ruleName: autoModerationRule?.name ?? "Unknown rule",
+    matchedKeyword: matchedKeyword ?? matchedContent ?? undefined,
+    actionType: action.type,
+  });
+}
+
 export default async (bot: Client) => {
+  // Handle Discord's built-in automod actions
+  bot.on(Events.AutoModerationActionExecution, async (execution) => {
+    try {
+      await handleAutomodAction(execution);
+    } catch (e) {
+      log("error", "Automod", "Failed to handle automod action", {
+        error: e instanceof Error ? e.message : String(e),
+        userId: execution.userId,
+        guildId: execution.guild.id,
+      });
+    }
+  });
+
+  // Handle our custom spam detection
   bot.on(Events.MessageCreate, async (msg) => {
     if (msg.author.id === bot.user?.id || !msg.guild) return;
 
diff --git a/app/discord/client.server.ts b/app/discord/client.server.ts
@@ -13,6 +13,7 @@ export const client = new Client({
     GatewayIntentBits.GuildMessageReactions,
     GatewayIntentBits.DirectMessages,
     GatewayIntentBits.DirectMessageReactions,
+    GatewayIntentBits.AutoModerationExecution,
   ],
   partials: [Partials.Message, Partials.Channel, Partials.Reaction],
 });
diff --git a/app/helpers/escalate.tsx b/app/helpers/escalate.tsx
@@ -7,10 +7,13 @@ import {
 } from "discord.js";
 
 export async function escalationControls(
-  reportedMessage: Message,
+  reportedMessageOrUserId: Message | string,
   thread: ThreadChannel,
 ) {
-  const reportedUserId = reportedMessage.author.id;
+  const reportedUserId =
+    typeof reportedMessageOrUserId === "string"
+      ? reportedMessageOrUserId
+      : reportedMessageOrUserId.author.id;
 
   await thread.send({
     content: "Moderator controls",
diff --git a/app/helpers/modLog.ts b/app/helpers/modLog.ts
@@ -1,10 +1,12 @@
 import { formatDistanceToNowStrict } from "date-fns";
 import {
+  AutoModerationActionType,
   ChannelType,
   messageLink,
   MessageReferenceType,
   type AnyThreadChannel,
   type APIEmbed,
+  type Guild,
   type Message,
   type MessageCreateOptions,
   type TextChannel,
@@ -45,6 +47,7 @@ const ReadableReasons: Record<ReportReasons, string> = {
   [ReportReasons.track]: "tracked",
   [ReportReasons.modResolution]: "Mod vote resolved",
   [ReportReasons.spam]: "detected as spam",
+  [ReportReasons.automod]: "detected by automod",
 };
 
 const isForwardedMessage = (message: Message): boolean => {
@@ -118,6 +121,167 @@ const getOrCreateUserThread = async (message: Message, user: User) => {
   return thread;
 };
 
+export interface AutomodReport {
+  guild: Guild;
+  user: User;
+  content: string;
+  channelId?: string;
+  messageId?: string;
+  ruleName: string;
+  matchedKeyword?: string;
+  actionType: AutoModerationActionType;
+}
+
+const ActionTypeLabels: Record<AutoModerationActionType, string> = {
+  [AutoModerationActionType.BlockMessage]: "blocked message",
+  [AutoModerationActionType.SendAlertMessage]: "sent alert",
+  [AutoModerationActionType.Timeout]: "timed out user",
+  [AutoModerationActionType.BlockMemberInteraction]: "blocked interaction",
+};
+
+const getOrCreateUserThreadForAutomod = async (guild: Guild, user: User) => {
+  // Check if we already have a thread for this user
+  const existingThread = await getUserThread(user.id, guild.id);
+
+  if (existingThread) {
+    try {
+      // Verify the thread still exists and is accessible
+      const thread = await guild.channels.fetch(existingThread.thread_id);
+      if (thread?.isThread()) {
+        return thread;
+      }
+    } catch (error) {
+      log(
+        "warn",
+        "getOrCreateUserThreadForAutomod",
+        "Existing thread not accessible, will create new one",
+        { error },
+      );
+    }
+  }
+
+  // Create new thread and store in database
+  const { modLog: modLogId } = await fetchSettings(guild.id, [SETTINGS.modLog]);
+  const modLog = await guild.channels.fetch(modLogId);
+  if (!modLog || modLog.type !== ChannelType.GuildText) {
+    throw new Error("Invalid mod log channel");
+  }
+
+  // Create freestanding private thread
+  const thread = await makeUserThread(modLog, user);
+  await escalationControls(user.id, thread);
+
+  // Store or update the thread reference
+  if (existingThread) {
+    await updateUserThread(user.id, guild.id, thread.id);
+  } else {
+    await createUserThread(user.id, guild.id, thread.id);
+  }
+
+  return thread;
+};
+
+/**
+ * Reports an automod action when we don't have a full Message object.
+ * Used when Discord's automod blocks/deletes a message before we can fetch it.
+ */
+export const reportAutomod = async ({
+  guild,
+  user,
+  content,
+  channelId,
+  messageId,
+  ruleName,
+  matchedKeyword,
+  actionType,
+}: AutomodReport): Promise<void> => {
+  log("info", "reportAutomod", `Automod triggered for ${user.username}`, {
+    userId: user.id,
+    guildId: guild.id,
+    ruleName,
+    actionType,
+  });
+
+  // Get or create persistent user thread
+  const thread = await getOrCreateUserThreadForAutomod(guild, user);
+
+  // Get mod log for forwarding
+  const { modLog, moderator } = await fetchSettings(guild.id, [
+    SETTINGS.modLog,
+    SETTINGS.moderator,
+  ]);
+
+  // Construct the log message
+  const channelMention = channelId ? `<#${channelId}>` : "Unknown channel";
+  const actionLabel = ActionTypeLabels[actionType] ?? "took action";
+
+  const logContent = truncateMessage(`**Automod ${actionLabel}**
+<@${user.id}> (${user.username}) in ${channelMention}
+-# Rule: ${ruleName}${matchedKeyword ? ` · Matched: \`${matchedKeyword}\`` : ""}`).trim();
+
+  // Send log to thread
+  const [logMessage] = await Promise.all([
+    thread.send({
+      content: logContent,
+      allowedMentions: { roles: moderator ? [moderator] : [] },
+    }),
+    thread.send({
+      content: quoteAndEscape(content).trim(),
+      allowedMentions: {},
+    }),
+  ]);
+
+  // Record to database if we have a messageId
+  if (messageId) {
+    await retry(3, async () => {
+      const result = await recordReport({
+        reportedMessageId: messageId,
+        reportedChannelId: channelId ?? "unknown",
+        reportedUserId: user.id,
+        guildId: guild.id,
+        logMessageId: logMessage.id,
+        logChannelId: thread.id,
+        reason: ReportReasons.automod,
+        extra: `Rule: ${ruleName}`,
+      });
+
+      if (!result.wasInserted) {
+        log(
+          "warn",
+          "reportAutomod",
+          "duplicate detected at database level, retrying check",
+        );
+        throw new Error("Race condition detected in recordReport, retrying…");
+      }
+
+      return result;
+    });
+  }
+
+  // Forward to mod log
+  await logMessage.forward(modLog).catch((e) => {
+    log("error", "reportAutomod", "failed to forward to modLog", { error: e });
+  });
+
+  // Send summary to parent channel
+  if (thread.parent?.isSendable()) {
+    const singleLine = content.slice(0, 80).replaceAll("\n", "\\n ");
+    const truncatedContent =
+      singleLine.length > 80 ? `${singleLine.slice(0, 80)}…` : singleLine;
+
+    await thread.parent
+      .send({
+        allowedMentions: {},
+        content: `> ${escapeDisruptiveContent(truncatedContent)}\n-# [Automod: ${ruleName}](${messageLink(logMessage.channelId, logMessage.id)})`,
+      })
+      .catch((e) => {
+        log("error", "reportAutomod", "failed to send summary to parent", {
+          error: e,
+        });
+      });
+  }
+};
+
 // const warningMessages = new ();
 export const reportUser = async ({
   reason,
diff --git a/app/models/reportedMessages.server.ts b/app/models/reportedMessages.server.ts
@@ -18,6 +18,7 @@ export const enum ReportReasons {
   track = "track",
   modResolution = "modResolution",
   spam = "spam",
+  automod = "automod",
 }
 
 export async function recordReport(data: {
diff --git a/notes/2026-01-13_1_automod-logging.md b/notes/2026-01-13_1_automod-logging.md
@@ -0,0 +1,40 @@
+# Automod Event Logging
+
+Added functionality to log Discord's built-in automod trigger events to user mod threads.
+
+## Changes
+
+### Client Intent
+Added `GatewayIntentBits.AutoModerationExecution` to `client.server.ts` to receive automod events.
+
+### Event Handler (`automod.ts`)
+- Added handler for `Events.AutoModerationActionExecution`
+- Skips `Timeout` actions (no message content to log)
+- Tries to fetch the message if `messageId` exists
+  - If successful: uses existing `reportUser()` with `ReportReasons.automod`
+  - If failed (message blocked/deleted): uses new `reportAutomod()` fallback
+
+### New Function (`modLog.ts`)
+Created `reportAutomod()` for cases where we don't have a full `Message` object:
+- Gets/creates user thread (reusing pattern from `getOrCreateUserThread`)
+- Logs automod-specific info: rule name, matched keyword, action type
+- Records to database if `messageId` available
+- Forwards to mod log and sends summary to parent channel
+
+Also modified `escalationControls()` in `escalate.tsx` to accept either a `Message` or just a `userId` string.
+
+## Design Decisions
+
+1. **Two-path approach**: Try to fetch the message first for full context, fallback to minimal logging if unavailable. This maximizes information captured.
+
+2. **Skip Timeout actions**: These don't have associated message content worth logging. The timeout itself is visible in Discord's audit log.
+
+3. **No MESSAGE_CONTENT intent**: The `content` field in automod events requires privileged intent. We work with what's available (`matchedContent`, `matchedKeyword`).
+
+4. **Database recording conditional on messageId**: If automod blocked the message before sending, there's no message ID to record. We still log to the thread for visibility.
+
+## Related Files
+- `app/discord/client.server.ts` - intent added
+- `app/discord/automod.ts` - event handler
+- `app/helpers/modLog.ts` - `reportAutomod()` function
+- `app/helpers/escalate.tsx` - signature update

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ export const enum ReportReasons {`
`18`	`18`	`track = "track",`
`19`	`19`	`modResolution = "modResolution",`
`20`	`20`	`spam = "spam",`
	`21`	`+ automod = "automod",`
`21`	`22`	`}`
`22`	`23`
`23`	`24`	`export async function recordReport(data: {`