mercury-agent 0.4.5

package/src/extensions/installer.ts

@@ -0,0 +1,306 @@
+/**
+ * Install/remove Mercury extensions from the host (CLI + dashboard).
+ * Uses the same layout as `mercury add` / `mercury remove`.
+ */
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import type { Logger } from "../logger.js";
+import type { ExtensionCatalogEntry } from "./catalog.js";
+import { RESERVED_EXTENSION_NAMES } from "./reserved.js";
+
+const VALID_EXT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function loadEnvFile(envPath: string): Record<string, string> {
+  const content = readFileSync(envPath, "utf-8");
+  const vars: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = trimmed.match(/^([^=]+)=(.*)$/);
+    if (match) {
+      vars[match[1]] = match[2];
+    }
+  }
+  return vars;
+}
+
+/** Resolve MERCURY_DATA_DIR from project `.env` (default `.mercury`). */
+export function getProjectDataDir(cwd: string): string {
+  const envPath = join(cwd, ".env");
+  if (existsSync(envPath)) {
+    const envVars = loadEnvFile(envPath);
+    if (envVars.MERCURY_DATA_DIR) return envVars.MERCURY_DATA_DIR;
+  }
+  return ".mercury";
+}
+
+export function getUserExtensionsDir(cwd: string): string {
+  return join(cwd, getProjectDataDir(cwd), "extensions");
+}
+
+export function getGlobalDir(cwd: string): string {
+  const envPath = join(cwd, ".env");
+  if (existsSync(envPath)) {
+    const envVars = loadEnvFile(envPath);
+    if (envVars.MERCURY_GLOBAL_DIR) return envVars.MERCURY_GLOBAL_DIR;
+  }
+  return join(cwd, getProjectDataDir(cwd), "global");
+}
+
+/** Path to `examples/extensions/<sourceDir>` inside the mercury-agent package. */
+export function resolveExamplesExtensionDir(
+  packageRoot: string,
+  sourceDir: string,
+): string {
+  return join(packageRoot, "examples", "extensions", sourceDir);
+}
+
+export type ExtensionInstallResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+function validateForInstall(
+  destName: string,
+  sourceDir: string,
+  extensionsDir: string,
+): string | null {
+  if (!VALID_EXT_NAME_RE.test(destName)) {
+    return `Invalid extension name "${destName}" (lowercase letters, digits, hyphens only).`;
+  }
+  if (RESERVED_EXTENSION_NAMES.has(destName)) {
+    return `"${destName}" is a reserved built-in name.`;
+  }
+  if (!existsSync(join(sourceDir, "index.ts"))) {
+    return "Extension source has no index.ts.";
+  }
+  if (existsSync(join(extensionsDir, destName))) {
+    return `Extension "${destName}" is already installed. Remove it first.`;
+  }
+  return null;
+}
+
+/** Validate that `index.ts` exists and default-exports a function (for CLI doctor). */
+export async function checkExtensionIndexLoads(
+  extDir: string,
+  logicalName: string,
+): Promise<string | null> {
+  const indexPath = join(extDir, "index.ts");
+  try {
+    const mod = await import(indexPath);
+    if (typeof mod.default !== "function") {
+      return `${logicalName}/index.ts must export a default function`;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Failed to load ${logicalName}/index.ts: ${msg}`;
+  }
+  return null;
+}
+
+function installSkillIfPresent(
+  extDir: string,
+  name: string,
+  cwd: string,
+): void {
+  const skillDir = join(extDir, "skill");
+  if (!existsSync(join(skillDir, "SKILL.md"))) return;
+
+  const globalDir = getGlobalDir(cwd);
+  const dst = join(globalDir, "skills", name);
+  mkdirSync(dirname(dst), { recursive: true });
+  rmSync(dst, { recursive: true, force: true });
+  cpSync(skillDir, dst, { recursive: true });
+}
+
+/**
+ * Copy an extension from a local directory into `.mercury/extensions/<destName>/`.
+ */
+export async function installExtensionFromDirectory(options: {
+  cwd: string;
+  sourceDir: string;
+  destName: string;
+}): Promise<ExtensionInstallResult> {
+  const { cwd, sourceDir, destName } = options;
+  const extensionsDir = getUserExtensionsDir(cwd);
+  mkdirSync(extensionsDir, { recursive: true });
+
+  const err = validateForInstall(destName, sourceDir, extensionsDir);
+  if (err) return { ok: false, error: err };
+
+  const loadErr = await checkExtensionIndexLoads(sourceDir, destName);
+  if (loadErr) return { ok: false, error: loadErr };
+
+  const destDir = join(extensionsDir, destName);
+  try {
+    cpSync(sourceDir, destDir, { recursive: true });
+
+    if (existsSync(join(destDir, "package.json"))) {
+      const installResult = spawnSync("bun", ["install"], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        cwd: destDir,
+      });
+      if (installResult.status !== 0) {
+        const stderr = installResult.stderr?.toString?.() ?? "";
+        rmSync(destDir, { recursive: true, force: true });
+        return {
+          ok: false,
+          error: `bun install failed in extension: ${stderr || "unknown error"}`,
+        };
+      }
+    }
+
+    installSkillIfPresent(destDir, destName, cwd);
+    return { ok: true };
+  } catch (e) {
+    if (existsSync(destDir)) {
+      rmSync(destDir, { recursive: true, force: true });
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, error: msg };
+  }
+}
+
+export function removeInstalledExtension(options: {
+  cwd: string;
+  name: string;
+}): ExtensionInstallResult {
+  const { cwd, name } = options;
+  if (!VALID_EXT_NAME_RE.test(name)) {
+    return { ok: false, error: `Invalid extension name "${name}".` };
+  }
+
+  const extensionsDir = getUserExtensionsDir(cwd);
+  const extDir = join(extensionsDir, name);
+
+  if (!existsSync(extDir)) {
+    return { ok: false, error: `Extension "${name}" is not installed.` };
+  }
+
+  const globalDir = getGlobalDir(cwd);
+  const skillDst = join(globalDir, "skills", name);
+  if (existsSync(skillDst)) {
+    rmSync(skillDst, { recursive: true, force: true });
+  }
+
+  rmSync(extDir, { recursive: true, force: true });
+  return { ok: true };
+}
+
+/**
+ * On startup, re-copy any installed catalog extension whose bundled source
+ * differs from the installed copy. Triggered when a new image ships a patched
+ * extension (e.g. MERCURY_BROWSER_SESSIONS fix) but running agents still have
+ * the old installed copy on their data volume.
+ *
+ * Uses an atomic temp-dir swap so a failed copy never leaves an extension
+ * partially installed or fully deleted.
+ */
+export async function syncBundledCatalogExtensions(options: {
+  packageRoot: string;
+  extensionsDir: string;
+  globalDir: string;
+  catalog: ExtensionCatalogEntry[];
+  logger: Logger;
+}): Promise<void> {
+  const { packageRoot, extensionsDir, globalDir, catalog, logger } = options;
+  if (!existsSync(extensionsDir)) return;
+
+  for (const entry of catalog) {
+    const installedDir = join(extensionsDir, entry.name);
+    if (!existsSync(installedDir)) continue;
+
+    const bundledDir = resolveExamplesExtensionDir(
+      packageRoot,
+      entry.sourceDir,
+    );
+    if (!existsSync(bundledDir)) continue;
+
+    const bundledIndex = join(bundledDir, "index.ts");
+    if (!existsSync(bundledIndex)) continue;
+
+    let needsUpdate = false;
+    try {
+      for (const file of ["index.ts", "package.json"]) {
+        const bundledFile = join(bundledDir, file);
+        const installedFile = join(installedDir, file);
+        if (!existsSync(bundledFile)) continue;
+        const bundledContent = readFileSync(bundledFile, "utf-8");
+        const installedContent = existsSync(installedFile)
+          ? readFileSync(installedFile, "utf-8")
+          : null;
+        if (bundledContent !== installedContent) {
+          needsUpdate = true;
+          break;
+        }
+      }
+    } catch {
+      needsUpdate = true;
+    }
+
+    if (!needsUpdate) continue;
+
+    logger.info("Bundled extension source updated — reinstalling", {
+      name: entry.name,
+    });
+
+    // Atomic swap: copy to a temp sibling dir first, then replace.
+    // This ensures a copy failure never leaves the extension deleted.
+    const tmpDir = `${installedDir}.tmp`;
+    rmSync(tmpDir, { recursive: true, force: true });
+    try {
+      cpSync(bundledDir, tmpDir, { recursive: true });
+
+      if (existsSync(join(tmpDir, "package.json"))) {
+        const installResult = spawnSync("bun", ["install"], {
+          stdio: "pipe",
+          encoding: "utf-8",
+          cwd: tmpDir,
+        });
+        if (installResult.status !== 0) {
+          // bun install failed — discard the temp dir; keep the old install.
+          rmSync(tmpDir, { recursive: true, force: true });
+          logger.warn(
+            "Extension sync skipped: bun install failed in bundled source",
+            {
+              name: entry.name,
+              stderr: installResult.stderr?.toString?.() ?? "",
+            },
+          );
+          continue;
+        }
+      }
+
+      // Swap: remove old, rename temp into place.
+      rmSync(installedDir, { recursive: true, force: true });
+      renameSync(tmpDir, installedDir);
+
+      // Sync skill dir to global skills.
+      const skillDir = join(installedDir, "skill");
+      if (existsSync(join(skillDir, "SKILL.md"))) {
+        const dst = join(globalDir, "skills", entry.name);
+        mkdirSync(dirname(dst), { recursive: true });
+        rmSync(dst, { recursive: true, force: true });
+        cpSync(skillDir, dst, { recursive: true });
+      }
+
+      logger.info("Extension reinstalled from bundled source", {
+        name: entry.name,
+      });
+    } catch (e) {
+      rmSync(tmpDir, { recursive: true, force: true });
+      logger.warn("Failed to reinstall extension from bundled source", {
+        name: entry.name,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+}

package/src/extensions/jobs.ts

@@ -0,0 +1,122 @@
+/**
+ * Job runner — executes background jobs registered by extensions.
+ *
+ * Supports interval-based and cron-based scheduling.
+ */
+
+import { CronExpressionParser } from "cron-parser";
+import type { Logger } from "../logger.js";
+import type {
+  ExtensionMeta,
+  JobDef,
+  MercuryExtensionContext,
+} from "./types.js";
+
+export class JobRunner {
+  private readonly timers = new Map<string, NodeJS.Timeout>();
+  private running = false;
+
+  /**
+   * Start all registered jobs from loaded extensions.
+   * Interval jobs run immediately, then repeat.
+   * Cron jobs schedule for the next matching time.
+   */
+  start(extensions: ExtensionMeta[], ctx: MercuryExtensionContext): void {
+    if (this.running) return;
+    this.running = true;
+
+    for (const ext of extensions) {
+      for (const [jobName, jobDef] of ext.jobs) {
+        const fullName = `${ext.name}:${jobName}`;
+        const log = ctx.log.child({ job: fullName });
+
+        if (jobDef.interval) {
+          // Run immediately, then on interval
+          void this.runJob(fullName, jobDef, ctx, log);
+          const timer = setInterval(
+            () => void this.runJob(fullName, jobDef, ctx, log),
+            jobDef.interval,
+          );
+          this.timers.set(fullName, timer);
+          log.info("Started interval job", { intervalMs: jobDef.interval });
+        }
+
+        if (jobDef.cron) {
+          this.scheduleCron(fullName, jobDef, ctx, log);
+          log.info("Started cron job", { cron: jobDef.cron });
+        }
+      }
+    }
+  }
+
+  /** Stop all running jobs and clear timers. */
+  stop(): void {
+    this.running = false;
+    for (const timer of this.timers.values()) {
+      clearInterval(timer);
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+  }
+
+  /** Number of active jobs. */
+  get activeCount(): number {
+    return this.timers.size;
+  }
+
+  private scheduleCron(
+    name: string,
+    def: JobDef,
+    ctx: MercuryExtensionContext,
+    log: Logger,
+  ): void {
+    if (!this.running || !def.cron) return;
+
+    const delayMs = getNextCronDelay(def.cron);
+    if (delayMs === null) {
+      log.error("Invalid cron expression, job not scheduled", {
+        cron: def.cron,
+      });
+      return;
+    }
+
+    const timer = setTimeout(async () => {
+      if (!this.running) return;
+      await this.runJob(name, def, ctx, log);
+      // Reschedule for next tick
+      this.timers.delete(name);
+      this.scheduleCron(name, def, ctx, log);
+    }, delayMs);
+
+    this.timers.set(name, timer);
+  }
+
+  private async runJob(
+    _name: string,
+    def: JobDef,
+    ctx: MercuryExtensionContext,
+    log: Logger,
+  ): Promise<void> {
+    log.info("Job starting");
+    try {
+      await def.run(ctx);
+      log.info("Job complete");
+    } catch (err) {
+      log.error("Job failed", err instanceof Error ? err : undefined);
+    }
+  }
+}
+
+/**
+ * Compute the delay in milliseconds until the next cron tick.
+ * Returns null if the expression is invalid.
+ */
+export function getNextCronDelay(cronExpr: string): number | null {
+  try {
+    const cron = CronExpressionParser.parse(cronExpr);
+    const next = cron.next().getTime();
+    return Math.max(0, next - Date.now());
+  } catch {
+    return null;
+  }
+}

package/src/extensions/loader.ts

@@ -0,0 +1,271 @@
+/**
+ * Extension discovery, loading, and registry.
+ *
+ * Scans `.mercury/extensions/` for directories with index.ts,
+ * loads them, validates, and builds a registry.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Logger } from "../logger.js";
+import type { Db } from "../storage/db.js";
+import { MercuryExtensionAPIImpl } from "./api.js";
+import type { ConfigRegistry } from "./config-registry.js";
+import { RESERVED_EXTENSION_NAMES } from "./reserved.js";
+import type {
+  EventHandler,
+  ExtensionMeta,
+  JobDef,
+  MercuryEvents,
+} from "./types.js";
+
+/** Extension names must be alphanumeric + hyphens. */
+const VALID_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+const __loaderDir = path.dirname(fileURLToPath(import.meta.url));
+/** Root of the mercury-agent package (parent of `src/`). */
+const MERCURY_PACKAGE_ROOT = path.resolve(__loaderDir, "../..");
+
+/**
+ * Ensure `<extensionsDir>/node_modules/mercury-agent` resolves to this framework
+ * package so extensions can `import ... from "mercury-agent"` (e.g. `mercury-agent/tts`).
+ */
+function ensurePackageLink(extensionsDir: string): void {
+  const expectedRoot = path.resolve(MERCURY_PACKAGE_ROOT);
+  const nmDir = path.join(extensionsDir, "node_modules");
+  const linkPath = path.join(nmDir, "mercury-agent");
+
+  try {
+    if (fs.existsSync(linkPath) && fs.realpathSync(linkPath) === expectedRoot) {
+      return;
+    }
+  } catch {
+    /* broken symlink or unreadable — replace */
+  }
+
+  if (fs.lstatSync(linkPath, { throwIfNoEntry: false }) !== undefined) {
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  }
+
+  fs.mkdirSync(nmDir, { recursive: true });
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  fs.symlinkSync(expectedRoot, linkPath, linkType);
+}
+
+export class ExtensionRegistry {
+  private readonly extensions = new Map<string, ExtensionMeta>();
+
+  /**
+   * Load all extensions from one or more directories.
+   * The first directory is the primary (user extensions),
+   * additional directories are for built-in extensions shipped with Mercury.
+   *
+   * `envOverride` replaces `process.env` for credential gate checks only —
+   * used by the pre-build endpoint to simulate the target container's env.
+   */
+  async loadAll(
+    extensionsDir: string,
+    db: Db,
+    log: Logger,
+    configRegistry?: ConfigRegistry | null,
+    extraDirs: string[] = [],
+    envOverride?: Record<string, string>,
+  ): Promise<void> {
+    const dirs = [extensionsDir, ...extraDirs];
+    for (const dir of dirs) {
+      await this.loadFromDir(
+        dir,
+        db,
+        log,
+        configRegistry ?? undefined,
+        envOverride,
+      );
+    }
+  }
+
+  private async loadFromDir(
+    extensionsDir: string,
+    db: Db,
+    log: Logger,
+    configRegistry?: ConfigRegistry,
+    envOverride?: Record<string, string>,
+  ): Promise<void> {
+    if (!fs.existsSync(extensionsDir)) {
+      log.debug(`Extensions directory not found: ${extensionsDir}`);
+      return;
+    }
+
+    ensurePackageLink(extensionsDir);
+
+    const entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const name = entry.name;
+      if (name === "node_modules") continue;
+
+      const extDir = path.join(extensionsDir, name);
+
+      // Validate name format
+      if (!VALID_NAME_RE.test(name)) {
+        log.warn(
+          `Skipping extension "${name}": invalid name (must be lowercase alphanumeric + hyphens)`,
+        );
+        continue;
+      }
+
+      // Check reserved names
+      if (RESERVED_EXTENSION_NAMES.has(name)) {
+        throw new Error(`Extension "${name}" conflicts with built-in command`);
+      }
+
+      // Check for index.ts
+      const indexPath = path.join(extDir, "index.ts");
+      if (!fs.existsSync(indexPath)) {
+        log.warn(
+          `Skipping extension "${name}": no index.ts found in ${extDir}`,
+        );
+        continue;
+      }
+
+      // Skip if already loaded (user extensions take precedence over built-in)
+      if (this.extensions.has(name)) {
+        log.debug(`Skipping duplicate extension "${name}" (already loaded)`);
+        continue;
+      }
+
+      try {
+        const meta = await loadExtension(name, extDir, indexPath, db);
+
+        // Credential gate: skip connection extensions whose credential env var is unset.
+        // When envOverride is provided (pre-build simulation), check it instead of process.env.
+        const credVar = meta.connection?.credentialEnvVar;
+        const envToCheck = envOverride ?? process.env;
+        if (credVar && !envToCheck[credVar]) {
+          log.debug(
+            `Skipping extension "${name}": connection credential env var ${credVar} is not set`,
+          );
+          continue;
+        }
+
+        // Register extension config keys in the config registry
+        if (configRegistry) {
+          for (const [key, def] of meta.configs) {
+            configRegistry.register(name, key, def);
+          }
+        }
+        this.extensions.set(name, meta);
+        log.info(`Loaded extension: ${name}`);
+      } catch (err) {
+        log.error(
+          `Failed to load extension "${name}": ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  /** Get an extension by name. */
+  get(name: string): ExtensionMeta | undefined {
+    return this.extensions.get(name);
+  }
+
+  /** List all loaded extensions. */
+  list(): ExtensionMeta[] {
+    return [...this.extensions.values()];
+  }
+
+  /** Get extensions that declare a CLI. */
+  getCliExtensions(): ExtensionMeta[] {
+    return this.list().filter((ext) => ext.clis.length > 0);
+  }
+
+  /** Get all env var source names claimed by extensions (for passthrough filtering). */
+  getClaimedEnvSources(): Set<string> {
+    const sources = new Set<string>();
+    for (const ext of this.extensions.values()) {
+      for (const envDef of ext.envVars) {
+        sources.add(envDef.from);
+      }
+    }
+    return sources;
+  }
+
+  /** Get all hook handlers for a specific event, across all extensions. */
+  getHookHandlers<E extends keyof MercuryEvents>(event: E): EventHandler<E>[] {
+    const handlers: EventHandler<E>[] = [];
+    for (const ext of this.extensions.values()) {
+      const extHandlers = ext.hooks.get(event);
+      if (extHandlers) {
+        handlers.push(...(extHandlers as EventHandler<E>[]));
+      }
+    }
+    return handlers;
+  }
+
+  /** Get all jobs across all extensions. */
+  getJobs(): Array<{ extension: string; name: string; def: JobDef }> {
+    const jobs: Array<{ extension: string; name: string; def: JobDef }> = [];
+    for (const ext of this.extensions.values()) {
+      for (const [name, def] of ext.jobs) {
+        jobs.push({ extension: ext.name, name, def });
+      }
+    }
+    return jobs;
+  }
+
+  /** Number of loaded extensions. */
+  get size(): number {
+    return this.extensions.size;
+  }
+}
+
+/**
+ * Load a single extension: import its index.ts, run the setup function,
+ * and return the collected metadata.
+ */
+async function loadExtension(
+  name: string,
+  extDir: string,
+  indexPath: string,
+  db: Db,
+): Promise<ExtensionMeta> {
+  const mod = await import(indexPath);
+  const setup = mod.default;
+
+  if (typeof setup !== "function") {
+    throw new Error(
+      `Extension "${name}": index.ts must export a default function`,
+    );
+  }
+
+  const api = new MercuryExtensionAPIImpl(name, extDir, db);
+  setup(api);
+  const meta = api.getMeta();
+
+  if (meta.connection) {
+    if (!meta.permission) {
+      throw new Error(
+        `Extension "${name}": connection() requires permission() — credentials must be gated`,
+      );
+    }
+    const { credentialEnvVar, statusCheck } = meta.connection;
+    if (!credentialEnvVar && !statusCheck) {
+      throw new Error(
+        `Extension "${name}": connection requires at least one of credentialEnvVar or statusCheck`,
+      );
+    }
+    if (credentialEnvVar) {
+      const declared = meta.envVars.some((e) => e.from === credentialEnvVar);
+      if (!declared) {
+        throw new Error(
+          `Extension "${name}": connection.credentialEnvVar "${credentialEnvVar}" is not declared via mercury.env()`,
+        );
+      }
+    }
+  }
+
+  return meta;
+}