mercury-agent 0.4.5

package/src/core/handler.ts

@@ -0,0 +1,206 @@
+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 { inferConversationKind, resolveConversation } from "./conversation.js";
+import type { MercuryCoreRuntime } from "./runtime.js";
+import { loadTriggerConfig, matchTrigger } from "./trigger.js";
+
+export interface MessageHandlerOptions {
+  bridge: PlatformBridge;
+  core: MercuryCoreRuntime;
+  config: AppConfig;
+  ctx: NormalizeContext;
+}
+
+export function createMessageHandler(opts: MessageHandlerOptions) {
+  const { bridge, core, config, ctx } = opts;
+  const defaultPatterns = config.triggerPatterns
+    .split(",")
+    .map((s: string) => s.trim())
+    .filter(Boolean);
+
+  return async (
+    adapter: Adapter,
+    threadId: string,
+    message: Message,
+  ): Promise<void> => {
+    try {
+      logger.debug("Incoming message", {
+        adapter: adapter.name,
+        threadId,
+        textPreview: String(message.text ?? "").slice(0, 80),
+        isMe: message.author.isMe,
+      });
+
+      if (message.author.isMe) return;
+
+      const text = message.text.trim();
+      const looksLikeMedia =
+        bridge.platform === "telegram"
+          ? telegramInboundLooksLikeMedia(message)
+          : (message.attachments?.length ?? 0) > 0;
+      if (!text && !looksLikeMedia) {
+        return;
+      }
+
+      const { externalId, isDM } = bridge.parseThread(threadId);
+      const kind = inferConversationKind(bridge.platform, externalId, isDM);
+      const resolution = resolveConversation(
+        core.db,
+        bridge.platform,
+        externalId,
+        kind,
+      );
+
+      if (!resolution) {
+        logger.debug("Message ignored: conversation not linked to a space", {
+          platform: bridge.platform,
+          externalId,
+          kind,
+        });
+        return;
+      }
+
+      const { spaceId } = resolution;
+
+      const triggerConfig = loadTriggerConfig(core.db, spaceId, {
+        patterns: defaultPatterns,
+        match: config.triggerMatch,
+      });
+      const hasAttachments = looksLikeMedia;
+      const triggerResult = matchTrigger(
+        text,
+        triggerConfig,
+        isDM,
+        hasAttachments,
+      );
+
+      if (triggerResult.matched) {
+        try {
+          await adapter.startTyping(threadId);
+        } catch {
+          // Best-effort typing indicator
+        }
+      }
+
+      const ingress = await bridge.normalize(threadId, message, ctx, spaceId);
+      if (!ingress) return;
+
+      logger.info(
+        `Message from: ${ingress.callerId}${ingress.authorName ? ` (${ingress.authorName})` : ""}`,
+      );
+
+      if (ingress.isReplyToBot && !isDM && !triggerResult.matched) {
+        try {
+          await adapter.startTyping(threadId);
+        } catch {
+          // Best-effort typing indicator
+        }
+      }
+
+      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);
+      }
+
+      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,
+          );
+
+          // 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,
+            );
+          }
+        }
+      }
+    } catch (err) {
+      logger.error("Message handler error", {
+        platform: bridge.platform,
+        threadId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  };
+}

package/src/core/media.ts

@@ -0,0 +1,200 @@
+/**
+ * Shared media utilities for ingress/egress pipeline.
+ *
+ * - MIME detection (filename → MIME, MIME → extension, MIME → MediaType)
+ * - Generic URL-based media downloader (for Discord, Slack attachments)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../logger.js";
+import type { MediaType, MessageAttachment } from "../types.js";
+
+// ─── MIME Maps ──────────────────────────────────────────────────────────
+
+/** Extension → MIME type */
+const EXT_TO_MIME: Record<string, string> = {
+  // Images
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  // Audio
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  wav: "audio/wav",
+  // Video
+  mp4: "video/mp4",
+  "3gp": "video/3gpp",
+  webm: "video/webm",
+  // Documents
+  pdf: "application/pdf",
+  txt: "text/plain",
+  csv: "text/csv",
+  json: "application/json",
+  html: "text/html",
+  md: "text/markdown",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+
+/** MIME type → extension */
+const MIME_TO_EXT: Record<string, string> = {
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/svg+xml": "svg",
+  "audio/ogg": "ogg",
+  "audio/ogg; codecs=opus": "ogg",
+  "audio/mpeg": "mp3",
+  "audio/mp4": "m4a",
+  "audio/aac": "aac",
+  "audio/wav": "wav",
+  "video/mp4": "mp4",
+  "video/3gpp": "3gp",
+  "video/webm": "webm",
+  "application/pdf": "pdf",
+  "text/plain": "txt",
+  "text/csv": "csv",
+  "application/json": "json",
+  "text/html": "html",
+  "text/markdown": "md",
+  "application/msword": "doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    "docx",
+  "application/vnd.ms-excel": "xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+};
+
+// ─── MIME Utilities ─────────────────────────────────────────────────────
+
+/** Detect MIME type from filename extension. */
+export function extToMime(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  return EXT_TO_MIME[ext] ?? "application/octet-stream";
+}
+
+/** Get file extension from MIME type. Handles MIME params (e.g., "audio/ogg; codecs=opus"). */
+export function mimeToExt(mimeType: string): string {
+  const baseMime = mimeType.split(";")[0].trim();
+  return MIME_TO_EXT[baseMime] ?? MIME_TO_EXT[mimeType] ?? "bin";
+}
+
+/** Classify MIME type into MediaType. */
+export function mimeToMediaType(mimeType: string): MediaType {
+  const base = mimeType.split(";")[0].trim();
+  if (base.startsWith("image/")) return "image";
+  if (base.startsWith("video/")) return "video";
+  if (base.startsWith("audio/")) return "audio";
+  return "document";
+}
+
+// ─── URL-based Media Downloader ─────────────────────────────────────────
+
+/**
+ * Download a file from a URL to a local directory.
+ *
+ * Used by Discord and Slack bridges to fetch attachments to workspace inbox/.
+ * Returns a MessageAttachment on success, null if skipped or failed.
+ */
+export async function downloadMediaFromUrl(
+  url: string,
+  options: {
+    type: MediaType;
+    mimeType: string;
+    filename?: string;
+    expectedSizeBytes?: number;
+    maxSizeBytes: number;
+    outputDir: string;
+    headers?: Record<string, string>;
+  },
+): Promise<MessageAttachment | null> {
+  const { maxSizeBytes, outputDir, headers } = options;
+
+  // Check expected size before downloading
+  if (options.expectedSizeBytes && options.expectedSizeBytes > maxSizeBytes) {
+    logger.warn("Skipping large media file", {
+      url: url.slice(0, 100),
+      type: options.type,
+      sizeBytes: options.expectedSizeBytes,
+      maxBytes: maxSizeBytes,
+    });
+    return null;
+  }
+
+  try {
+    const response = await fetch(url, {
+      headers: headers ?? {},
+    });
+
+    if (!response.ok) {
+      logger.error("Media download failed", {
+        url: url.slice(0, 100),
+        status: response.status,
+      });
+      return null;
+    }
+
+    // Check Content-Length header before buffering
+    const contentLength = response.headers.get("content-length");
+    if (contentLength && Number.parseInt(contentLength, 10) > maxSizeBytes) {
+      logger.warn("Media download exceeds size limit", {
+        url: url.slice(0, 100),
+        sizeBytes: Number.parseInt(contentLength, 10),
+        maxBytes: maxSizeBytes,
+      });
+      return null;
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+
+    // Check actual size after download
+    if (buffer.length > maxSizeBytes) {
+      logger.warn("Downloaded media exceeds size limit, discarding", {
+        sizeBytes: buffer.length,
+        maxBytes: maxSizeBytes,
+      });
+      return null;
+    }
+
+    // Ensure output directory exists
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    // Generate filename: {timestamp}-{original} or {timestamp}-{type}.{ext}
+    const ext = mimeToExt(options.mimeType);
+    const filename = options.filename
+      ? `${Date.now()}-${options.filename}`
+      : `${Date.now()}-${options.type}.${ext}`;
+
+    const filePath = path.join(outputDir, filename);
+    fs.writeFileSync(filePath, buffer);
+
+    logger.info("Downloaded media", {
+      type: options.type,
+      mimeType: options.mimeType,
+      sizeBytes: buffer.length,
+      path: filePath,
+    });
+
+    return {
+      path: filePath,
+      type: options.type,
+      mimeType: options.mimeType,
+      filename: options.filename,
+      sizeBytes: buffer.length,
+    };
+  } catch (error) {
+    logger.error("Failed to download media", {
+      url: url.slice(0, 100),
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}

package/src/core/mute-duration.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse a duration string like "10m", "1h", "24h", "7d" into milliseconds.
+ */
+export function parseMuteDuration(input: string): number | null {
+  const match = input.match(/^(\d+)\s*(m|min|h|hr|d|day)s?$/i);
+  if (!match) return null;
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "m":
+    case "min":
+      return value * 60 * 1000;
+    case "h":
+    case "hr":
+      return value * 60 * 60 * 1000;
+    case "d":
+    case "day":
+      return value * 24 * 60 * 60 * 1000;
+    default:
+      return null;
+  }
+}

package/src/core/outbox.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../logger.js";
+import type { EgressFile } from "../types.js";
+import { extToMime } from "./media.js";
+
+/** Default max file size for outbox files (25 MB) */
+const DEFAULT_MAX_FILE_SIZE = 25 * 1024 * 1024;
+
+/**
+ * Scan outbox/ for files created or modified during a container run.
+ *
+ * Files with mtime >= startTimeMs are considered new or modified.
+ * Skips dotfiles, directories, and files exceeding maxSizeBytes.
+ * Non-recursive (one level only).
+ */
+export function scanOutbox(
+  workspacePath: string,
+  startTimeMs: number,
+  maxSizeBytes = DEFAULT_MAX_FILE_SIZE,
+): EgressFile[] {
+  const outboxDir = path.join(workspacePath, "outbox");
+
+  if (!fs.existsSync(outboxDir)) return [];
+
+  const files: EgressFile[] = [];
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(outboxDir, { withFileTypes: true });
+  } catch (error) {
+    logger.warn("Failed to read outbox directory", {
+      outboxDir,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (entry.name.startsWith(".")) continue;
+
+    const filePath = path.join(outboxDir, entry.name);
+
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(filePath);
+    } catch (error) {
+      logger.warn("Failed to stat outbox file, skipping", {
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+
+    if (stat.mtimeMs < startTimeMs) continue;
+
+    if (stat.size > maxSizeBytes) {
+      logger.warn("Outbox file exceeds max size, skipping", {
+        path: filePath,
+        sizeBytes: stat.size,
+        maxSizeBytes,
+      });
+      continue;
+    }
+
+    files.push({
+      path: filePath,
+      filename: entry.name,
+      mimeType: extToMime(entry.name),
+      sizeBytes: stat.size,
+    });
+  }
+
+  return files;
+}

package/src/core/permissions.ts

@@ -0,0 +1,192 @@
+import type { Db } from "../storage/db.js";
+
+// ---------------------------------------------------------------------------
+// Built-in permissions (static, cannot be overridden)
+// ---------------------------------------------------------------------------
+
+const BUILT_IN_PERMISSIONS = new Set([
+  "prompt",
+  "stop",
+  "compact",
+  "clear",
+  "tasks.list",
+  "tasks.create",
+  "tasks.pause",
+  "tasks.resume",
+  "tasks.delete",
+  "config.get",
+  "config.set",
+  "prefs.get",
+  "prefs.set",
+  "roles.list",
+  "roles.grant",
+  "roles.revoke",
+  "permissions.get",
+  "permissions.set",
+  "spaces.list",
+  "spaces.rename",
+  "spaces.delete",
+  /** Purge inbox/outbox media files. */
+  "media.purge",
+  /** Host Text-to-Speech (/api/tts); admin-only by default. */
+  "tts.synthesize",
+]);
+
+// ---------------------------------------------------------------------------
+// Extension-registered permissions (dynamic, added at runtime)
+// ---------------------------------------------------------------------------
+
+const registeredPermissions = new Map<string, { defaultRoles: string[] }>();
+
+/**
+ * Register a new permission from an extension.
+ * Throws if the name collides with a built-in permission.
+ */
+export function registerPermission(
+  name: string,
+  opts: { defaultRoles: string[] },
+): void {
+  if (BUILT_IN_PERMISSIONS.has(name)) {
+    throw new Error(
+      `Permission "${name}" is a built-in and cannot be overridden`,
+    );
+  }
+  registeredPermissions.set(name, opts);
+}
+
+/**
+ * Get all valid permission names (built-in + extension-registered).
+ */
+export function getAllPermissions(): string[] {
+  return [...BUILT_IN_PERMISSIONS, ...registeredPermissions.keys()];
+}
+
+/**
+ * Check if a permission name is valid (built-in or registered).
+ */
+export function isValidPermission(name: string): boolean {
+  return BUILT_IN_PERMISSIONS.has(name) || registeredPermissions.has(name);
+}
+
+/**
+ * Clear all registered extension permissions. For test isolation only.
+ */
+export function resetPermissions(): void {
+  registeredPermissions.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Seeded groups tracking
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks which groups have had admins seeded to avoid redundant DB calls.
+ * Exported for test isolation (tests should clear this in beforeEach).
+ */
+export const seededSpaces = new Set<string>();
+
+// ---------------------------------------------------------------------------
+// System callers
+// ---------------------------------------------------------------------------
+
+/**
+ * System callers — these identities get full permissions without DB lookup.
+ * Used for scheduled tasks, internal system calls, etc.
+ */
+const SYSTEM_CALLERS = new Set(["system"]);
+
+export function isSystemCaller(callerId: string): boolean {
+  return SYSTEM_CALLERS.has(callerId);
+}
+
+// ---------------------------------------------------------------------------
+// Default role permissions
+// ---------------------------------------------------------------------------
+
+/** Built-in defaults for the member role */
+const DEFAULT_MEMBER_PERMISSIONS = new Set(["prompt", "prefs.get"]);
+
+/**
+ * Compute the default permission set for a role, merging built-in defaults
+ * with extension-registered defaults.
+ *
+ * - `admin` and `system` get all permissions (built-in + extension)
+ * - `member` gets `prompt`, `prefs.get`, plus any extension permissions that list "member" in defaultRoles
+ * - Other roles get extension permissions that list them in defaultRoles
+ */
+function getDefaultPermissions(role: string): Set<string> {
+  if (role === "admin" || role === "system") {
+    return new Set(getAllPermissions());
+  }
+
+  const perms = new Set<string>(
+    role === "member" ? DEFAULT_MEMBER_PERMISSIONS : [],
+  );
+
+  for (const [name, opts] of registeredPermissions) {
+    if (opts.defaultRoles.includes(role)) {
+      perms.add(name);
+    }
+  }
+
+  return perms;
+}
+
+// ---------------------------------------------------------------------------
+// Permission resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the permission set for a role in a group.
+ * Checks group_config for "role.<name>.permissions" override,
+ * falls back to defaults (built-in + extension).
+ */
+export function getRolePermissions(
+  db: Db,
+  spaceId: string,
+  role: string,
+): Set<string> {
+  if (role === "system") return getDefaultPermissions("system");
+
+  const key = `role.${role}.permissions`;
+  const stored = db.getSpaceConfig(spaceId, key);
+
+  if (stored !== null) {
+    const perms = stored
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => isValidPermission(s));
+    return new Set(perms);
+  }
+
+  return getDefaultPermissions(role);
+}
+
+export function hasPermission(
+  db: Db,
+  spaceId: string,
+  role: string,
+  permission: string,
+): boolean {
+  return getRolePermissions(db, spaceId, role).has(permission);
+}
+
+export function resolveRole(
+  db: Db,
+  spaceId: string,
+  platformUserId: string,
+  seededAdmins: string[],
+  displayName?: string | null,
+): string {
+  // System callers bypass DB entirely
+  if (isSystemCaller(platformUserId)) return "system";
+
+  if (seededAdmins.length > 0 && !seededSpaces.has(spaceId)) {
+    db.seedAdmins(spaceId, seededAdmins);
+    seededSpaces.add(spaceId);
+  }
+
+  db.upsertMember(spaceId, platformUserId, displayName);
+
+  return db.getRole(spaceId, platformUserId) ?? "member";
+}