Plugin platform
Hermes plugins are optional extensions that add provider profiles, tools, chat platforms, agent behavior, and product surfaces without changing the core agent flow. The platform treats a plugin as a declared and governed unit: it finds the plugin, checks what it asks for, publishes it safely, runs it within a defined trust boundary, and keeps its live registrations tied to the plugin that owns them. See Plugin lifecycle and integration for the detailed lifecycle and runtime contracts.
Extension model
The plugin platform connects third-party code to named Hermes extension points. A plugin exposes capabilities through a manifest and a registration context, while Hermes keeps routing, policy, state ownership, and cleanup under host control.
Extension categories
Plugins extend Hermes at several product boundaries. The same platform supports both background integrations and user-facing features, so a plugin can add a provider or tool without becoming a separate application.
| Category | Product role |
|---|---|
| Providers | Supply model, web search, browser, media, speech, terminal, secret, memory, or context services. |
| Tools and skills | Add actions or reusable agent abilities to sessions. |
| Platforms | Connect Hermes to an inbound or outbound chat service. |
| Hooks and middleware | Observe or shape agent, tool, gateway, approval, and session events through named contracts. |
| Product surfaces | Add commands, dashboard pages, dashboard slots, language packs, prompt sections, and auxiliary tasks. |
References: hermes_cli/plugins.py• L455-498 hermes_cli/plugins.py• L685-808 hermes_cli/plugins.py• L933-1011 web/…/registry.ts• L63-191
Profile scope
Plugin selection and plugin-owned data belong to a Hermes profile. This keeps one profile's providers, settings, credentials, and registrations from leaking into another profile when one process serves many profiles.
References: hermes_cli/plugins.py• L1153-1239 hermes_cli/plugins_state.py• L134-195 providers/__init__.py• L67-90
Discovery and admission
Discovery turns possible plugin sources into candidate manifests. Admission then decides which candidate is trusted, compatible, enabled, and safe enough to publish; finding a plugin does not by itself execute or activate it.
Plugin sources
Hermes can discover bundled plugins, profile-local plugins, opt-in project plugins, and installed Python packages that advertise the Hermes plugin entry-point group. The Desktop app also probes Git repositories and optional subdirectories for desktop plugin artifacts. Later sources can replace an earlier plugin with the same identity, while project discovery stays explicitly disabled unless the operator opts in.
References: hermes_cli/plugins_discovery.py• L134-218 hermes_cli/plugins_discovery.py• L221-243 hermes_cli/plugins_discovery.py• L72-100 apps/…/desktop-plugin-install.ts• L66-121 apps/…/desktop-plugin-install.ts• L475-509
Manifest contract
A manifest gives Hermes the identity, kind, compatibility, dependencies, declared capabilities, configuration shape, and product surfaces of a plugin before normal runtime loading. Hermes accepts older manifest forms, ignores unknown fields for forward compatibility, and treats plugin-to-plugin dependencies as load-order advice rather than a reason to remove the dependent plugin.
References: hermes_cli/plugins_manifest.py• L27-42 hermes_cli/plugins_manifest.py• L129-184 hermes_cli/plugins_manifest.py• L219-265
Trust and compatibility gates
Admission checks the candidate tree before it can replace the installed tree. The checks cover manifest shape, Hermes version requirements, declared environment and configuration data, actual registered capabilities, security findings, and product-surface rules. Capability consent is separate from installation: an installed plugin may remain unable to use a gated action until the operator grants it.
References: hermes_cli/plugin_validate.py• L1-11 hermes_cli/plugins_cmd.py• L183-225 hermes_cli/plugin_capabilities.py• L27-51 hermes_cli/plugin_capabilities.py• L161-210
Installation and publication
Installation changes a profile in stages so untrusted or incomplete code does not become the live plugin by accident. Hermes obtains a candidate, checks it, prepares dependencies and required environment values with user consent, then publishes the candidate and its provenance as one recoverable change.
Installation transaction
The install flow stages the source outside the live plugin directory. It reads and validates the manifest, scans the final staged tree, checks portable package availability, prepares dependencies through the Hermes package manager, and only then publishes the tree and install record. A declined dependency decision leaves the plugin installed but disabled rather than silently changing the active environment.
References: hermes_cli/plugins_cmd_install.py• L331-359 hermes_cli/plugins_cmd_install.py• L377-429 hermes_cli/plugins_cmd_install.py• L470-491 hermes_cli/plugins_transaction.py• L16-49
Desktop installation
The Desktop Git installer separates review from publication. It probes a temporary clone, identifies whether the source has an agent half, a desktop half, or both, and records the reviewed commit. Installation uses that exact commit, so a source that moves after review is refused instead of silently changing the code being installed.
The installer publishes only a checked desktop tree into the app-level desktop plugin root. A unified package uses the agent package name and a marker so the Desktop copy stays paired with its agent half; a desktop-only repository remains independent. Staging and a shared root lock keep incomplete copies and concurrent reconcile passes out of the live root.
References: apps/…/desktop-plugin-install.ts• L263-320 apps/…/desktop-plugin-install.ts• L423-447 apps/…/desktop-plugin-install.ts• L522-615 apps/…/desktop-plugins-root.ts• L74-96 apps/…/desktop-plugins-root.ts• L369-469
Provenance records
Hermes records how a plugin entered the profile so later update decisions do not rely on claims inside plugin code. A tracked Git installation can be updated from its approved source, a manual copy is not auto-updatable, and a mismatch between the recorded source and the installed tree is treated as drift that needs repair.
References: hermes_cli/plugins_provenance.py• L1-15 hermes_cli/plugins_provenance.py• L28-43 hermes_cli/plugins_provenance.py• L106-141
Runtime activation
Activation converts an admitted plugin into live registrations that Hermes can route to. Hermes records ownership for each registration, which lets it remove or replace a plugin without leaving stale tools, hooks, providers, platform handlers, or product entries behind.
Registration boundary
The plugin receives a controlled context rather than the core's private registries. Through that context it can register public extension types, read or write namespaced settings, keep profile-scoped state, and request gated actions. Hermes checks types and conflicts at the boundary and tracks each accepted registration for later teardown.
References: hermes_cli/plugins.py• L230-285 hermes_cli/plugins.py• L296-373 hermes_cli/plugins.py• L455-498 hermes_cli/plugins_state.py• L24-90
Activation timing
An installed or enabled plugin can become partly useful without a full process restart. Gateway commands, transforms, platform callbacks, locales, portable MCP connections, and skills can become live during activation, while Python tools and prompt sections wait for a new session to preserve prompt and tool-cache behavior.
This diagram shows the handoff from a published plugin to the surfaces that can use it immediately or later.
flowchart LR
A[Published and enabled plugin] --> B[Profile discovery]
B --> C[Registration ledger]
C --> D[Gateway handlers and callbacks]
C --> E[Skills and MCP connections]
C --> F[Next-session tools and prompt sections]
D --> G[Live gateway]
E --> H[Open chats]
F --> I[New session]
References: hermes_cli/plugins_activation.py• L24-74 hermes_cli/plugins_activation.py• L96-127 hermes_cli/plugins_activation_live.py• L1-13
Product-surface integration
Product surfaces use the same trust and enablement decisions as runtime plugins. Dashboard metadata can add a tab, replace a route, fill a named slot, load browser assets, or expose a protected API route; the browser SDK supplies the approved API, authentication, UI, and slot interfaces. The Desktop app loads its own app-level plugin root for panes, palette commands, themes, and other native product surfaces, separate from profile-owned agent execution.
References: hermes_cli/web_server_dashboard.py• L517-589 hermes_cli/web_server_dashboard.py• L869-895 web/…/registry.ts• L99-191 apps/…/desktop-plugins-root.ts• L1-17 apps/…/desktop-plugins-root.ts• L138-186
Isolation boundary
Isolation controls whether user plugin code shares the Hermes interpreter. In-process mode gives the plugin the normal runtime path; host mode moves supported third-party code to one plugin-host process per profile so a plugin failure does not directly stop Hermes or mix code between profiles.
Host process
The host process runs plugin code and forwards approved context calls to Hermes as data or controlled proxies. Hermes still owns registries, policy checks, profile scope, and lifecycle cleanup, so the rest of the system sees ordinary registrations while the plugin code stays outside the main process.
References: hermes_cli/plugin_isolation.py• L1-17 hermes_cli/plugin_isolation.py• L32-73 hermes_cli/plugin_host.py• L1-18 hermes_cli/plugin_host.py• L202-252
Isolation limits
Some extensions need live SDK clients, event-loop objects, or launch-scope services. Those surfaces remain in-process or are refused in host mode; supported provider objects and data-only facades can cross the boundary. A host crash makes its proxies unavailable, then Hermes performs bounded recovery and avoids repeatedly reloading a plugin that keeps killing the host.
References: hermes_cli/plugin_isolation.py• L32-73 hermes_cli/plugin_isolation.py• L114-135 hermes_cli/plugin_host.py• L141-182
Update and removal
Updates use the same admission and publication rules as installation. Hermes first establishes that the installed provenance is still trusted, obtains a new catalog pin or source revision, validates the staged replacement, rechecks new dependency or capability requests, and publishes only when the live tree has not changed underneath it.
Update sources
Catalog plugins move only through a newly reviewed catalog pin. Other tracked Git plugins use their recorded source or an approved update feed, while pinned, manual, drifted, and untrusted-source installations are not silently moved. Update checks are read-only until an explicit update action or the opt-in automatic apply policy runs.
References: hermes_cli/plugins_updates.py• L1-13 hermes_cli/plugins_updates.py• L133-234 hermes_cli/plugins_cadence.py• L1-8 hermes_cli/plugins_cadence.py• L181-199
Replacement and removal
Replacement preserves user-owned plugin data where the update flow identifies it and refuses to publish when dependency consent, compatibility, scanning, or file-integrity checks fail. Removal and forced rediscovery use the ownership ledger to detach registrations, cancel plugin tasks, and prevent an old registration from surviving under a new plugin version.
Desktop removal applies a separate ownership rule. A standalone desktop folder can be removed only as one direct child of the app-level root; a marked desktop half is refused because reconciliation must remove it with the agent package. Reconciliation copies the first matching package from the known local homes, refreshes it when its source changes, and prunes it only when the source is known to be gone.
References: hermes_cli/plugins_transaction.py• L51-87 hermes_cli/plugins_transaction.py• L90-208 hermes_cli/plugins.py• L1290-1327 apps/…/desktop-plugin-remove.ts• L1-82 apps/…/desktop-plugins-root.ts• L505-582
Change checklist
When these files or sections are changed, remember to consider these:
- Keep manifest declarations, validation probes, catalog capability data, and the actual registration surface aligned. A declaration mismatch can block admission or hide a capability.
- Keep profile scope attached to provider registries, plugin settings, state, host processes, and activation requests. A process can serve more than one profile.
- Keep staged publication, install metadata, dependency preparation, and enablement as one admission decision. Do not make the live tree or active environment change before the required gate passes.
- Keep isolation support aligned across the context method tables, host wire contract, category loaders, and product-surface loaders.
- Keep activation summaries honest about what is live now and what waits for a new session or a service reload.
- Keep catalog SHA pins and update provenance aligned. A new catalog revision requires a reviewed catalog change.
- Keep Desktop Git review SHAs, source detection, package markers, and the published folder name aligned. A unified package must remain paired with its agent row.
- Keep every writer of the app-level Desktop plugin root behind the shared lock. Reconcile, install, and remove must not publish or delete the same folder at the same time.
- Keep desktop publication plain and staged. Do not allow symlinks, an incomplete copy, or a source that is no longer readable to become a live plugin or trigger a false prune.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A plugin declares a capability that its code does not register | Admission rejects the plugin or the product shows an incorrect trust request | Isolated validation probes compare declared and observed registrations |
| A user plugin is installed but not enabled | Its code is not loaded into the normal runtime path | The enable list and disable list gate discovery; product APIs apply the same gate |
| A plugin requests a new dependency without consent | The active environment and plugin selection remain unchanged | Dependency preparation runs before publication and requires an explicit answer |
| A plugin host exits | Plugin tools and hooks fail for that host while Hermes stays available | Proxy errors are contained and host restarts are bounded |
| An update source or saved update tag changes unexpectedly | Automatic update is refused until the source is reviewed | Provenance reconciliation reports drift or a trust-update-url action |
| A plugin is enabled during an open session | Some live handlers work but cached tools or prompt sections do not change | Activation reports immediate and deferred surfaces separately |
| The Git source moves between probe and install | The Desktop install may place code that the user did not review | Installation checks out the reviewed full commit and refuses when it is unavailable |
| A unified package's desktop half is removed as a standalone folder | The next reconcile restores it or the Desktop row flickers | The remover rejects folders carrying the package marker and the agent package owns the half |
| A reconcile pass cannot read one package | One desktop plugin is not published, but other plugins continue to load | Reconcile records the refusal and keeps the existing root copy unless the source is known to be gone |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/plugins.py | Central plugin manager, context boundary, registration ownership, and discovery entry point. |
| hermes_cli/plugins_discovery.py | Plugin source scanning, precedence, enablement, and kind routing. |
| hermes_cli/plugins_manifest.py | Manifest model, compatibility fields, configuration schema, and dependency order. |
| hermes_cli/plugin_validate.py | Admission checks and isolated capability probing. |
| hermes_cli/plugins_cmd_install.py | Staged installation, consent, scanning, and enablement flow. |
| hermes_cli/plugins_transaction.py | Recoverable publication and update replacement rules. |
| hermes_cli/plugin_isolation.py and hermes_cli/plugin_host.py | Isolation modes and the profile-scoped host boundary. |
| hermes_cli/plugins_activation.py | Immediate versus deferred activation behavior. |
| hermes_cli/plugins_provenance.py and hermes_cli/plugins_updates.py | Update trust, provenance classes, and source checks. |
| plugin-catalog/README.md | Catalog trust model, reviewed pins, and admission policy. |
| web/…/registry.ts | Browser product-surface SDK and dashboard plugin contract. |
| apps/…/desktop-plugin-install.ts | Desktop Git probing, reviewed-commit installs, component pairing, and staged publication. |
| apps/…/desktop-plugins-root.ts | App-level Desktop root, profile migration, unified package materialization, and source reconciliation. |
| apps/…/desktop-plugin-remove.ts | Safe removal rules for standalone Desktop plugins and unified package halves. |