Files
hermes-agent/hermes_cli/subcommands/plugins.py
T
hans 17030939db feat(plugins): inter-plugin event bus with declared emits/listens
Give plugins a first-class, namespaced pub/sub event bus so plugin↔plugin
interaction is a declared, testable contract instead of ad-hoc imports.
Closes #64164 (sub-issue 03/14 of the plugin-interface expansion epic #64182).
Additive-only: when no plugin calls emit/subscribe, behavior is unchanged.

Interface (on PluginContext):
- `ctx.emit(event, payload=None) -> int` publishes to subscribers and returns
  the count invoked. The namespace is FORCED to the plugin's own registry key
  (`manifest.key or manifest.name`): pass only the bare event name, delivered
  as `<key>:<event>`. Fail-closed — any name containing `:` (a `hermes:`
  reserved-core prefix, a foreign `other:` namespace, or an own-colon'd name)
  is rejected with a ValueError + logged warning naming the plugin.
- `ctx.subscribe(full_event, callback)` registers an ordered listener for a
  fully-qualified `<plugin>:<event>`. Subscribing is unrestricted (any plugin
  may listen to any published event); only emitting is namespace-gated.

Delivery mirrors invoke_hook: registration-order iteration, per-callback
try/except isolation (one raising subscriber never breaks delivery to the
rest), payload passed as `cb(**payload)`. A per-thread depth counter caps
re-entrant emits at 8 — mutually-emitting plugins terminate cleanly with one
logged warning, never an infinite loop or RecursionError.

Discoverability: optional advisory `emits:`/`listens:` manifest fields (no
manifest-v2 dependency; not enforced) are parsed and surfaced by a new
`hermes plugins show <name>` (alias `info`) command. `get_plugin_subscriptions()`
module accessor mirrors `get_plugin_auxiliary_tasks()`.

Tests (tests/hermes_cli/test_plugin_event_bus.py, 22): two-plugin delivery +
listener count; forced namespace (delivered as `b:ping`); spoof rejection
(parametrized `hermes:x` / foreign / own-colon'd / `:x` / `x:` / empty) with
no delivery; name-fallback when key empty; per-callback isolation; recursion
cap termination + warning; manifest emits/listens parsed (present/absent/from
yaml); module accessor; `plugins show` output. `pytest test_plugin_event_bus.py
test_plugin_auxiliary_tasks.py` → 37 passed. I independently re-verified the
namespace rejection and recursion-cap termination outside the test suite.

Note: the reserved-name gate rejects any `:`-containing input rather than a
bare-name denylist — a bare `core_event` is allowed and delivered under the
plugin's own namespace. Say the word if a reserved bare-name list is wanted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013b1XyXitAxV7phGmKWigJX
2026-08-12 18:57:51 -07:00

184 lines
6.1 KiB
Python

"""``hermes plugins`` subcommand parser.
Extracted from ``hermes_cli/main.py:main()`` (god-file Phase 2 follow-up).
Handler injected to avoid importing ``main``.
"""
from __future__ import annotations
from typing import Callable
def build_plugins_parser(subparsers, *, cmd_plugins: Callable) -> None:
"""Attach the ``plugins`` subcommand to ``subparsers``."""
plugins_parser = subparsers.add_parser(
"plugins",
help="Manage and validate plugins",
description=(
"Install, update, remove, list, or validate native Hermes plugins "
"and portable Agent Plugins v1 packages. Portable packages install disabled."
),
)
plugins_subparsers = plugins_parser.add_subparsers(dest="plugins_action")
plugins_install = plugins_subparsers.add_parser(
"install", help="Install a plugin from a Git URL, owner/repo, or index name"
)
plugins_install.add_argument(
"identifier",
help=(
"Git URL, owner/repo shorthand (e.g. anpicasso/hermes-plugin-chrome-profiles), "
"or a bare plugin name resolved through the community index "
"(see `hermes plugins search`)"
),
)
plugins_install.add_argument(
"--force",
"-f",
action="store_true",
help="Remove existing plugin and reinstall",
)
plugins_install.add_argument(
"--ref",
metavar="COMMIT_SHA",
help="Install exactly one immutable 40-character Git commit SHA",
)
_install_enable_group = plugins_install.add_mutually_exclusive_group()
_install_enable_group.add_argument(
"--enable",
action="store_true",
help="Auto-enable the plugin after install (skip confirmation prompt)",
)
_install_enable_group.add_argument(
"--no-enable",
action="store_true",
help="Install disabled (skip confirmation prompt); enable later with `hermes plugins enable <name>`",
)
plugins_search = plugins_subparsers.add_parser(
"search", help="Search the community plugin index"
)
plugins_search.add_argument(
"term",
nargs="?",
default="",
help="Search term matched fuzzily against name, description, and tags "
"(omit to browse the full index)",
)
plugins_search.add_argument(
"--json",
action="store_true",
help="Print machine-readable JSON",
)
plugins_search.add_argument(
"--capability",
metavar="CAP",
help="Filter by declared capability (e.g. tools, platform, commands)",
)
plugins_search.add_argument(
"--refresh",
action="store_true",
help="Bypass the local cache and re-fetch the index",
)
plugins_update = plugins_subparsers.add_parser(
"update", help="Pull latest changes for an installed plugin"
)
plugins_update.add_argument("name", help="Plugin name to update")
plugins_remove = plugins_subparsers.add_parser(
"remove", aliases=["rm", "uninstall"], help="Remove an installed plugin"
)
plugins_remove.add_argument("name", help="Plugin directory name to remove")
plugins_list = plugins_subparsers.add_parser(
"list", aliases=["ls"], help="List installed plugins"
)
plugins_list.add_argument(
"--enabled",
action="store_true",
help="Show only enabled plugins",
)
plugins_list.add_argument(
"--user",
action="store_true",
help="Show only user-installed plugins (including git plugins)",
)
plugins_list.add_argument(
"--no-bundled",
action="store_true",
help="Hide bundled plugins",
)
plugins_list.add_argument(
"--plain",
action="store_true",
help="Print compact plain-text output instead of a Rich table",
)
plugins_list.add_argument(
"--json",
action="store_true",
help="Print machine-readable JSON",
)
plugins_enable = plugins_subparsers.add_parser(
"enable", help="Enable a disabled plugin"
)
plugins_enable.add_argument("name", help="Plugin name to enable")
_enable_override_group = plugins_enable.add_mutually_exclusive_group()
_enable_override_group.add_argument(
"--allow-tool-override",
action="store_true",
help="Grant this plugin permission to replace built-in tools "
"(e.g. shell_exec, write_file). Skips the confirmation prompt.",
)
_enable_override_group.add_argument(
"--no-allow-tool-override",
action="store_true",
help="Enable without granting built-in tool override (skip prompt).",
)
plugins_disable = plugins_subparsers.add_parser(
"disable", help="Disable a plugin without removing it"
)
plugins_disable.add_argument("name", help="Plugin name to disable")
plugins_capabilities = plugins_subparsers.add_parser(
"capabilities",
help="Show declared vs granted capabilities per plugin",
description=(
"Show each plugin's declared capabilities (from plugin.yaml) "
"against what the user has granted. Capabilities are a consent "
"and audit layer over host API surfaces — NOT a sandbox."
),
)
plugins_capabilities.add_argument(
"name",
nargs="?",
default=None,
help="Plugin id to inspect (omit to list all plugins with capabilities)",
)
plugins_doctor = plugins_subparsers.add_parser(
"doctor", help="Validate a plugin with the real runtime contracts"
)
plugins_doctor.add_argument(
"target",
nargs="?",
default=".",
help="Plugin path or installed plugin id (default: current directory)",
)
plugins_doctor.add_argument(
"--ci",
action="store_true",
help="Exit non-zero when validation reports an error",
)
plugins_show = plugins_subparsers.add_parser(
"show",
aliases=["info"],
help="Show details for a single plugin (including emits/listens)",
)
plugins_show.add_argument("name", help="Plugin name or key to show")
plugins_parser.set_defaults(func=cmd_plugins)