feat: Telegram message debounce (PR moazbuilds#31)

- Add debounceMs config for Telegram message batching
- Messages from same chat within window are merged into single prompt
- Preserves attachments (photos, voice, audio, documents)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Fenrur

src/commands/telegram.ts

@@ -920,6 +920,77 @@ async function registerBotCommands(token: string): Promise<void> {
   }
 }
 
+// --- Debounce buffer ---
+
+interface DebouncedEntry {
+  messages: TelegramMessage[];
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const debounceBuffer = new Map<number, DebouncedEntry>();
+
+function flushDebounced(chatId: number): void {
+  const entry = debounceBuffer.get(chatId);
+  if (!entry || entry.messages.length === 0) {
+    debounceBuffer.delete(chatId);
+    return;
+  }
+  debounceBuffer.delete(chatId);
+
+  if (entry.messages.length === 1) {
+    handleMessage(entry.messages[0]).catch((err) => {
+      console.error(`[Telegram] Unhandled: ${err}`);
+    });
+    return;
+  }
+
+  const first = entry.messages[0];
+  const merged: TelegramMessage = {
+    message_id: first.message_id,
+    from: first.from,
+    reply_to_message: first.reply_to_message,
+    chat: first.chat,
+    message_thread_id: first.message_thread_id,
+    text: entry.messages
+      .map((m) => {
+        const { text } = getMessageTextAndEntities(m);
+        return text;
+      })
+      .filter(Boolean)
+      .join("\n"),
+    entities: first.entities,
+  };
+
+  for (const m of entry.messages) {
+    if (m.photo && m.photo.length > 0 && !merged.photo) merged.photo = m.photo;
+    if (m.voice && !merged.voice) merged.voice = m.voice;
+    if (m.audio && !merged.audio) merged.audio = m.audio;
+    if (m.document && !merged.document) merged.document = m.document;
+  }
+
+  const count = entry.messages.length;
+  debugLog(`Debounce flush: chat=${chatId} merged=${count} messages`);
+  console.log(`[Telegram] Debounced ${count} messages from chat ${chatId}`);
+
+  handleMessage(merged).catch((err) => {
+    console.error(`[Telegram] Unhandled: ${err}`);
+  });
+}
+
+function enqueueDebounced(message: TelegramMessage, debounceMs: number): void {
+  const chatId = message.chat.id;
+  const existing = debounceBuffer.get(chatId);
+
+  if (existing) {
+    clearTimeout(existing.timer);
+    existing.messages.push(message);
+    existing.timer = setTimeout(() => flushDebounced(chatId), debounceMs);
+  } else {
+    const timer = setTimeout(() => flushDebounced(chatId), debounceMs);
+    debounceBuffer.set(chatId, { messages: [message], timer });
+  }
+}
+
 // --- Polling loop ---
 
 let running = true;
@@ -941,6 +1012,7 @@ async function poll(): Promise<void> {
 
   console.log("Telegram bot started (long polling)");
   console.log(`  Allowed users: ${config.allowedUserIds.length === 0 ? "all" : config.allowedUserIds.join(", ")}`);
+  if (config.debounceMs > 0) console.log(`  Debounce: ${config.debounceMs}ms`);
   if (telegramDebug) console.log("  Debug: enabled");
 
   // Register available skills as bot command menu (non-blocking)
@@ -968,9 +1040,13 @@ async function poll(): Promise<void> {
           update.edited_channel_post,
         ].filter((m): m is TelegramMessage => Boolean(m));
         for (const incoming of incomingMessages) {
-          handleMessage(incoming).catch((err) => {
-            console.error(`[Telegram] Unhandled: ${err}`);
-          });
+          if (config.debounceMs > 0) {
+            enqueueDebounced(incoming, config.debounceMs);
+          } else {
+            handleMessage(incoming).catch((err) => {
+              console.error(`[Telegram] Unhandled: ${err}`);
+            });
+          }
         }
         if (update.my_chat_member) {
           handleMyChatMember(update.my_chat_member).catch((err) => {

src/config.ts

@@ -29,7 +29,7 @@ const DEFAULT_SETTINGS: Settings = {
     excludeWindows: [],
     forwardToTelegram: true,
   },
-  telegram: { token: "", allowedUserIds: [], receiveEnabled: true },
+  telegram: { token: "", allowedUserIds: [], receiveEnabled: true, debounceMs: 0 },
   discord: { token: "", allowedUserIds: [], listenChannels: [] },
   security: { level: "moderate", allowedTools: [], disallowedTools: [] },
   web: { enabled: false, host: "127.0.0.1", port: 4632 },
@@ -56,6 +56,9 @@ export interface TelegramConfig {
   allowedUserIds: number[];
   /** When false, skip Telegram polling (incoming messages). Useful for send-only instances. Default: true */
   receiveEnabled: boolean;
+  /** Debounce window in ms. Messages from the same chat arriving within this
+   *  window are merged into a single prompt. 0 = disabled (default). */
+  debounceMs: number;
 }
 
 export interface DiscordConfig {
@@ -172,6 +175,7 @@ function parseSettings(raw: Record<string, any>, discordUserIds?: string[]): Set
       token: raw.telegram?.token ?? "",
       allowedUserIds: raw.telegram?.allowedUserIds ?? [],
       receiveEnabled: raw.telegram?.receiveEnabled !== false,
+      debounceMs: Number.isFinite(raw.telegram?.debounceMs) ? Number(raw.telegram.debounceMs) : 0,
     },
     discord: {
       token: typeof raw.discord?.token === "string" ? raw.discord.token.trim() : "",