mercury-agent 0.4.5

package/src/core/profiles.ts

@@ -0,0 +1,245 @@
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+
+// ─── Profile Schema ───────────────────────────────────────────────────────
+
+const profileEnvVarSchema = z.object({
+  key: z.string().regex(/^[A-Z][A-Z0-9_]*$/),
+  description: z.string().optional(),
+  required: z.boolean().default(false),
+  default: z.string().optional(),
+});
+
+const profileExtensionSchema = z.object({
+  name: z
+    .string()
+    .regex(
+      /^[a-z0-9][a-z0-9-]*$/,
+      "Extension names must be lowercase alphanumeric with hyphens",
+    ),
+  source: z.string(),
+});
+
+const profileDefaultsSchema = z.object({
+  model_provider: z.string().optional(),
+  model: z.string().optional(),
+  trigger_patterns: z.string().optional(),
+  bot_username: z.string().optional(),
+});
+
+export const profileSchema = z.object({
+  name: z
+    .string()
+    .regex(
+      /^[a-z0-9][a-z0-9-]*$/,
+      "Profile name must be lowercase alphanumeric with hyphens",
+    ),
+  description: z.string().optional(),
+  version: z.string().default("0.1.0"),
+  agents_md: z.string().optional(),
+  extensions: z.array(profileExtensionSchema).default([]),
+  env: z.array(profileEnvVarSchema).default([]),
+  defaults: profileDefaultsSchema.optional(),
+});
+
+export type MercuryProfile = z.infer<typeof profileSchema>;
+export type ProfileEnvVar = z.infer<typeof profileEnvVarSchema>;
+
+// ─── YAML Parsing (lightweight, no dependency) ────────────────────────────
+
+function parseSimpleYaml(content: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = content.split("\n");
+  let currentKey = "";
+  let currentArray: unknown[] | null = null;
+  let currentObject: Record<string, unknown> | null = null;
+
+  for (const raw of lines) {
+    const line = raw.replace(/\r$/, "");
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+
+    // Top-level key: value
+    const topMatch = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (topMatch) {
+      if (currentArray && currentKey) {
+        result[currentKey] = currentArray;
+        currentArray = null;
+      }
+      const [, key, value] = topMatch;
+      currentKey = key;
+      if (value) {
+        result[key] = value.replace(/^["']|["']$/g, "");
+      }
+      continue;
+    }
+
+    // Array item: "  - key: value" or "  - value"
+    const arrayItemMatch = line.match(/^\s+-\s+(.+)$/);
+    if (arrayItemMatch) {
+      if (!currentArray) currentArray = [];
+      const item = arrayItemMatch[1];
+
+      // Check if it's a "key: value" object entry
+      const kvMatch = item.match(/^([a-z_]+):\s*(.*)$/);
+      if (kvMatch) {
+        currentObject = { [kvMatch[1]]: parseYamlValue(kvMatch[2]) };
+        currentArray.push(currentObject);
+      } else {
+        currentObject = null;
+        currentArray.push(parseYamlValue(item));
+      }
+      continue;
+    }
+
+    // Nested key inside array object: "    key: value"
+    const nestedMatch = line.match(/^\s{4,}([a-z_]+):\s*(.*)$/);
+    if (nestedMatch && currentObject) {
+      currentObject[nestedMatch[1]] = parseYamlValue(nestedMatch[2]);
+      continue;
+    }
+
+    // Nested key for non-array objects (e.g., defaults section)
+    const subMatch = line.match(/^\s{2}([a-z_]+):\s*(.*)$/);
+    if (subMatch && currentKey && !currentArray) {
+      if (
+        typeof result[currentKey] !== "object" ||
+        result[currentKey] === null
+      ) {
+        result[currentKey] = {};
+      }
+      (result[currentKey] as Record<string, unknown>)[subMatch[1]] =
+        parseYamlValue(subMatch[2]);
+    }
+  }
+
+  if (currentArray && currentKey) {
+    result[currentKey] = currentArray;
+  }
+
+  return result;
+}
+
+function parseYamlValue(raw: string): string | number | boolean {
+  const trimmed = raw.replace(/^["']|["']$/g, "").trim();
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== "") return num;
+  return trimmed;
+}
+
+// ─── Profile Loading ──────────────────────────────────────────────────────
+
+export function loadProfileFromDir(dir: string): MercuryProfile {
+  const yamlPath = join(dir, "mercury-profile.yaml");
+  if (!existsSync(yamlPath)) {
+    throw new Error(`Profile manifest not found: ${yamlPath}`);
+  }
+
+  const content = readFileSync(yamlPath, "utf-8");
+  const parsed = parseSimpleYaml(content);
+  return profileSchema.parse(parsed);
+}
+
+export function resolveProfileSource(
+  source: string,
+  profilesDir: string,
+): {
+  dir: string;
+  cleanup: () => void;
+} {
+  // 1. Built-in profile
+  const builtinPath = join(profilesDir, source);
+  if (existsSync(join(builtinPath, "mercury-profile.yaml"))) {
+    return { dir: builtinPath, cleanup: () => {} };
+  }
+
+  // 2. Local path
+  const localPath = resolve(source);
+  if (existsSync(join(localPath, "mercury-profile.yaml"))) {
+    return { dir: localPath, cleanup: () => {} };
+  }
+
+  // 3. Git URL
+  if (
+    source.startsWith("http://") ||
+    source.startsWith("https://") ||
+    source.startsWith("git@")
+  ) {
+    const tmp = join(tmpdir(), `mercury-profile-${Date.now()}`);
+    const cloneResult = spawnSync(
+      "git",
+      ["clone", "--depth", "1", source, tmp],
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+    if (cloneResult.status !== 0) {
+      throw new Error(`Failed to clone profile from ${source}`);
+    }
+    return {
+      dir: tmp,
+      cleanup: () => rmSync(tmp, { recursive: true, force: true }),
+    };
+  }
+
+  throw new Error(`Profile not found: ${source}`);
+}
+
+export function applyProfile(
+  profile: MercuryProfile,
+  profileDir: string,
+  projectDir: string,
+): void {
+  const dataDir = join(projectDir, ".mercury");
+  mkdirSync(dataDir, { recursive: true });
+
+  // Copy AGENTS.md
+  if (profile.agents_md) {
+    const agentsMdSrc = join(profileDir, profile.agents_md);
+    if (existsSync(agentsMdSrc)) {
+      const globalDir = join(dataDir, "global");
+      mkdirSync(globalDir, { recursive: true });
+      cpSync(agentsMdSrc, join(globalDir, "AGENTS.md"));
+    }
+  }
+
+  // Copy extensions
+  for (const ext of profile.extensions) {
+    if (ext.source.startsWith("./") || ext.source.startsWith("../")) {
+      const extSrc = join(profileDir, ext.source);
+      if (existsSync(extSrc)) {
+        const extDst = join(dataDir, "extensions", ext.name);
+        mkdirSync(dirname(extDst), { recursive: true });
+        cpSync(extSrc, extDst, { recursive: true });
+      }
+    }
+  }
+}
+
+export function listBuiltinProfiles(profilesDir: string): MercuryProfile[] {
+  if (!existsSync(profilesDir)) return [];
+
+  const profiles: MercuryProfile[] = [];
+  for (const entry of readdirSync(profilesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const yamlPath = join(profilesDir, entry.name, "mercury-profile.yaml");
+    if (!existsSync(yamlPath)) continue;
+    try {
+      profiles.push(loadProfileFromDir(join(profilesDir, entry.name)));
+    } catch {
+      // Skip invalid profiles
+    }
+  }
+  return profiles;
+}

package/src/core/rate-limiter.ts

@@ -0,0 +1,127 @@
+/**
+ * Sliding window rate limiter for per-user per-group message limiting.
+ *
+ * Uses a simple sliding window approach: tracks timestamps of recent requests
+ * and counts how many fall within the current window.
+ */
+export class RateLimiter {
+  /** Map of "spaceId:userId" -> array of request timestamps */
+  private readonly buckets = new Map<string, number[]>();
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    /** Max requests per user per group within the window */
+    private readonly maxRequests: number,
+    /** Window size in milliseconds */
+    private readonly windowMs: number,
+  ) {}
+
+  /**
+   * Check if a request is allowed and record it if so.
+   * @param limitOverride - Optional per-group limit override
+   * @returns true if allowed, false if rate limited
+   */
+  isAllowed(spaceId: string, userId: string, limitOverride?: number): boolean {
+    const key = `${spaceId}:${userId}`;
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    const effectiveLimit = limitOverride ?? this.maxRequests;
+
+    let timestamps = this.buckets.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.buckets.set(key, timestamps);
+    }
+
+    // Remove timestamps outside the current window
+    const validTimestamps = timestamps.filter((t) => t > windowStart);
+
+    if (validTimestamps.length >= effectiveLimit) {
+      // Over limit — update bucket with pruned timestamps but don't add new one
+      this.buckets.set(key, validTimestamps);
+      return false;
+    }
+
+    // Under limit — record this request
+    validTimestamps.push(now);
+    this.buckets.set(key, validTimestamps);
+    return true;
+  }
+
+  /**
+   * Get remaining requests for a user in a group.
+   */
+  getRemaining(spaceId: string, userId: string): number {
+    const key = `${spaceId}:${userId}`;
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    const timestamps = this.buckets.get(key);
+    if (!timestamps) return this.maxRequests;
+
+    const validCount = timestamps.filter((t) => t > windowStart).length;
+    return Math.max(0, this.maxRequests - validCount);
+  }
+
+  /**
+   * Start periodic cleanup of expired entries.
+   * Call this once at startup to prevent memory leaks.
+   */
+  startCleanup(intervalMs = 60_000): void {
+    if (this.cleanupTimer) return;
+
+    this.cleanupTimer = setInterval(() => {
+      this.cleanup();
+    }, intervalMs);
+
+    // Don't keep the process alive just for cleanup
+    if (this.cleanupTimer.unref) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Stop the cleanup timer.
+   */
+  stopCleanup(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  /**
+   * Remove all expired entries from the bucket map.
+   */
+  cleanup(): number {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    let removed = 0;
+
+    for (const [key, timestamps] of this.buckets) {
+      const valid = timestamps.filter((t) => t > windowStart);
+      if (valid.length === 0) {
+        this.buckets.delete(key);
+        removed++;
+      } else if (valid.length !== timestamps.length) {
+        this.buckets.set(key, valid);
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Clear all rate limit state. Useful for testing.
+   */
+  clear(): void {
+    this.buckets.clear();
+  }
+
+  /**
+   * Get the number of tracked buckets (for monitoring).
+   */
+  get bucketCount(): number {
+    return this.buckets.size;
+  }
+}

package/src/core/router.ts

@@ -0,0 +1,191 @@
+import type { AppConfig } from "../config.js";
+import type { Db } from "../storage/db.js";
+import type { MessageAttachment } from "../types.js";
+import { SLASH_COMMANDS } from "./commands.js";
+import { hasPermission, resolveRole } from "./permissions.js";
+import { loadTriggerConfig, matchTrigger } from "./trigger.js";
+
+export type RouteResult =
+  | {
+      type: "assistant";
+      prompt: string;
+      callerId: string;
+      role: string;
+      isReplyToBot: boolean;
+      isDM: boolean;
+    }
+  | {
+      type: "command";
+      command: string;
+      verb?: string;
+      arg?: string;
+      callerId: string;
+      role: string;
+    }
+  | { type: "denied"; reason: string }
+  | { type: "ignore" };
+
+/**
+ * Chat-level commands that bypass the LLM.
+ * Mapped to the permission required to execute them.
+ */
+const CHAT_COMMANDS: Record<string, string> = {
+  stop: "stop",
+  compact: "compact",
+  clear: "clear",
+};
+
+export function routeInput(input: {
+  text: string;
+  spaceId: string;
+  callerId: string;
+  isDM: boolean;
+  isReplyToBot: boolean;
+  db: Db;
+  config: AppConfig;
+  /** Attachments after normalize (saved to inbox). */
+  attachments?: MessageAttachment[];
+  /**
+   * True when the inbound message had attachments or downloadable media before
+   * normalize, even if nothing was persisted (routing vs silent drop).
+   */
+  hadIncomingAttachments?: boolean;
+  /** Display name of the message author (e.g. WhatsApp pushName). */
+  authorName?: string | null;
+}): RouteResult {
+  const text = input.text.trim();
+  const persisted = (input.attachments?.length ?? 0) > 0;
+  const hadIncoming = input.hadIncomingAttachments ?? false;
+  const hasAttachments = persisted || hadIncoming;
+  if (!text && !hasAttachments) return { type: "ignore" };
+
+  const seededAdmins = input.config.admins
+    ? input.config.admins
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  input.db.ensureSpace(input.spaceId);
+
+  // Resolve role (seeds admins + auto-upserts member)
+  const role = resolveRole(
+    input.db,
+    input.spaceId,
+    input.callerId,
+    seededAdmins,
+    input.authorName,
+  );
+
+  // Load trigger config for this group
+  const defaultPatterns = input.config.triggerPatterns
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const triggerConfig = loadTriggerConfig(input.db, input.spaceId, {
+    patterns: defaultPatterns,
+    match: input.config.triggerMatch,
+  });
+
+  // Match trigger OR reply-to-bot
+  const result = matchTrigger(text, triggerConfig, input.isDM, hasAttachments);
+  const isReplyTrigger = input.isReplyToBot && !input.isDM;
+  if (!result.matched && !isReplyTrigger) return { type: "ignore" };
+
+  // Use stripped prompt if trigger matched, otherwise full text for replies
+  const prompt = result.matched ? result.prompt : text;
+
+  // Check for slash commands (e.g. "/model list", "/model switch 2")
+  // Only parse the first line — appended context (reply quotes etc.) must not
+  // bleed into verb/arg tokens.
+  if (prompt.startsWith("/")) {
+    const firstLine = prompt.split("\n")[0].trim();
+    const [rawCategory, rawVerb, ...argParts] = firstLine
+      .slice(1)
+      .trim()
+      .split(/\s+/);
+    const category = rawCategory.toLowerCase();
+    const verb = rawVerb?.toLowerCase() || undefined;
+    const arg = argParts.join(" ").trim().toLowerCase() || undefined;
+    if (SLASH_COMMANDS.some((c) => c.name === category)) {
+      return gateSlashCommand(
+        input.db,
+        input.spaceId,
+        category,
+        role,
+        input.callerId,
+        input.isDM,
+        verb,
+        arg,
+      );
+    }
+  }
+
+  // Check for commands after trigger (e.g. "@Pi stop", "Pi compact")
+  const cmdWord = prompt.toLowerCase().trim();
+  if (cmdWord in CHAT_COMMANDS) {
+    return gateCommand(input.db, input.spaceId, cmdWord, role, input.callerId);
+  }
+
+  // Check prompt permission
+  if (!hasPermission(input.db, input.spaceId, role, "prompt")) {
+    return {
+      type: "denied",
+      reason: "You don't have permission to use the agent in this group.",
+    };
+  }
+
+  return {
+    type: "assistant",
+    prompt,
+    callerId: input.callerId,
+    role,
+    isReplyToBot: input.isReplyToBot,
+    isDM: input.isDM,
+  };
+}
+
+function gateSlashCommand(
+  db: Db,
+  spaceId: string,
+  command: string,
+  role: string,
+  callerId: string,
+  isDM: boolean,
+  verb?: string,
+  arg?: string,
+): RouteResult {
+  if (!isDM && role !== "admin" && role !== "system") {
+    return {
+      type: "denied",
+      reason: "Slash commands are only available to admins in groups.",
+    };
+  }
+  if (!hasPermission(db, spaceId, role, "prompt")) {
+    return {
+      type: "denied",
+      reason: `You don't have permission to use '/${command}'.`,
+    };
+  }
+  return { type: "command", command, verb, arg, callerId, role };
+}
+
+function gateCommand(
+  db: Db,
+  spaceId: string,
+  command: string,
+  role: string,
+  callerId: string,
+): RouteResult {
+  const permission = CHAT_COMMANDS[command];
+  if (!permission) return { type: "ignore" };
+
+  if (!hasPermission(db, spaceId, role, permission)) {
+    return {
+      type: "denied",
+      reason: `You don't have permission to use '${command}'.`,
+    };
+  }
+
+  return { type: "command", command, callerId, role };
+}