mercury-agent 0.4.5

package/src/config.ts

@@ -0,0 +1,316 @@
+import path from "node:path";
+import { z } from "zod";
+import {
+  type ModelCapabilities,
+  parseModelCapabilitiesEnv,
+  resolveModelChainCapabilities,
+} from "./agent/model-capabilities.js";
+import { mergeRawMercuryConfig } from "./config-file.js";
+import { parseModelLegsArray } from "./config-model-chain.js";
+
+/** One model leg in the ordered fallback chain (primary first). */
+export type ModelLeg = { provider: string; model: string };
+
+function parseModelChainJson(raw: string): ModelLeg[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("MERCURY_MODEL_CHAIN must be valid JSON array");
+  }
+  return parseModelLegsArray(parsed, "MERCURY_MODEL_CHAIN");
+}
+
+function resolveModelChain(base: {
+  modelChain: string | undefined;
+  modelProvider: string;
+  model: string;
+  modelFallbackProvider: string | undefined;
+  modelFallback: string | undefined;
+}): ModelLeg[] {
+  const trimmed = base.modelChain?.trim();
+  if (trimmed) {
+    return parseModelChainJson(trimmed);
+  }
+  const legs: ModelLeg[] = [
+    { provider: base.modelProvider, model: base.model },
+  ];
+  const fp = base.modelFallbackProvider?.trim();
+  const fm = base.modelFallback?.trim();
+  if (fp && fm) {
+    legs.push({ provider: fp, model: fm });
+  }
+  return legs;
+}
+
+/** Parse boolean from env var strings — case-insensitive "true"/"1" → true, everything else → false */
+const booleanFromEnv = z.union([z.boolean(), z.string()]).transform((val) => {
+  if (typeof val === "boolean") return val;
+  const lower = val.toLowerCase();
+  return lower === "true" || lower === "1";
+});
+
+const schema = z.object({
+  // ─── API Key Mode ───────────────────────────────────────────────────
+  apiKeyMode: z.enum(["platform", "byok"]).default("platform"),
+
+  // ─── Logging ────────────────────────────────────────────────────────
+  logLevel: z
+    .enum(["debug", "info", "warn", "error", "silent"])
+    .default("info"),
+  logFormat: z.enum(["text", "json"]).default("text"),
+
+  // ─── AI Model ───────────────────────────────────────────────────────
+  modelProvider: z.string().default("anthropic"),
+  model: z.string().default("claude-opus-4-6"),
+  modelFallbackProvider: z.string().optional(),
+  modelFallback: z.string().optional(),
+  /** JSON array of `{ provider, model }`. When set, overrides legacy primary+fallback pair. */
+  modelChain: z.string().optional(),
+  /** Extra attempts after the first failure on the same leg (retryable errors only). Default 2 => 3 tries max per leg. */
+  modelMaxRetriesPerLeg: z.coerce.number().int().min(0).max(5).default(2),
+  /** Wall-clock budget for the whole chain (ms). Clamped below container timeout. Default 120s. */
+  modelChainBudgetMs: z.coerce
+    .number()
+    .int()
+    .min(5000)
+    .max(55 * 60 * 1000)
+    .default(120_000),
+  /**
+   * Optional JSON object overriding model capabilities for all chain legs, e.g.
+   * `{"tools":false,"vision":true}`. Highest priority over YAML and built-in map.
+   */
+  modelCapabilitiesEnv: z.string().optional(),
+
+  // ─── Trigger Behavior ───────────────────────────────────────────────
+  triggerPatterns: z.string().default("@Pi,Pi"),
+  triggerMatch: z.string().default("mention"),
+
+  // ─── Context Behavior ───────────────────────────────────────────────
+  /** Default context mode seeded into the `main` space on first boot. */
+  contextMode: z.enum(["clear", "context"]).default("context"),
+  /** Default sliding-window turn count for `context` mode (1–50). Seeded into `main` on first boot. */
+  contextWindowSize: z.coerce.number().int().min(1).max(50).default(10),
+  /** Default reply-chain depth for `clear` mode (1–50). Seeded into `main` on first boot. */
+  contextReplyChainDepth: z.coerce.number().int().min(1).max(50).default(10),
+
+  // ─── Storage ────────────────────────────────────────────────────────
+  dataDir: z.string().default(".mercury"),
+  /** Max disk usage in MB for the agent's data directory. Unset = no enforcement (local/self-hosted). */
+  maxDiskMb: z.coerce.number().int().min(0).optional(),
+
+  // ─── Storage Lifecycle ─────────────────────────────────────────────
+  /** Days before inbox files are auto-deleted. */
+  inboxTtlDays: z.coerce.number().min(1).max(365).default(7),
+  /** Days before outbox files are auto-deleted. */
+  outboxTtlDays: z.coerce.number().min(1).max(365).default(3),
+  /** Interval in ms between storage cleanup runs. Default 1 hour. */
+  cleanupIntervalMs: z.coerce
+    .number()
+    .int()
+    .min(60_000)
+    .max(86_400_000)
+    .default(3_600_000),
+  authPath: z.string().optional(),
+  /** WhatsApp Baileys auth directory; default `<dataDir>/whatsapp-auth`. */
+  whatsappAuthDir: z.string().optional(),
+
+  // ─── Container / Agent ──────────────────────────────────────────────
+  agentContainerImage: z
+    .string()
+    .default("ghcr.io/michaelliv/mercury-agent:latest"),
+  containerTimeoutMs: z.coerce
+    .number()
+    .int()
+    .min(10_000)
+    .max(60 * 60 * 1000)
+    .default(5 * 60 * 1000), // 5 minutes
+  /**
+   * OCI runtime for inner (pi) containers.
+   * - "runc" (default): standard Docker runtime; uses bubblewrap inside the container for sandboxing.
+   * - "runsc": gVisor runtime — intercepts syscalls at a user-space kernel boundary.
+   *   Stronger isolation than bwrap; restores full Docker hardening (no SYS_ADMIN relaxation needed).
+   *   Requires gVisor installed on the compute node (auto-installed by cloud-init on provisioned nodes).
+   */
+  containerRuntime: z.enum(["runc", "runsc"]).default("runc"),
+  /**
+   * @deprecated Use MERCURY_CONTAINER_RUNTIME=runsc instead.
+   * When true, `docker run` uses looser outer sandbox so bubblewrap can nest (e.g. Docker Desktop).
+   * Ignored when containerRuntime is "runsc". See docs/container-lifecycle.md.
+   */
+  containerBwrapDockerCompat: booleanFromEnv.default(false),
+  /**
+   * Docker network to attach inner (pi) containers to. When set, inner containers join this
+   * network and can reach the Mercury host container by its container name rather than via
+   * host.docker.internal. Required on Linux where host.docker.internal is not available.
+   * Set via MERCURY_CONTAINER_NETWORK (e.g. "mercury-net").
+   */
+  containerNetwork: z.string().optional(),
+  /**
+   * Hostname (and optional port) that inner containers use to reach the Mercury host API.
+   * When set, overrides the default "host.docker.internal" in the API_URL passed to mrctl.
+   * Set via MERCURY_CONTAINER_API_HOST (e.g. "mercury-agent-<uuid>").
+   */
+  containerApiHost: z.string().optional(),
+  maxConcurrency: z.coerce.number().int().min(1).max(32).default(2),
+  /**
+   * When true, Mercury uses `--system-prompt` instead of `--append-system-prompt` when invoking pi,
+   * making Mercury the sole author of the system prompt. The prompt includes accurate tool snippets
+   * and Mercury identity without any pi-specific references.
+   * Default: false (append mode, preserves existing behaviour).
+   */
+  overridePiSystemPrompt: booleanFromEnv.default(false),
+
+  // ─── Rate Limiting ──────────────────────────────────────────────────
+  rateLimitPerUser: z.coerce.number().int().min(1).max(1000).default(10),
+  rateLimitWindowMs: z.coerce
+    .number()
+    .int()
+    .min(1000)
+    .max(60 * 60 * 1000)
+    .default(60 * 1000), // 1 minute
+
+  // ─── Server ─────────────────────────────────────────────────────────
+  port: z.coerce.number().int().min(1).max(65535).default(8787),
+  botUsername: z.string().default("mercury"),
+
+  // ─── Discord ────────────────────────────────────────────────────────
+  enableDiscord: booleanFromEnv.default(false),
+  discordGatewayDurationMs: z.coerce
+    .number()
+    .int()
+    .min(60_000)
+    .max(60 * 60 * 1000)
+    .default(10 * 60 * 1000),
+  discordGatewaySecret: z.string().optional(),
+
+  // ─── Slack ──────────────────────────────────────────────────────────
+  enableSlack: booleanFromEnv.default(false),
+
+  // ─── Teams ───────────────────────────────────────────────────────────
+  enableTeams: booleanFromEnv.default(false),
+
+  // ─── WhatsApp ───────────────────────────────────────────────────────
+  enableWhatsApp: booleanFromEnv.default(false),
+
+  // ─── Telegram ───────────────────────────────────────────────────────
+  enableTelegram: booleanFromEnv.default(false),
+  /** When true, convert Markdown to Telegram HTML for formatted replies. */
+  telegramFormatEnabled: booleanFromEnv.default(true),
+
+  // ─── Media Handling ─────────────────────────────────────────────────
+  mediaEnabled: booleanFromEnv.default(true),
+  mediaMaxSizeMb: z.coerce.number().min(1).max(100).default(10),
+
+  // ─── Permissions ────────────────────────────────────────────────────
+  admins: z.string().default(""),
+
+  // ─── Security ─────────────────────────────────────────────────────
+  /** Shared secret for API authentication. Required for /api/* routes. */
+  apiSecret: z.string().optional(),
+  /** Optional API key for the /chat endpoint. When unset, /chat is open (for local use). */
+  chatApiKey: z.string().optional(),
+  /**
+   * URL of the Mercury Cloud Console managing this agent (e.g. "https://console.mercury.app").
+   * When set, the dashboard keys page redirects users to the Console instead of allowing
+   * direct key edits — the Console is the single source of truth for API keys.
+   * Env-only; not settable from mercury.yaml.
+   */
+  consoleUrl: z.string().url().optional(),
+  /** User ID in the Mercury Cloud Console — used for per-message quota checks. Env-only. */
+  consoleUserId: z.string().optional(),
+  /** Shared secret for calling console internal API endpoints. Env-only. */
+  consoleInternalSecret: z.string().optional(),
+
+  // ─── Scheduling ─────────────────────────────────────────────────────
+  /** IANA timezone used when a scheduled task is created without an explicit --timezone flag (e.g. "Asia/Jerusalem"). */
+  defaultTimezone: z.string().optional(),
+
+  // ─── TradeStation (host order API) ────────────────────────────────
+  /**
+   * When false (default), POST /api/tradestation/orders rejects non-SIM accounts.
+   * Set true only when you intentionally allow live brokerage orders from the assistant flow.
+   */
+  tsAllowLiveOrders: booleanFromEnv.default(false),
+
+  // ─── Cloud TTS (host-only; /api/tts, optional voice-synth extension) ───
+  /** `google` | `azure` | `auto` — auto picks Google if credentials file set, else Azure if key+region set. */
+  ttsProvider: z.enum(["google", "azure", "auto"]).default("auto"),
+  /** Azure Speech resource key (secret; env-only). */
+  azureSpeechKey: z.string().optional(),
+  /** Azure region, e.g. `eastus`. */
+  azureSpeechRegion: z.string().optional(),
+  /**
+   * Path to GCP service account JSON for Text-to-Speech.
+   * Also accepts standard `GOOGLE_APPLICATION_CREDENTIALS` via mergeRawMercuryConfig.
+   */
+  googleApplicationCredentials: z.string().optional(),
+  /** Max input characters per /api/tts request (clamped 500–10000). */
+  ttsMaxChars: z.coerce.number().int().min(500).max(10_000).default(5000),
+});
+
+export type AppConfig = z.infer<typeof schema> & {
+  /** Derived paths from dataDir */
+  dbPath: string;
+  globalDir: string;
+  spacesDir: string;
+  whatsappAuthDir: string;
+  /** Ordered model legs (primary first), max 20. */
+  resolvedModelChain: ModelLeg[];
+  /** Parsed MERCURY_MODEL_CAPABILITIES override, if valid. */
+  parsedModelCapabilitiesEnv: ModelCapabilities | null;
+  /** Capabilities per chain leg (same order as resolvedModelChain). */
+  resolvedModelChainCapabilities: ModelCapabilities[];
+  /** Effective budget after clamping to container timeout. */
+  effectiveModelChainBudgetMs: number;
+};
+
+export function loadConfig(): AppConfig {
+  const raw = mergeRawMercuryConfig(process.env);
+  const base = schema.parse(raw);
+
+  const dataDir = base.dataDir;
+
+  const resolvedModelChain = resolveModelChain({
+    modelChain: base.modelChain,
+    modelProvider: base.modelProvider,
+    model: base.model,
+    modelFallbackProvider: base.modelFallbackProvider,
+    modelFallback: base.modelFallback,
+  });
+
+  const dataDirAbsolute = resolveProjectPath(base.dataDir);
+  const parsedModelCapabilitiesEnv = parseModelCapabilitiesEnv(
+    base.modelCapabilitiesEnv,
+  );
+  const { chainCaps: resolvedModelChainCapabilities } =
+    resolveModelChainCapabilities(
+      resolvedModelChain,
+      dataDirAbsolute,
+      parsedModelCapabilitiesEnv,
+    );
+
+  const slackMs = 10_000;
+  const effectiveModelChainBudgetMs = Math.min(
+    base.modelChainBudgetMs,
+    Math.max(5000, base.containerTimeoutMs - slackMs),
+  );
+
+  return {
+    ...base,
+    dbPath: path.join(dataDir, "state.db"),
+    globalDir: path.join(dataDir, "global"),
+    spacesDir: path.join(dataDir, "spaces"),
+    whatsappAuthDir:
+      base.whatsappAuthDir ?? path.join(dataDir, "whatsapp-auth"),
+    resolvedModelChain,
+    parsedModelCapabilitiesEnv,
+    resolvedModelChainCapabilities,
+    effectiveModelChainBudgetMs,
+  };
+}
+
+export function resolveProjectPath(p: string): string {
+  if (path.isAbsolute(p)) return p;
+  return path.join(process.cwd(), p);
+}

package/src/core/api-types.ts

@@ -0,0 +1,58 @@
+import type { Context } from "hono";
+import type { AgentContainerRunner } from "../agent/container-runner.js";
+import type { AppConfig } from "../config.js";
+import type { ConfigRegistry } from "../extensions/config-registry.js";
+import type { ExtensionRegistry } from "../extensions/loader.js";
+import type { Db } from "../storage/db.js";
+import type { TradeStationFetch } from "../tradestation/host-api.js";
+import { hasPermission } from "./permissions.js";
+import type { SpaceQueue } from "./space-queue.js";
+import type { TaskScheduler } from "./task-scheduler.js";
+
+// ─── Context Types ────────────────────────────────────────────────────────
+
+export interface ApiContext {
+  db: Db;
+  config: AppConfig;
+  containerRunner: AgentContainerRunner;
+  queue: SpaceQueue;
+  scheduler: TaskScheduler;
+  registry: ExtensionRegistry;
+  configRegistry: ConfigRegistry;
+  /** Optional mock for TradeStation HTTP in tests */
+  tradeStationFetch?: TradeStationFetch;
+}
+
+export interface AuthContext {
+  callerId: string;
+  spaceId: string;
+  role: string;
+}
+
+export type Env = {
+  Variables: {
+    auth: AuthContext;
+    apiCtx: ApiContext;
+  };
+};
+
+// ─── Helper Functions ─────────────────────────────────────────────────────
+
+export const getAuth = (c: Context<Env>): AuthContext => c.get("auth");
+export const getApiCtx = (c: Context<Env>): ApiContext => c.get("apiCtx");
+
+export const checkPerm = (
+  c: Context<Env>,
+  permission: string,
+): Response | null => {
+  const { spaceId, role } = c.get("auth");
+  const { db } = c.get("apiCtx");
+
+  if (!hasPermission(db, spaceId, role, permission)) {
+    return c.json(
+      { error: `Forbidden: requires '${permission}' permission` },
+      403,
+    );
+  }
+  return null;
+};

package/src/core/api.ts

@@ -0,0 +1,105 @@
+import { timingSafeEqual } from "node:crypto";
+import { Hono } from "hono";
+import type { ApiContext, AuthContext, Env } from "./api-types.js";
+import { resolveRole } from "./permissions.js";
+import {
+  config,
+  connections,
+  control,
+  conversations,
+  extensions,
+  media,
+  messages,
+  mutes,
+  permissions,
+  prefs,
+  roles,
+  spaces,
+  tasks,
+  tradestation,
+  tts,
+} from "./routes/index.js";
+
+function safeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+// ─── App Factory ──────────────────────────────────────────────────────────
+
+export function createApiApp(apiCtx: ApiContext): Hono<Env> {
+  const app = new Hono<Env>();
+
+  // ─── Auth Middleware ────────────────────────────────────────────────────
+
+  app.use("*", async (c, next) => {
+    // Validate API secret when configured
+    const secret = apiCtx.config.apiSecret;
+    if (secret) {
+      const authHeader = c.req.header("authorization");
+      const token = authHeader?.startsWith("Bearer ")
+        ? authHeader.slice(7)
+        : undefined;
+
+      if (!token || !safeCompare(token, secret)) {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+    }
+
+    // Parse auth headers
+    const callerId = c.req.header("x-mercury-caller");
+    const spaceId = c.req.header("x-mercury-space");
+
+    if (!callerId || !spaceId) {
+      return c.json(
+        { error: "Missing X-Mercury-Caller or X-Mercury-Space headers" },
+        400,
+      );
+    }
+
+    // Resolve role
+    const seededAdmins = apiCtx.config.admins
+      ? apiCtx.config.admins
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+
+    apiCtx.db.ensureSpace(spaceId);
+    const role = resolveRole(apiCtx.db, spaceId, callerId, seededAdmins);
+
+    // Store in request context
+    c.set("auth", { callerId, spaceId, role } as AuthContext);
+    c.set("apiCtx", apiCtx);
+    await next();
+  });
+
+  // ─── Mount Routes ───────────────────────────────────────────────────────
+
+  app.route("/", control);
+  app.route("/tasks", tasks);
+  app.route("/config", config);
+  app.route("/prefs", prefs);
+  app.route("/roles", roles);
+  app.route("/permissions", permissions);
+  app.route("/spaces", spaces);
+  app.route("/conversations", conversations);
+  app.route("/media", media);
+  app.route("/messages", messages);
+  app.route("/mutes", mutes);
+  app.route("/ext", extensions);
+  app.route("/connections", connections);
+  app.route("/tradestation", tradestation);
+  app.route("/tts", tts);
+
+  // ─── Fallback ───────────────────────────────────────────────────────────
+
+  app.all("*", (c) => {
+    return c.json({ error: "Not found" }, 404);
+  });
+
+  return app;
+}
+
+// Re-export types for convenience
+export type { ApiContext, AuthContext, Env } from "./api-types.js";

package/src/core/commands.ts

@@ -0,0 +1,76 @@
+export interface CommandVerb {
+  verb: string;
+  args?: string; // e.g. "<N|MODEL_ID>"
+  description: string;
+}
+
+export interface CommandEntry {
+  name: string; // e.g. "model", "help"
+  description: string; // one-liner shown in /help
+  verbs?: CommandVerb[]; // defined ⟹ category; absent ⟹ leaf command
+}
+
+// Slash-command registry — source of truth for /help and router recognition.
+// Add new categories here; router + executeCommand both derive from this list.
+export const SLASH_COMMANDS: CommandEntry[] = [
+  {
+    name: "help",
+    description: "list all available commands",
+  },
+  {
+    name: "model",
+    description: "list, switch, and inspect your AI models",
+    verbs: [
+      { verb: "list", description: "list your configured models" },
+      { verb: "active", description: "show the active model" },
+      {
+        verb: "switch",
+        args: "<N|MODEL_ID>",
+        description: "switch by number or model ID",
+      },
+    ],
+  },
+];
+
+// Legacy bare commands — still work without a slash; shown in /help for discoverability.
+export const BARE_COMMANDS: Array<{ name: string; description: string }> = [
+  {
+    name: "stop",
+    description: "abort the current agent run and queued requests",
+  },
+  { name: "compact", description: "reset the session context window" },
+  { name: "clear", description: "clear context for this message" },
+];
+
+// Generates the /help response listing all commands.
+export function formatHelp(): string {
+  const lines: string[] = ["Available commands:", ""];
+
+  for (const cmd of SLASH_COMMANDS) {
+    lines.push(`  /${cmd.name.padEnd(12)}  ${cmd.description}`);
+  }
+
+  lines.push("", "Bare commands (no slash needed):");
+  for (const cmd of BARE_COMMANDS) {
+    lines.push(`  ${cmd.name.padEnd(12)}  ${cmd.description}`);
+  }
+
+  lines.push("", "Type /<category> to see detailed help for that category.");
+  return lines.join("\n");
+}
+
+// Generates the /<category> no-verb response.
+// Returns null if name is not in the registry or the command has no verbs.
+export function formatCategoryHelp(name: string): string | null {
+  const entry = SLASH_COMMANDS.find((c) => c.name === name);
+  if (!entry?.verbs || entry.verbs.length === 0) return null;
+
+  const lines: string[] = [`/${name} — ${entry.description}`, ""];
+  for (const v of entry.verbs) {
+    const usage = v.args
+      ? `/${name} ${v.verb} ${v.args}`
+      : `/${name} ${v.verb}`;
+    lines.push(`  ${usage.padEnd(28)}  ${v.description}`);
+  }
+  return lines.join("\n");
+}

package/src/core/conversation.ts

@@ -0,0 +1,47 @@
+import type { Db } from "../storage/db.js";
+import type { Conversation } from "../types.js";
+
+export interface ConversationResolution {
+  conversation: Conversation;
+  spaceId: string;
+}
+
+export function resolveConversation(
+  db: Db,
+  platform: string,
+  externalId: string,
+  kind: string,
+  observedTitle?: string,
+): ConversationResolution | null {
+  const conversation = db.ensureConversation(
+    platform,
+    externalId,
+    kind,
+    observedTitle,
+  );
+
+  if (!conversation.spaceId) return null;
+
+  return { conversation, spaceId: conversation.spaceId };
+}
+
+export function inferConversationKind(
+  platform: string,
+  externalId: string,
+  isDM: boolean,
+): string {
+  if (isDM) return "dm";
+
+  switch (platform) {
+    case "whatsapp":
+      return "group";
+    case "discord":
+      return externalId.includes(":") ? "thread" : "channel";
+    case "slack":
+      return "channel";
+    case "teams":
+      return "channel";
+    default:
+      return "group";
+  }
+}