Plugin lifecycle and integration
Hermes manages plugins as trusted, profile-scoped extensions that can add tools, providers, hooks, platform links, skills, and product surfaces. The lifecycle moves a plugin from a catalog or source into a checked and recorded install, then into an isolated runtime where its registrations and state remain bounded. See Plugin platform for the wider platform model.
Catalog and manifest model
The catalog and manifest together describe what a plugin is, where it comes from, what it needs, and what it can expose. The catalog identifies reviewed source revisions, while the plugin manifest describes the extension at that revision.
Catalog identity
The catalog in hermes_cli/plugin_catalog.py is a curated view of installable plugins. Each entry names an HTTPS repository and an exact commit SHA. It can also state a category, supported platforms, Hermes version needs, and declared capabilities. A bare catalog name resolves to the reviewed entry; a URL or repository shorthand is treated as a custom source instead.
The catalog is available from the checkout and from a published JSON feed. Hermes uses a cached feed when possible and falls back to the checkout when the feed is unavailable. The catalog also has a removal list. A matching name or repository is blocked at install, enable, and update time unless the operator explicitly bypasses that block.
References: hermes_cli/plugin_catalog.py• L1-12 hermes_cli/plugin_catalog.py• L74-115 hermes_cli/plugin_catalog.py• L264-305 hermes_cli/plugin_catalog.py• L353-388
Manifest contract
A native plugin uses plugin.yaml or plugin.yml. A portable Agent Plugin uses plugin.json. The manifest supplies the plugin name and version, its kind, the surfaces it provides, required environment values, declared capabilities, optional settings schema, and compatibility data. Hermes accepts older manifest files and treats newer unknown fields as forward-compatible warnings rather than silently granting new behavior.
Manifest identity has two forms: a path-based key for discovery and a name for display and configuration. Category plugins therefore keep their category in the key, which prevents two plugins with the same leaf name from sharing activation or state by accident. Advisory plugin dependencies affect load order and warnings; they do not make discovery fail when a dependency is absent.
References: hermes_cli/plugins_manifest.py• L27-42 hermes_cli/plugins_manifest.py• L219-265 hermes_cli/plugins_manifest.py• L336-395 hermes_cli/plugins_discovery.py• L134-186
Trust and compatibility gates
Hermes checks both the source and the requested runtime surface before plugin code becomes active. These checks separate reviewed provenance, version fit, user consent, and actual runtime availability.
Provenance classes
The installer-owned .install-metadata.json record is the authority for what Hermes installed. Hermes compares that record with the presence of a Git checkout to classify an installed directory:
| Class | Meaning | Lifecycle result |
|---|---|---|
| Git | Hermes recorded the install and the directory has Git metadata | The recorded source can be checked for updates. |
| Manual | Neither record nor Git metadata exists | The plugin is usable as a local drop but is not auto-updatable. |
| Self-cloned | Git metadata exists without an installer record | The operator can adopt the recorded Git origin explicitly. |
| Drift | Hermes recorded the install but Git metadata is missing | Hermes reports a provenance problem and asks for reinstall rather than guessing. |
Catalog identity is stored in the installer record, not trusted from a file inside the plugin tree. This stops a custom repository from claiming that it is a reviewed catalog install.
References: hermes_cli/plugins_provenance.py• L1-15 hermes_cli/plugins_provenance.py• L28-43 hermes_cli/plugins_provenance.py• L106-141 hermes_cli/plugins_cmd_catalog.py• L67-80 hermes_cli/plugins_cmd_catalog.py• L142-175
Compatibility and capability consent
The manifest can require a Hermes version. Hermes checks that requirement before import and records an incompatible plugin as skipped. Catalog entries can also limit supported operating systems, and portable packages can reject unavailable local resources. A manifest version newer than the install path supports stops publication so the plugin is not installed into an interpreter that cannot understand its file format.
Capabilities are declarations of sensitive actions, not grants. Known declarations map to existing enforcement gates such as tool replacement, alternate model routing, or platform actions. Enabling or installing a non-bundled plugin asks for consent. An update that adds a capability, tool, hook, dependency, or Desktop surface needs a new consent decision; a non-interactive path leaves the new access ungranted.
References: hermes_cli/plugins_manifest.py• L362-383 hermes_cli/plugins_manifest.py• L433-486 hermes_cli/plugin_capabilities.py• L27-63 hermes_cli/plugin_capabilities.py• L130-147 hermes_cli/plugin_capabilities.py• L196-210 hermes_cli/plugins_cmd_catalog.py• L481-524
Installation transactions
Installation is a staged publication, not a copy into the live plugin directory. Hermes prepares and checks a candidate tree first, then commits code, dependency selection, and install records through one recoverable handoff.
Staged publication
When Hermes processes an install, it follows this sequence:
flowchart LR
Source[Catalog or source] --> Clone[Staged clone]
Clone --> Manifest[Read manifest and compatibility]
Manifest --> Scan[Security and tree checks]
Scan --> Consent[Dependency and capability consent]
Consent --> Admit[Admit environment and selection]
Admit --> Publish[Publish code and metadata]
Publish --> Activate[Activate or leave disabled]
The candidate is cloned into a temporary location. Hermes validates its manifest, checks readability and source boundaries, scans the final tree, prepares declared dependencies, and only then replaces the live tree. If a check or admission step fails, the existing install remains in place. User-owned files are carried into a replacement only when Hermes can distinguish them from plugin code; tracked edits that cannot be carried are saved outside the plugin directory.
References: hermes_cli/plugins_cmd_install.py• L331-359 hermes_cli/plugins_cmd_install.py• L377-427 hermes_cli/plugins_cmd_install.py• L442-491 hermes_cli/plugins_transaction.py• L16-49
Dependency admission
Plugin dependency changes are part of the same decision as activation. Python requirements are prepared in the shared Hermes environment only through the package manager admission path. Node dependencies are kept in the plugin's own sidecar area and use a separate consent question. Discovery reports missing Python packages but does not install them.
The admission step resolves the proposed enabled and disabled sets against the active environment and the existing pinned dependencies. A conflict or refusal leaves both the configuration and environment unchanged. This prevents a plugin from becoming enabled while its runtime dependencies are only partly prepared.
References: hermes_cli/plugins_admission.py• L8-25 hermes_cli/plugins_admission.py• L50-80 hermes_cli/plugins_cmd_install.py• L69-161 hermes_cli/plugins_loader.py• L412-430
Isolation and activation
Discovery finds a plugin, but activation decides whether Hermes loads it and where its code runs. The selected mode must preserve profile boundaries and must not expose a capability before its trust and dependency gates pass.
Process isolation
Hermes supports in-process loading and host-process loading. Bundled plugins remain in the Hermes process. With plugins.isolation: host, non-bundled Python plugins run in one plugin-host process per profile and communicate through the plugin context. Hermes keeps the same registration view on its side, so tools and hooks still use normal dispatch paths.
The host boundary keeps third-party code out of a pooled or gateway process. A plugin crash or hang can therefore take down its host without taking down Hermes. Some integrations need live Hermes objects, such as native platform clients or dashboard authentication, and are refused or limited in host mode rather than being passed across the boundary.
References: hermes_cli/plugin_isolation.py• L1-17 hermes_cli/plugin_isolation.py• L32-73 hermes_cli/plugin_isolation.py• L114-136 hermes_cli/plugin_host.py• L1-17 hermes_cli/plugin_host.py• L54-73
Activation timing
Enabling a plugin records a canonical key in the profile selection. The explicit disabled list wins over the enabled list. Bundled backends and platform adapters can be active by default, while ordinary installed plugins normally need explicit enablement. A successful install or enable then asks the running serve process and gateway to reload the plugin.
Activation is intentionally split by surface:
| Surface | Availability after a live activation |
|---|---|
| Gateway commands, transforms, hooks, and platform callbacks | Live after the registry reload. |
| Portable skills and connected MCP servers | Live in open chats when their connection succeeds. |
| Python tools and system-prompt sections | Available to the next session. |
| No answering gateway or serve process | The plugin is recorded, but a restart is required. |
This split protects prompt caching and gives each running process an honest result instead of claiming that every registration is immediately usable.
References: hermes_cli/plugins_cmd.py• L471-519 hermes_cli/plugins_cmd.py• L560-640 hermes_cli/plugins_activation.py• L1-10 hermes_cli/plugins_activation.py• L31-74 hermes_cli/plugins_activation.py• L96-127
Runtime message injection
Plugins can inject text into the local CLI or into a live session owned by the TUI, Desktop, or messaging gateway. The caller chooses either an existing session key or a message origin for a new gateway session, never both. Gateway injection is denied unless the plugin has the profile setting that permits it.
The target profile comes from the plugin manager rather than from the ambient process context. Hermes first gives an owned session to the TUI or Desktop injector, then falls back to the gateway. A failed handoff returns false and does not send the same message through a second route.
References: hermes_cli/plugins_injection.py• L1-10 hermes_cli/plugins_injection.py• L12-37 hermes_cli/plugins_injection.py• L38-62
State and lifecycle changes
Plugin code is replaceable, but plugin-owned state must survive normal updates and remain isolated from other profiles and plugins. Update and removal therefore change code, records, selection, and state as related but separate concerns.
Profile-scoped state
Each plugin receives a profile-scoped data area and a namespaced JSON state store. State keys are bounded and validated, writes are atomic, and each plugin has a fixed quota. Plugin settings use plugins.entries.<plugin-id>.settings; relative keys cannot escape that namespace or write core configuration roots.
Secrets declared by a settings schema do not go into config.yaml. They resolve to a named .env value and use the existing credential write path. Removing a plugin clears its selection, grants, settings entry, and provider selection so a later reinstall does not inherit old trust or silently reactivate the plugin.
References: hermes_cli/plugins_state.py• L16-39 hermes_cli/plugins_state.py• L66-91 hermes_cli/plugins_state.py• L134-195 hermes_cli/plugins_settings.py• L1-10 hermes_cli/plugins_cmd.py• L575-604
Update and removal behavior
Catalog updates re-pin to the current reviewed commit rather than pulling an arbitrary branch. Custom Git installs update from their recorded source when their provenance is valid. Both paths stage a replacement, preserve eligible user files, re-check the manifest and dependencies, and publish only after the live tree is unchanged since preparation.
An update that changes the plugin name moves the selection to the new name and removes the old directory. A recalled plugin cannot be enabled or updated. Removal first keeps the install record and tree consistent. If a running process holds files open, Hermes moves the tree to a pending-delete area or strips its manifests so it cannot load again; a later sweep finishes deletion.
References: hermes_cli/plugins_transaction.py• L90-117 hermes_cli/plugins_transaction.py• L135-203 hermes_cli/plugins_cmd_catalog.py• L527-634 hermes_cli/plugins_cmd_remove.py• L22-68 hermes_cli/plugins_cmd_remove.py• L71-101
Change checklist
When these files or sections are changed, remember to consider these:
- Keep catalog pins, removal entries, live-catalog merging, and installer-owned provenance records aligned. The in-tree catalog must not be able to silently un-recall a live removal.
- Keep manifest capability declarations aligned with the enforcement gate and the consent hash. A new declared capability must not become active through an update without a new grant.
- Keep the staged publication path aligned with package-manager admission. Code publication and enabled selection must not commit when dependency resolution or configuration writing fails.
- Keep canonical plugin keys aligned across discovery, enabled and disabled lists, provider selection, settings, state namespaces, and update rename handling.
- Keep host-mode supported and refused context methods aligned with both the host runtime and the isolation audit.
- Keep activation summaries honest when adding a registration surface. Mark whether it is live, connected, or deferred to a new session.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Catalog name or repository is on the removal list | Install, enable, or update can activate recalled code | The in-tree and cached live kill lists block the operation unless the operator uses the explicit bypass. |
Catalog entry is installed from an off-pin --ref | The tree is not the reviewed revision and normal catalog update status can be misleading | Installer metadata records the checked-out revision separately from the reviewed pin. |
| Hermes version or host platform is incompatible | The plugin is installed or discovered but does not load | Manifest and catalog compatibility checks reject or skip it before activation. |
| Enablement conflicts with Hermes or another plugin's dependencies | A partial environment could leave the plugin enabled but unusable | Package-manager admission commits dependency state and selection as one transaction. |
| A plugin widens its capabilities or runtime surface on update | New code could gain access without a fresh user decision | Surface deltas require consent; unattended updates leave additions inactive. |
| Plugin host exits or a plugin load exceeds its deadline | Plugin registrations fail while Hermes continues | Host restart limits, load deadlines, and registration cleanup isolate the failure. |
| Removal meets a locked file or mapped module | Old plugin files could remain discoverable or removal could split from metadata | Hermes parks or strips the tree and sweeps pending deletes later. |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/plugin_catalog.py | Catalog pins, live-feed fallback, and the removal list. |
| hermes_cli/plugins_manifest.py | Native and portable manifest meaning, compatibility fields, and dependency ordering. |
| hermes_cli/plugins_provenance.py | The four-way distinction between tracked, manual, self-cloned, and drifted installs. |
| hermes_cli/plugins_cmd_install.py | The install stages from source resolution through staged publication and enablement. |
| hermes_cli/plugins_admission.py | The package-manager transaction that protects environment and selection consistency. |
| hermes_cli/plugin_isolation.py and hermes_cli/plugin_host.py | The process boundary and its profile-scoped host behavior. |
| hermes_cli/plugins_activation.py | Live reload behavior and the boundary between immediate and next-session activation. |
| hermes_cli/plugins_state.py | Profile-scoped settings and durable plugin state rules. |
| hermes_cli/plugins_transaction.py and hermes_cli/plugins_cmd_catalog.py | Recoverable update publication, catalog re-pin, and user-file preservation. |
| hermes_cli/plugins_cmd_remove.py | Removal bookkeeping and deferred cleanup for locked trees. |