Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

3.5 KB
Raw Blame
/**
 * Plugin API 1.0: what an in-process plugin sees.
 *
 * A plugin module exports `activate(ctx)` and, optionally, `deactivate()`.
 * Everything it registers or schedules through `ctx` is torn down
 * automatically when the plugin is disabled, uninstalled or updated, so a
 * plugin that only uses the context cannot leak timers or tools.
 *
 * `mercury plugins init` writes these types into every new plugin as
 * mercury-plugin.d.ts (src/plugins/sdk-dts.ts, regenerated by
 * `node scripts/gen-plugin-sdk.mjs`; a test keeps the two in sync).
 */

export interface Disposable {
  dispose(): void;
}

export interface PluginLogger {
  debug(message: string, data?: Record<string, unknown>): void;
  info(message: string, data?: Record<string, unknown>): void;
  warn(message: string, data?: Record<string, unknown>): void;
  error(message: string, data?: Record<string, unknown>): void;
}

export interface PluginToolDefinition {
  /** Must match a tool declared in the manifest's `contributes.tools`. */
  name: string;
  /** JSON Schema (type "object") for the tool's arguments. */
  inputSchema: Record<string, unknown>;
  /**
   * Runs the tool. Return a string, or any JSON-serialisable value. Throwing
   * reports an error to the model; repeated failures disable the plugin.
   * `signal` aborts on timeout, on disable, and when the turn is cancelled.
   */
  execute(args: Record<string, unknown>, options: { signal: AbortSignal }): unknown | Promise<unknown>;
}

export interface PluginCommandIO {
  /** Send a message back to whoever ran the command (terminal, Telegram, web). */
  reply(text: string): Promise<void>;
  signal: AbortSignal;
}

export interface PluginCommandDefinition {
  /** Must match a command declared in the manifest's `contributes.commands`. Invoked as `/<name>`. */
  name: string;
  run(args: string, io: PluginCommandIO): void | Promise<void>;
}

export interface PluginContext {
  /** Plugin API version Mercury implements, e.g. "1.0.0". */
  readonly apiVersion: string;
  readonly mercuryVersion: string;
  readonly plugin: {
    readonly id: string;
    readonly version: string;
    /** A folder this plugin owns. Kept across updates; deleted only on uninstall --purge. */
    readonly dataDir: string;
  };
  readonly log: PluginLogger;
  readonly settings: {
    get<T = unknown>(key: string): T | undefined;
    all(): Record<string, unknown>;
  };
  /** Only the secrets declared in the manifest's `permissions.secrets` are readable. */
  readonly secrets: {
    get(name: string): string | undefined;
  };
  readonly tools: {
    register(definition: PluginToolDefinition): Disposable;
  };
  readonly commands: {
    register(definition: PluginCommandDefinition): Disposable;
  };
  /** Tracked timers: cleared automatically on disable. Errors inside them are contained. */
  readonly timers: {
    setTimeout(fn: () => void | Promise<void>, ms: number): Disposable;
    setInterval(fn: () => void | Promise<void>, ms: number): Disposable;
  };
  /**
   * fetch() limited to the hosts declared in `permissions.network`, through
   * Mercury's SSRF guard (private and loopback addresses are blocked).
   * Requests are aborted when the plugin is disabled.
   */
  fetch(url: string, init?: RequestInit): Promise<Response>;
  /** Aborted when the plugin is being disabled, updated or uninstalled. */
  readonly signal: AbortSignal;
  /** Run cleanup when the plugin stops. */
  onDispose(fn: () => void | Promise<void>): void;
}

export interface PluginModule {
  activate(ctx: PluginContext): void | Promise<void>;
  deactivate?(): void | Promise<void>;
}