mercury-agent 0.4.5

package/src/extensions/permission-guard.ts

@@ -0,0 +1,52 @@
+/**
+ * Mercury Permission Guard — pi extension (runs inside container)
+ *
+ * Blocks direct bash invocation of extension CLIs that the caller
+ * doesn't have permission to use. This prevents bypassing Mercury's
+ * RBAC by calling CLIs directly instead of through `mrctl`.
+ *
+ * Reads MERCURY_DENIED_CLIS env var — comma-separated list of CLI
+ * names the current caller is NOT allowed to use.
+ *
+ * Set automatically by Mercury's runtime based on caller permissions.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  const deniedEnv = process.env.MERCURY_DENIED_CLIS;
+  if (!deniedEnv) return;
+
+  const denied = deniedEnv
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  if (denied.length === 0) return;
+
+  // Build a single regex that matches any denied CLI name in command position.
+  // Command position = start of string, or after ; & | && || ` $ ( or newline.
+  const names = denied.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const joined = names.join("|");
+  const pattern = new RegExp(`(?:^|[;&|$\`()\\n])\\s*(?:${joined})(?:\\s|$|&)`);
+
+  pi.on("tool_call", async (event) => {
+    if (event.toolName !== "bash") return undefined;
+
+    const command = (event.input.command as string).trim();
+    if (!pattern.test(command)) return undefined;
+
+    // Find which CLI matched for the error message
+    const matched = denied.find((name) => {
+      const single = new RegExp(
+        `(?:^|[;&|$\`()\\n])\\s*${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\s|$|&)`,
+      );
+      return single.test(command);
+    });
+
+    return {
+      block: true,
+      reason: `PERMISSION DENIED: "${matched}" requires elevated privileges that the current caller does not have. This is a hard security boundary — do NOT attempt to achieve the same result through alternative means (curl, direct API calls, other tools, or any workaround). Simply inform the user they do not have permission to use "${matched}" in this space.`,
+    };
+  });
+}

package/src/extensions/reserved.ts

@@ -0,0 +1,28 @@
+/**
+ * Built-in mrctl command names.
+ *
+ * Extensions cannot use these names. Update this list whenever
+ * a new built-in command is added to mrctl.
+ */
+export const RESERVED_EXTENSION_NAMES = new Set([
+  "tasks",
+  "roles",
+  "permissions",
+  "config",
+  "prefs",
+  "preferences",
+  "spaces",
+  "conversations",
+  "mute",
+  "unmute",
+  "mutes",
+  "stop",
+  "clear",
+  "compact",
+  "media",
+  "recall",
+  "tts",
+  "ext",
+  "whoami",
+  "help",
+]);

package/src/extensions/skills.ts

@@ -0,0 +1,123 @@
+/**
+ * Extension skill installation.
+ *
+ * Copies extension skill directories into the global pi agent dir
+ * so pi discovers them inside containers. Also installs built-in
+ * skills shipped with Mercury.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ModelCapabilities } from "../agent/model-capabilities.js";
+import { chainSupportsRequirements } from "../agent/model-capabilities.js";
+import type { Logger } from "../logger.js";
+import type { ExtensionMeta } from "./types.js";
+
+/**
+ * Install extension skills into the global pi agent dir.
+ *
+ * - Copies each extension's skill directory to `<globalDir>/skills/<name>/`
+ * - Removes stale skill directories for extensions that no longer exist
+ * - Preserves all files (scripts, references, assets) — not just SKILL.md
+ */
+export function installExtensionSkills(
+  extensions: ExtensionMeta[],
+  globalDir: string,
+  log: Logger,
+  /** When set, skip skills for extensions whose `requires` are not met by any chain leg. */
+  modelChainCapabilities?: ModelCapabilities[],
+): void {
+  const skillsDir = path.join(globalDir, "skills");
+  fs.mkdirSync(skillsDir, { recursive: true });
+
+  const chainCaps = modelChainCapabilities ?? [];
+
+  // Track which extension names have skills (after capability filter)
+  const activeSkillNames = new Set(
+    extensions
+      .filter((e) => {
+        if (!e.skillDir) return false;
+        if (!e.requires?.length) return true;
+        if (chainCaps.length === 0) return true;
+        return chainSupportsRequirements(e.requires, chainCaps);
+      })
+      .map((e) => e.name),
+  );
+
+  // Clean up stale skill directories
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!activeSkillNames.has(entry.name)) {
+      const stale = path.join(skillsDir, entry.name);
+      fs.rmSync(stale, { recursive: true, force: true });
+      log.info(`Removed stale skill: ${entry.name}`);
+    }
+  }
+
+  // Copy skill directories
+  for (const ext of extensions) {
+    if (!ext.skillDir) continue;
+    if (ext.requires?.length && chainCaps.length > 0) {
+      if (!chainSupportsRequirements(ext.requires, chainCaps)) {
+        log.debug(`Skipping skill install (capabilities): ${ext.name}`, {
+          requires: ext.requires,
+        });
+        continue;
+      }
+    }
+    const dst = path.join(skillsDir, ext.name);
+    fs.rmSync(dst, { recursive: true, force: true });
+    fs.cpSync(ext.skillDir, dst, { recursive: true });
+    log.info(`Installed skill: ${ext.name}`);
+  }
+}
+
+/**
+ * Install built-in skills shipped with Mercury.
+ *
+ * Copies from `resources/skills/` into `<globalDir>/skills/`.
+ * Built-in skills are for mrctl built-in commands (tasks, roles, etc.).
+ */
+export function installBuiltinSkills(
+  builtinSkillsDir: string,
+  globalDir: string,
+  log: Logger,
+  /** Built-in skills assume tool use (mrctl). Skip when no leg has tools. */
+  modelChainCapabilities?: ModelCapabilities[],
+): void {
+  if (!fs.existsSync(builtinSkillsDir)) {
+    log.debug(`No built-in skills directory: ${builtinSkillsDir}`);
+    return;
+  }
+
+  const chainCaps = modelChainCapabilities ?? [];
+  if (chainCaps.length > 0 && !chainCaps.some((c) => c.tools)) {
+    const skillsDir = path.join(globalDir, "skills");
+    for (const name of fs.readdirSync(builtinSkillsDir, {
+      withFileTypes: true,
+    })) {
+      if (!name.isDirectory()) continue;
+      const stale = path.join(skillsDir, name.name);
+      if (fs.existsSync(stale)) {
+        fs.rmSync(stale, { recursive: true, force: true });
+        log.info(
+          `Removed built-in skill (no tools on model chain): ${name.name}`,
+        );
+      }
+    }
+    return;
+  }
+
+  const skillsDir = path.join(globalDir, "skills");
+  fs.mkdirSync(skillsDir, { recursive: true });
+
+  for (const entry of fs.readdirSync(builtinSkillsDir, {
+    withFileTypes: true,
+  })) {
+    if (!entry.isDirectory()) continue;
+    const src = path.join(builtinSkillsDir, entry.name);
+    const dst = path.join(skillsDir, entry.name);
+    fs.cpSync(src, dst, { recursive: true });
+    log.debug(`Installed built-in skill: ${entry.name}`);
+  }
+}

package/src/extensions/types.ts

@@ -0,0 +1,462 @@
+/**
+ * Mercury Extension System — Type Definitions
+ *
+ * All types for the extension API, events, metadata, and supporting structures.
+ * No runtime code — types only.
+ */
+
+import type { ContainerError } from "../agent/container-error.js";
+import type { ModelCapabilityKey } from "../agent/model-capabilities.js";
+import type { AppConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+import type { Db } from "../storage/db.js";
+import type { EgressFile, MessageAttachment } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Extension context — passed to event handlers and job runners
+// ---------------------------------------------------------------------------
+
+/** Context available to extension hooks and jobs at runtime. */
+export interface MercuryExtensionContext {
+  /** Database access. */
+  readonly db: Db;
+  /** Mercury configuration. */
+  readonly config: AppConfig;
+  /** Logger scoped to the extension. */
+  readonly log: Logger;
+  /**
+   * True if the caller has the permission in this space (built-in or extension-registered).
+   * Used by extensions in hooks to mirror container RBAC.
+   */
+  hasCallerPermission(
+    spaceId: string,
+    callerId: string,
+    permission: string,
+  ): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+/** All lifecycle events an extension can subscribe to. */
+export interface MercuryEvents {
+  /** Fired after all extensions are loaded and the runtime is ready. */
+  startup: StartupEvent;
+  /** Fired when Mercury is shutting down. */
+  shutdown: ShutdownEvent;
+  /** Fired when a space workspace directory is created or ensured. */
+  workspace_init: WorkspaceInitEvent;
+  /** Fired just before a container is spawned for a message. */
+  before_container: BeforeContainerEvent;
+  /** Fired after a container finishes (success or error). */
+  after_container: AfterContainerEvent;
+}
+
+export type StartupEvent = Record<string, never>;
+
+export type ShutdownEvent = Record<string, never>;
+
+export interface WorkspaceInitEvent {
+  /** The space this workspace belongs to. */
+  spaceId: string;
+  /** Absolute path to the workspace directory. */
+  workspace: string;
+  /** Container-relative path to the workspace (e.g. /spaces/main). */
+  containerWorkspace: string;
+}
+
+export interface BeforeContainerEvent {
+  /** The space the message belongs to. */
+  spaceId: string;
+  /** The user's prompt. */
+  prompt: string;
+  /** Platform-specific caller identifier. */
+  callerId: string;
+  /** Absolute path to the space workspace. */
+  workspace: string;
+  /** Container-relative path to the workspace (e.g. /spaces/main). */
+  containerWorkspace: string;
+  /** Incoming attachments (e.g. voice, images), if any. */
+  attachments?: MessageAttachment[];
+}
+
+export interface AfterContainerEvent {
+  /** The space the message belongs to. */
+  spaceId: string;
+  /** Absolute path to the space workspace on the host. */
+  workspace: string;
+  /** Platform user id for this turn (same as container `CALLER_ID`). */
+  callerId: string;
+  /** User prompt for this turn (includes any `promptAppend` from `before_container`). */
+  prompt: string;
+  /** The agent's reply (empty string on error). */
+  reply: string;
+  /** How long the container ran, in milliseconds. */
+  durationMs: number;
+  /** Present if the container failed. */
+  error?: ContainerError;
+}
+
+// ---------------------------------------------------------------------------
+// Event return types — mutations hooks can apply
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value from a `before_container` handler.
+ * All fields are optional — return only what you want to mutate.
+ */
+export interface BeforeContainerResult {
+  /** Extra text appended to the system prompt inside the container. */
+  systemPrompt?: string;
+  /** Text appended to the user prompt (newline-joined across handlers). */
+  promptAppend?: string;
+  /** Extra environment variables passed to the container. */
+  env?: Record<string, string>;
+  /** If set, blocks the container from running entirely. */
+  block?: { reason: string };
+}
+
+/**
+ * Return value from an `after_container` handler.
+ * All fields are optional — return only what you want to mutate.
+ */
+export interface AfterContainerResult {
+  /** Replace the agent's reply. */
+  reply?: string;
+  /** If true, suppress the reply (don't send it to the chat). */
+  suppress?: boolean;
+  /**
+   * Extra egress files to attach (e.g. host-generated audio). Appended after
+   * container outbox files; order is concatenation of handlers in registration order.
+   */
+  files?: EgressFile[];
+}
+
+/** Maps event names to their allowed return types. */
+export type EventResult<E extends keyof MercuryEvents> =
+  E extends "before_container"
+    ? BeforeContainerResult | undefined
+    : E extends "after_container"
+      ? AfterContainerResult | undefined
+      : undefined;
+
+/** A typed event handler for a specific event. */
+export type EventHandler<E extends keyof MercuryEvents> = (
+  event: MercuryEvents[E],
+  ctx: MercuryExtensionContext,
+) => Promise<EventResult<E>>;
+
+// ---------------------------------------------------------------------------
+// Jobs
+// ---------------------------------------------------------------------------
+
+/** Definition for a background job registered by an extension. */
+export interface JobDef {
+  /** Run on a fixed interval (milliseconds). Mutually exclusive with `cron`. */
+  interval?: number;
+  /** Run on a cron schedule (5-field expression). Mutually exclusive with `interval`. */
+  cron?: string;
+  /** The function to execute on each tick. */
+  run: (ctx: MercuryExtensionContext) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/** Definition for a per-space config key registered by an extension. */
+export interface ConfigDef {
+  /** Human-readable description shown in `mrctl config get`. */
+  description: string;
+  /** Default value when not explicitly set. */
+  default: string;
+  /** Optional validator — return true if value is acceptable. */
+  validate?: (value: string) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Widgets
+// ---------------------------------------------------------------------------
+
+/** Definition for a dashboard widget registered by an extension. */
+export interface WidgetDef {
+  /** Display label shown in the dashboard. */
+  label: string;
+  /** Render function returning an HTML fragment. */
+  render: (ctx: MercuryExtensionContext) => string;
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+/** Scoped key-value store for extension-private persistent state. */
+export interface ExtensionStore {
+  /** Get a value by key, or null if not set. */
+  get(key: string): string | null;
+  /** Set a key-value pair (upsert). */
+  set(key: string, value: string): void;
+  /** Delete a key. Returns true if the key existed. */
+  delete(key: string): boolean;
+  /** List all key-value pairs for this extension. */
+  list(): Array<{ key: string; value: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Extension API — the object passed to each extension's setup function
+// ---------------------------------------------------------------------------
+
+/** The API surface available to extensions during setup. */
+export interface MercuryExtensionAPI {
+  /** The extension's name (directory name). */
+  readonly name: string;
+
+  /**
+   * Declare a CLI tool to install in the derived container image.
+   * Can only be called once per extension.
+   *
+   * @example
+   * mercury.cli({ name: "napkin", install: "bun add -g napkin-ai" });
+   */
+  cli(opts: CliDef): void;
+
+  /**
+   * Register this extension's permission and set which roles get it by default.
+   * The permission name is the extension name. Can only be called once.
+   *
+   * @example
+   * mercury.permission({ defaultRoles: ["admin", "member"] });
+   */
+  permission(opts: PermissionDef): void;
+
+  /**
+   * Declare an environment variable this extension needs.
+   * Only injected into containers when the caller has permission for this extension.
+   * Can be called multiple times for multiple env vars.
+   *
+   * @example
+   * mercury.env({ from: "MERCURY_GH_TOKEN" }); // injected as GH_TOKEN
+   * mercury.env({ from: "MERCURY_GH_TOKEN", as: "GITHUB_TOKEN" }); // custom name
+   */
+  env(def: EnvDef): void;
+
+  /**
+   * Register a skill directory containing a SKILL.md for agent discovery.
+   * Path is relative to the extension directory.
+   *
+   * @example
+   * mercury.skill("./skill");
+   */
+  skill(relativePath: string): void;
+
+  /**
+   * Declare capability requirements for this extension's skill / CLI workflows.
+   * If no model leg in the chain satisfies all listed capabilities, the extension
+   * skill is not installed and a startup warning is logged.
+   *
+   * @example
+   * mercury.requires(["tools"]);
+   */
+  requires(capabilities: ModelCapabilityKey[]): void;
+
+  /**
+   * Subscribe to a lifecycle event.
+   *
+   * @example
+   * mercury.on("workspace_init", async (event, ctx) => {
+   *   mkdirSync(join(event.workspace, "my-dir"), { recursive: true });
+   * });
+   */
+  on<E extends keyof MercuryEvents>(event: E, handler: EventHandler<E>): void;
+
+  /**
+   * Register a background job that runs on the host.
+   *
+   * @example
+   * mercury.job("cleanup", { interval: 3600_000, run: async (ctx) => { ... } });
+   */
+  job(name: string, def: JobDef): void;
+
+  /**
+   * Register a per-space config key. Namespaced to the extension automatically.
+   *
+   * @example
+   * mercury.config("enabled", { description: "Enable for this group", default: "true" });
+   * // Registers as "napkin.enabled" in the DB
+   */
+  config(key: string, def: ConfigDef): void;
+
+  /**
+   * Register a dashboard widget.
+   *
+   * @example
+   * mercury.widget({ label: "Status", render: (ctx) => "<p>OK</p>" });
+   */
+  widget(def: WidgetDef): void;
+
+  /**
+   * Declare this extension as a personal service connection. Additive on top
+   * of cli/env/skill; extensions that never call this are unaffected. Can
+   * only be called once per extension.
+   *
+   * @example
+   * mercury.connection({
+   *   displayName: "Google Workspace",
+   *   category: "workspace",
+   *   authType: "credentials-file",
+   *   credentialEnvVar: "MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE",
+   * });
+   */
+  connection(def: ConnectionDef): void;
+
+  /** Scoped key-value store for persistent extension state. */
+  readonly store: ExtensionStore;
+}
+
+// ---------------------------------------------------------------------------
+// CLI + Permission definitions
+// ---------------------------------------------------------------------------
+
+/** Declaration for a CLI tool to install in the container image. */
+export interface CliDef {
+  /** CLI binary name (should match the extension name). */
+  name: string;
+  /** Shell command to install the CLI (runs as a Dockerfile RUN step). */
+  install: string;
+  /**
+   * Absolute path to a local script to copy into `/usr/local/bin/{name}`.
+   * Set by the extension loader from the extension's directory.
+   */
+  bin?: string;
+}
+
+/** Permission configuration for an extension. */
+export interface PermissionDef {
+  /** Roles that should have this permission by default. */
+  defaultRoles: string[];
+}
+
+/** Environment variable declaration for an extension. */
+export interface EnvDef {
+  /** Env var name as it appears in .env (e.g. "MERCURY_GH_TOKEN"). */
+  from: string;
+  /** Env var name inside the container (e.g. "GH_TOKEN"). Defaults to `from` with MERCURY_ prefix stripped. */
+  as?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Connection metadata — first-class personal service connections
+// ---------------------------------------------------------------------------
+
+/** Runtime status of a personal service connection. */
+export type ConnectionStatus =
+  | "connected"
+  | "needs-reauth"
+  | "broken"
+  | "unknown";
+
+/** Closed category taxonomy for connections (v1 — tags deferred). */
+export type ConnectionCategory =
+  | "email"
+  | "drive"
+  | "calendar"
+  | "finance"
+  | "messaging"
+  | "docs"
+  | "workspace"
+  | "other";
+
+/** How the connection authenticates. */
+export type ConnectionAuthType =
+  | "oauth2"
+  | "apikey"
+  | "app-password"
+  | "credentials-file"
+  | "form"
+  | "custom";
+
+/** Result of an on-request `statusCheck` probe. */
+export interface ConnectionStatusResult {
+  status: ConnectionStatus;
+  /** Optional one-line explanation surfaced to the UI (e.g. "token expired 2h ago"). */
+  detail?: string;
+}
+
+/**
+ * Declaration for a personal service connection registered via
+ * `mercury.connection()`. At least one of `credentialEnvVar` or `statusCheck`
+ * must be set — enforced at load.
+ */
+export interface ConnectionDef {
+  /** User-facing name (e.g. "Google Workspace"). */
+  displayName: string;
+  /** Optional icon URL surfaced to the console. */
+  iconUrl?: string;
+  /** Category used for grouping in the UI. */
+  category: ConnectionCategory;
+  /** Auth mechanism used by the upstream service. */
+  authType: ConnectionAuthType;
+  /**
+   * Optional. If set, MUST match one of the env var names declared via
+   * `mercury.env({ from })`. Validated at load. Used for the default
+   * presence-check status when `statusCheck` is absent. Extensions that store
+   * credentials in `extension_state` (e.g. tradestation OAuth) omit this and
+   * rely on `statusCheck`.
+   */
+  credentialEnvVar?: string;
+  /** Optional OAuth-style scope list (informational, surfaced to the UI). */
+  scopes?: string[];
+  /**
+   * Optional probe. Runs on the host with the full extension context. The
+   * caller enforces a 5-second timeout. Must be side-effect free.
+   */
+  statusCheck?: (
+    ctx: MercuryExtensionContext,
+  ) => Promise<ConnectionStatusResult>;
+  /**
+   * If true, this connection accesses personal/sensitive data (email, finance,
+   * authenticated browser). In group-linked spaces, the runtime guard requires
+   * explicit admin enablement and per-request confirmation before proceeding.
+   */
+  sensitive?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Extension metadata — collected after running the setup function
+// ---------------------------------------------------------------------------
+
+/** Fully resolved metadata for a loaded extension. */
+export interface ExtensionMeta {
+  /** Extension name (directory name). */
+  name: string;
+  /** Absolute path to the extension directory. */
+  dir: string;
+  /** CLI declarations (may be empty). */
+  clis: CliDef[];
+  /** Permission configuration, if any. */
+  permission?: PermissionDef;
+  /** If set, skill install requires these capabilities on at least one model chain leg. */
+  requires?: ModelCapabilityKey[];
+  /** Absolute path to the skill directory, if declared. */
+  skillDir?: string;
+  /** Event handlers keyed by event name. */
+  hooks: Map<keyof MercuryEvents, EventHandler<keyof MercuryEvents>[]>;
+  /** Background jobs keyed by job name. */
+  jobs: Map<string, JobDef>;
+  /** Config key definitions keyed by local key (not namespaced). */
+  configs: Map<string, ConfigDef>;
+  /** Dashboard widgets. */
+  widgets: WidgetDef[];
+  /** Declared environment variables. */
+  envVars: EnvDef[];
+  /** Personal service connection metadata, if declared via `mercury.connection()`. */
+  connection?: ConnectionDef;
+}
+
+// ---------------------------------------------------------------------------
+// Extension setup function signature
+// ---------------------------------------------------------------------------
+
+/** The default export every extension must provide. */
+export type ExtensionSetupFn = (api: MercuryExtensionAPI) => void;