mercury-agent 0.5.16 → 0.5.18-beta.3

package/examples/extensions/napkin/index.ts

@@ -11,6 +11,7 @@ import {
 import { createRequire } from "node:module";
 import { homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
+import { getApiKeyFromPiAuthFile } from "mercury-agent/storage/pi-auth";
 
 const KNOWLEDGE_DIR = "knowledge";
 const VAULT_DIRS = ["people", "projects", "references", "daily", "episodes", "weekly", "monthly", "templates"];
@@ -175,6 +176,7 @@ function runPromptAgent(
   vaultDir: string,
   promptPath: string,
   instruction: string,
+  extraEnv?: Record<string, string>,
 ): Promise<{ ok: boolean; detail?: string }> {
   let promptText: string;
   try {
@@ -206,7 +208,7 @@ function runPromptAgent(
       ],
       {
         cwd: vaultDir,
-        env: envWithPiOnPath(),
+        env: { ...envWithPiOnPath(), ...extraEnv },
         // Capture stderr (a background job has no console to inherit usefully):
         // the captured tail is what makes a non-zero exit diagnosable in logs.
         stdio: ["ignore", "inherit", "pipe"],
@@ -236,11 +238,13 @@ function runPromptAgent(
 function runDistiller(
   vaultDir: string,
   dateFile: string,
+  extraEnv?: Record<string, string>,
 ): Promise<{ ok: boolean; detail?: string }> {
   return runPromptAgent(
     vaultDir,
     KB_DISTILLER_PROMPT_PATH,
     `Distill knowledge from: ${dateFile}`,
+    extraEnv,
   );
 }
 
@@ -399,6 +403,38 @@ export default function (mercury: {
     };
   });
 
+  // ---------------------------------------------------------------------------
+  // LLM credential resolution for host-side pi spawns
+  // ---------------------------------------------------------------------------
+
+  async function resolvePiAuthEnv(config: {
+    authPath?: string;
+    globalDir: string;
+    modelProvider: string;
+  }): Promise<Record<string, string>> {
+    const env: Record<string, string> = {};
+
+    // 1. Explicit env vars (strip MERCURY_ prefix, matching container-runner)
+    if (process.env.MERCURY_ANTHROPIC_API_KEY) {
+      env.ANTHROPIC_API_KEY = process.env.MERCURY_ANTHROPIC_API_KEY;
+    }
+    if (process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN) {
+      env.ANTHROPIC_API_KEY = process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN;
+    }
+
+    // 2. Fall back to Mercury's auth.json (OAuth token refresh)
+    if (!env.ANTHROPIC_API_KEY) {
+      const authPath = config.authPath ?? join(config.globalDir, "auth.json");
+      const key = await getApiKeyFromPiAuthFile({
+        provider: config.modelProvider,
+        authPath,
+      });
+      if (key) env.ANTHROPIC_API_KEY = key;
+    }
+
+    return env;
+  }
+
   // ---------------------------------------------------------------------------
   // KB Distillation job
   // ---------------------------------------------------------------------------
@@ -417,6 +453,8 @@ export default function (mercury: {
           return;
         }
 
+        const piAuthEnv = await resolvePiAuthEnv(ctx.config);
+
         const db = new Database(dbPath, { readonly: true });
 
         const spaces = db
@@ -561,7 +599,7 @@ export default function (mercury: {
           // --- Step 6: Distill each eligible date ---
           for (const date of eligibleDates) {
             const dateFile = join(messagesDir, `${date}.jsonl`);
-            const result = await runDistiller(knowledgeDir, dateFile);
+            const result = await runDistiller(knowledgeDir, dateFile, piAuthEnv);
             if (result.ok) {
               ctx.log.info("Distillation complete", { spaceId, date });
               // Only persist past dates to distilled set (today will always be re-checked)
@@ -642,6 +680,9 @@ export default function (mercury: {
 
         const dbPath = join(ctx.config.dataDir, "state.db");
         if (!existsSync(dbPath)) return;
+
+        const piAuthEnv = await resolvePiAuthEnv(ctx.config);
+
         const db = new Database(dbPath, { readonly: true });
 
         const spaces = db
@@ -706,6 +747,7 @@ export default function (mercury: {
                 knowledgeDir,
                 WEEKLY_CONSOLIDATION_PROMPT_PATH,
                 instruction,
+                piAuthEnv,
               );
               if (result.ok) {
                 ctx.log.info("Weekly consolidation complete", { spaceId, week });
@@ -777,6 +819,7 @@ export default function (mercury: {
                   knowledgeDir,
                   MONTHLY_CONSOLIDATION_PROMPT_PATH,
                   instruction,
+                  piAuthEnv,
                 );
                 if (result.ok) {
                   ctx.log.info("Monthly consolidation complete", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.5.16",
+  "version": "0.5.18-beta.3",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -24,6 +24,10 @@
       "types": "./src/extensions/types.ts",
       "default": "./src/extensions/types.ts"
     },
+    "./storage/pi-auth": {
+      "types": "./src/storage/pi-auth.ts",
+      "default": "./src/storage/pi-auth.ts"
+    },
     "./tts": {
       "types": "./src/tts/index.ts",
       "default": "./src/tts/index.ts"

package/src/cli/mercury.ts

@@ -18,6 +18,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { loadConfig, resolveProjectPath } from "../config.js";
+import { getCatalogEntryByName } from "../extensions/catalog.js";
 import {
   checkExtensionIndexLoads,
   getProjectDataDir,
@@ -1930,6 +1931,13 @@ function extensionsListAction(): void {
     console.log(
       `${ext.name.padEnd(nameWidth)}  ${features.padEnd(featWidth)}${tag}${desc}`,
     );
+    const cat = getCatalogEntryByName(ext.name);
+    if (cat?.prerequisites?.length) {
+      const prereq = cat.prerequisites.join(", ");
+      console.log(
+        `${"".padEnd(nameWidth)}  ${"".padEnd(featWidth)}  Requires: ${prereq.slice(0, 60)}${prereq.length > 60 ? "…" : ""}`,
+      );
+    }
   }
 }
 

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 {

package/src/core/routes/dashboard.ts

@@ -1698,11 +1698,14 @@ export function createDashboardRoutes(ctx: DashboardContext) {
                 .filter(Boolean)
                 .join(", ");
               const label = cat?.label ?? ext.name;
+              const prereqHint = cat?.prerequisites?.length
+                ? `<div class="muted" style="font-size:12px;margin-top:4px">Requires: ${escapeHtml(cat.prerequisites.join(", "))}</div>`
+                : "";
               return `
               <tr>
                 <td class="mono">${escapeHtml(ext.name)}</td>
                 <td>${escapeHtml(label)}</td>
-                <td class="muted" style="max-width:320px">${escapeHtml(desc)}</td>
+                <td class="muted" style="max-width:320px">${escapeHtml(desc)}${prereqHint}</td>
                 <td class="muted">${escapeHtml(feats || "—")}</td>
                 <td>
                   <button type="button" class="btn btn-sm btn-danger"
@@ -1731,6 +1734,9 @@ export function createDashboardRoutes(ctx: DashboardContext) {
               const envHint = entry.requiredEnvVars?.length
                 ? `<div class="muted" style="font-size:12px;margin-top:4px">Env: ${escapeHtml(entry.requiredEnvVars.join(", "))}</div>`
                 : "";
+              const prereqHint = entry.prerequisites?.length
+                ? `<div class="muted" style="font-size:12px;margin-top:4px">Requires: ${escapeHtml(entry.prerequisites.join(", "))}</div>`
+                : "";
               const installBtn = missing
                 ? `<button type="button" class="btn btn-sm" disabled title="examples/extensions missing in this install">Unavailable</button>`
                 : `<form style="display:inline" hx-post="/dashboard/api/extensions/install" hx-target="#features-toast" hx-swap="innerHTML">
@@ -1744,6 +1750,7 @@ export function createDashboardRoutes(ctx: DashboardContext) {
                 <td class="muted" style="max-width:320px">
                   ${escapeHtml(entry.description)}
                   ${envHint}
+                  ${prereqHint}
                 </td>
                 <td class="muted">${escapeHtml(entry.category)}</td>
                 <td>${installBtn}</td>

package/src/extensions/catalog.ts

@@ -19,6 +19,8 @@ export interface ExtensionCatalogEntry {
   /** Subdirectory of `examples/extensions/` to copy from */
   sourceDir: string;
   requiredEnvVars?: string[];
+  /** Host-level prerequisites (CLI tools, system packages) shown to the user before install */
+  prerequisites?: string[];
   requiresRestart: boolean;
 }
 
@@ -39,6 +41,7 @@ export const EXTENSION_CATALOG: ExtensionCatalogEntry[] = [
       "Obsidian-style vault, napkin CLI, and optional KB distillation job.",
     category: "knowledge",
     sourceDir: "napkin",
+    prerequisites: ["pi CLI: bun install -g @earendil-works/pi-coding-agent"],
     requiresRestart: true,
   },
   {