@hybridaione/hybridclaw 0.2.3 → 0.2.7

package/src/channels/discord/delivery.ts

@@ -1,9 +1,25 @@
-import { AttachmentBuilder, type ChatInputCommandInteraction, type Message as DiscordMessage } from 'discord.js';
+import type {
+  AttachmentBuilder,
+  ChatInputCommandInteraction,
+  Message as DiscordMessage,
+} from 'discord.js';
 
 import { chunkMessage } from '../../chunk.js';
-import { rewriteUserMentions, type MentionLookup } from './mentions.js';
+import {
+  DISCORD_MAX_LINES_PER_MESSAGE,
+  DISCORD_TEXT_CHUNK_LIMIT,
+} from '../../config.js';
+import {
+  getHumanDelayMs,
+  type HumanDelayConfig,
+  sleep,
+} from './human-delay.js';
+import { type MentionLookup, rewriteUserMentions } from './mentions.js';
 
-export type DiscordRetryFn = <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+export type DiscordRetryFn = <T>(
+  label: string,
+  fn: () => Promise<T>,
+) => Promise<T>;
 
 export function buildResponseText(text: string, toolsUsed?: string[]): string {
   let body = text;
@@ -27,12 +43,19 @@ export function prepareChunkedPayloads(
   files?: AttachmentBuilder[],
   mentionLookup?: MentionLookup,
 ): { content: string; files?: AttachmentBuilder[] }[] {
-  const prepared = mentionLookup ? rewriteUserMentions(text, mentionLookup) : text;
-  const chunks = chunkMessage(prepared, { maxChars: 1_900, maxLines: 20 });
+  const prepared = mentionLookup
+    ? rewriteUserMentions(text, mentionLookup)
+    : text;
+  const chunks = chunkMessage(prepared, {
+    maxChars: Math.max(200, Math.min(2_000, DISCORD_TEXT_CHUNK_LIMIT)),
+    maxLines: Math.max(4, Math.min(200, DISCORD_MAX_LINES_PER_MESSAGE)),
+  });
   const safeChunks = chunks.length > 0 ? chunks : ['(no content)'];
   return safeChunks.map((content, i) => ({
     content,
-    ...(i === safeChunks.length - 1 && files && files.length > 0 ? { files } : {}),
+    ...(i === safeChunks.length - 1 && files && files.length > 0
+      ? { files }
+      : {}),
   }));
 }
 
@@ -42,6 +65,7 @@ export async function sendChunkedReply(params: {
   withRetry: DiscordRetryFn;
   files?: AttachmentBuilder[];
   mentionLookup?: MentionLookup;
+  humanDelay?: HumanDelayConfig;
 }): Promise<void> {
   const payloads = prepareChunkedPayloads(
     params.text,
@@ -52,9 +76,20 @@ export async function sendChunkedReply(params: {
     if (i === 0) {
       await params.withRetry('reply', () => params.msg.reply(payloads[i]));
     } else {
-      await params.withRetry('send', () => (params.msg.channel as unknown as {
-        send: (next: { content: string; files?: AttachmentBuilder[] }) => Promise<void>;
-      }).send(payloads[i]));
+      const delayMs = getHumanDelayMs(params.humanDelay);
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+      await params.withRetry('send', () =>
+        (
+          params.msg.channel as unknown as {
+            send: (next: {
+              content: string;
+              files?: AttachmentBuilder[];
+            }) => Promise<void>;
+          }
+        ).send(payloads[i]),
+      );
     }
   }
 }
@@ -65,14 +100,24 @@ export async function sendChunkedDirectReply(params: {
   withRetry: DiscordRetryFn;
   files?: AttachmentBuilder[];
   mentionLookup?: MentionLookup;
+  humanDelay?: HumanDelayConfig;
 }): Promise<void> {
   const payloads = prepareChunkedPayloads(
     params.text,
     params.files,
     params.mentionLookup,
   );
-  const dm = await params.withRetry('dm-open', () => params.msg.author.createDM());
-  for (const payload of payloads) {
+  const dm = await params.withRetry('dm-open', () =>
+    params.msg.author.createDM(),
+  );
+  for (let i = 0; i < payloads.length; i += 1) {
+    if (i > 0) {
+      const delayMs = getHumanDelayMs(params.humanDelay);
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+    }
+    const payload = payloads[i];
     await params.withRetry('dm-send', () => dm.send(payload));
   }
 }
@@ -88,12 +133,18 @@ export async function sendChunkedInteractionReply(params: {
     const payload = { ...payloads[i], ephemeral: true };
     if (i === 0) {
       if (params.interaction.replied || params.interaction.deferred) {
-        await params.withRetry('interaction-followup', () => params.interaction.followUp(payload));
+        await params.withRetry('interaction-followup', () =>
+          params.interaction.followUp(payload),
+        );
       } else {
-        await params.withRetry('interaction-reply', () => params.interaction.reply(payload));
+        await params.withRetry('interaction-reply', () =>
+          params.interaction.reply(payload),
+        );
       }
       continue;
     }
-    await params.withRetry('interaction-followup', () => params.interaction.followUp(payload));
+    await params.withRetry('interaction-followup', () =>
+      params.interaction.followUp(payload),
+    );
   }
 }

package/src/channels/discord/human-delay.ts

@@ -0,0 +1,48 @@
+export interface HumanDelayConfig {
+  mode: 'off' | 'natural' | 'custom';
+  minMs?: number;
+  maxMs?: number;
+}
+
+export interface ResolvedHumanDelayConfig {
+  mode: 'off' | 'natural' | 'custom';
+  minMs: number;
+  maxMs: number;
+}
+
+export const DEFAULT_HUMAN_DELAY_MIN_MS = 800;
+export const DEFAULT_HUMAN_DELAY_MAX_MS = 2_500;
+
+export function resolveHumanDelayConfig(
+  config?: HumanDelayConfig,
+): ResolvedHumanDelayConfig {
+  const mode = config?.mode ?? 'natural';
+  const minMs = Math.max(
+    0,
+    Math.floor(config?.minMs ?? DEFAULT_HUMAN_DELAY_MIN_MS),
+  );
+  const rawMax = Math.max(
+    0,
+    Math.floor(config?.maxMs ?? DEFAULT_HUMAN_DELAY_MAX_MS),
+  );
+  const maxMs = Math.max(minMs, rawMax);
+  return {
+    mode,
+    minMs,
+    maxMs,
+  };
+}
+
+export function getHumanDelayMs(config?: HumanDelayConfig): number {
+  const resolved = resolveHumanDelayConfig(config);
+  if (resolved.mode === 'off') return 0;
+  if (resolved.maxMs <= resolved.minMs) return resolved.minMs;
+  const span = resolved.maxMs - resolved.minMs + 1;
+  return resolved.minMs + Math.floor(Math.random() * span);
+}
+
+export async function sleep(ms: number): Promise<void> {
+  const waitMs = Math.max(0, Math.floor(ms));
+  if (waitMs <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, waitMs));
+}

package/src/channels/discord/inbound.ts

@@ -5,8 +5,79 @@ export interface ParsedCommand {
 }
 
 export type DiscordGuildMessageMode = 'off' | 'mention' | 'free';
+export type DiscordCommandAccessMode = 'public' | 'restricted';
+const KNOWN_SUBCOMMANDS = new Set([
+  'bot',
+  'rag',
+  'model',
+  'status',
+  'approve',
+  'usage',
+  'export',
+  'sessions',
+  'audit',
+  'schedule',
+  'channel',
+  'ralph',
+  'clear',
+  'help',
+]);
 
-export function stripBotMentions(text: string, botMentionRegex: RegExp | null): string {
+const GREETING_ONLY_RE =
+  /^(hi|hey|hello|yo|sup|thanks|thank you|thx|ok|okay|got it|roger|cool)[!. ]*$/i;
+const FREE_MODE_ACK_ONLY_RE =
+  /^(ok|okay|thanks|thank you|thx|ty|cool|nice|got it|roger|sounds good|sgtm|lol|lmao)[!. ]*$/i;
+const FREE_MODE_QUESTION_START_RE =
+  /^(?:hey|hi|hello|yo|hmm|hm|well)?[\s,:-]*(?:can|could|would|will|should|do|does|did|is|are|am|how|what|why|when|where|who|which)\b/i;
+const FREE_MODE_REQUEST_VERB_RE =
+  /\b(?:please|pls|help|explain|review|check|debug|fix|summari[sz]e|create|write|show|tell|give|generate|compare|analy[sz]e)\b/i;
+const FREE_MODE_PROBLEM_SIGNAL_RE =
+  /\b(?:error|failed|failure|exception|stack trace|broken|issue|not working|doesn't work|cannot|can't|wont|won't)\b/i;
+const URL_ONLY_RE = /^https?:\/\/\S+$/i;
+const FREE_MODE_CHANNEL_ADDRESS_RE =
+  /\b(?:all|everyone|anyone|team|folks|guys|channel|chat|alle|zusammen|jemand)\b/i;
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function normalizeAlias(raw: string): string {
+  return raw.trim().replace(/^@+/, '').toLowerCase();
+}
+
+export function hasLooseBotMention(
+  content: string,
+  botAliases: string[],
+): boolean {
+  const normalized = content.trim().toLowerCase();
+  if (!normalized) return false;
+
+  for (const rawAlias of botAliases) {
+    const alias = normalizeAlias(rawAlias);
+    if (!alias || alias.length < 2) continue;
+    if (!/^[\p{L}\p{N}._-]+$/u.test(alias)) continue;
+
+    const escapedAlias = escapeRegex(alias);
+    const mentionRe = new RegExp(
+      `(?:^|[^\\p{L}\\p{N}_-])${escapedAlias}(?=$|[^\\p{L}\\p{N}_-])`,
+      'iu',
+    );
+    if (mentionRe.test(normalized)) return true;
+  }
+
+  return false;
+}
+
+export function isAddressedToChannel(content: string): boolean {
+  const normalized = content.trim();
+  if (!normalized) return false;
+  return FREE_MODE_CHANNEL_ADDRESS_RE.test(normalized);
+}
+
+export function stripBotMentions(
+  text: string,
+  botMentionRegex: RegExp | null,
+): string {
   if (!botMentionRegex) return text;
   return text.replace(botMentionRegex, '').trim();
 }
@@ -32,7 +103,22 @@ export function hasPrefixInvocation(
   return text.startsWith(prefix);
 }
 
-export function buildSessionIdFromContext(guildId: string | null, channelId: string, userId: string): string {
+export function hasSlashCommandInvocation(
+  content: string,
+  botMentionRegex: RegExp | null,
+): boolean {
+  const text = stripBotMentions(content, botMentionRegex).trim();
+  if (!text.startsWith('/')) return false;
+  const token = text.slice(1).split(/\s+/)[0]?.toLowerCase() || '';
+  if (!token) return false;
+  return KNOWN_SUBCOMMANDS.has(token);
+}
+
+export function buildSessionIdFromContext(
+  guildId: string | null,
+  channelId: string,
+  userId: string,
+): string {
   return guildId ? `${guildId}:${channelId}` : `dm:${userId}`;
 }
 
@@ -44,17 +130,99 @@ export function parseCommand(
   let text = stripBotMentions(content, botMentionRegex);
   if (text.startsWith(prefix)) {
     text = text.slice(prefix.length).trim();
+  } else if (text.startsWith('/')) {
+    text = text.slice(1).trim();
   }
 
   const parts = text.split(/\s+/);
-  const subcommands = ['bot', 'rag', 'model', 'sessions', 'audit', 'schedule', 'channel', 'clear', 'help'];
-  if (parts.length > 0 && subcommands.includes(parts[0].toLowerCase())) {
-    return { isCommand: true, command: parts[0].toLowerCase(), args: parts.slice(1) };
+  if (parts.length > 0 && KNOWN_SUBCOMMANDS.has(parts[0].toLowerCase())) {
+    return {
+      isCommand: true,
+      command: parts[0].toLowerCase(),
+      args: parts.slice(1),
+    };
   }
 
   return { isCommand: false, command: '', args: [] };
 }
 
+export function shouldSuppressAutoReply(
+  content: string,
+  suppressPatterns?: string[],
+): boolean {
+  const normalized = content.trim().toLowerCase();
+  if (!normalized) return false;
+  if (GREETING_ONLY_RE.test(normalized)) return true;
+  if (!suppressPatterns || suppressPatterns.length === 0) return false;
+  return suppressPatterns.some((pattern) => {
+    const needle = pattern.trim().toLowerCase();
+    if (!needle) return false;
+    return normalized.includes(needle);
+  });
+}
+
+export function shouldSkipFreeReplyBecauseOtherUsersMentioned(params: {
+  guildMessageMode: DiscordGuildMessageMode;
+  hasBotMention: boolean;
+  hasPrefixInvocation: boolean;
+  botUserId: string | null;
+  mentionedUserIds: string[];
+}): boolean {
+  if (params.guildMessageMode !== 'free') return false;
+  if (params.hasBotMention) return false;
+  if (params.hasPrefixInvocation) return false;
+  if (params.mentionedUserIds.length === 0) return false;
+
+  const botId = params.botUserId?.trim() || '';
+  return params.mentionedUserIds.some((userId) => userId !== botId);
+}
+
+export function shouldReplyInFreeMode(params: {
+  guildMessageMode: DiscordGuildMessageMode;
+  content: string;
+  hasBotMention: boolean;
+  hasLooseBotMention?: boolean;
+  isAddressedToChannel?: boolean;
+  hasPrefixInvocation: boolean;
+  isReplyToBot: boolean;
+  hasAttachments: boolean;
+}): boolean {
+  if (params.guildMessageMode !== 'free') return true;
+  if (params.hasPrefixInvocation) return true;
+  if (params.hasBotMention) return true;
+  if (params.hasLooseBotMention) return true;
+  if (params.isReplyToBot) return true;
+  if (params.hasAttachments) return true;
+
+  const normalized = params.content.trim();
+  if (!normalized) return false;
+  if (FREE_MODE_ACK_ONLY_RE.test(normalized)) return false;
+  if (URL_ONLY_RE.test(normalized)) return false;
+  if (params.isAddressedToChannel) return true;
+  if (normalized.includes('?')) return true;
+  if (FREE_MODE_QUESTION_START_RE.test(normalized)) return true;
+  if (FREE_MODE_REQUEST_VERB_RE.test(normalized)) return true;
+  if (FREE_MODE_PROBLEM_SIGNAL_RE.test(normalized)) return true;
+  if (normalized.includes('```') || /`[^`]+`/.test(normalized)) return true;
+  return false;
+}
+
+export function isAuthorizedCommandUser(params: {
+  mode: DiscordCommandAccessMode;
+  userId: string;
+  allowedUserIds: string[];
+  legacyCommandUserId?: string;
+}): boolean {
+  if (params.mode === 'public') return true;
+  const allowed = new Set(
+    params.allowedUserIds.map((entry) => entry.trim()).filter(Boolean),
+  );
+  const legacy = (params.legacyCommandUserId || '').trim();
+  if (legacy) allowed.add(legacy);
+  if (allowed.size === 0) return false;
+  return allowed.has(params.userId);
+}
+
 export function isTrigger(params: {
   content: string;
   isDm: boolean;
@@ -64,15 +232,29 @@ export function isTrigger(params: {
   prefix: string;
   botMentionRegex: RegExp | null;
   hasBotMention: boolean;
+  suppressPatterns?: string[];
 }): boolean {
+  const stripped = stripBotMentions(params.content, params.botMentionRegex);
+  const hasPrefixed = hasPrefixInvocation(
+    params.content,
+    params.botMentionRegex,
+    params.prefix,
+  );
+  const hasSlash = hasSlashCommandInvocation(
+    params.content,
+    params.botMentionRegex,
+  );
+
   if (params.commandsOnly) {
-    return hasPrefixInvocation(params.content, params.botMentionRegex, params.prefix);
+    return hasPrefixed || hasSlash;
   }
+  if (hasPrefixed || hasSlash) return true;
+  if (shouldSuppressAutoReply(stripped, params.suppressPatterns)) return false;
   if (params.isDm) return true;
-  if (hasPrefixInvocation(params.content, params.botMentionRegex, params.prefix)) return true;
   if (params.guildMessageMode === 'off') return false;
   if (params.guildMessageMode === 'free') return true;
-  if (params.respondToAllMessages) return true;
+  // Keep `respondToAllMessages` consumed for compatibility; mode resolution decides guild behavior.
+  void params.respondToAllMessages;
   if (params.hasBotMention) return true;
   return false;
 }

package/src/channels/discord/mentions.ts

@@ -21,7 +21,11 @@ export function normalizeMentionAlias(raw: string | null | undefined): string {
   return lowered;
 }
 
-export function addMentionAlias(lookup: MentionLookup, rawAlias: string | null | undefined, userId: string): void {
+export function addMentionAlias(
+  lookup: MentionLookup,
+  rawAlias: string | null | undefined,
+  userId: string,
+): void {
   const alias = normalizeMentionAlias(rawAlias);
   if (!alias) return;
   let ids = lookup.byAlias.get(alias);
@@ -36,7 +40,10 @@ export function extractMentionAliasHints(text: string): MentionAliasHint[] {
   if (!text) return [];
 
   const hints = new Map<string, MentionAliasHint>();
-  const collect = (rawAlias: string | null | undefined, rawUserId: string | null | undefined): void => {
+  const collect = (
+    rawAlias: string | null | undefined,
+    rawUserId: string | null | undefined,
+  ): void => {
     const userId = (rawUserId || '').trim();
     if (!/^\d{16,22}$/.test(userId)) return;
     const alias = normalizeMentionAlias(rawAlias);
@@ -45,32 +52,44 @@ export function extractMentionAliasHints(text: string): MentionAliasHint[] {
     if (!hints.has(key)) hints.set(key, { alias, userId });
   };
 
-  const aliasToId = /(^|[\s,;:.!?])@?([\p{L}\p{N}._-]{2,32})\s*(?:ist|is|=|->|=>|means|heißt)\s*(?:<@!?(\d{16,22})>|(\d{16,22}))/giu;
+  const aliasToId =
+    /(^|[\s,;:.!?])@?([\p{L}\p{N}._-]{2,32})\s*(?:ist|is|=|->|=>|means|heißt)\s*(?:<@!?(\d{16,22})>|(\d{16,22}))/giu;
   let match: RegExpExecArray | null;
-  while ((match = aliasToId.exec(text)) !== null) {
+  while (true) {
+    match = aliasToId.exec(text);
+    if (match === null) break;
     collect(match[2], match[3] || match[4]);
   }
 
-  const idToAlias = /(?:<@!?(\d{16,22})>|(\d{16,22}))\s*(?:ist|is|=|->|=>|means|heißt)\s*@?([\p{L}\p{N}._-]{2,32})/giu;
-  while ((match = idToAlias.exec(text)) !== null) {
+  const idToAlias =
+    /(?:<@!?(\d{16,22})>|(\d{16,22}))\s*(?:ist|is|=|->|=>|means|heißt)\s*@?([\p{L}\p{N}._-]{2,32})/giu;
+  while (true) {
+    match = idToAlias.exec(text);
+    if (match === null) break;
     collect(match[3], match[1] || match[2]);
   }
 
   return Array.from(hints.values());
 }
 
-export function rewriteUserMentions(text: string, lookup: MentionLookup): string {
+export function rewriteUserMentions(
+  text: string,
+  lookup: MentionLookup,
+): string {
   if (!text) return text;
   if (!lookup.byAlias.size) return text;
-  return text.replace(/(^|[\s([{:>])@([\p{L}\p{N}._-]{2,32})\b/gu, (full, prefix: string, rawAlias: string) => {
-    const alias = normalizeMentionAlias(rawAlias);
-    if (!alias) return full;
-    const ids = lookup.byAlias.get(alias);
-    if (!ids || ids.size !== 1) return full;
-    const [id] = Array.from(ids);
-    if (!id) return full;
-    return `${prefix}<@${id}>`;
-  });
+  return text.replace(
+    /(^|[\s([{:>])@([\p{L}\p{N}._-]{2,32})\b/gu,
+    (full, prefix: string, rawAlias: string) => {
+      const alias = normalizeMentionAlias(rawAlias);
+      if (!alias) return full;
+      const ids = lookup.byAlias.get(alias);
+      if (!ids || ids.size !== 1) return full;
+      const [id] = Array.from(ids);
+      if (!id) return full;
+      return `${prefix}<@${id}>`;
+    },
+  );
 }
 
 function extractMentionAliases(text: string): string[] {
@@ -78,7 +97,9 @@ function extractMentionAliases(text: string): string[] {
   const aliases = new Set<string>();
   const re = /(^|[\s([{:>])@([\p{L}\p{N}._-]{2,32})\b/gu;
   let match: RegExpExecArray | null;
-  while ((match = re.exec(text)) !== null) {
+  while (true) {
+    match = re.exec(text);
+    if (match === null) break;
     const alias = normalizeMentionAlias(match[2]);
     if (!alias) continue;
     aliases.add(alias);
@@ -97,7 +118,10 @@ async function enrichMentionLookupFromGuild(
   for (const alias of aliases) {
     if (lookup.byAlias.has(alias)) continue;
     try {
-      const members = await msg.guild.members.search({ query: alias, limit: 5 });
+      const members = await msg.guild.members.search({
+        query: alias,
+        limit: 5,
+      });
       const exactMatches = Array.from(members.values()).filter((member) => {
         const username = normalizeMentionAlias(member.user?.username || '');
         const displayName = normalizeMentionAlias(member.displayName || '');

package/src/channels/discord/presence.ts

@@ -0,0 +1,148 @@
+import { ActivityType, type Client, type PresenceStatusData } from 'discord.js';
+
+import { logger } from '../../logger.js';
+
+export type PresenceHealthState =
+  | 'healthy'
+  | 'degraded'
+  | 'exhausted'
+  | 'maintenance';
+export type DiscordPresenceActivityType =
+  | 'playing'
+  | 'watching'
+  | 'listening'
+  | 'competing'
+  | 'custom';
+
+export interface DiscordAutoPresenceConfig {
+  enabled: boolean;
+  intervalMs: number;
+  healthyText: string;
+  degradedText: string;
+  exhaustedText: string;
+  activityType: DiscordPresenceActivityType;
+}
+
+type PresenceConfigResolver = () => DiscordAutoPresenceConfig;
+type PresenceStateResolver = () => PresenceHealthState;
+
+function toDiscordActivityType(
+  type: DiscordPresenceActivityType,
+): ActivityType {
+  switch (type) {
+    case 'playing':
+      return ActivityType.Playing;
+    case 'listening':
+      return ActivityType.Listening;
+    case 'competing':
+      return ActivityType.Competing;
+    case 'custom':
+      return ActivityType.Custom;
+    case 'watching':
+    default:
+      return ActivityType.Watching;
+  }
+}
+
+function presenceTextForState(
+  config: DiscordAutoPresenceConfig,
+  state: PresenceHealthState,
+): string {
+  if (state === 'degraded') return config.degradedText;
+  if (state === 'exhausted') return config.exhaustedText;
+  return config.healthyText;
+}
+
+function presenceStatusForState(
+  state: PresenceHealthState,
+): PresenceStatusData {
+  if (state === 'maintenance') return 'invisible';
+  if (state === 'exhausted') return 'dnd';
+  if (state === 'degraded') return 'idle';
+  return 'online';
+}
+
+export class DiscordAutoPresenceController {
+  private readonly client: Client;
+  private readonly getConfig: PresenceConfigResolver;
+  private readonly resolveState: PresenceStateResolver;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private running = false;
+  private maintenance = false;
+  private lastFingerprint = '';
+
+  constructor(params: {
+    client: Client;
+    getConfig: PresenceConfigResolver;
+    resolveState: PresenceStateResolver;
+  }) {
+    this.client = params.client;
+    this.getConfig = params.getConfig;
+    this.resolveState = params.resolveState;
+  }
+
+  start(): void {
+    this.stop();
+    this.running = true;
+    const tick = async (): Promise<void> => {
+      if (!this.running) return;
+      await this.evaluateNow();
+      if (!this.running) return;
+      const intervalMs = Math.max(
+        5_000,
+        Math.floor(this.getConfig().intervalMs),
+      );
+      this.timer = setTimeout(() => {
+        void tick();
+      }, intervalMs);
+    };
+    this.timer = setTimeout(() => {
+      void tick();
+    }, 0);
+  }
+
+  stop(): void {
+    this.running = false;
+    if (!this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  async setMaintenance(): Promise<void> {
+    this.maintenance = true;
+    await this.evaluateNow();
+  }
+
+  private async evaluateNow(): Promise<void> {
+    const config = this.getConfig();
+    if (!this.client.user) return;
+    if (!config.enabled && !this.maintenance) return;
+
+    const state = this.maintenance ? 'maintenance' : this.resolveState();
+    const status = presenceStatusForState(state);
+    const activityText =
+      state === 'maintenance' ? '' : presenceTextForState(config, state);
+    const activityType = toDiscordActivityType(config.activityType);
+    const fingerprint = `${state}:${status}:${activityType}:${activityText}`;
+    if (fingerprint === this.lastFingerprint) return;
+
+    try {
+      if (state === 'maintenance') {
+        await this.client.user.setPresence({
+          status,
+          activities: [],
+        });
+      } else {
+        await this.client.user.setPresence({
+          status,
+          activities: activityText
+            ? [{ name: activityText, type: activityType }]
+            : [],
+        });
+      }
+      this.lastFingerprint = fingerprint;
+    } catch (error) {
+      logger.debug({ error, state }, 'Failed to update Discord presence');
+    }
+  }
+}