mercury-agent 0.4.5

package/src/dashboard/tokens.css

@@ -0,0 +1,53 @@
+/* Canonical design tokens. Source of truth: docs/DESIGN.md §2.
+ * Consumed by the Mercury agent dashboard (mercury-fork).
+ * The cloud console's globals.css carries a duplicate declaration with
+ * matching names; keep both in sync when retuning the palette.
+ * Light-mode overrides omitted — dashboard has no theme toggle.
+ * Surface-local tokens (--sidebar-bg, --sidebar-admin-bg in console;
+ * --hero-blob-* in marketing) live in their own files, not here. */
+:root {
+  /* Surfaces */
+  --bg: #0d1117;
+  --surface: #161b22;
+  --surface-elevated: #1c2128;
+
+  /* Text */
+  --text: #e6edf3;
+  --muted: #8b949e;
+
+  /* Interactive */
+  --accent: #58a6ff;
+  --accent-subtle: rgba(88, 166, 255, 0.15); /* chips / selected rows */
+  --accent-tint: rgba(88, 166, 255, 0.05); /* surface wash */
+  --muted-subtle: rgba(139, 148, 158, 0.15);
+
+  /* Structure */
+  --border: #30363d;
+
+  /* Semantic */
+  --color-success: #3fb950;
+  --color-error: #f85149;
+  --color-warning: #d29922;
+  --success-tint: rgba(63, 185, 80, 0.05); /* surface wash */
+
+  /* Shape */
+  --radius: 6px;
+
+  /* Space badge palette — 8 deterministic slots */
+  --space-palette-0-bg: rgba(88, 166, 255, 0.15);
+  --space-palette-0-fg: #58a6ff;
+  --space-palette-1-bg: rgba(63, 185, 80, 0.15);
+  --space-palette-1-fg: #3fb950;
+  --space-palette-2-bg: rgba(248, 81, 73, 0.15);
+  --space-palette-2-fg: #f85149;
+  --space-palette-3-bg: rgba(210, 153, 34, 0.15);
+  --space-palette-3-fg: #d29922;
+  --space-palette-4-bg: rgba(188, 140, 255, 0.15);
+  --space-palette-4-fg: #bc8cff;
+  --space-palette-5-bg: rgba(57, 197, 207, 0.15);
+  --space-palette-5-fg: #39c5cf;
+  --space-palette-6-bg: rgba(227, 105, 61, 0.15);
+  --space-palette-6-fg: #e3693d;
+  --space-palette-7-bg: rgba(255, 123, 114, 0.15);
+  --space-palette-7-fg: #ff7b72;
+}

package/src/extensions/api.ts

@@ -0,0 +1,252 @@
+/**
+ * MercuryExtensionAPI implementation.
+ *
+ * Each extension gets its own instance, scoped to its name.
+ * The API collects declarations into ExtensionMeta during setup.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ModelCapabilityKey } from "../agent/model-capabilities.js";
+import { registerPermission } from "../core/permissions.js";
+import type { Db } from "../storage/db.js";
+import type {
+  CliDef,
+  ConfigDef,
+  ConnectionCategory,
+  ConnectionDef,
+  EnvDef,
+  EventHandler,
+  ExtensionMeta,
+  ExtensionStore,
+  JobDef,
+  MercuryEvents,
+  MercuryExtensionAPI,
+  PermissionDef,
+  WidgetDef,
+} from "./types.js";
+
+const CONNECTION_CATEGORIES: ReadonlySet<ConnectionCategory> =
+  new Set<ConnectionCategory>([
+    "email",
+    "drive",
+    "calendar",
+    "finance",
+    "messaging",
+    "docs",
+    "workspace",
+    "other",
+  ]);
+
+const CONNECTION_AUTH_TYPES = new Set([
+  "oauth2",
+  "apikey",
+  "app-password",
+  "credentials-file",
+  "form",
+  "custom",
+]);
+
+export class MercuryExtensionAPIImpl implements MercuryExtensionAPI {
+  private readonly meta: ExtensionMeta;
+
+  constructor(
+    readonly name: string,
+    private readonly dir: string,
+    private readonly db: Db,
+  ) {
+    this.meta = {
+      name,
+      dir,
+      clis: [],
+      hooks: new Map(),
+      jobs: new Map(),
+      configs: new Map(),
+      widgets: [],
+      envVars: [],
+    };
+  }
+
+  cli(opts: CliDef): void {
+    if (!opts.name || !opts.install) {
+      throw new Error(
+        `Extension "${this.name}": cli() requires name and install`,
+      );
+    }
+    const def = { ...opts };
+    if (def.bin) {
+      def.bin = path.resolve(this.meta.dir, def.bin);
+    }
+    this.meta.clis.push(def);
+  }
+
+  permission(opts: PermissionDef): void {
+    if (this.meta.permission) {
+      throw new Error(
+        `Extension "${this.name}": permission() can only be called once`,
+      );
+    }
+    if (!Array.isArray(opts.defaultRoles)) {
+      throw new Error(
+        `Extension "${this.name}": permission() requires defaultRoles array`,
+      );
+    }
+    this.meta.permission = opts;
+    registerPermission(this.name, opts);
+  }
+
+  env(def: EnvDef): void {
+    if (!def.from) {
+      throw new Error(
+        `Extension "${this.name}": env() requires a "from" field`,
+      );
+    }
+    this.meta.envVars.push(def);
+  }
+
+  skill(relativePath: string): void {
+    const absPath = path.resolve(this.dir, relativePath);
+    const skillMd = path.join(absPath, "SKILL.md");
+    if (!fs.existsSync(skillMd)) {
+      throw new Error(
+        `Extension "${this.name}": SKILL.md not found at ${skillMd}`,
+      );
+    }
+    this.meta.skillDir = absPath;
+  }
+
+  requires(capabilities: ModelCapabilityKey[]): void {
+    if (!Array.isArray(capabilities) || capabilities.length === 0) {
+      throw new Error(
+        `Extension "${this.name}": requires() needs a non-empty capabilities array`,
+      );
+    }
+    const allowed = new Set([
+      "tools",
+      "vision",
+      "audio_input",
+      "audio_output",
+      "extended_thinking",
+    ]);
+    for (const c of capabilities) {
+      if (!allowed.has(c)) {
+        throw new Error(
+          `Extension "${this.name}": requires() unknown capability "${c}"`,
+        );
+      }
+    }
+    this.meta.requires = [...capabilities];
+  }
+
+  on<E extends keyof MercuryEvents>(event: E, handler: EventHandler<E>): void {
+    const handlers = this.meta.hooks.get(event);
+    if (handlers) {
+      handlers.push(handler as EventHandler<keyof MercuryEvents>);
+    } else {
+      this.meta.hooks.set(event, [
+        handler as EventHandler<keyof MercuryEvents>,
+      ]);
+    }
+  }
+
+  job(name: string, def: JobDef): void {
+    if (!name) {
+      throw new Error(`Extension "${this.name}": job() requires a name`);
+    }
+    if (this.meta.jobs.has(name)) {
+      throw new Error(
+        `Extension "${this.name}": job "${name}" already registered`,
+      );
+    }
+    if (!def.interval && !def.cron) {
+      throw new Error(
+        `Extension "${this.name}": job "${name}" requires interval or cron`,
+      );
+    }
+    if (def.interval && def.cron) {
+      throw new Error(
+        `Extension "${this.name}": job "${name}" cannot have both interval and cron`,
+      );
+    }
+    if (typeof def.run !== "function") {
+      throw new Error(
+        `Extension "${this.name}": job "${name}" requires a run function`,
+      );
+    }
+    this.meta.jobs.set(name, def);
+  }
+
+  config(key: string, def: ConfigDef): void {
+    if (!key) {
+      throw new Error(`Extension "${this.name}": config() requires a key`);
+    }
+    if (this.meta.configs.has(key)) {
+      throw new Error(
+        `Extension "${this.name}": config key "${key}" already registered`,
+      );
+    }
+    this.meta.configs.set(key, def);
+  }
+
+  widget(def: WidgetDef): void {
+    if (!def.label) {
+      throw new Error(`Extension "${this.name}": widget() requires a label`);
+    }
+    if (typeof def.render !== "function") {
+      throw new Error(
+        `Extension "${this.name}": widget() requires a render function`,
+      );
+    }
+    this.meta.widgets.push(def);
+  }
+
+  connection(def: ConnectionDef): void {
+    if (this.meta.connection) {
+      throw new Error(
+        `Extension "${this.name}": connection() can only be called once`,
+      );
+    }
+    if (!def.displayName) {
+      throw new Error(
+        `Extension "${this.name}": connection() requires a displayName`,
+      );
+    }
+    if (!CONNECTION_CATEGORIES.has(def.category)) {
+      throw new Error(
+        `Extension "${this.name}": connection() unknown category "${def.category}"`,
+      );
+    }
+    if (!CONNECTION_AUTH_TYPES.has(def.authType)) {
+      throw new Error(
+        `Extension "${this.name}": connection() unknown authType "${def.authType}"`,
+      );
+    }
+    if (
+      def.statusCheck !== undefined &&
+      typeof def.statusCheck !== "function"
+    ) {
+      throw new Error(
+        `Extension "${this.name}": connection() statusCheck must be a function`,
+      );
+    }
+    // At-least-one-signal and credentialEnvVar <-> envVars matching are
+    // validated in the loader after setup() returns, because mercury.connection()
+    // may legitimately be called before mercury.env() inside setup.
+    this.meta.connection = def;
+  }
+
+  get store(): ExtensionStore {
+    return {
+      get: (key: string) => this.db.getExtState(this.name, key),
+      set: (key: string, value: string) =>
+        this.db.setExtState(this.name, key, value),
+      delete: (key: string) => this.db.deleteExtState(this.name, key),
+      list: () => this.db.listExtState(this.name),
+    };
+  }
+
+  /** Called by the loader after setup — returns collected metadata. */
+  getMeta(): ExtensionMeta {
+    return this.meta;
+  }
+}

package/src/extensions/catalog.ts

@@ -0,0 +1,117 @@
+/**
+ * Bundled extension catalog for dashboard install. Sources live under
+ * `examples/extensions/<sourceDir>/` in the mercury-agent package (or repo).
+ */
+export type ExtensionCatalogCategory =
+  | "browsing"
+  | "automation"
+  | "knowledge"
+  | "voice"
+  | "code"
+  | "other";
+
+export interface ExtensionCatalogEntry {
+  /** Installed directory name under `.mercury/extensions/` */
+  name: string;
+  label: string;
+  description: string;
+  category: ExtensionCatalogCategory;
+  /** Subdirectory of `examples/extensions/` to copy from */
+  sourceDir: string;
+  requiredEnvVars?: string[];
+  requiresRestart: boolean;
+}
+
+export const EXTENSION_CATALOG: ExtensionCatalogEntry[] = [
+  {
+    name: "web-browser",
+    label: "Web browsing & automation",
+    description:
+      "Web search (Brave) and interactive browser (pinchtab) for sites like Gmail, banks, and forms.",
+    category: "automation",
+    sourceDir: "pinchtab",
+    requiredEnvVars: ["MERCURY_BRAVE_API_KEY"],
+    requiresRestart: true,
+  },
+  {
+    name: "napkin",
+    label: "Knowledge vault",
+    description:
+      "Obsidian-style vault, napkin CLI, and optional KB distillation job.",
+    category: "knowledge",
+    sourceDir: "napkin",
+    requiresRestart: true,
+  },
+  {
+    name: "charts",
+    label: "Charts",
+    description: "Minimal charts CLI extension example.",
+    category: "other",
+    sourceDir: "charts",
+    requiresRestart: true,
+  },
+  {
+    name: "pdf",
+    label: "PDF tools",
+    description: "PDF form filling and scripts (see extension skill).",
+    category: "other",
+    sourceDir: "pdf",
+    requiresRestart: true,
+  },
+  {
+    name: "gws",
+    label: "Google Workspace",
+    description: "Google Workspace integration (see extension skill).",
+    category: "other",
+    sourceDir: "gws",
+    requiresRestart: true,
+  },
+  {
+    name: "voice-transcribe",
+    label: "Voice transcription",
+    description:
+      "Transcribe voice with local Python (Transformers or Faster-Whisper) or Hugging Face Inference API.",
+    category: "voice",
+    sourceDir: "voice-transcribe",
+    requiresRestart: true,
+  },
+  {
+    name: "voice-synth",
+    label: "Voice synthesis (TTS)",
+    description:
+      "Google or Azure cloud TTS for English/Hebrew; mrctl tts synthesize and optional auto voice per space. Set Azure key+region and/or Google credentials path on the host.",
+    category: "voice",
+    sourceDir: "voice-synth",
+    requiresRestart: true,
+  },
+  {
+    name: "tradestation",
+    label: "TradeStation",
+    description:
+      "TradeStation API v3 (accounts, balances, positions, bars, host-gated orders via mrctl) with OAuth refresh; admin-only by default.",
+    category: "other",
+    sourceDir: "tradestation",
+    requiredEnvVars: [
+      "MERCURY_TS_CLIENT_ID",
+      "MERCURY_TS_CLIENT_SECRET",
+      "MERCURY_TRADESTATION_REFRESH_TOKEN",
+    ],
+    requiresRestart: true,
+  },
+  {
+    name: "yahoo-mail",
+    label: "Yahoo Mail",
+    description:
+      "Read, search, and send Yahoo Mail via IMAP/SMTP with an app-specific password.",
+    category: "other",
+    sourceDir: "yahoo-mail",
+    requiredEnvVars: ["MERCURY_YAHOO_EMAIL", "MERCURY_YAHOO_APP_PASSWORD"],
+    requiresRestart: true,
+  },
+];
+
+export function getCatalogEntryByName(
+  name: string,
+): ExtensionCatalogEntry | undefined {
+  return EXTENSION_CATALOG.find((e) => e.name === name);
+}

package/src/extensions/config-registry.ts

@@ -0,0 +1,83 @@
+/**
+ * Config registry — extensions register per-group config keys
+ * with descriptions, defaults, and optional validation.
+ *
+ * Keys are namespaced: extension "napkin" registering "enabled"
+ * becomes "napkin.enabled" in the DB.
+ */
+
+import type { ConfigDef } from "./types.js";
+
+export interface RegisteredConfig {
+  /** Extension that owns this key. */
+  extension: string;
+  /** Full namespaced key (e.g., "napkin.enabled"). */
+  key: string;
+  /** Human-readable description. */
+  description: string;
+  /** Default value when not set. */
+  default: string;
+  /** Optional validator. */
+  validate?: (value: string) => boolean;
+}
+
+export class ConfigRegistry {
+  private readonly configs = new Map<string, RegisteredConfig>();
+
+  /** Register a config key for an extension. */
+  register(extension: string, key: string, def: ConfigDef): void {
+    const fullKey = `${extension}.${key}`;
+    if (this.configs.has(fullKey)) {
+      throw new Error(`Config key "${fullKey}" already registered`);
+    }
+    this.configs.set(fullKey, {
+      extension,
+      key: fullKey,
+      description: def.description,
+      default: def.default,
+      validate: def.validate,
+    });
+  }
+
+  /** Get all registered configs. */
+  getAll(): RegisteredConfig[] {
+    return [...this.configs.values()];
+  }
+
+  /** Get configs for a specific extension. */
+  getForExtension(name: string): RegisteredConfig[] {
+    return [...this.configs.values()].filter((c) => c.extension === name);
+  }
+
+  /** Get a specific config by full key. */
+  get(fullKey: string): RegisteredConfig | undefined {
+    return this.configs.get(fullKey);
+  }
+
+  /** Check if a key is a registered extension config key. */
+  isValidKey(key: string): boolean {
+    return this.configs.has(key);
+  }
+
+  /**
+   * Validate a value for a registered key.
+   * Returns true if the key has no validator or the value passes.
+   * Returns false if the key is unknown or validation fails.
+   */
+  validate(key: string, value: string): boolean {
+    const config = this.configs.get(key);
+    if (!config) return false;
+    if (!config.validate) return true;
+    return config.validate(value);
+  }
+
+  /** Number of registered config keys. */
+  get size(): number {
+    return this.configs.size;
+  }
+
+  /** Clear all registrations (for testing). */
+  reset(): void {
+    this.configs.clear();
+  }
+}

package/src/extensions/context.ts

@@ -0,0 +1,36 @@
+/**
+ * Factory for MercuryExtensionContext — keeps dashboard and runtime in sync.
+ */
+
+import type { AppConfig } from "../config.js";
+import { hasPermission, resolveRole } from "../core/permissions.js";
+import type { Logger } from "../logger.js";
+import type { Db } from "../storage/db.js";
+import type { MercuryExtensionContext } from "./types.js";
+
+export function createMercuryExtensionContext(opts: {
+  db: Db;
+  config: AppConfig;
+  log: Logger;
+}): MercuryExtensionContext {
+  const { db, config, log } = opts;
+  return {
+    db,
+    config,
+    log,
+    hasCallerPermission(
+      spaceId: string,
+      callerId: string,
+      permission: string,
+    ): boolean {
+      const seededAdmins = config.admins
+        ? config.admins
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+      const role = resolveRole(db, spaceId, callerId, seededAdmins);
+      return hasPermission(db, spaceId, role, permission);
+    },
+  };
+}

package/src/extensions/hooks.ts

@@ -0,0 +1,156 @@
+/**
+ * Hook dispatcher — emits lifecycle events and dispatches to extension handlers.
+ *
+ * Handles mutation semantics for before_container and after_container events.
+ * Errors in handlers are caught and logged — never crash Mercury.
+ */
+
+import type { Logger } from "../logger.js";
+import type { EgressFile } from "../types.js";
+import type { ExtensionRegistry } from "./loader.js";
+import type {
+  AfterContainerResult,
+  BeforeContainerResult,
+  MercuryEvents,
+  MercuryExtensionContext,
+} from "./types.js";
+
+export class HookDispatcher {
+  constructor(
+    private readonly registry: ExtensionRegistry,
+    private readonly log: Logger,
+  ) {}
+
+  /**
+   * Emit a non-mutating event (startup, shutdown, workspace_init).
+   * Runs all handlers in load order. Errors are caught and logged.
+   */
+  async emit<E extends "startup" | "shutdown" | "workspace_init">(
+    event: E,
+    data: MercuryEvents[E],
+    ctx: MercuryExtensionContext,
+  ): Promise<void> {
+    const handlers = this.registry.getHookHandlers(event);
+    for (const handler of handlers) {
+      try {
+        await handler(data, ctx);
+      } catch (err) {
+        this.log.error(
+          `Hook "${event}" handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Emit before_container event with mutation support.
+   *
+   * Mutation semantics:
+   * - systemPrompt: concatenated across handlers (newline-separated)
+   * - promptAppend: concatenated across handlers (newline-separated)
+   * - env: merged (last-write-wins on key conflict)
+   * - block: first handler to block stops the chain
+   */
+  async emitBeforeContainer(
+    data: MercuryEvents["before_container"],
+    ctx: MercuryExtensionContext,
+  ): Promise<BeforeContainerResult | undefined> {
+    const handlers = this.registry.getHookHandlers("before_container");
+    if (handlers.length === 0) return undefined;
+
+    const systemPromptParts: string[] = [];
+    const promptAppendParts: string[] = [];
+    let env: Record<string, string> = {};
+    let hasMutations = false;
+
+    for (const handler of handlers) {
+      try {
+        const result = await handler(data, ctx);
+        if (!result) continue;
+
+        hasMutations = true;
+
+        if (result.block) {
+          return { block: result.block };
+        }
+        if (result.systemPrompt) {
+          systemPromptParts.push(result.systemPrompt);
+        }
+        if (result.promptAppend) {
+          promptAppendParts.push(result.promptAppend);
+        }
+        if (result.env) {
+          env = { ...env, ...result.env };
+        }
+      } catch (err) {
+        this.log.error(
+          `Hook "before_container" handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    if (!hasMutations) return undefined;
+
+    return {
+      ...(systemPromptParts.length > 0
+        ? { systemPrompt: systemPromptParts.join("\n") }
+        : {}),
+      ...(promptAppendParts.length > 0
+        ? { promptAppend: promptAppendParts.join("\n") }
+        : {}),
+      ...(Object.keys(env).length > 0 ? { env } : {}),
+    };
+  }
+
+  /**
+   * Emit after_container event with mutation support.
+   *
+   * Mutation semantics:
+   * - reply: last handler to return a reply wins
+   * - suppress: any handler returning true suppresses
+   * - files: arrays concatenated in handler registration order (append-only)
+   */
+  async emitAfterContainer(
+    data: MercuryEvents["after_container"],
+    ctx: MercuryExtensionContext,
+  ): Promise<AfterContainerResult | undefined> {
+    const handlers = this.registry.getHookHandlers("after_container");
+    if (handlers.length === 0) return undefined;
+
+    let reply: string | undefined;
+    let suppress = false;
+    const fileParts: EgressFile[] = [];
+    let hasMutations = false;
+
+    for (const handler of handlers) {
+      try {
+        const result = await handler(data, ctx);
+        if (!result) continue;
+
+        hasMutations = true;
+
+        if (result.reply !== undefined) {
+          reply = result.reply;
+        }
+        if (result.suppress) {
+          suppress = true;
+        }
+        if (result.files?.length) {
+          fileParts.push(...result.files);
+        }
+      } catch (err) {
+        this.log.error(
+          `Hook "after_container" handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    if (!hasMutations) return undefined;
+
+    return {
+      ...(reply !== undefined ? { reply } : {}),
+      ...(suppress ? { suppress } : {}),
+      ...(fileParts.length > 0 ? { files: fileParts } : {}),
+    };
+  }
+}