mercury-agent 0.4.5

package/src/core/routes/chat.ts

@@ -0,0 +1,172 @@
+import { timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Hono } from "hono";
+import { logger } from "../../logger.js";
+import { ensureSpaceWorkspace } from "../../storage/memory.js";
+import type { IngressMessage, MessageAttachment } from "../../types.js";
+import { extToMime, mimeToMediaType } from "../media.js";
+import type { MercuryCoreRuntime } from "../runtime.js";
+import { isOverQuota } from "../storage-guard.js";
+
+interface ChatFileInput {
+  name: string;
+  data: string; // base64
+}
+
+interface ChatFileOutput {
+  filename: string;
+  mimeType: string;
+  sizeBytes: number;
+  data: string; // base64
+}
+
+export function createChatRoute(core: MercuryCoreRuntime): Hono {
+  const app = new Hono();
+
+  app.post("/", async (c) => {
+    // Validate chat API key when configured
+    const chatApiKey = core.config.chatApiKey;
+    let authenticated = false;
+    if (chatApiKey) {
+      const authHeader = c.req.header("authorization");
+      const token = authHeader?.startsWith("Bearer ")
+        ? authHeader.slice(7)
+        : undefined;
+
+      if (
+        !token ||
+        token.length !== chatApiKey.length ||
+        !timingSafeEqual(Buffer.from(token), Buffer.from(chatApiKey))
+      ) {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+      authenticated = true;
+    }
+
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.text !== "string" || !body.text.trim()) {
+      return c.json({ error: "Missing or empty 'text' field" }, 400);
+    }
+
+    const callerId =
+      typeof body.callerId === "string" && body.callerId.trim()
+        ? body.callerId.trim()
+        : "api:anonymous";
+
+    const spaceId =
+      typeof body.spaceId === "string" && body.spaceId.trim()
+        ? body.spaceId.trim()
+        : "main";
+
+    const authorName =
+      typeof body.authorName === "string" ? body.authorName.trim() : undefined;
+
+    // Save incoming files to inbox/
+    const attachments: MessageAttachment[] = [];
+    if (Array.isArray(body.files)) {
+      if (await isOverQuota(core.config)) {
+        return c.json({ error: "Storage quota exceeded" }, 413);
+      }
+      const workspace = ensureSpaceWorkspace(core.config.spacesDir, spaceId);
+      const inboxDir = path.join(workspace, "inbox");
+      fs.mkdirSync(inboxDir, { recursive: true });
+
+      for (const file of body.files as ChatFileInput[]) {
+        if (!file.name || !file.data) continue;
+        try {
+          const buffer = Buffer.from(file.data, "base64");
+          const safeName = path
+            .basename(file.name)
+            .replace(/[^a-zA-Z0-9._-]/g, "_");
+          const filename = `${Date.now()}-${safeName || "file"}`;
+          const filePath = path.join(inboxDir, filename);
+          fs.writeFileSync(filePath, buffer);
+
+          const mimeType = extToMime(file.name);
+          attachments.push({
+            path: filePath,
+            type: mimeToMediaType(mimeType),
+            mimeType,
+            filename: file.name,
+            sizeBytes: buffer.length,
+          });
+        } catch (err) {
+          logger.warn("Failed to save chat file", {
+            name: file.name,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    if (!core.db.getSpace(spaceId)) {
+      return c.json({ error: "Space not found" }, 404);
+    }
+
+    if (authenticated) {
+      core.db.seedAdmins(spaceId, [callerId]);
+    }
+
+    const ingress: IngressMessage = {
+      platform: "api",
+      spaceId,
+      conversationExternalId: `api:${callerId}`,
+      callerId,
+      authorName,
+      text: body.text.trim(),
+      isDM: true,
+      isReplyToBot: false,
+      attachments,
+    };
+
+    logger.info("API chat inbound", {
+      callerId,
+      spaceId,
+      preview: ingress.text.slice(0, 80),
+      fileCount: attachments.length,
+    });
+
+    const result = await core.handleRawInput(ingress, "cli");
+
+    if (result.type === "ignore") {
+      return c.json({ reply: "", files: [] });
+    }
+
+    if (result.type === "denied") {
+      return c.json({ error: result.reason }, 403);
+    }
+
+    const reply = result.result?.reply ?? "";
+    const egressFiles = result.result?.files ?? [];
+
+    // Encode outbox files as base64
+    const outputFiles: ChatFileOutput[] = [];
+    for (const f of egressFiles) {
+      try {
+        const buffer = fs.readFileSync(f.path);
+        outputFiles.push({
+          filename: f.filename,
+          mimeType: f.mimeType,
+          sizeBytes: f.sizeBytes,
+          data: buffer.toString("base64"),
+        });
+      } catch (err) {
+        logger.warn("Failed to read outbox file for chat response", {
+          path: f.path,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    logger.info("API chat outbound", {
+      spaceId,
+      preview: reply.slice(0, 80),
+      fileCount: outputFiles.length,
+    });
+
+    return c.json({ reply, files: outputFiles });
+  });
+
+  return app;
+}

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

@@ -0,0 +1,107 @@
+/** Built-in space config keys (trigger + ambient). */
+
+export const BUILTIN_CONFIG_KEYS = new Set([
+  "trigger.match",
+  "trigger.patterns",
+  "trigger.case_sensitive",
+  "trigger.media_in_groups",
+  "ambient.enabled",
+  "context.mode",
+  "context.window_size",
+  "context.reply_chain_depth",
+  "security.sensitive_connections_allowed",
+]);
+
+/**
+ * One-line plain-English descriptions for each builtin config key, surfaced as
+ * native browser tooltips on the agent dashboard space-settings rows. The key
+ * set MUST match BUILTIN_CONFIG_KEYS exactly — enforced by
+ * tests/builtin-config-descriptions.test.ts.
+ */
+export const BUILTIN_CONFIG_DESCRIPTIONS: Record<string, string> = {
+  "trigger.match":
+    "How a message triggers the agent: 'mention' (name appears as a word), 'prefix' (message starts with the name), or 'always' (every message).",
+  "trigger.patterns":
+    "Comma-separated list of names/aliases the agent responds to (e.g. '@Mercury, Mercury').",
+  "trigger.case_sensitive":
+    "When true, trigger pattern matching is case-sensitive. When false, case is ignored.",
+  "trigger.media_in_groups":
+    "When true, media-only messages (image/audio with no text) trigger the agent in group chats.",
+  "ambient.enabled":
+    "When true, non-triggered group messages are still stored as ambient context. Set false for strict tag-only mode.",
+  "context.mode":
+    "'clear' = each message starts fresh (reply to bot for chain context). 'context' = include a sliding window of recent turns automatically.",
+  "context.window_size":
+    "Number of recent turns included as context when context.mode=context. Integer 1-50.",
+  "context.reply_chain_depth":
+    "Max number of turns walked back when following a reply chain. Integer 1-50.",
+  "security.sensitive_connections_allowed":
+    "When true, sensitive integrations (e.g. payments, identity) are usable in this group space. False blocks them by default.",
+};
+
+const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
+  "trigger.match": (v) =>
+    ["prefix", "mention", "always"].includes(v)
+      ? null
+      : "Invalid trigger.match value. Valid: prefix, mention, always",
+  "trigger.case_sensitive": (v) =>
+    ["true", "false"].includes(v)
+      ? null
+      : "Invalid trigger.case_sensitive value. Valid: true, false",
+  "trigger.media_in_groups": (v) =>
+    ["true", "false"].includes(v)
+      ? null
+      : "Invalid trigger.media_in_groups value. Valid: true, false",
+  "ambient.enabled": (v) =>
+    ["true", "false"].includes(v)
+      ? null
+      : "Invalid ambient.enabled value. Valid: true, false",
+  "context.mode": (v) =>
+    ["clear", "context"].includes(v)
+      ? null
+      : "Invalid context.mode value. Valid: clear, context",
+  "context.window_size": (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 1 && n <= 50
+      ? null
+      : "Invalid context.window_size value. Must be an integer between 1 and 50";
+  },
+  "context.reply_chain_depth": (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 1 && n <= 50
+      ? null
+      : "Invalid context.reply_chain_depth value. Must be an integer between 1 and 50";
+  },
+  "security.sensitive_connections_allowed": (v) =>
+    ["true", "false"].includes(v)
+      ? null
+      : "Invalid security.sensitive_connections_allowed value. Valid: true, false",
+};
+
+export function isBuiltinConfigKey(key: string): boolean {
+  return BUILTIN_CONFIG_KEYS.has(key);
+}
+
+/**
+ * Validate a built-in space config key/value. Returns an error message or null if valid.
+ * Call only when the key is known to be built-in, or use {@link validateDashboardBuiltinConfig}.
+ */
+export function validateBuiltinConfigValue(
+  key: string,
+  value: string,
+): string | null {
+  const validator = BUILTIN_VALIDATORS[key];
+  if (validator) return validator(value);
+  return null;
+}
+
+/** For dashboard-only updates: key must be built-in. */
+export function validateDashboardBuiltinConfig(
+  key: string,
+  value: string,
+): string | null {
+  if (!isBuiltinConfigKey(key)) {
+    return "Invalid config key for dashboard";
+  }
+  return validateBuiltinConfigValue(key, value);
+}

package/src/core/routes/config.ts

@@ -0,0 +1,81 @@
+import { Hono } from "hono";
+import { checkPerm, type Env, getApiCtx, getAuth } from "../api-types.js";
+import {
+  isBuiltinConfigKey,
+  validateBuiltinConfigValue,
+} from "./config-builtin.js";
+
+export const config = new Hono<Env>();
+
+config.get("/", (c) => {
+  const { spaceId } = getAuth(c);
+  const denied = checkPerm(c, "config.get");
+  if (denied) return denied;
+
+  const { db, configRegistry } = getApiCtx(c);
+  const entries = db.listSpaceConfig(spaceId);
+  const configMap: Record<string, string> = {};
+  for (const e of entries) configMap[e.key] = e.value;
+
+  // Include registered extension config keys with descriptions and defaults
+  const available = configRegistry.getAll().map((rc) => ({
+    key: rc.key,
+    description: rc.description,
+    default: rc.default,
+  }));
+
+  return c.json({ spaceId, config: configMap, available });
+});
+
+config.put("/", async (c) => {
+  const { spaceId, callerId } = getAuth(c);
+  const denied = checkPerm(c, "config.set");
+  if (denied) return denied;
+
+  const { db, configRegistry } = getApiCtx(c);
+  const body = await c.req.json<{ key?: string; value?: string }>();
+
+  if (!body.key || body.value === undefined) {
+    return c.json({ error: "Missing key or value" }, 400);
+  }
+
+  const isBuiltin = isBuiltinConfigKey(body.key);
+  const isExtension = configRegistry.isValidKey(body.key);
+
+  if (!isBuiltin && !isExtension) {
+    return c.json(
+      {
+        error: `Invalid config key. Run mrctl config get for valid keys.`,
+      },
+      400,
+    );
+  }
+
+  if (isBuiltin) {
+    const error = validateBuiltinConfigValue(body.key, body.value);
+    if (error) return c.json({ error }, 400);
+
+    // Extra guard: enabling sensitive connections on a DM-only space has no effect
+    if (
+      body.key === "security.sensitive_connections_allowed" &&
+      body.value === "true" &&
+      !db.hasGroupLinkedConversation(spaceId)
+    ) {
+      return c.json(
+        {
+          error:
+            "This space has no group-linked conversations; the sensitive connections guard has no effect here.",
+        },
+        400,
+      );
+    }
+  }
+
+  // Extension config validation
+  if (isExtension && !configRegistry.validate(body.key, body.value)) {
+    return c.json({ error: `Invalid value for ${body.key}` }, 400);
+  }
+
+  db.setSpaceConfig(spaceId, body.key, body.value, callerId);
+  return c.json({ spaceId, key: body.key, value: body.value });
+});

package/src/core/routes/connections.ts

@@ -0,0 +1,190 @@
+import { Hono } from "hono";
+import type { AppConfig } from "../../config.js";
+import { createMercuryExtensionContext } from "../../extensions/context.js";
+import type { ExtensionRegistry } from "../../extensions/loader.js";
+import type {
+  ConnectionDef,
+  ConnectionStatus,
+  ExtensionMeta,
+  MercuryExtensionContext,
+} from "../../extensions/types.js";
+import { logger } from "../../logger.js";
+import type { Db } from "../../storage/db.js";
+import { type Env, getApiCtx } from "../api-types.js";
+
+export const connections = new Hono<Env>();
+
+const STATUS_CHECK_TIMEOUT_MS = 5000;
+
+const VALID_STATUSES: ReadonlySet<ConnectionStatus> = new Set<ConnectionStatus>(
+  ["connected", "needs-reauth", "broken", "unknown"],
+);
+
+interface ResolvedStatus {
+  status: ConnectionStatus;
+  detail: string | null;
+  error: string | null;
+}
+
+async function resolveStatus(
+  ext: ExtensionMeta,
+  conn: ConnectionDef,
+  ctx: MercuryExtensionContext,
+): Promise<ResolvedStatus> {
+  if (conn.statusCheck) {
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const result = await Promise.race([
+        conn.statusCheck(ctx),
+        new Promise<never>((_, reject) => {
+          timeoutHandle = setTimeout(
+            () =>
+              reject(
+                new Error(
+                  `statusCheck timed out after ${STATUS_CHECK_TIMEOUT_MS}ms`,
+                ),
+              ),
+            STATUS_CHECK_TIMEOUT_MS,
+          );
+        }),
+      ]);
+      if (!VALID_STATUSES.has(result.status)) {
+        ctx.log.error(
+          `Extension "${ext.name}": statusCheck returned invalid status`,
+          { status: result.status },
+        );
+        return {
+          status: "unknown",
+          detail: null,
+          error: "statusCheck returned invalid status",
+        };
+      }
+      return {
+        status: result.status,
+        detail: result.detail ?? null,
+        error: null,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.log.error(`Extension "${ext.name}": statusCheck failed`, { err });
+      return { status: "unknown", detail: null, error: message };
+    } finally {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+    }
+  }
+
+  if (conn.credentialEnvVar) {
+    const present = !!process.env[conn.credentialEnvVar];
+    return {
+      status: present ? "connected" : "unknown",
+      detail: null,
+      error: null,
+    };
+  }
+
+  // Loader validation guarantees at least one signal, so this is defensive.
+  return {
+    status: "unknown",
+    detail: null,
+    error: "connection declares no signal",
+  };
+}
+
+export interface ResolvedConnection {
+  name: string;
+  displayName: string;
+  iconUrl: string | null;
+  category: string;
+  authType: string;
+  scopes: string[];
+  status: ConnectionStatus;
+  detail: string | null;
+  error: string | null;
+  sensitive: boolean;
+}
+
+/**
+ * Resolve the merged connection list for an agent. Shared between the internal
+ * `/api/connections` route (caller-authed) and the `/api/console/connections`
+ * route (Bearer-authed). Same shape — so the console merges runtime status
+ * against its per-user `user_connections` rows without caring which endpoint
+ * it hit.
+ */
+export async function resolveConnectionList(opts: {
+  registry: ExtensionRegistry;
+  db: Db;
+  config: AppConfig;
+}): Promise<ResolvedConnection[]> {
+  const entries = opts.registry
+    .list()
+    .filter(
+      (ext): ext is ExtensionMeta & { connection: ConnectionDef } =>
+        !!ext.connection,
+    );
+
+  // Promise.allSettled is belt-and-suspenders: resolveStatus already catches
+  // every internal failure, but if a future change regresses that we still
+  // isolate one extension's crash from the rest of the response.
+  const settled = await Promise.allSettled(
+    entries.map(async (ext) => {
+      const conn = ext.connection;
+      const extCtx = createMercuryExtensionContext({
+        db: opts.db,
+        config: opts.config,
+        log: logger.child({ extension: ext.name }),
+      });
+      const resolvedStatus = await resolveStatus(ext, conn, extCtx);
+      return {
+        name: ext.name,
+        displayName: conn.displayName,
+        iconUrl: conn.iconUrl ?? null,
+        category: conn.category,
+        authType: conn.authType,
+        scopes: conn.scopes ?? [],
+        status: resolvedStatus.status,
+        detail: resolvedStatus.detail,
+        error: resolvedStatus.error,
+        sensitive: conn.sensitive ?? false,
+      } satisfies ResolvedConnection;
+    }),
+  );
+
+  return settled.map((result, i) => {
+    if (result.status === "fulfilled") return result.value;
+    const ext = entries[i];
+    const message =
+      result.reason instanceof Error
+        ? result.reason.message
+        : String(result.reason);
+    logger.error(`connections route: resolver threw for "${ext.name}"`, {
+      err: result.reason,
+    });
+    return {
+      name: ext.name,
+      displayName: ext.connection.displayName,
+      iconUrl: ext.connection.iconUrl ?? null,
+      category: ext.connection.category,
+      authType: ext.connection.authType,
+      scopes: ext.connection.scopes ?? [],
+      status: "unknown" as ConnectionStatus,
+      detail: null,
+      error: message,
+      sensitive: ext.connection.sensitive ?? false,
+    };
+  });
+}
+
+/** GET /connections — list all connection-enabled extensions with live status. */
+connections.get("/", async (c) => {
+  const apiCtx = getApiCtx(c);
+  if (!apiCtx.registry) {
+    logger.error("connections route: registry missing from apiCtx");
+    return c.json({ error: "Extension registry not initialized" }, 500);
+  }
+  const resolved = await resolveConnectionList({
+    registry: apiCtx.registry,
+    db: apiCtx.db,
+    config: apiCtx.config,
+  });
+  return c.json({ connections: resolved });
+});