| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851 |
- """Plugin loading: directory/entry-point module import, deferred bundled platforms, portable packages,
- dependency/config-schema warnings. Mixed into :class:`hermes_cli.plugins.PluginManager`.
- Origin-internal names (``PluginContext``, ``LoadedPlugin``, ``_PLUGINS_DEBUG`` …) are imported lazily
- through ``hermes_cli.plugins`` so tests that patch them on the origin keep working.
- """
- from __future__ import annotations
- import contextvars
- import hashlib
- import importlib
- import importlib.metadata
- import importlib.util
- import logging
- import re
- import sys
- import threading
- import types
- from contextlib import contextmanager
- from functools import wraps
- from pathlib import Path
- from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Union
- from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override
- from registration_lifecycle import replacement_coordinator
- from hermes_cli.plugins_discovery import ENTRY_POINTS_GROUP, _select_entry_point_group
- from hermes_cli.plugins_manifest import PluginManifest, manifest_key, portable_mcp_server_name, validate_config_schema
- from hermes_cli.plugins_state import _plugin_settings_entry
- if TYPE_CHECKING: # pragma: no cover
- from hermes_cli.plugins import LoadedPlugin, PluginContext
- logger = logging.getLogger("hermes_cli.plugins")
- _NS_PARENT = "hermes_plugins"
- _MODULE_NAMESPACE_LOCK = threading.RLock()
- _BARE_MODULE_SCOPE: dict[str, str] = {} # bare module name -> owning scope_key
- # Per-plugin deadline on import + register(): ``plugins.load_timeout_seconds`` (default 10s, 0 disables,
- # clamped to the max). A plugin that never returns is skipped with a named reason and loading moves on
- # (#108139). Python cannot kill a thread, so the worker is abandoned as a daemon; the cap bounds how many
- # abandoned loaders one process may accumulate (#98382) — past it, further loads are refused, not run inline.
- _LOAD_TIMEOUT_SECS = 10.0
- _MAX_LOAD_TIMEOUT_SECS = 600.0
- _MAX_ABANDONED_LOADERS = 8
- _LOADER_THREAD_PREFIX = "plugin-load:" # names each deadline-bounded load worker; the re-arm guard matches it
- _ABANDONED_LOADERS: list[threading.Thread] = []
- _ABANDONED_LOADERS_LOCK = threading.Lock()
- # Guards creating a manager's plugin host, so concurrent first callers share one host process.
- _PLUGIN_HOST_CREATE_LOCK = threading.Lock()
- # PluginContexts of the outermost deadline-bounded load; set only inside its worker.
- _IN_PLUGIN_LOAD: contextvars.ContextVar[Optional[list[PluginContext]]] = contextvars.ContextVar(
- "hermes_plugin_load_scope", default=None,
- )
- class PluginLoadTimeout(Exception):
- """Raised on the loading thread when a plugin's import + ``register()`` overran its deadline."""
- def in_plugin_load_worker() -> bool:
- """True on a deadline worker thread; re-entrant discovery from there must not block on its own parent."""
- return _IN_PLUGIN_LOAD.get() is not None
- def _resolve_plugin_load_timeout() -> float:
- """Effective per-plugin load deadline from ``plugins.load_timeout_seconds`` (default 10s; ``0`` runs
- loads inline with no deadline; clamped to ``_MAX_LOAD_TIMEOUT_SECS``)."""
- default = _LOAD_TIMEOUT_SECS
- try:
- from hermes_cli.config import load_config_readonly
- plugins_cfg = (load_config_readonly() or {}).get("plugins")
- if not isinstance(plugins_cfg, dict) or plugins_cfg.get("load_timeout_seconds") is None:
- return default
- timeout = float(plugins_cfg["load_timeout_seconds"])
- except (TypeError, ValueError):
- logger.warning("plugins.load_timeout_seconds is not a number; using default %gs", default)
- return default
- except Exception:
- return default
- if timeout < 0:
- logger.warning("plugins.load_timeout_seconds=%g is negative; using default %gs", timeout, default)
- return default
- if timeout > _MAX_LOAD_TIMEOUT_SECS:
- logger.warning("plugins.load_timeout_seconds=%g exceeds max %gs; clamping", timeout,
- _MAX_LOAD_TIMEOUT_SECS)
- return _MAX_LOAD_TIMEOUT_SECS
- return timeout
- def _reserve_abandoned_loader_slot() -> None:
- """Drop finished abandoned loaders; refuse the load once the live cap is reached. Refusing beats
- loading inline: at the cap the process already holds several hung loaders, so an inline load is the
- exact startup hang this deadline exists to prevent."""
- with _ABANDONED_LOADERS_LOCK:
- _ABANDONED_LOADERS[:] = [t for t in _ABANDONED_LOADERS if t.is_alive()]
- if len(_ABANDONED_LOADERS) < _MAX_ABANDONED_LOADERS:
- return
- raise PluginLoadTimeout(
- f"not loaded: {_MAX_ABANDONED_LOADERS} abandoned plugin loader thread(s) are still running "
- f"(plugins.load_timeout_seconds); restart Hermes to retry"
- )
- def run_with_load_deadline(plugin_key: str, ctx: PluginContext, fn: Callable[[], Any]) -> Any:
- """Run ``fn`` (a plugin's import + ``register()``) under the per-plugin deadline.
- The worker inherits the caller's context (the Hermes-home override is a ContextVar). On timeout the
- worker is abandoned as a daemon, ``ctx`` is marked so any registration it still attempts is ignored,
- and :class:`PluginLoadTimeout` is raised on the calling thread so the usual failure path records the
- reason and disposes whatever was registered before the hang.
- """
- # Re-entrant load on our own deadline worker: run inline; the outer deadline covers it.
- outer_scope = _IN_PLUGIN_LOAD.get()
- if outer_scope is not None:
- outer_scope.append(ctx)
- try:
- return fn()
- finally:
- outer_scope.remove(ctx)
- timeout = _resolve_plugin_load_timeout()
- if timeout <= 0:
- return fn()
- _reserve_abandoned_loader_slot()
- outcome: list[Any] = []
- failure: list[BaseException] = []
- scope = [ctx]
- def _worker() -> None:
- token = _IN_PLUGIN_LOAD.set(scope)
- try:
- outcome.append(fn())
- except BaseException as exc: # re-raised on the loading thread, KeyboardInterrupt included
- failure.append(exc)
- finally:
- _IN_PLUGIN_LOAD.reset(token)
- worker = threading.Thread(
- target=contextvars.copy_context().run, args=(_worker,), name=f"{_LOADER_THREAD_PREFIX}{plugin_key}", daemon=True,
- )
- worker.start()
- worker.join(timeout)
- if worker.is_alive():
- for loaded_ctx in scope:
- loaded_ctx._abandon_load()
- with _ABANDONED_LOADERS_LOCK:
- _ABANDONED_LOADERS.append(worker)
- raise PluginLoadTimeout(f"load timed out after {timeout:g}s (import + register() never returned)")
- if failure:
- raise failure[0]
- return outcome[0]
- def _evict_modules(module_name: str) -> None:
- """Drop ``module_name`` and every ``module_name.*`` submodule from ``sys.modules``.
- ``sys.modules`` is process-global, so any concurrent import — another profile's plugin
- load, a lazy import on a worker thread — mutates it while this runs. The ``list()`` is
- load-bearing, not a style choice: it is one atomic C-level copy, where iterating the live
- mapping raises ``RuntimeError: dictionary changed size during iteration`` and
- ``PluginLoaderMixin._load_plugin_scoped`` degrades that to a warning that loses the whole
- plugin. ``pop`` (not ``del``) keeps the snapshot-to-delete window tolerant of a key another
- evictor already removed.
- """
- prefix = f"{module_name}."
- for name in list(sys.modules): # snapshot first — never iterate the live mapping
- if name == module_name or name.startswith(prefix):
- sys.modules.pop(name, None)
- def _serialized_replacement(method):
- """Make snapshot → write → lease attachment one atomic transaction."""
- @wraps(method)
- def wrapped(*args, **kwargs):
- with replacement_coordinator.transaction():
- return method(*args, **kwargs)
- return wrapped
- @contextmanager
- def _plugin_home_scope(home: Path):
- """Bind discovery and loading to the manager's immutable Hermes home."""
- token = set_hermes_home_override(home)
- try:
- yield
- finally:
- reset_hermes_home_override(token)
- def _load_error_text(exc: BaseException) -> str:
- """Human-readable load failure; ``sys.exit(0)`` has an empty ``str()`` so name the class and code."""
- if isinstance(exc, SystemExit):
- return f"SystemExit({exc.code!r}) raised during import/register()"
- return str(exc)
- def _dist_name(req: str) -> str:
- return re.split(r"[<>=!~\[;\s]", req, maxsplit=1)[0].strip()
- def _dist_installed(req: str, path: Optional[list[str]] = None) -> Optional[bool]:
- """Best-effort probe: a distribution the requirement accepts is installed (on ``path`` when given,
- else this process's ``sys.path``); ``None`` when unprobeable. The version counts: a running
- process holding ``x 1.2`` cannot serve a plugin that now requires ``x>=1.3``."""
- dist = _dist_name(req)
- if not dist:
- return None
- try:
- found = next(iter(importlib.metadata.distributions(name=dist, path=path) if path
- else importlib.metadata.distributions(name=dist)), None)
- except Exception:
- return None
- if found is None:
- return False
- try:
- from packaging.requirements import Requirement
- return Requirement(req).specifier.contains(found.version, prereleases=True)
- except (ImportError, ValueError): # no packaging, or an unparseable requirement/version: presence decides
- return True
- def missing_python_dependencies(manifest: Any) -> list[str]:
- """The plugin's effective Python requirements (:func:`_declared_requirements`) this process
- cannot import.
- A requirement whose environment marker excludes this interpreter is never missing: PM does not
- install it here, so reporting it would ask for a restart or repair that can never help."""
- return [req for req in _declared_requirements(manifest)
- if _applies_here(req) and _dist_installed(req) is False]
- def _declared_requirements(manifest: Any) -> tuple[str, ...]:
- """What PM installs into Hermes's environment for this plugin: its declaration read the way
- admission reads it (``pm.plugin_declarations.read_python_declaration`` — an authored
- ``pyproject.toml`` first, then ``python_dependencies`` / ``pip_dependencies``; nothing for a
- ``python_runtime: external`` sidecar). A plugin with no directory (an entry point) has only its
- manifest list."""
- path = getattr(manifest, "path", None)
- if not path or not Path(path).is_dir():
- return tuple(getattr(manifest, "python_dependencies", None) or ())
- from pm.plugin_declarations import read_python_declaration
- try:
- return read_python_declaration(Path(path)).install_requirements
- except (OSError, ValueError): # a declaration PM cannot read is refused at admission, not ours to report
- return ()
- def hermes_fit_error(manifest: Any) -> Optional[str]:
- """Why this Hermes is not one the plugin accepts: ``requires_hermes``, then the plugin's own
- requirement on ``hermes-agent``. PM's build leaves such a plugin out by the same gate
- (``pm.workspace.hermes_fit_error``), so it is skipped here rather than imported without its
- dependencies, and loads again once Hermes fits."""
- from hermes_cli.plugins_manifest import requires_hermes_error
- reason = requires_hermes_error(manifest)
- path = getattr(manifest, "path", None)
- if reason or not path or not Path(path).is_dir():
- return reason
- from pm.plugin_declarations import read_python_declaration
- from pm.workspace import core_requirement_error
- try:
- return core_requirement_error(read_python_declaration(Path(path)))
- except (OSError, ValueError): # a declaration PM cannot read is refused at admission, not ours to report
- return None
- def _applies_here(req: str) -> bool:
- if ";" not in req:
- return True
- try:
- from packaging.requirements import InvalidRequirement, Requirement
- except ImportError:
- return True
- try:
- marker = Requirement(req).marker
- return marker is None or marker.evaluate()
- except (InvalidRequirement, ValueError, KeyError): # unparseable: keep reporting it
- return True
- def installed_in_selected_environment(requirements: list[str]) -> bool:
- """Whether every one of *requirements* is in the dependency environment PM currently selects.
- Activation is a boot decision (``pm.environments.activate_dependencies``): a gateway or dashboard
- that was running when ``hermes plugins enable`` committed a new generation keeps the old one. A
- requirement it cannot import that the selected generation carries therefore needs a restart, not
- a repair. False when unknown."""
- try:
- from pm.environments import selected_venv, site_packages
- from pm.paths import repo_root
- site = str(site_packages(selected_venv(repo_root())))
- return bool(requirements) and all(_dist_installed(req, [site]) for req in requirements)
- except (OSError, RuntimeError, ValueError): # unreadable or invalid selection record
- return False
- class PluginLoaderMixin:
- def on_plugin_loaded(self, callback: Callable[[list[dict[str, Any]]], Any]) -> Callable[[], None]:
- """Subscribe to "a discovery sweep loaded plugins this process did not have": fires from INSIDE
- :meth:`discover_and_load` (never emitted by an install RPC) with one
- ``{name, key, activated_now, deferred}`` summary per NEWLY loaded plugin — every plugin at boot,
- just the newcomer after a mid-run ``hermes plugins install/enable``, Desktop / dashboard /
- ``plugins.manage`` install-enable-update, a tool-triggered force re-discovery or the gateway's
- ``reload-plugins`` verb (all of which run ``discover_plugins(force=True)``; a non-forced call
- short-circuits on ``_discovered`` and never fires). See
- :func:`hermes_cli.plugins_activation.plugin_activation_summary` for the payload: ``activated_now``
- (gateway commands/transforms/hooks/callbacks, live at once) vs ``deferred`` (``tools``/``prompt``
- until the next session, ``mcp_servers`` — the plugin's mcp.json server names — until ``mcp.reload``).
- Listeners belong to the process (gateway runner, TUI server), not to a plugin, so ``unload()``
- never clears them. Returns an unsubscribe callable. Fires on the discovering thread with the
- discovery lock released; marshal onto your own loop."""
- if not callable(callback):
- raise ValueError("on_plugin_loaded requires a callable")
- listeners = self._plugin_loaded_listeners
- listeners.append(callback)
- def _unsubscribe() -> None:
- try:
- listeners.remove(callback)
- except ValueError:
- pass
- return _unsubscribe
- def _notify_plugin_loaded(self, loaded_before: frozenset) -> None:
- """Fire every :meth:`on_plugin_loaded` listener for the plugins this sweep added over
- ``loaded_before``; nothing new = no event. One raising listener never starves the rest."""
- if not self._plugin_loaded_listeners:
- return
- from hermes_cli.plugins_activation import activation_summaries
- summaries = [s for s in activation_summaries(self) if s["key"] not in loaded_before]
- if not summaries:
- return
- for callback in list(self._plugin_loaded_listeners):
- try:
- callback(summaries)
- except Exception:
- logger.warning("plugin-loaded listener %r raised", callback, exc_info=True)
- @staticmethod
- def _platform_name_from_manifest(manifest: PluginManifest) -> str:
- """Derive the platform name without importing the adapter: strip a trailing ``-platform`` from the
- manifest name, else the directory basename (the bundled convention)."""
- name = manifest.name or ""
- if name.endswith("-platform"):
- return name[: -len("-platform")]
- return Path(manifest.path).name if manifest.path else name
- def _register_deferred_platform(self, manifest: PluginManifest) -> None:
- """Register a lazy loader for a bundled platform: the adapter imports only when the
- ``platform_registry`` is first asked for it; a placeholder ``LoadedPlugin`` keeps it visible in
- ``hermes plugins list`` until then."""
- from hermes_cli.plugins import LoadedPlugin
- lookup_key = manifest_key(manifest)
- loaded = LoadedPlugin(manifest=manifest, enabled=True, deferred=True)
- self._plugins[lookup_key] = loaded
- if not self._lease_deferred_platform(manifest, lookup_key):
- # Fall back to eager loading so the platform is never silently lost. Runs outside the
- # replacement transaction: the eager load's register() executes on a deadline worker, whose
- # registrations need the coordinator lock this thread would otherwise still hold.
- self._load_plugin(manifest)
- return
- self._register_deferred_platform_tools(manifest, loaded)
- def rearm_failed_platform(self, platform_name: str) -> bool:
- """Re-lease the deferred loader of a platform plugin whose load failed, so the next registry lookup
- retries the import. A failed load disposes its lease (the registry forgets the platform), so without
- this a load that raised or overran its deadline at startup stays down until a forced re-discovery
- (#126356). True when a loader was re-armed."""
- from hermes_cli.plugins_discovery import _get_disabled_plugins, _get_enabled_plugins, gate_manifest
- with self._discovery_lock, _plugin_home_scope(self.home_path):
- failed = next((p.manifest for p in self._plugins.values()
- if p.error and not p.enabled and p.manifest.kind == "platform"
- and self._platform_name_from_manifest(p.manifest) == platform_name), None)
- # Re-gate: a placeholder (disabled, not enabled, catalog-removed) or a requires_hermes mismatch
- # carries the same error-set shape as a failed load but must never be imported.
- if failed is None or hermes_fit_error(failed) or gate_manifest(
- failed, _get_disabled_plugins(), _get_enabled_plugins()).action not in ("defer", "load"):
- return False
- with _ABANDONED_LOADERS_LOCK: # its hung import is still running: another retry only leaks a thread
- if any(t.is_alive() and t.name == f"{_LOADER_THREAD_PREFIX}{manifest_key(failed)}" for t in _ABANDONED_LOADERS):
- return False
- logger.info("Re-arming failed platform plugin load: %s", platform_name)
- self._register_deferred_platform(failed)
- return True
- @_serialized_replacement
- def _lease_deferred_platform(self, manifest: PluginManifest, lookup_key: str) -> bool:
- """Publish the deferred loader as a ledger-owned lease; False when the registry refused it."""
- platform_name = self._platform_name_from_manifest(manifest)
- try:
- from gateway.platform_registry import platform_registry
- scope = self.scope_key
- def _loader(_manifest: PluginManifest = manifest) -> None:
- # Lock before checking cancellation: if an unload won the race it restored the predecessor
- # and this loader must publish nothing; if loading won, unload waits and disposes the set.
- with self._discovery_lock, _plugin_home_scope(self.home_path):
- if platform_registry.is_deferred_load_cancelled(platform_name, scope=scope):
- return
- self._load_plugin_scoped(_manifest)
- previous = platform_registry.snapshot_registration(platform_name, scope=scope)
- platform_registry.register_deferred(platform_name, _loader, scope=scope)
- # Lets the gateway config pass recognise an env-only setup (sms: TWILIO_*) without
- # importing the adapter; see gateway.platform_activation.
- platform_registry.note_activation_env(
- platform_name, [e.get("name") if isinstance(e, dict) else e for e in manifest.requires_env or ()])
- current = platform_registry.snapshot_registration(platform_name, scope=scope)
- if current[0] is None and current[1] is _loader:
- self._plugin_platform_names.add(platform_name)
- self._track_scoped_registration(
- manifest, "platform", platform_name, platform_registry, current, previous,
- finalize=lambda: self._remove_platform_name_if_unowned(platform_name),
- )
- logger.debug("Registered deferred platform loader: %s (plugin=%s)", platform_name, lookup_key)
- except Exception:
- logger.debug(
- "Deferred platform registration failed for '%s'; eager-loading", lookup_key, exc_info=True)
- return False
- return True
- def _register_deferred_platform_tools(self, manifest: PluginManifest, loaded: LoadedPlugin) -> None:
- """Register a deferred platform's *client* tools without its adapter. Deferring the plugin would
- otherwise defer its outbound tools too, so CLI/TUI processes (which never materialize platforms)
- would miss them in ``hermes tools`` / ``platform_toolsets``. Opt-in is explicit via ``provides_tools``;
- tools live in a ``tools`` submodule so ``__init__`` stays import-light.
- A platform plugin can ship two independent things: an inbound adapter (heavy — it imports the
- platform SDK) and outbound client tools the agent calls like any other tool. Deferring the plugin
- defers both, so in a CLI/TUI process the client tools never register at all: ``resolve_toolset()``
- returns ``[]``, the toolset is missing from the ``hermes tools`` checklist, and even an explicit
- ``platform_toolsets`` entry is dropped because the key is unknown. The same tools work in
- gateway/web processes only because those materialize every platform at startup (issue #78050).
- Opting in is explicit: the manifest must declare ``provides_tools`` (the field the plugin list and
- web server already read to name a plugin's tools, per #78538). Keying off the mere presence of a
- ``tools.py`` would opt a plugin in by accident — a platform is free to put internal helpers there —
- and would leave the contract invisible to anyone reading the manifest. ``tools.py`` remains where
- the code is imported from; ``provides_tools`` is what asks for it. A platform that does not declare
- the field is untouched and stays fully deferred.
- """
- from hermes_cli.plugins import PluginContext, _PLUGINS_DEBUG
- if not manifest.provides_tools:
- return
- lookup_key = manifest_key(manifest)
- # Never let a client-tool import break discovery — the platform stays deferred and behaves exactly
- # as it did before. But a broken tools.py produces the #78050 symptom itself (declared tools missing
- # from the session), so this has to be visible without turning on debug logging to find it. Where it
- # failed is the first thing an operator needs: nothing registered points at the import or the module
- # body, a partial run points at one tool's definition, and a full run that still raised points past
- # the registrations entirely.
- declared = list(manifest.provides_tools)
- plugin_dir = Path(manifest.path) if manifest.path else None
- if plugin_dir is None or not (plugin_dir / "tools.py").is_file():
- # Declared but undeliverable — staying quiet reproduces the very symptom this fixes.
- logger.warning(
- # Staying quiet here reproduces the exact symptom this path exists to fix — tools the
- # manifest promises, silently absent from the session (#78050) — so say so.
- "Plugin '%s' declares provides_tools %s but has no tools.py; "
- "those tools will not be available in CLI/TUI sessions.", lookup_key, declared,
- )
- return
- before = set(self._plugin_tool_names) # lets the failure path credit partial registrations
- def _credit() -> list[str]:
- """Attribute every tool registered since ``before`` to this plugin."""
- registered = [t for t in self._plugin_tool_names if t not in before]
- if registered:
- loaded.tools_registered = registered
- self._predeclared_tools[lookup_key] = registered
- return registered
- try:
- module = self._load_directory_module(manifest)
- # Record the module even if nothing registers: the package body has run, so materializing the
- # adapter later must reuse it rather than execute it twice.
- loaded.module = module
- self._predeclared_modules[lookup_key] = module
- tools_module = importlib.import_module(f"{module.__name__}.tools")
- register_tools = getattr(tools_module, "register_tools", None)
- if register_tools is None:
- logger.warning(
- "Plugin '%s' declares provides_tools %s but its tools.py "
- "has no register_tools(ctx); those tools will not be "
- "available in CLI/TUI sessions.", lookup_key, declared,
- )
- return
- register_tools(PluginContext(manifest, self))
- registered = _credit()
- logger.debug(
- "Deferred platform '%s': pre-registered %d client tool(s) %s", lookup_key, len(registered),
- registered,
- )
- except (Exception, SystemExit) as exc:
- # Tools registered before the raise are live: credit them or `hermes plugins list` under-reports
- # (and _load_plugin's later diff would miss them too). Never break discovery (the platform stays
- # deferred), but a broken tools.py IS the symptom, so warn — and say where it failed first.
- partial, total = _credit(), len(declared)
- complete = len(partial) >= total
- scope = (
- f"before registering any of its {total} declared tool(s)" if not partial
- else f"after registering all {total} declared tool(s)" if complete
- else f"after registering {len(partial)} of {total} declared tool(s)"
- )
- logger.warning(
- "Plugin '%s': client-tool pre-registration failed %s (%s).%s", lookup_key, scope, exc,
- "" if complete else " The remainder will be missing from CLI/TUI sessions.",
- exc_info=_PLUGINS_DEBUG,
- )
- def _warn_python_dependencies(self, manifest: PluginManifest) -> None:
- """Report missing dependencies without installing during discovery.
- Plugin admission and PM repair own dependency changes.
- """
- missing = missing_python_dependencies(manifest)
- if not missing:
- return
- key = manifest_key(manifest)
- if installed_in_selected_environment(missing):
- logger.warning(
- "Plugin %s's Python dependencies were installed after this process started: %s. "
- "A running process never switches dependency environments; restart Hermes "
- "(hermes gateway restart for the gateway) to load them.",
- key, ", ".join(missing),
- )
- else:
- logger.warning(
- "Plugin %s declares Python dependencies that are not "
- "installed: %s. For an enabled plugin, run hermes pm repair, "
- "then restart Hermes. Discovery does not install dependencies.",
- key, ", ".join(missing),
- )
- def _validate_plugin_config_schema(self, manifest: PluginManifest) -> None:
- """Warn (never block) on plugins.entries.<id> settings that violate config_schema.
- See #64165.
- """
- if not manifest.config_schema:
- return
- plugin_id = manifest_key(manifest)
- settings: Mapping[str, Any] = {}
- try:
- from hermes_cli.config import load_config
- entry = _plugin_settings_entry(load_config() or {}, plugin_id) or {}
- raw = entry.get("settings")
- if not isinstance(raw, Mapping):
- raw = entry.get("config") # migration fallback mirroring ctx.get_config
- settings = raw if isinstance(raw, Mapping) else {}
- except Exception:
- settings = {}
- for warning in validate_config_schema(plugin_id, manifest.config_schema, settings):
- logger.warning("Plugin %s config: %s", plugin_id, warning)
- def _load_plugin(self, manifest: PluginManifest) -> None:
- """Import a plugin module and call its ``register(ctx)`` function."""
- with self._discovery_lock, _plugin_home_scope(self.home_path):
- self._load_plugin_scoped(manifest)
- def _load_plugin_scoped(self, manifest: PluginManifest) -> None:
- """Load one plugin with the manager's home bound as current."""
- from hermes_cli.plugins import LoadedPlugin, PluginContext, _PLUGINS_DEBUG
- loaded = LoadedPlugin(manifest=manifest)
- plugin_key = manifest_key(manifest)
- logger.debug(
- "Loading plugin '%s' (source=%s, kind=%s, path=%s)",
- plugin_key, manifest.source, manifest.kind, manifest.path,
- )
- if manifest.portable:
- self._load_portable_plugin(manifest, loaded)
- return
- # Version gate: skip cleanly (no import, no traceback) on a version mismatch.
- reason = hermes_fit_error(manifest)
- if reason:
- loaded.error = reason
- logger.warning("Plugin '%s' skipped: %s", plugin_key, reason)
- self._plugins[plugin_key] = loaded
- return
- registration_start = len(self._registration_order)
- module_name = self._policy_module_name(manifest)
- self._track_tool_override_policy(manifest, module_name)
- ctx = PluginContext(manifest, self)
- in_host = self._runs_in_plugin_host(manifest)
- def _import_and_register() -> bool:
- """Import + register() — the part a plugin controls, so the part the deadline covers."""
- # Declared language packs register before any plugin code runs, inside the same ledger slice
- # so a failing register() unwinds them too.
- self._register_declared_locales(manifest, ctx)
- if in_host and not self._is_manifest_only_language_pack(manifest):
- self._plugin_host().load(manifest, ctx, module_name=module_name,
- entrypoint=manifest.source not in {"user", "project"})
- return True
- # Reuse a deferred platform's already-imported package so its body doesn't run twice.
- # See #78050.
- module = self._predeclared_modules.pop(plugin_key, None)
- if module is None and manifest.source in {"user", "project", "bundled"}:
- if self._is_manifest_only_language_pack(manifest):
- return True # pure pack: locales/ is the whole plugin, no register() to run
- module = self._load_directory_module(manifest, module_name=module_name)
- elif module is None:
- module = self._load_entrypoint_module(manifest)
- register_fn = None
- if module is not None and not isinstance(module, types.ModuleType) and callable(module):
- # An entry point declared as ``module:function`` resolves to the function object itself via
- # ``ep.load()``, not its module (#72052).
- register_fn = module
- module = sys.modules.get(getattr(register_fn, "__module__", ""))
- loaded.module = module
- if register_fn is None:
- register_fn = getattr(module, "register", None)
- if register_fn is None:
- loaded.error = "no register() function"
- logger.warning("Plugin '%s' has no register() function", manifest.name)
- return False
- register_fn(ctx)
- return True
- try:
- if run_with_load_deadline(plugin_key, ctx, _import_and_register):
- self._attribute_registrations(loaded, plugin_key, registration_start)
- loaded.enabled = True
- from hermes_cli.plugins_ledger import _hook_source_of
- self._drop_fallback_hooks(_hook_source_of(manifest.name, loaded.module))
- except (Exception, SystemExit) as exc:
- # SystemExit too: a plugin module with an unguarded ``main()``/``sys.exit()`` must not take the
- # whole process (and every other plugin's registry) down with it; KeyboardInterrupt still propagates.
- # PluginLoadTimeout lands here as well: the abandoned worker's later registrations are refused
- # by ``ctx``, and whatever it registered before hanging is disposed below.
- owned = [r for r in self._registration_order if r.plugin_key == plugin_key]
- self._dispose_registrations(owned)
- self._forget_registrations(owned)
- loaded.error = _load_error_text(exc)
- # register() may have subscribed before raising; a failed plugin must leave no callable reachable
- # from later event dispatch.
- self._remove_plugin_subscriptions(plugin_key)
- logger.warning("Failed to load plugin '%s': %s", manifest.name, _load_error_text(exc), exc_info=_PLUGINS_DEBUG)
- # The failure path swept this plugin's whole ledger (not just the registration_start slice), so
- # discovery-time pre-registrations are gone too.
- # There is no live tool left to credit — attribution and the registry agree at zero. Only the
- # success path pops _predeclared_tools, so drop the entry here rather than let the bookkeeping
- # outlive the load attempt (#78050).
- if not loaded.enabled:
- self._predeclared_tools.pop(plugin_key, None)
- self._plugins[plugin_key] = loaded
- @staticmethod
- def _is_manifest_only_language_pack(manifest: PluginManifest) -> bool:
- """A ``provides_locales`` plugin with no ``__init__.py`` is complete without Python — like a
- manifest-only desktop plugin, it loads from its declared files alone."""
- return bool(manifest.provides_locales and manifest.path
- and not (Path(manifest.path) / "__init__.py").is_file())
- def _register_declared_locales(self, manifest: PluginManifest, ctx) -> None:
- """``provides_locales`` -> ``ctx.register_locale_dir(<plugin>/locales)``; a declared id with no file
- is a warning (the pack promised a language it does not ship), never a load failure."""
- if not manifest.provides_locales or not manifest.path:
- return
- locales_dir = Path(manifest.path) / "locales"
- handles = ctx.register_locale_dir(locales_dir, metadata=manifest.locale_metadata)
- registered = {handle.key.split(".", 1)[0] for handle in handles}
- for lang_id in manifest.provides_locales:
- if lang_id not in registered:
- logger.warning("Plugin '%s' declares provides_locales %r but %s has no %s.yaml",
- manifest.name, lang_id, locales_dir, lang_id)
- def _runs_in_plugin_host(self, manifest: PluginManifest) -> bool:
- """``plugins.isolation: host`` sends every non-bundled Python plugin to the profile's host."""
- from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
- return manifest.source != "bundled" and isolation_mode() == ISOLATION_HOST
- def _plugin_host(self) -> Any:
- """This manager's plugin host (one process per profile home), created on first use. Creation
- is atomic, so concurrent first callers share one host (which starts its process once); a
- failed creation stores nothing, and the next caller tries again."""
- host = getattr(self, "_plugin_host_instance", None)
- if host is None:
- from hermes_cli.plugin_host import PluginHost
- with _PLUGIN_HOST_CREATE_LOCK:
- host = getattr(self, "_plugin_host_instance", None)
- if host is None:
- host = self._plugin_host_instance = PluginHost(self)
- return host
- def _track_tool_override_policy(self, manifest: PluginManifest, module_name: str) -> None:
- """Install the plugin's tool-override policy in tools.registry as a ledger-owned lease."""
- from hermes_cli.plugins import PluginContext
- from tools.registry import registry as _registry
- scope = self.scope_key
- with replacement_coordinator.transaction():
- previous_policy = _registry.snapshot_plugin_override_policy(module_name, scope=scope)
- current_policy = _registry.register_plugin_override_policy(
- module_name, PluginContext(manifest, self)._tool_override_allowed(""), scope=scope,
- )
- policy_lease = replacement_coordinator.acquire(
- ("tool_override_policy", scope, module_name), current=current_policy,
- previous=previous_policy,
- restore=lambda replacement: _registry.restore_plugin_override_policy(
- module_name, current_policy, replacement, scope=scope,
- ),
- )
- self._track_registration(manifest, "tool_override_policy", module_name, policy_lease.dispose)
- def _attribute_registrations(
- self, loaded: LoadedPlugin, plugin_key: str, registration_start: int
- ) -> None:
- """Fill ``loaded.*_registered`` from the ledger slice this plugin's register() produced."""
- registrations = [
- r for r in self._registration_order[registration_start:]
- if r.plugin_key == plugin_key and r.active
- ]
- def _keys(kind: str) -> list[str]:
- return [r.key for r in registrations if r.kind == kind]
- # Discovery-time tools predate registration_start; credit them back or `hermes plugins list`
- # under-reports once the deferred adapter materializes.
- predeclared = [t for t in self._predeclared_tools.pop(plugin_key, []) if t in self._plugin_tool_names]
- loaded.tools_registered = predeclared + [k for k in _keys("tool") if k not in predeclared]
- loaded.hooks_registered = _keys("hook")
- loaded.middleware_registered = _keys("middleware")
- loaded.commands_registered = _keys("command")
- logger.debug(
- " registered: %d tool(s), %d hook(s), %d middleware, %d slash command(s), %d CLI command(s)",
- len(loaded.tools_registered), len(loaded.hooks_registered),
- len(loaded.middleware_registered), len(loaded.commands_registered),
- sum(1 for c in self._cli_commands if c in _keys("cli_command")),
- )
- def _load_portable_plugin(self, manifest: PluginManifest, loaded: LoadedPlugin) -> None:
- """Load validated portable components without importing Python code."""
- from hermes_cli.plugins import PluginContext
- lookup_key = manifest_key(manifest)
- try:
- from hermes_cli.agent_plugins import load_agent_plugin
- package = load_agent_plugin(
- Path(manifest.path), get_hermes_home() / "plugin-data" / manifest.data_namespace)
- ctx = PluginContext(manifest, self)
- for diagnostic in package.diagnostics:
- logger.warning("Agent Plugin '%s' [%s]: %s", lookup_key, diagnostic.scope, diagnostic.message)
- for skill in package.skills:
- try:
- ctx.register_skill(skill.name, skill.skill_md, skill.description, skill.frontmatter)
- except Exception as exc:
- logger.warning("Agent Plugin '%s' skill '%s' skipped: %s", lookup_key, skill.name, exc)
- from hermes_cli.agent_plugins import _clear_liveness, _set_liveness
- from hermes_platform import declaration
- registered: list[str] = []
- try:
- for server_name, config in package.mcp_servers.items():
- internal_name = portable_mcp_server_name(lookup_key, server_name)
- if internal_name in self._portable_mcp_servers:
- logger.warning("Agent Plugin '%s' MCP server '%s' skipped: name already taken by plugin '%s'; rename one server",
- lookup_key, internal_name, self._portable_mcp_server_plugins.get(internal_name, "?"))
- continue
- self._portable_mcp_servers[internal_name] = dict(config)
- self._portable_mcp_server_plugins[internal_name] = lookup_key
- server_decl = package.server_declarations.get(server_name)
- if server_decl is not None:
- declaration.register(internal_name, server_decl.declaration)
- _set_liveness(internal_name, server_decl.liveness)
- registered.append(internal_name)
- for internal_name in registered:
- def release(name: str = internal_name) -> None:
- self._portable_mcp_servers.pop(name, None)
- self._portable_mcp_server_plugins.pop(name, None)
- declaration.unregister(name)
- _clear_liveness(name)
- self._track_registration(manifest, "portable_mcp", internal_name, release)
- loaded.enabled = True
- except BaseException:
- for internal_name in registered:
- self._portable_mcp_servers.pop(internal_name, None)
- self._portable_mcp_server_plugins.pop(internal_name, None)
- declaration.unregister(internal_name)
- _clear_liveness(internal_name)
- raise
- except (Exception, SystemExit) as exc:
- loaded.error = _load_error_text(exc)
- logger.warning("Agent Plugin '%s' disabled: %s", lookup_key, loaded.error)
- self._plugins[lookup_key] = loaded
- def _directory_module_name(self, manifest: PluginManifest) -> str:
- """Profile-safe import namespace for a directory plugin: the bare ``hermes_plugins.<slug>`` for the
- first scope that claims it, a ``__home_<digest>`` suffix for any other scope."""
- slug = manifest_key(manifest).replace("/", "__").replace("-", "_")
- bare_name = f"{_NS_PARENT}.{slug}"
- with _MODULE_NAMESPACE_LOCK:
- if _BARE_MODULE_SCOPE.setdefault(bare_name, self.scope_key) == self.scope_key:
- return bare_name
- digest = hashlib.sha256(self.scope_key.encode("utf-8")).hexdigest()[:12]
- return f"{bare_name}__home_{digest}"
- def _policy_module_name(self, manifest: PluginManifest) -> str:
- """Return the module prefix whose callbacks inherit plugin policy."""
- if manifest.source == "entrypoint" and manifest.path:
- module_name = str(manifest.path).partition(":")[0].strip()
- if module_name:
- return module_name
- return self._directory_module_name(manifest)
- def _load_directory_module(
- self, manifest: PluginManifest, *, module_name: Optional[str] = None,
- ) -> types.ModuleType:
- """Import a directory plugin as ``hermes_plugins.<slug>`` (slug from ``manifest.key`` so
- ``image_gen/openai`` cannot collide with ``tts/openai``)."""
- plugin_dir = Path(manifest.path) # type: ignore[arg-type]
- init_file = plugin_dir / "__init__.py"
- if not init_file.exists():
- raise FileNotFoundError(f"No __init__.py in {plugin_dir}")
- if _NS_PARENT not in sys.modules:
- ns_pkg = types.ModuleType(_NS_PARENT)
- ns_pkg.__path__ = [] # type: ignore[attr-defined]
- ns_pkg.__package__ = _NS_PARENT
- sys.modules[_NS_PARENT] = ns_pkg
- module_name = module_name or self._directory_module_name(manifest)
- # Evict stale entries for this slug (same slug cached from another Hermes home, or an earlier force
- # reload). Replacing only sys.modules[module_name] is not enough: the plugin's relative imports are
- # cached as "module_name.sub" and resolve from sys.modules first, so a stale submodule would keep
- # serving the previous load's code/state.
- _evict_modules(module_name)
- spec = importlib.util.spec_from_file_location(
- module_name, init_file, submodule_search_locations=[str(plugin_dir)])
- if spec is None or spec.loader is None:
- raise ImportError(f"Cannot create module spec for {init_file}")
- module = importlib.util.module_from_spec(spec)
- module.__package__ = module_name
- module.__path__ = [str(plugin_dir)] # type: ignore[attr-defined]
- sys.modules[module_name] = module
- try:
- spec.loader.exec_module(module)
- except BaseException:
- # Don't leave a half-initialized module (or its partially imported relative submodules) cached — a
- # retry or a same-slug plugin in another profile would inherit broken state.
- _evict_modules(module_name)
- raise
- return module
- def _load_entrypoint_module(self, manifest: PluginManifest) -> types.ModuleType | Callable[..., Any]:
- """Load a pip-installed plugin via its entry-point reference: the module for a bare ``module`` target,
- the referenced attribute (normally ``register``) for the ``module:function`` form."""
- for ep in _select_entry_point_group(importlib.metadata.entry_points(), ENTRY_POINTS_GROUP):
- if ep.name == manifest.name:
- return ep.load()
- raise ImportError(f"Entry point '{manifest.name}' not found in group '{ENTRY_POINTS_GROUP}'")
|