mercury-agent 0.4.5

package/src/agent/user-error-messages.ts

@@ -0,0 +1,78 @@
+export type UserErrorCategory =
+  | "auth"
+  | "key-limit"
+  | "credits"
+  | "rate-limit"
+  | "server-error"
+  | "generic";
+
+const AUTH_RE =
+  /\b401\b|\b403\b|invalid\s+api\s+key|incorrect\s+api\s+key|authentication\s+failed|invalid\s+authentication|unauthorized|access\s+denied/i;
+
+const KEY_LIMIT_RE = /quota|billing|usage\s+limit|spending\s+limit/i;
+
+const CREDITS_RE =
+  /\b402\b|insufficient\s+credits?|not\s+enough\s+credits?|purchase\s+(more\s+)?credits?|no\s+credits?/i;
+
+const RATE_LIMIT_RE = /\b429\b|rate[_\s]+limit/i;
+
+const SERVER_ERROR_RE =
+  /\b502\b|\b503\b|\b504\b|timeout|timed\s+out|ETIMEDOUT|ECONNRESET|temporarily\s+unavailable|overload|service\s+unavailable|bad\s+gateway|gateway\s+timeout/i;
+
+export function classifyUserError(errorText: string): UserErrorCategory {
+  if (AUTH_RE.test(errorText)) return "auth";
+  if (KEY_LIMIT_RE.test(errorText)) return "key-limit";
+  if (CREDITS_RE.test(errorText)) return "credits";
+  if (RATE_LIMIT_RE.test(errorText)) return "rate-limit";
+  if (SERVER_ERROR_RE.test(errorText)) return "server-error";
+  return "generic";
+}
+
+const MESSAGES: Record<UserErrorCategory, { platform: string; byok: string }> =
+  {
+    "key-limit": {
+      platform: "I've reached my usage limit for now. Please try again later.",
+      byok: "Your API key has hit its spending limit. Check your provider's key settings to increase it.",
+    },
+    "rate-limit": {
+      platform:
+        "I'm handling too many requests right now — please try again in a moment.",
+      byok: "Your API key is being rate-limited. Try again in a moment.",
+    },
+    auth: {
+      platform:
+        "Something went wrong on my end. This has been logged and the admin will be notified.",
+      byok: "Your API key appears to be invalid or expired. Please update it.",
+    },
+    credits: {
+      platform: "I've reached my usage limit for now. Please try again later.",
+      byok: "Your API provider account has insufficient credits. Add credits to continue.",
+    },
+    "server-error": {
+      platform:
+        "The AI service is temporarily unavailable. Please try again in a few minutes.",
+      byok: "The AI service is temporarily unavailable. Please try again in a few minutes.",
+    },
+    generic: {
+      platform:
+        "Something went wrong processing your request. Please try again.",
+      byok: "Something went wrong processing your request. Please try again, or check your API key and provider status.",
+    },
+  };
+
+export function friendlyErrorMessage(
+  category: UserErrorCategory,
+  mode: "platform" | "byok",
+  consoleUrl?: string,
+): string {
+  let message = MESSAGES[category][mode];
+  const base = consoleUrl?.replace(/\/+$/, "");
+  if (base && mode === "platform") {
+    if (category === "key-limit" || category === "credits") {
+      message += `\n\nUpgrade your plan: ${base}/dashboard/billing`;
+    } else if (category === "auth") {
+      return `Your Anthropic session has expired. Please reconnect: ${base}/dashboard/model`;
+    }
+  }
+  return message;
+}

package/src/bridges/discord.ts

@@ -0,0 +1,171 @@
+import path from "node:path";
+import type { Message } from "chat";
+import type { DiscordNativeAdapter } from "../adapters/discord-native.js";
+import { downloadMediaFromUrl, mimeToMediaType } from "../core/media.js";
+import { logger } from "../logger.js";
+import type {
+  EgressFile,
+  IngressMessage,
+  MessageAttachment,
+  NormalizeContext,
+  PlatformBridge,
+} from "../types.js";
+
+export class DiscordBridge implements PlatformBridge {
+  readonly platform = "discord";
+
+  constructor(private readonly adapter: DiscordNativeAdapter) {}
+
+  parseThread(threadId: string): { externalId: string; isDM: boolean } {
+    const parts = threadId.split(":");
+    const externalId = parts.slice(1).join(":");
+    const isDM = parts.length >= 2 && parts[1] === "@me";
+    return { externalId, isDM };
+  }
+
+  async normalize(
+    threadId: string,
+    message: unknown,
+    ctx: NormalizeContext,
+    spaceId: string,
+  ): Promise<IngressMessage | null> {
+    const msg = message as Message;
+    if (msg.author.isMe) return null;
+
+    let text = msg.text.trim();
+    const rawAttachments = msg.attachments ?? [];
+    if (!text && rawAttachments.length === 0) return null;
+
+    const botUserId = this.adapter.botUserId;
+    if (botUserId) {
+      text = text.replace(
+        new RegExp(`<@!?${botUserId}>`, "g"),
+        `@${ctx.botUserName}`,
+      );
+    }
+
+    const metadata = msg.metadata as {
+      isReplyToBot?: boolean;
+      replyToMessageId?: string;
+      platformMessageId?: string;
+    };
+    const isReplyToBot = metadata?.isReplyToBot ?? false;
+
+    const attachments: MessageAttachment[] = [];
+    if (ctx.media.enabled && rawAttachments.length > 0) {
+      if (await ctx.isOverQuota()) {
+        logger.warn("Skipping media download — storage quota exceeded", {
+          spaceId,
+        });
+      } else {
+        const workspace = ctx.getWorkspace(spaceId);
+        const inboxDir = path.join(workspace, "inbox");
+        for (const att of rawAttachments) {
+          if (!att.url) continue;
+          const type = mimeToMediaType(
+            att.mimeType || "application/octet-stream",
+          );
+          const result = await downloadMediaFromUrl(att.url, {
+            type,
+            mimeType: att.mimeType || "application/octet-stream",
+            filename: att.name,
+            expectedSizeBytes: att.size,
+            maxSizeBytes: ctx.media.maxSizeBytes,
+            outputDir: inboxDir,
+          });
+          if (result) attachments.push(result);
+        }
+      }
+    }
+
+    const { externalId, isDM } = this.parseThread(threadId);
+
+    return {
+      platform: "discord",
+      spaceId,
+      conversationExternalId: externalId,
+      callerId: `discord:${msg.author.userId || "unknown"}`,
+      authorName: msg.author.userName,
+      text,
+      isDM,
+      isReplyToBot,
+      attachments,
+      replyToPlatformMessageId: metadata?.replyToMessageId ?? undefined,
+      platformMessageId: metadata?.platformMessageId ?? undefined,
+    };
+  }
+
+  async sendReply(
+    threadId: string,
+    text: string,
+    files?: EgressFile[],
+  ): Promise<string | undefined> {
+    if (files && files.length > 0) {
+      return this.sendWithFiles(threadId, text, files);
+    } else if (text) {
+      const sent = await this.adapter.postMessage(threadId, text);
+      return sent.id;
+    }
+    return undefined;
+  }
+
+  async deleteMessages(threadId: string, messageIds: string[]): Promise<void> {
+    for (const id of messageIds) {
+      try {
+        await this.adapter.deleteMessage(threadId, id);
+      } catch (err) {
+        logger.debug("Discord deleteMessage failed (best-effort)", {
+          messageId: id,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  private async sendWithFiles(
+    threadId: string,
+    text: string,
+    files: EgressFile[],
+  ): Promise<string | undefined> {
+    const client = this.adapter.discordClient;
+    const { channelId, threadId: discordThreadId } =
+      this.adapter.decodeThreadId(threadId);
+    const targetId = discordThreadId || channelId;
+
+    try {
+      const channel = await client.channels.fetch(targetId);
+      if (!channel || !("send" in channel)) {
+        logger.warn("Discord channel not sendable, falling back to text-only", {
+          targetId,
+        });
+        if (text) {
+          const sent = await this.adapter.postMessage(threadId, text);
+          return sent.id;
+        }
+        return undefined;
+      }
+
+      const discordFiles = files.map((f) => ({
+        attachment: f.path,
+        name: f.filename,
+      }));
+
+      const sent = await (
+        channel as { send: (opts: unknown) => Promise<{ id: string }> }
+      ).send({
+        content: text || undefined,
+        files: discordFiles,
+      });
+      return sent?.id;
+    } catch (err) {
+      logger.error("Failed to send files via Discord", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      if (text) {
+        const sent = await this.adapter.postMessage(threadId, text);
+        return sent.id;
+      }
+      return undefined;
+    }
+  }
+}

package/src/bridges/slack.ts

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Adapter, Message } from "chat";
+import { downloadMediaFromUrl, mimeToMediaType } from "../core/media.js";
+import { logger } from "../logger.js";
+import type {
+  EgressFile,
+  IngressMessage,
+  MessageAttachment,
+  NormalizeContext,
+  PlatformBridge,
+} from "../types.js";
+
+export class SlackBridge implements PlatformBridge {
+  readonly platform = "slack";
+
+  constructor(
+    private readonly adapter: Adapter,
+    private readonly botToken: string,
+  ) {}
+
+  parseThread(threadId: string): { externalId: string; isDM: boolean } {
+    const parts = threadId.split(":");
+    const externalId = parts.slice(1).join(":");
+    const ch = parts[1] || "";
+    const isDM = ch.startsWith("D") || ch.startsWith("G");
+    return { externalId, isDM };
+  }
+
+  async normalize(
+    threadId: string,
+    message: unknown,
+    ctx: NormalizeContext,
+    spaceId: string,
+  ): Promise<IngressMessage | null> {
+    const msg = message as Message;
+    if (msg.author.isMe) return null;
+
+    const text = msg.text.trim();
+    const rawAttachments = msg.attachments ?? [];
+    if (!text && rawAttachments.length === 0) return null;
+
+    const attachments: MessageAttachment[] = [];
+    if (ctx.media.enabled && rawAttachments.length > 0) {
+      if (await ctx.isOverQuota()) {
+        logger.warn("Skipping media download — storage quota exceeded", {
+          spaceId,
+        });
+      } else {
+        const workspace = ctx.getWorkspace(spaceId);
+        const inboxDir = path.join(workspace, "inbox");
+        for (const att of rawAttachments) {
+          const url = att.url || (att as { url_private?: string }).url_private;
+          if (!url) continue;
+          const type = mimeToMediaType(
+            att.mimeType || "application/octet-stream",
+          );
+          const result = await downloadMediaFromUrl(url, {
+            type,
+            mimeType: att.mimeType || "application/octet-stream",
+            filename: att.name,
+            expectedSizeBytes: att.size,
+            maxSizeBytes: ctx.media.maxSizeBytes,
+            outputDir: inboxDir,
+            headers: { Authorization: `Bearer ${this.botToken}` },
+          });
+          if (result) attachments.push(result);
+        }
+      }
+    }
+
+    const { externalId, isDM } = this.parseThread(threadId);
+
+    // Extract Slack-specific fields from raw event for reply chain tracking
+    const raw = msg.raw as
+      | {
+          ts?: string;
+          thread_ts?: string;
+        }
+      | undefined;
+    const slackTs = raw?.ts;
+    const slackThreadTs = raw?.thread_ts;
+    // In Slack, a threaded reply has thread_ts pointing to the parent message.
+    // isReplyToBot: we can't determine this without knowing the parent author;
+    // will be resolved via platform ID lookup in the runtime.
+    const isReplyToBot =
+      (msg.metadata as { isReplyToBot?: boolean })?.isReplyToBot ?? false;
+
+    return {
+      platform: "slack",
+      spaceId,
+      conversationExternalId: externalId,
+      callerId: `slack:${msg.author.userId || "unknown"}`,
+      authorName: msg.author.userName,
+      text,
+      isDM,
+      isReplyToBot,
+      attachments,
+      replyToPlatformMessageId:
+        slackThreadTs && slackThreadTs !== slackTs ? slackThreadTs : undefined,
+      platformMessageId: slackTs,
+    };
+  }
+
+  async sendReply(
+    threadId: string,
+    text: string,
+    files?: EgressFile[],
+  ): Promise<string | undefined> {
+    let sentPlatformId: string | undefined;
+    if (text) {
+      const sent = await this.adapter.postMessage(threadId, text);
+      sentPlatformId = sent.id;
+    }
+
+    if (files && files.length > 0) {
+      await this.uploadFiles(threadId, files);
+    }
+
+    return sentPlatformId;
+  }
+
+  async deleteMessages(
+    _threadId: string,
+    _messageIds: string[],
+  ): Promise<void> {
+    // Slack delete not implemented — silent no-op for v1
+  }
+
+  private async uploadFiles(
+    threadId: string,
+    files: EgressFile[],
+  ): Promise<void> {
+    const parts = threadId.split(":");
+    const channelId = parts.length >= 2 ? parts[1] : threadId;
+
+    for (const file of files) {
+      try {
+        const buffer = fs.readFileSync(file.path);
+        const form = new FormData();
+        form.append("channel_id", channelId);
+        form.append("filename", file.filename);
+        form.append(
+          "file",
+          new Blob([buffer], { type: file.mimeType }),
+          file.filename,
+        );
+
+        const resp = await fetch("https://slack.com/api/files.uploadV2", {
+          method: "POST",
+          headers: { Authorization: `Bearer ${this.botToken}` },
+          body: form,
+        });
+
+        if (!resp.ok) {
+          logger.error("Slack file upload HTTP error", {
+            filename: file.filename,
+            status: resp.status,
+          });
+        } else {
+          const body = (await resp.json()) as { ok?: boolean; error?: string };
+          if (!body.ok) {
+            logger.error("Slack file upload API error", {
+              filename: file.filename,
+              error: body.error,
+            });
+          }
+        }
+      } catch (err) {
+        logger.error("Slack file upload failed", {
+          filename: file.filename,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+}

package/src/bridges/teams.ts

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Adapter, Message } from "chat";
+import { downloadMediaFromUrl, mimeToMediaType } from "../core/media.js";
+import { logger } from "../logger.js";
+import type {
+  EgressFile,
+  IngressMessage,
+  MessageAttachment,
+  NormalizeContext,
+  PlatformBridge,
+} from "../types.js";
+
+export class TeamsBridge implements PlatformBridge {
+  readonly platform = "teams";
+
+  constructor(private readonly adapter: Adapter) {}
+
+  parseThread(threadId: string): { externalId: string; isDM: boolean } {
+    // Teams thread IDs are "teams:<base64url-conversationId>:<base64url-serviceUrl>"
+    const parts = threadId.split(":");
+    const externalId = parts.slice(1).join(":");
+
+    // Teams DMs have conversation IDs that don't start with "19:"
+    // The conversationId is base64url-encoded in parts[1]
+    let isDM = true;
+    try {
+      const conversationId = Buffer.from(parts[1] || "", "base64url").toString(
+        "utf-8",
+      );
+      isDM = !conversationId.startsWith("19:");
+    } catch {
+      // If decoding fails, assume DM
+    }
+
+    return { externalId, isDM };
+  }
+
+  async normalize(
+    threadId: string,
+    message: unknown,
+    ctx: NormalizeContext,
+    spaceId: string,
+  ): Promise<IngressMessage | null> {
+    const msg = message as Message;
+    if (msg.author.isMe) return null;
+
+    const text = msg.text.trim();
+    const rawAttachments = msg.attachments ?? [];
+    if (!text && rawAttachments.length === 0) return null;
+
+    // Download media attachments
+    const attachments: MessageAttachment[] = [];
+    if (ctx.media.enabled && rawAttachments.length > 0) {
+      const workspace = ctx.getWorkspace(spaceId);
+      const inboxDir = path.join(workspace, "inbox");
+      for (const att of rawAttachments) {
+        if (!att.url) continue;
+        const type = mimeToMediaType(
+          att.mimeType || "application/octet-stream",
+        );
+        const result = await downloadMediaFromUrl(att.url, {
+          type,
+          mimeType: att.mimeType || "application/octet-stream",
+          filename: att.name,
+          expectedSizeBytes: att.size,
+          maxSizeBytes: ctx.media.maxSizeBytes,
+          outputDir: inboxDir,
+        });
+        if (result) attachments.push(result);
+      }
+    }
+
+    const { externalId, isDM } = this.parseThread(threadId);
+
+    // Check reply-to-bot via raw activity
+    const raw = msg.raw as { replyToId?: string; id?: string } | undefined;
+    const isReplyToBot = Boolean(raw?.replyToId);
+
+    return {
+      platform: "teams",
+      spaceId,
+      conversationExternalId: externalId,
+      callerId: `teams:${msg.author.userId || "unknown"}`,
+      authorName: msg.author.userName,
+      text,
+      isDM,
+      isReplyToBot,
+      attachments,
+      replyToPlatformMessageId: raw?.replyToId ?? undefined,
+      platformMessageId: raw?.id ?? msg.id,
+    };
+  }
+
+  async sendReply(
+    threadId: string,
+    text: string,
+    files?: EgressFile[],
+  ): Promise<string | undefined> {
+    if (files && files.length > 0) {
+      return this.sendWithFiles(threadId, text, files);
+    } else if (text) {
+      const sent = await this.adapter.postMessage(threadId, text);
+      return sent.id;
+    }
+    return undefined;
+  }
+
+  async deleteMessages(
+    _threadId: string,
+    _messageIds: string[],
+  ): Promise<void> {
+    // Teams delete not implemented — silent no-op for v1
+  }
+
+  private async sendWithFiles(
+    threadId: string,
+    text: string,
+    files: EgressFile[],
+  ): Promise<string | undefined> {
+    // Build file uploads from EgressFile paths
+    const fileUploads: { filename: string; mimeType: string; data: Buffer }[] =
+      [];
+    for (const file of files) {
+      try {
+        const buffer = fs.readFileSync(file.path);
+        fileUploads.push({
+          filename: file.filename,
+          mimeType: file.mimeType,
+          data: buffer,
+        });
+      } catch (err) {
+        logger.error("Failed to read egress file", {
+          path: file.path,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Send text + files together via postMessage
+    // Teams adapter extracts files from the message object and converts to inline attachments
+    try {
+      const sent = await this.adapter.postMessage(threadId, {
+        markdown: text || "",
+        files: fileUploads,
+      } as never);
+      return sent.id;
+    } catch (err) {
+      logger.error("Teams send with files failed", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      // Fall back to text-only
+      if (text) {
+        const sent = await this.adapter.postMessage(threadId, text);
+        return sent.id;
+      }
+      return undefined;
+    }
+  }
+}