@hybridaione/hybridclaw 0.2.2 → 0.2.6

package/src/channels/discord/inbound.ts

@@ -4,7 +4,15 @@ export interface ParsedCommand {
   args: string[];
 }
 
-export function stripBotMentions(text: string, botMentionRegex: RegExp | null): string {
+export type DiscordGuildMessageMode = 'off' | 'mention' | 'free';
+
+const GREETING_ONLY_RE =
+  /^(hi|hey|hello|yo|sup|thanks|thank you|thx|ok|okay|got it|roger|cool)[!. ]*$/i;
+
+export function stripBotMentions(
+  text: string,
+  botMentionRegex: RegExp | null,
+): string {
   if (!botMentionRegex) return text;
   return text.replace(botMentionRegex, '').trim();
 }
@@ -30,7 +38,11 @@ export function hasPrefixInvocation(
   return text.startsWith(prefix);
 }
 
-export function buildSessionIdFromContext(guildId: string | null, channelId: string, userId: string): string {
+export function buildSessionIdFromContext(
+  guildId: string | null,
+  channelId: string,
+  userId: string,
+): string {
   return guildId ? `${guildId}:${channelId}` : `dm:${userId}`;
 }
 
@@ -45,28 +57,75 @@ export function parseCommand(
   }
 
   const parts = text.split(/\s+/);
-  const subcommands = ['bot', 'rag', 'model', 'sessions', 'audit', 'schedule', 'clear', 'help'];
+  const subcommands = [
+    'bot',
+    'rag',
+    'model',
+    'usage',
+    'export',
+    '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) };
+    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 isTrigger(params: {
   content: string;
   isDm: boolean;
   commandsOnly: boolean;
   respondToAllMessages: boolean;
+  guildMessageMode: DiscordGuildMessageMode;
   prefix: string;
   botMentionRegex: RegExp | null;
   hasBotMention: boolean;
+  suppressPatterns?: string[];
 }): boolean {
+  const stripped = stripBotMentions(params.content, params.botMentionRegex);
+
   if (params.commandsOnly) {
-    return hasPrefixInvocation(params.content, params.botMentionRegex, params.prefix);
+    return hasPrefixInvocation(
+      params.content,
+      params.botMentionRegex,
+      params.prefix,
+    );
   }
+  if (
+    hasPrefixInvocation(params.content, params.botMentionRegex, params.prefix)
+  )
+    return true;
+  if (shouldSuppressAutoReply(stripped, params.suppressPatterns)) return false;
   if (params.isDm) return true;
-  if (params.respondToAllMessages) return true;
+  if (params.guildMessageMode === 'off') return false;
+  if (params.guildMessageMode === 'free') return true;
+  // Keep `respondToAllMessages` consumed for compatibility; mode resolution decides guild behavior.
+  void params.respondToAllMessages;
   if (params.hasBotMention) return true;
-  return params.content.startsWith(params.prefix);
+  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');
+    }
+  }
+}

package/src/channels/discord/rate-limiter.ts

@@ -0,0 +1,58 @@
+export interface RateLimitDecision {
+  allowed: boolean;
+  remaining: number;
+  retryAfterMs: number;
+}
+
+export class SlidingWindowRateLimiter {
+  private readonly windowMs: number;
+  private readonly buckets = new Map<string, number[]>();
+  private readonly notifyAt = new Map<string, number>();
+
+  constructor(windowMs = 60_000) {
+    this.windowMs = Math.max(1_000, Math.floor(windowMs));
+  }
+
+  check(key: string, limit: number, nowMs = Date.now()): RateLimitDecision {
+    const boundedLimit = Math.max(0, Math.floor(limit));
+    if (!key || boundedLimit === 0) {
+      return {
+        allowed: true,
+        remaining: Number.POSITIVE_INFINITY,
+        retryAfterMs: 0,
+      };
+    }
+
+    const cutoff = nowMs - this.windowMs;
+    const timestamps = this.buckets.get(key) ?? [];
+    const active = timestamps.filter((ts) => ts > cutoff);
+
+    if (active.length >= boundedLimit) {
+      this.buckets.set(key, active);
+      const oldest = active[0];
+      const retryAfterMs = Math.max(0, oldest + this.windowMs - nowMs);
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfterMs,
+      };
+    }
+
+    active.push(nowMs);
+    this.buckets.set(key, active);
+    return {
+      allowed: true,
+      remaining: Math.max(0, boundedLimit - active.length),
+      retryAfterMs: 0,
+    };
+  }
+
+  shouldNotify(key: string, cooldownMs = 10_000, nowMs = Date.now()): boolean {
+    if (!key) return true;
+    const boundedCooldown = Math.max(1_000, Math.floor(cooldownMs));
+    const nextAllowedAt = this.notifyAt.get(key) ?? 0;
+    if (nowMs < nextAllowedAt) return false;
+    this.notifyAt.set(key, nowMs + boundedCooldown);
+    return true;
+  }
+}

package/src/channels/discord/reactions.ts

@@ -0,0 +1,211 @@
+import type { Message as DiscordMessage } from 'discord.js';
+
+import { logger } from '../../logger.js';
+
+export type LifecyclePhase =
+  | 'queued'
+  | 'thinking'
+  | 'toolUse'
+  | 'streaming'
+  | 'done'
+  | 'error';
+export type DiscordRetryFn = <T>(
+  label: string,
+  fn: () => Promise<T>,
+) => Promise<T>;
+
+const MIN_REACTION_GAP_MS = 350;
+const DONE_REACTION_VISIBILITY_MS = 1_000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function findReactionByEmoji(
+  message: DiscordMessage,
+  emoji: string,
+): { users: { remove: (userId: string) => Promise<unknown> } } | null {
+  const direct = message.reactions.resolve(emoji);
+  if (direct) return direct;
+  const trimmed = emoji.trim();
+  if (!trimmed) return null;
+  const fallback = message.reactions.cache.find(
+    (reaction) =>
+      reaction.emoji.toString() === trimmed || reaction.emoji.name === trimmed,
+  );
+  return fallback ?? null;
+}
+
+export async function addAckReaction(params: {
+  message: DiscordMessage;
+  emoji: string;
+  withRetry: DiscordRetryFn;
+  botUserId: string;
+}): Promise<() => Promise<void>> {
+  const reactionEmoji = params.emoji.trim();
+  if (!reactionEmoji) {
+    return async () => {};
+  }
+
+  try {
+    await params.withRetry('reaction-ack-add', () =>
+      params.message.react(reactionEmoji),
+    );
+  } catch (error) {
+    logger.debug(
+      {
+        error,
+        channelId: params.message.channelId,
+        messageId: params.message.id,
+        reactionEmoji,
+      },
+      'Failed to add ack reaction',
+    );
+    return async () => {};
+  }
+
+  return async () => {
+    try {
+      const reaction = findReactionByEmoji(params.message, reactionEmoji);
+      if (!reaction) return;
+      await params.withRetry('reaction-ack-remove', () =>
+        reaction.users.remove(params.botUserId),
+      );
+    } catch (error) {
+      logger.debug(
+        {
+          error,
+          channelId: params.message.channelId,
+          messageId: params.message.id,
+          reactionEmoji,
+        },
+        'Failed to remove ack reaction',
+      );
+    }
+  };
+}
+
+interface LifecycleReactionConfig {
+  enabled: boolean;
+  removeOnComplete: boolean;
+  phases: Record<LifecyclePhase, string>;
+}
+
+export class LifecycleReactionController {
+  private readonly message: DiscordMessage;
+  private readonly withRetry: DiscordRetryFn;
+  private readonly botUserId: string;
+  private readonly config: LifecycleReactionConfig;
+  private currentEmoji: string | null = null;
+  private currentPhase: LifecyclePhase | null = null;
+  private queue = Promise.resolve();
+  private lastReactionAt = 0;
+
+  constructor(params: {
+    message: DiscordMessage;
+    withRetry: DiscordRetryFn;
+    botUserId: string;
+    config: LifecycleReactionConfig;
+  }) {
+    this.message = params.message;
+    this.withRetry = params.withRetry;
+    this.botUserId = params.botUserId;
+    this.config = params.config;
+  }
+
+  setPhase(phase: LifecyclePhase): void {
+    if (!this.config.enabled) return;
+    if (this.currentPhase === phase) return;
+    this.currentPhase = phase;
+    this.queue = this.queue
+      .then(async () => {
+        await this.transitionToPhase(phase);
+      })
+      .catch((error) => {
+        logger.debug(
+          {
+            error,
+            channelId: this.message.channelId,
+            messageId: this.message.id,
+            phase,
+          },
+          'Lifecycle reaction transition failed',
+        );
+      });
+  }
+
+  async clear(): Promise<void> {
+    if (!this.config.enabled) return;
+    await this.queue;
+    if (!this.currentEmoji) return;
+    await this.removeReaction(this.currentEmoji);
+    this.currentEmoji = null;
+    this.currentPhase = null;
+  }
+
+  private async transitionToPhase(phase: LifecyclePhase): Promise<void> {
+    const nextEmoji = (this.config.phases[phase] || '').trim();
+    if (!nextEmoji) return;
+    if (this.currentEmoji && this.currentEmoji !== nextEmoji) {
+      await this.removeReaction(this.currentEmoji);
+      this.currentEmoji = null;
+    }
+
+    await this.addReaction(nextEmoji);
+    this.currentEmoji = nextEmoji;
+
+    if (phase === 'done' && this.config.removeOnComplete) {
+      await sleep(DONE_REACTION_VISIBILITY_MS);
+      await this.removeReaction(nextEmoji);
+      this.currentEmoji = null;
+    }
+  }
+
+  private async waitForReactionWindow(): Promise<void> {
+    const elapsed = Date.now() - this.lastReactionAt;
+    if (elapsed >= MIN_REACTION_GAP_MS) return;
+    await sleep(MIN_REACTION_GAP_MS - elapsed);
+  }
+
+  private async addReaction(emoji: string): Promise<void> {
+    await this.waitForReactionWindow();
+    try {
+      await this.withRetry('reaction-lifecycle-add', () =>
+        this.message.react(emoji),
+      );
+      this.lastReactionAt = Date.now();
+    } catch (error) {
+      logger.debug(
+        {
+          error,
+          channelId: this.message.channelId,
+          messageId: this.message.id,
+          emoji,
+        },
+        'Failed to add lifecycle reaction',
+      );
+    }
+  }
+
+  private async removeReaction(emoji: string): Promise<void> {
+    await this.waitForReactionWindow();
+    try {
+      const reaction = findReactionByEmoji(this.message, emoji);
+      if (!reaction) return;
+      await this.withRetry('reaction-lifecycle-remove', () =>
+        reaction.users.remove(this.botUserId),
+      );
+      this.lastReactionAt = Date.now();
+    } catch (error) {
+      logger.debug(
+        {
+          error,
+          channelId: this.message.channelId,
+          messageId: this.message.id,
+          emoji,
+        },
+        'Failed to remove lifecycle reaction',
+      );
+    }
+  }
+}