Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
/**
* 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>;
}