mercury-agent 0.5.16 → 0.5.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/src/core/conversation.ts

@@ -86,6 +86,7 @@ export function resolveConversation(
 
   seedSpaceConfigIfAbsent(db, spaceId, "trigger.match", "always");
   seedSpaceConfigIfAbsent(db, spaceId, "context.mode", "context");
+  seedSpaceConfigIfAbsent(db, spaceId, "debounce.idle_timeout_ms", "2000");
   if (autoSpace.defaultMemberPermissions) {
     seedSpaceConfigIfAbsent(
       db,

package/src/core/debounce.ts

@@ -0,0 +1,135 @@
+import { logger } from "../logger.js";
+import type { IngressMessage } from "../types.js";
+
+interface DebounceEntry {
+  ingresses: IngressMessage[];
+  timer: ReturnType<typeof setTimeout>;
+}
+
+interface ProcessingEntry {
+  pending: IngressMessage[] | null;
+}
+
+type FlushCallback = (merged: IngressMessage) => Promise<void>;
+
+const DEBOUNCE_PLATFORMS: Record<string, number> = {
+  whatsapp: 2000,
+  telegram: 2000,
+};
+
+export function getDefaultDebounceMs(platform: string): number {
+  return DEBOUNCE_PLATFORMS[platform] ?? 0;
+}
+
+export function mergeIngresses(batch: IngressMessage[]): IngressMessage {
+  if (batch.length === 1) return batch[0];
+
+  const first = batch[0];
+  const last = batch[batch.length - 1];
+
+  return {
+    platform: first.platform,
+    spaceId: first.spaceId,
+    conversationExternalId: first.conversationExternalId,
+    callerId: first.callerId,
+    authorName: first.authorName,
+    text: batch.map((m) => m.text).join("\n"),
+    isDM: first.isDM,
+    isReplyToBot: first.isReplyToBot,
+    attachments: batch.flatMap((m) => m.attachments),
+    hadIncomingAttachments: batch.some((m) => m.hadIncomingAttachments),
+    replyToPlatformMessageId: first.replyToPlatformMessageId,
+    platformMessageId: last.platformMessageId,
+  };
+}
+
+export class MessageDebouncer {
+  private batches = new Map<string, DebounceEntry>();
+  private processing = new Map<string, ProcessingEntry>();
+
+  submit(
+    key: string,
+    ingress: IngressMessage,
+    timeoutMs: number,
+    onFlush: FlushCallback,
+  ): void {
+    const proc = this.processing.get(key);
+    if (proc) {
+      if (!proc.pending) {
+        proc.pending = [ingress];
+      } else {
+        proc.pending.push(ingress);
+      }
+      return;
+    }
+
+    const existing = this.batches.get(key);
+    if (existing) {
+      clearTimeout(existing.timer);
+      existing.ingresses.push(ingress);
+      existing.timer = setTimeout(() => {
+        this.flush(key, onFlush);
+      }, timeoutMs);
+    } else {
+      const timer = setTimeout(() => {
+        this.flush(key, onFlush);
+      }, timeoutMs);
+      this.batches.set(key, { ingresses: [ingress], timer });
+    }
+  }
+
+  flushKey(key: string, onFlush: FlushCallback): void {
+    const entry = this.batches.get(key);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    this.batches.delete(key);
+    this.executeFlush(key, entry.ingresses, onFlush);
+  }
+
+  isProcessing(key: string): boolean {
+    return this.processing.has(key);
+  }
+
+  flushAll(onFlush: FlushCallback): void {
+    for (const [key, entry] of this.batches) {
+      clearTimeout(entry.timer);
+      this.executeFlush(key, entry.ingresses, onFlush);
+    }
+    this.batches.clear();
+  }
+
+  private flush(key: string, onFlush: FlushCallback): void {
+    const entry = this.batches.get(key);
+    if (!entry) return;
+    this.batches.delete(key);
+    this.executeFlush(key, entry.ingresses, onFlush);
+  }
+
+  private executeFlush(
+    key: string,
+    ingresses: IngressMessage[],
+    onFlush: FlushCallback,
+  ): void {
+    const merged = mergeIngresses(ingresses);
+    this.processing.set(key, { pending: null });
+
+    onFlush(merged)
+      .catch((err) => {
+        logger.error("Debounce flush error", {
+          key,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      })
+      .finally(() => {
+        const proc = this.processing.get(key);
+        if (proc?.pending) {
+          const batch = proc.pending;
+          proc.pending = null;
+          this.processing.delete(key);
+          this.executeFlush(key, batch, onFlush);
+        } else {
+          this.processing.delete(key);
+        }
+      });
+  }
+}

package/src/core/handler.ts

@@ -2,12 +2,17 @@ import type { Adapter, Message } from "chat";
 import { telegramInboundLooksLikeMedia } from "../bridges/telegram.js";
 import type { AppConfig } from "../config.js";
 import { logger } from "../logger.js";
-import type { NormalizeContext, PlatformBridge } from "../types.js";
+import type {
+  IngressMessage,
+  NormalizeContext,
+  PlatformBridge,
+} from "../types.js";
 import {
   type AutoSpaceConfig,
   inferConversationKind,
   resolveConversation,
 } from "./conversation.js";
+import { getDefaultDebounceMs, MessageDebouncer } from "./debounce.js";
 import type { MercuryCoreRuntime } from "./runtime.js";
 import { loadTriggerConfig, matchTrigger } from "./trigger.js";
 
@@ -38,6 +43,105 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
       }
     : undefined;
 
+  const debouncer = new MessageDebouncer();
+
+  async function processIngress(
+    ingress: IngressMessage,
+    threadId: string,
+  ): Promise<void> {
+    const startTime = Date.now();
+    let lastStatusMessageId: string | undefined;
+    let hadStatusMessage = false;
+
+    const heartbeat = setInterval(() => {
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      const statusText = `⏳ Processing… (${elapsed}s)`;
+      const currentId = lastStatusMessageId;
+
+      if (currentId && bridge.editMessage) {
+        bridge
+          .editMessage(threadId, currentId, statusText)
+          .then((ok) => {
+            if (!ok) {
+              bridge
+                .sendReply(threadId, statusText)
+                .then(async (id) => {
+                  await bridge
+                    .deleteMessages?.(threadId, [currentId])
+                    .catch(() => {});
+                  if (id) lastStatusMessageId = id;
+                })
+                .catch(() => {});
+            }
+          })
+          .catch(() => {});
+      } else {
+        const prevId = lastStatusMessageId;
+        bridge
+          .sendReply(threadId, statusText)
+          .then(async (id) => {
+            if (prevId) {
+              await bridge.deleteMessages?.(threadId, [prevId]).catch(() => {});
+            }
+            if (id) {
+              lastStatusMessageId = id;
+              hadStatusMessage = true;
+            }
+          })
+          .catch(() => {});
+      }
+    }, 30_000);
+
+    let result: Awaited<ReturnType<typeof core.handleRawInput>>;
+    try {
+      result = await core.handleRawInput(ingress, "chat-sdk");
+    } finally {
+      clearInterval(heartbeat);
+    }
+
+    if (lastStatusMessageId) {
+      await bridge
+        .deleteMessages?.(threadId, [lastStatusMessageId])
+        .catch(() => {});
+    }
+
+    if (result.type === "ignore") return;
+
+    if (result.type === "denied") {
+      await bridge.sendReply(threadId, result.reason);
+      return;
+    }
+
+    if (result.result) {
+      const { reply, files, assistantMessageId } = result.result;
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      const finalReply =
+        hadStatusMessage && reply
+          ? `${reply}\n\n_(responded in ${elapsed}s)_`
+          : reply;
+      if (finalReply || files.length > 0) {
+        const sentPlatformId = await bridge.sendReply(
+          threadId,
+          finalReply,
+          files.length > 0 ? files : undefined,
+        );
+
+        if (
+          sentPlatformId &&
+          assistantMessageId &&
+          ingress.conversationExternalId
+        ) {
+          core.recordOutboundPlatformId(
+            assistantMessageId,
+            bridge.platform,
+            ingress.conversationExternalId,
+            sentPlatformId,
+          );
+        }
+      }
+    }
+  }
+
   return async (
     adapter: Adapter,
     threadId: string,
@@ -120,101 +224,38 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
         }
       }
 
-      const startTime = Date.now();
-      let lastStatusMessageId: string | undefined;
-      let hadStatusMessage = false;
-
-      const heartbeat = setInterval(() => {
-        const elapsed = Math.round((Date.now() - startTime) / 1000);
-        const statusText = `⏳ Processing… (${elapsed}s)`;
-        const currentId = lastStatusMessageId;
-
-        if (currentId && bridge.editMessage) {
-          bridge
-            .editMessage(threadId, currentId, statusText)
-            .then((ok) => {
-              if (!ok) {
-                // Edit failed — fall back to delete+send
-                bridge
-                  .sendReply(threadId, statusText)
-                  .then(async (id) => {
-                    await bridge
-                      .deleteMessages?.(threadId, [currentId])
-                      .catch(() => {});
-                    if (id) lastStatusMessageId = id;
-                  })
-                  .catch(() => {});
-              }
-            })
-            .catch(() => {});
-        } else {
-          const prevId = lastStatusMessageId;
-          bridge
-            .sendReply(threadId, statusText)
-            .then(async (id) => {
-              if (prevId) {
-                await bridge
-                  .deleteMessages?.(threadId, [prevId])
-                  .catch(() => {});
-              }
-              if (id) {
-                lastStatusMessageId = id;
-                hadStatusMessage = true;
-              }
-            })
-            .catch(() => {});
-        }
-      }, 30_000);
-
-      let result: Awaited<ReturnType<typeof core.handleRawInput>>;
-      try {
-        result = await core.handleRawInput(ingress, "chat-sdk");
-      } finally {
-        clearInterval(heartbeat);
-      }
+      const isCommand = text.startsWith("/");
+      const shouldProcess =
+        triggerResult.matched || (ingress.isReplyToBot && !isDM);
 
-      if (lastStatusMessageId) {
-        await bridge
-          .deleteMessages?.(threadId, [lastStatusMessageId])
-          .catch(() => {});
-      }
+      if (!shouldProcess && !isCommand) return;
 
-      if (result.type === "ignore") return;
+      const debounceKey = `${spaceId}:${ingress.callerId}`;
+      const onFlush = (merged: IngressMessage) =>
+        processIngress(merged, threadId);
 
-      if (result.type === "denied") {
-        await bridge.sendReply(threadId, result.reason);
+      if (isCommand) {
+        debouncer.flushKey(debounceKey, onFlush);
+        await processIngress(ingress, threadId);
         return;
       }
 
-      if (result.result) {
-        const { reply, files, assistantMessageId } = result.result;
-        const elapsed = Math.round((Date.now() - startTime) / 1000);
-        const finalReply =
-          hadStatusMessage && reply
-            ? `${reply}\n\n_(responded in ${elapsed}s)_`
-            : reply;
-        if (finalReply || files.length > 0) {
-          const sentPlatformId = await bridge.sendReply(
-            threadId,
-            finalReply,
-            files.length > 0 ? files : undefined,
-          );
+      const configuredMs = core.db.getSpaceConfig(
+        spaceId,
+        "debounce.idle_timeout_ms",
+      );
+      const parsed =
+        configuredMs !== null ? Number.parseInt(configuredMs, 10) : Number.NaN;
+      const timeoutMs = Number.isNaN(parsed)
+        ? getDefaultDebounceMs(bridge.platform)
+        : parsed;
 
-          // Record the platform message ID mapping for the bot's outbound message
-          if (
-            sentPlatformId &&
-            assistantMessageId &&
-            ingress.conversationExternalId
-          ) {
-            core.recordOutboundPlatformId(
-              assistantMessageId,
-              bridge.platform,
-              ingress.conversationExternalId,
-              sentPlatformId,
-            );
-          }
-        }
+      if (timeoutMs <= 0) {
+        await processIngress(ingress, threadId);
+        return;
       }
+
+      debouncer.submit(debounceKey, ingress, timeoutMs, onFlush);
     } catch (err) {
       logger.error("Message handler error", {
         platform: bridge.platform,

package/src/core/routes/config-builtin.ts

@@ -13,6 +13,7 @@ export const BUILTIN_CONFIG_KEYS = new Set([
   "rate_limit",
   "rate_limit.member",
   "rate_limit.admin",
+  "debounce.idle_timeout_ms",
 ]);
 
 /**
@@ -46,6 +47,8 @@ export const BUILTIN_CONFIG_DESCRIPTIONS: Record<string, string> = {
     "Daily message cap for members in this space. Overrides global rate_limit_daily_member. Integer ≥ 1, or 0 for unlimited.",
   "rate_limit.admin":
     "Daily message cap for admins in this space. Overrides global rate_limit_daily_admin. Integer ≥ 1, or 0 for unlimited.",
+  "debounce.idle_timeout_ms":
+    "Milliseconds to wait for additional messages before processing a batch. 0 disables debounce. Platform default: 2000 for WhatsApp/Telegram, 0 for others.",
 };
 
 const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
@@ -103,6 +106,12 @@ const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
       ? null
       : "Invalid rate_limit.admin value. Must be an integer between 0 and 10000";
   },
+  "debounce.idle_timeout_ms": (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 0 && n <= 10000
+      ? null
+      : "Invalid debounce.idle_timeout_ms value. Must be an integer between 0 and 10000";
+  },
 };
 
 export function isBuiltinConfigKey(key: string): boolean {