Plugin

Plugin = object

Defined in: types/plugin-types/index.ts:418

The plugin module: the single value the core’s loader consumes. A plugin package exports one as a plain object — it must not import the app it plugs into, so compatibility is checked where the core’s plugin list is typed against this.

apiVersion: the contract version this plugin was built against (see PLUGIN_API_VERSION). Mandatory; the loader refuses a mismatch.
name: the plugin’s name, what dependsOn and the logs refer to it by; for a CLI plugin, the binary it owns.
description: what the plugin lets the assistant do, in one English sentence written for the model ({{assistant}} stands for its name). The system prompt lists the plugins offered to the person with theirs, and the model answers “what can you do?” from that list. It says what, never how: usage instructions belong to skills and systemPromptFragment. Mandatory and on one line; the loader refuses a plugin without one, or with a line break inside it.
dependsOn: names of plugins this one requires present. The loader loads dependencies first and skips this plugin fail-soft if any is absent or failed (see loadPlugins). Presence + ordering only — a dependency shares its capability through the usual registries, not a handle injected here. Absent/empty ⇒ no dependency.
systemPromptFragment: the tool-surface description spliced into the system prompt when the plugin is active.
build: the env/model-dependent contributions (its tool, post-processors, status describers, guards). A plugin that owns a CLI tool validates its own allowlist here (schema only — its pinned binary is co-shipped) before building the tool.
skills: Agent-Skills the plugin contributes (see Skill); their descriptors go in the system prompt, their bodies load on demand.
surfaces: reserved (see PluginSurface); absent for a plugin with none.
messages: the plugin’s texts a person sees, in English (see Messages), every key under <name>.; the loader refuses a plugin with a key outside it. The instance’s language files translate them.
actsAs: whose identity the plugin’s tools act with at the service they reach. "person": the person the turn is for, who logs in to it through Mercury (the plugin contributes login). "mercury": Mercury’s own service identity, whoever asks. "anyone": no identity at all (a public service, no login): offered to everyone, and its tools still get the turn’s person, to keep what belongs to them; an older core reads it as "mercury". Undeclared counts as "mercury". A "mercury" plugin is offered to people only when they hold the permission to make Mercury act as itself (mercury.act-as-self, or mercury.act-as-self.<plugin>), and on the terminal.

A plugin no longer carries a raw cliConfig: the core knows nothing about CLIs. A CLI-based plugin owns its allowlist and, using @mercury-fw/cli-engine, builds its own tool in build() — the core just collects the contributed tools.