plugins_loader.py 45 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851
  1. """Plugin loading: directory/entry-point module import, deferred bundled platforms, portable packages,
  2. dependency/config-schema warnings. Mixed into :class:`hermes_cli.plugins.PluginManager`.
  3. Origin-internal names (``PluginContext``, ``LoadedPlugin``, ``_PLUGINS_DEBUG`` …) are imported lazily
  4. through ``hermes_cli.plugins`` so tests that patch them on the origin keep working.
  5. """
  6. from __future__ import annotations
  7. import contextvars
  8. import hashlib
  9. import importlib
  10. import importlib.metadata
  11. import importlib.util
  12. import logging
  13. import re
  14. import sys
  15. import threading
  16. import types
  17. from contextlib import contextmanager
  18. from functools import wraps
  19. from pathlib import Path
  20. from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Union
  21. from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override
  22. from registration_lifecycle import replacement_coordinator
  23. from hermes_cli.plugins_discovery import ENTRY_POINTS_GROUP, _select_entry_point_group
  24. from hermes_cli.plugins_manifest import PluginManifest, manifest_key, portable_mcp_server_name, validate_config_schema
  25. from hermes_cli.plugins_state import _plugin_settings_entry
  26. if TYPE_CHECKING: # pragma: no cover
  27. from hermes_cli.plugins import LoadedPlugin, PluginContext
  28. logger = logging.getLogger("hermes_cli.plugins")
  29. _NS_PARENT = "hermes_plugins"
  30. _MODULE_NAMESPACE_LOCK = threading.RLock()
  31. _BARE_MODULE_SCOPE: dict[str, str] = {} # bare module name -> owning scope_key
  32. # Per-plugin deadline on import + register(): ``plugins.load_timeout_seconds`` (default 10s, 0 disables,
  33. # clamped to the max). A plugin that never returns is skipped with a named reason and loading moves on
  34. # (#108139). Python cannot kill a thread, so the worker is abandoned as a daemon; the cap bounds how many
  35. # abandoned loaders one process may accumulate (#98382) — past it, further loads are refused, not run inline.
  36. _LOAD_TIMEOUT_SECS = 10.0
  37. _MAX_LOAD_TIMEOUT_SECS = 600.0
  38. _MAX_ABANDONED_LOADERS = 8
  39. _LOADER_THREAD_PREFIX = "plugin-load:" # names each deadline-bounded load worker; the re-arm guard matches it
  40. _ABANDONED_LOADERS: list[threading.Thread] = []
  41. _ABANDONED_LOADERS_LOCK = threading.Lock()
  42. # Guards creating a manager's plugin host, so concurrent first callers share one host process.
  43. _PLUGIN_HOST_CREATE_LOCK = threading.Lock()
  44. # PluginContexts of the outermost deadline-bounded load; set only inside its worker.
  45. _IN_PLUGIN_LOAD: contextvars.ContextVar[Optional[list[PluginContext]]] = contextvars.ContextVar(
  46. "hermes_plugin_load_scope", default=None,
  47. )
  48. class PluginLoadTimeout(Exception):
  49. """Raised on the loading thread when a plugin's import + ``register()`` overran its deadline."""
  50. def in_plugin_load_worker() -> bool:
  51. """True on a deadline worker thread; re-entrant discovery from there must not block on its own parent."""
  52. return _IN_PLUGIN_LOAD.get() is not None
  53. def _resolve_plugin_load_timeout() -> float:
  54. """Effective per-plugin load deadline from ``plugins.load_timeout_seconds`` (default 10s; ``0`` runs
  55. loads inline with no deadline; clamped to ``_MAX_LOAD_TIMEOUT_SECS``)."""
  56. default = _LOAD_TIMEOUT_SECS
  57. try:
  58. from hermes_cli.config import load_config_readonly
  59. plugins_cfg = (load_config_readonly() or {}).get("plugins")
  60. if not isinstance(plugins_cfg, dict) or plugins_cfg.get("load_timeout_seconds") is None:
  61. return default
  62. timeout = float(plugins_cfg["load_timeout_seconds"])
  63. except (TypeError, ValueError):
  64. logger.warning("plugins.load_timeout_seconds is not a number; using default %gs", default)
  65. return default
  66. except Exception:
  67. return default
  68. if timeout < 0:
  69. logger.warning("plugins.load_timeout_seconds=%g is negative; using default %gs", timeout, default)
  70. return default
  71. if timeout > _MAX_LOAD_TIMEOUT_SECS:
  72. logger.warning("plugins.load_timeout_seconds=%g exceeds max %gs; clamping", timeout,
  73. _MAX_LOAD_TIMEOUT_SECS)
  74. return _MAX_LOAD_TIMEOUT_SECS
  75. return timeout
  76. def _reserve_abandoned_loader_slot() -> None:
  77. """Drop finished abandoned loaders; refuse the load once the live cap is reached. Refusing beats
  78. loading inline: at the cap the process already holds several hung loaders, so an inline load is the
  79. exact startup hang this deadline exists to prevent."""
  80. with _ABANDONED_LOADERS_LOCK:
  81. _ABANDONED_LOADERS[:] = [t for t in _ABANDONED_LOADERS if t.is_alive()]
  82. if len(_ABANDONED_LOADERS) < _MAX_ABANDONED_LOADERS:
  83. return
  84. raise PluginLoadTimeout(
  85. f"not loaded: {_MAX_ABANDONED_LOADERS} abandoned plugin loader thread(s) are still running "
  86. f"(plugins.load_timeout_seconds); restart Hermes to retry"
  87. )
  88. def run_with_load_deadline(plugin_key: str, ctx: PluginContext, fn: Callable[[], Any]) -> Any:
  89. """Run ``fn`` (a plugin's import + ``register()``) under the per-plugin deadline.
  90. The worker inherits the caller's context (the Hermes-home override is a ContextVar). On timeout the
  91. worker is abandoned as a daemon, ``ctx`` is marked so any registration it still attempts is ignored,
  92. and :class:`PluginLoadTimeout` is raised on the calling thread so the usual failure path records the
  93. reason and disposes whatever was registered before the hang.
  94. """
  95. # Re-entrant load on our own deadline worker: run inline; the outer deadline covers it.
  96. outer_scope = _IN_PLUGIN_LOAD.get()
  97. if outer_scope is not None:
  98. outer_scope.append(ctx)
  99. try:
  100. return fn()
  101. finally:
  102. outer_scope.remove(ctx)
  103. timeout = _resolve_plugin_load_timeout()
  104. if timeout <= 0:
  105. return fn()
  106. _reserve_abandoned_loader_slot()
  107. outcome: list[Any] = []
  108. failure: list[BaseException] = []
  109. scope = [ctx]
  110. def _worker() -> None:
  111. token = _IN_PLUGIN_LOAD.set(scope)
  112. try:
  113. outcome.append(fn())
  114. except BaseException as exc: # re-raised on the loading thread, KeyboardInterrupt included
  115. failure.append(exc)
  116. finally:
  117. _IN_PLUGIN_LOAD.reset(token)
  118. worker = threading.Thread(
  119. target=contextvars.copy_context().run, args=(_worker,), name=f"{_LOADER_THREAD_PREFIX}{plugin_key}", daemon=True,
  120. )
  121. worker.start()
  122. worker.join(timeout)
  123. if worker.is_alive():
  124. for loaded_ctx in scope:
  125. loaded_ctx._abandon_load()
  126. with _ABANDONED_LOADERS_LOCK:
  127. _ABANDONED_LOADERS.append(worker)
  128. raise PluginLoadTimeout(f"load timed out after {timeout:g}s (import + register() never returned)")
  129. if failure:
  130. raise failure[0]
  131. return outcome[0]
  132. def _evict_modules(module_name: str) -> None:
  133. """Drop ``module_name`` and every ``module_name.*`` submodule from ``sys.modules``.
  134. ``sys.modules`` is process-global, so any concurrent import — another profile's plugin
  135. load, a lazy import on a worker thread — mutates it while this runs. The ``list()`` is
  136. load-bearing, not a style choice: it is one atomic C-level copy, where iterating the live
  137. mapping raises ``RuntimeError: dictionary changed size during iteration`` and
  138. ``PluginLoaderMixin._load_plugin_scoped`` degrades that to a warning that loses the whole
  139. plugin. ``pop`` (not ``del``) keeps the snapshot-to-delete window tolerant of a key another
  140. evictor already removed.
  141. """
  142. prefix = f"{module_name}."
  143. for name in list(sys.modules): # snapshot first — never iterate the live mapping
  144. if name == module_name or name.startswith(prefix):
  145. sys.modules.pop(name, None)
  146. def _serialized_replacement(method):
  147. """Make snapshot → write → lease attachment one atomic transaction."""
  148. @wraps(method)
  149. def wrapped(*args, **kwargs):
  150. with replacement_coordinator.transaction():
  151. return method(*args, **kwargs)
  152. return wrapped
  153. @contextmanager
  154. def _plugin_home_scope(home: Path):
  155. """Bind discovery and loading to the manager's immutable Hermes home."""
  156. token = set_hermes_home_override(home)
  157. try:
  158. yield
  159. finally:
  160. reset_hermes_home_override(token)
  161. def _load_error_text(exc: BaseException) -> str:
  162. """Human-readable load failure; ``sys.exit(0)`` has an empty ``str()`` so name the class and code."""
  163. if isinstance(exc, SystemExit):
  164. return f"SystemExit({exc.code!r}) raised during import/register()"
  165. return str(exc)
  166. def _dist_name(req: str) -> str:
  167. return re.split(r"[<>=!~\[;\s]", req, maxsplit=1)[0].strip()
  168. def _dist_installed(req: str, path: Optional[list[str]] = None) -> Optional[bool]:
  169. """Best-effort probe: a distribution the requirement accepts is installed (on ``path`` when given,
  170. else this process's ``sys.path``); ``None`` when unprobeable. The version counts: a running
  171. process holding ``x 1.2`` cannot serve a plugin that now requires ``x>=1.3``."""
  172. dist = _dist_name(req)
  173. if not dist:
  174. return None
  175. try:
  176. found = next(iter(importlib.metadata.distributions(name=dist, path=path) if path
  177. else importlib.metadata.distributions(name=dist)), None)
  178. except Exception:
  179. return None
  180. if found is None:
  181. return False
  182. try:
  183. from packaging.requirements import Requirement
  184. return Requirement(req).specifier.contains(found.version, prereleases=True)
  185. except (ImportError, ValueError): # no packaging, or an unparseable requirement/version: presence decides
  186. return True
  187. def missing_python_dependencies(manifest: Any) -> list[str]:
  188. """The plugin's effective Python requirements (:func:`_declared_requirements`) this process
  189. cannot import.
  190. A requirement whose environment marker excludes this interpreter is never missing: PM does not
  191. install it here, so reporting it would ask for a restart or repair that can never help."""
  192. return [req for req in _declared_requirements(manifest)
  193. if _applies_here(req) and _dist_installed(req) is False]
  194. def _declared_requirements(manifest: Any) -> tuple[str, ...]:
  195. """What PM installs into Hermes's environment for this plugin: its declaration read the way
  196. admission reads it (``pm.plugin_declarations.read_python_declaration`` — an authored
  197. ``pyproject.toml`` first, then ``python_dependencies`` / ``pip_dependencies``; nothing for a
  198. ``python_runtime: external`` sidecar). A plugin with no directory (an entry point) has only its
  199. manifest list."""
  200. path = getattr(manifest, "path", None)
  201. if not path or not Path(path).is_dir():
  202. return tuple(getattr(manifest, "python_dependencies", None) or ())
  203. from pm.plugin_declarations import read_python_declaration
  204. try:
  205. return read_python_declaration(Path(path)).install_requirements
  206. except (OSError, ValueError): # a declaration PM cannot read is refused at admission, not ours to report
  207. return ()
  208. def hermes_fit_error(manifest: Any) -> Optional[str]:
  209. """Why this Hermes is not one the plugin accepts: ``requires_hermes``, then the plugin's own
  210. requirement on ``hermes-agent``. PM's build leaves such a plugin out by the same gate
  211. (``pm.workspace.hermes_fit_error``), so it is skipped here rather than imported without its
  212. dependencies, and loads again once Hermes fits."""
  213. from hermes_cli.plugins_manifest import requires_hermes_error
  214. reason = requires_hermes_error(manifest)
  215. path = getattr(manifest, "path", None)
  216. if reason or not path or not Path(path).is_dir():
  217. return reason
  218. from pm.plugin_declarations import read_python_declaration
  219. from pm.workspace import core_requirement_error
  220. try:
  221. return core_requirement_error(read_python_declaration(Path(path)))
  222. except (OSError, ValueError): # a declaration PM cannot read is refused at admission, not ours to report
  223. return None
  224. def _applies_here(req: str) -> bool:
  225. if ";" not in req:
  226. return True
  227. try:
  228. from packaging.requirements import InvalidRequirement, Requirement
  229. except ImportError:
  230. return True
  231. try:
  232. marker = Requirement(req).marker
  233. return marker is None or marker.evaluate()
  234. except (InvalidRequirement, ValueError, KeyError): # unparseable: keep reporting it
  235. return True
  236. def installed_in_selected_environment(requirements: list[str]) -> bool:
  237. """Whether every one of *requirements* is in the dependency environment PM currently selects.
  238. Activation is a boot decision (``pm.environments.activate_dependencies``): a gateway or dashboard
  239. that was running when ``hermes plugins enable`` committed a new generation keeps the old one. A
  240. requirement it cannot import that the selected generation carries therefore needs a restart, not
  241. a repair. False when unknown."""
  242. try:
  243. from pm.environments import selected_venv, site_packages
  244. from pm.paths import repo_root
  245. site = str(site_packages(selected_venv(repo_root())))
  246. return bool(requirements) and all(_dist_installed(req, [site]) for req in requirements)
  247. except (OSError, RuntimeError, ValueError): # unreadable or invalid selection record
  248. return False
  249. class PluginLoaderMixin:
  250. def on_plugin_loaded(self, callback: Callable[[list[dict[str, Any]]], Any]) -> Callable[[], None]:
  251. """Subscribe to "a discovery sweep loaded plugins this process did not have": fires from INSIDE
  252. :meth:`discover_and_load` (never emitted by an install RPC) with one
  253. ``{name, key, activated_now, deferred}`` summary per NEWLY loaded plugin — every plugin at boot,
  254. just the newcomer after a mid-run ``hermes plugins install/enable``, Desktop / dashboard /
  255. ``plugins.manage`` install-enable-update, a tool-triggered force re-discovery or the gateway's
  256. ``reload-plugins`` verb (all of which run ``discover_plugins(force=True)``; a non-forced call
  257. short-circuits on ``_discovered`` and never fires). See
  258. :func:`hermes_cli.plugins_activation.plugin_activation_summary` for the payload: ``activated_now``
  259. (gateway commands/transforms/hooks/callbacks, live at once) vs ``deferred`` (``tools``/``prompt``
  260. until the next session, ``mcp_servers`` — the plugin's mcp.json server names — until ``mcp.reload``).
  261. Listeners belong to the process (gateway runner, TUI server), not to a plugin, so ``unload()``
  262. never clears them. Returns an unsubscribe callable. Fires on the discovering thread with the
  263. discovery lock released; marshal onto your own loop."""
  264. if not callable(callback):
  265. raise ValueError("on_plugin_loaded requires a callable")
  266. listeners = self._plugin_loaded_listeners
  267. listeners.append(callback)
  268. def _unsubscribe() -> None:
  269. try:
  270. listeners.remove(callback)
  271. except ValueError:
  272. pass
  273. return _unsubscribe
  274. def _notify_plugin_loaded(self, loaded_before: frozenset) -> None:
  275. """Fire every :meth:`on_plugin_loaded` listener for the plugins this sweep added over
  276. ``loaded_before``; nothing new = no event. One raising listener never starves the rest."""
  277. if not self._plugin_loaded_listeners:
  278. return
  279. from hermes_cli.plugins_activation import activation_summaries
  280. summaries = [s for s in activation_summaries(self) if s["key"] not in loaded_before]
  281. if not summaries:
  282. return
  283. for callback in list(self._plugin_loaded_listeners):
  284. try:
  285. callback(summaries)
  286. except Exception:
  287. logger.warning("plugin-loaded listener %r raised", callback, exc_info=True)
  288. @staticmethod
  289. def _platform_name_from_manifest(manifest: PluginManifest) -> str:
  290. """Derive the platform name without importing the adapter: strip a trailing ``-platform`` from the
  291. manifest name, else the directory basename (the bundled convention)."""
  292. name = manifest.name or ""
  293. if name.endswith("-platform"):
  294. return name[: -len("-platform")]
  295. return Path(manifest.path).name if manifest.path else name
  296. def _register_deferred_platform(self, manifest: PluginManifest) -> None:
  297. """Register a lazy loader for a bundled platform: the adapter imports only when the
  298. ``platform_registry`` is first asked for it; a placeholder ``LoadedPlugin`` keeps it visible in
  299. ``hermes plugins list`` until then."""
  300. from hermes_cli.plugins import LoadedPlugin
  301. lookup_key = manifest_key(manifest)
  302. loaded = LoadedPlugin(manifest=manifest, enabled=True, deferred=True)
  303. self._plugins[lookup_key] = loaded
  304. if not self._lease_deferred_platform(manifest, lookup_key):
  305. # Fall back to eager loading so the platform is never silently lost. Runs outside the
  306. # replacement transaction: the eager load's register() executes on a deadline worker, whose
  307. # registrations need the coordinator lock this thread would otherwise still hold.
  308. self._load_plugin(manifest)
  309. return
  310. self._register_deferred_platform_tools(manifest, loaded)
  311. def rearm_failed_platform(self, platform_name: str) -> bool:
  312. """Re-lease the deferred loader of a platform plugin whose load failed, so the next registry lookup
  313. retries the import. A failed load disposes its lease (the registry forgets the platform), so without
  314. this a load that raised or overran its deadline at startup stays down until a forced re-discovery
  315. (#126356). True when a loader was re-armed."""
  316. from hermes_cli.plugins_discovery import _get_disabled_plugins, _get_enabled_plugins, gate_manifest
  317. with self._discovery_lock, _plugin_home_scope(self.home_path):
  318. failed = next((p.manifest for p in self._plugins.values()
  319. if p.error and not p.enabled and p.manifest.kind == "platform"
  320. and self._platform_name_from_manifest(p.manifest) == platform_name), None)
  321. # Re-gate: a placeholder (disabled, not enabled, catalog-removed) or a requires_hermes mismatch
  322. # carries the same error-set shape as a failed load but must never be imported.
  323. if failed is None or hermes_fit_error(failed) or gate_manifest(
  324. failed, _get_disabled_plugins(), _get_enabled_plugins()).action not in ("defer", "load"):
  325. return False
  326. with _ABANDONED_LOADERS_LOCK: # its hung import is still running: another retry only leaks a thread
  327. if any(t.is_alive() and t.name == f"{_LOADER_THREAD_PREFIX}{manifest_key(failed)}" for t in _ABANDONED_LOADERS):
  328. return False
  329. logger.info("Re-arming failed platform plugin load: %s", platform_name)
  330. self._register_deferred_platform(failed)
  331. return True
  332. @_serialized_replacement
  333. def _lease_deferred_platform(self, manifest: PluginManifest, lookup_key: str) -> bool:
  334. """Publish the deferred loader as a ledger-owned lease; False when the registry refused it."""
  335. platform_name = self._platform_name_from_manifest(manifest)
  336. try:
  337. from gateway.platform_registry import platform_registry
  338. scope = self.scope_key
  339. def _loader(_manifest: PluginManifest = manifest) -> None:
  340. # Lock before checking cancellation: if an unload won the race it restored the predecessor
  341. # and this loader must publish nothing; if loading won, unload waits and disposes the set.
  342. with self._discovery_lock, _plugin_home_scope(self.home_path):
  343. if platform_registry.is_deferred_load_cancelled(platform_name, scope=scope):
  344. return
  345. self._load_plugin_scoped(_manifest)
  346. previous = platform_registry.snapshot_registration(platform_name, scope=scope)
  347. platform_registry.register_deferred(platform_name, _loader, scope=scope)
  348. # Lets the gateway config pass recognise an env-only setup (sms: TWILIO_*) without
  349. # importing the adapter; see gateway.platform_activation.
  350. platform_registry.note_activation_env(
  351. platform_name, [e.get("name") if isinstance(e, dict) else e for e in manifest.requires_env or ()])
  352. current = platform_registry.snapshot_registration(platform_name, scope=scope)
  353. if current[0] is None and current[1] is _loader:
  354. self._plugin_platform_names.add(platform_name)
  355. self._track_scoped_registration(
  356. manifest, "platform", platform_name, platform_registry, current, previous,
  357. finalize=lambda: self._remove_platform_name_if_unowned(platform_name),
  358. )
  359. logger.debug("Registered deferred platform loader: %s (plugin=%s)", platform_name, lookup_key)
  360. except Exception:
  361. logger.debug(
  362. "Deferred platform registration failed for '%s'; eager-loading", lookup_key, exc_info=True)
  363. return False
  364. return True
  365. def _register_deferred_platform_tools(self, manifest: PluginManifest, loaded: LoadedPlugin) -> None:
  366. """Register a deferred platform's *client* tools without its adapter. Deferring the plugin would
  367. otherwise defer its outbound tools too, so CLI/TUI processes (which never materialize platforms)
  368. would miss them in ``hermes tools`` / ``platform_toolsets``. Opt-in is explicit via ``provides_tools``;
  369. tools live in a ``tools`` submodule so ``__init__`` stays import-light.
  370. A platform plugin can ship two independent things: an inbound adapter (heavy — it imports the
  371. platform SDK) and outbound client tools the agent calls like any other tool. Deferring the plugin
  372. defers both, so in a CLI/TUI process the client tools never register at all: ``resolve_toolset()``
  373. returns ``[]``, the toolset is missing from the ``hermes tools`` checklist, and even an explicit
  374. ``platform_toolsets`` entry is dropped because the key is unknown. The same tools work in
  375. gateway/web processes only because those materialize every platform at startup (issue #78050).
  376. Opting in is explicit: the manifest must declare ``provides_tools`` (the field the plugin list and
  377. web server already read to name a plugin's tools, per #78538). Keying off the mere presence of a
  378. ``tools.py`` would opt a plugin in by accident — a platform is free to put internal helpers there —
  379. and would leave the contract invisible to anyone reading the manifest. ``tools.py`` remains where
  380. the code is imported from; ``provides_tools`` is what asks for it. A platform that does not declare
  381. the field is untouched and stays fully deferred.
  382. """
  383. from hermes_cli.plugins import PluginContext, _PLUGINS_DEBUG
  384. if not manifest.provides_tools:
  385. return
  386. lookup_key = manifest_key(manifest)
  387. # Never let a client-tool import break discovery — the platform stays deferred and behaves exactly
  388. # as it did before. But a broken tools.py produces the #78050 symptom itself (declared tools missing
  389. # from the session), so this has to be visible without turning on debug logging to find it. Where it
  390. # failed is the first thing an operator needs: nothing registered points at the import or the module
  391. # body, a partial run points at one tool's definition, and a full run that still raised points past
  392. # the registrations entirely.
  393. declared = list(manifest.provides_tools)
  394. plugin_dir = Path(manifest.path) if manifest.path else None
  395. if plugin_dir is None or not (plugin_dir / "tools.py").is_file():
  396. # Declared but undeliverable — staying quiet reproduces the very symptom this fixes.
  397. logger.warning(
  398. # Staying quiet here reproduces the exact symptom this path exists to fix — tools the
  399. # manifest promises, silently absent from the session (#78050) — so say so.
  400. "Plugin '%s' declares provides_tools %s but has no tools.py; "
  401. "those tools will not be available in CLI/TUI sessions.", lookup_key, declared,
  402. )
  403. return
  404. before = set(self._plugin_tool_names) # lets the failure path credit partial registrations
  405. def _credit() -> list[str]:
  406. """Attribute every tool registered since ``before`` to this plugin."""
  407. registered = [t for t in self._plugin_tool_names if t not in before]
  408. if registered:
  409. loaded.tools_registered = registered
  410. self._predeclared_tools[lookup_key] = registered
  411. return registered
  412. try:
  413. module = self._load_directory_module(manifest)
  414. # Record the module even if nothing registers: the package body has run, so materializing the
  415. # adapter later must reuse it rather than execute it twice.
  416. loaded.module = module
  417. self._predeclared_modules[lookup_key] = module
  418. tools_module = importlib.import_module(f"{module.__name__}.tools")
  419. register_tools = getattr(tools_module, "register_tools", None)
  420. if register_tools is None:
  421. logger.warning(
  422. "Plugin '%s' declares provides_tools %s but its tools.py "
  423. "has no register_tools(ctx); those tools will not be "
  424. "available in CLI/TUI sessions.", lookup_key, declared,
  425. )
  426. return
  427. register_tools(PluginContext(manifest, self))
  428. registered = _credit()
  429. logger.debug(
  430. "Deferred platform '%s': pre-registered %d client tool(s) %s", lookup_key, len(registered),
  431. registered,
  432. )
  433. except (Exception, SystemExit) as exc:
  434. # Tools registered before the raise are live: credit them or `hermes plugins list` under-reports
  435. # (and _load_plugin's later diff would miss them too). Never break discovery (the platform stays
  436. # deferred), but a broken tools.py IS the symptom, so warn — and say where it failed first.
  437. partial, total = _credit(), len(declared)
  438. complete = len(partial) >= total
  439. scope = (
  440. f"before registering any of its {total} declared tool(s)" if not partial
  441. else f"after registering all {total} declared tool(s)" if complete
  442. else f"after registering {len(partial)} of {total} declared tool(s)"
  443. )
  444. logger.warning(
  445. "Plugin '%s': client-tool pre-registration failed %s (%s).%s", lookup_key, scope, exc,
  446. "" if complete else " The remainder will be missing from CLI/TUI sessions.",
  447. exc_info=_PLUGINS_DEBUG,
  448. )
  449. def _warn_python_dependencies(self, manifest: PluginManifest) -> None:
  450. """Report missing dependencies without installing during discovery.
  451. Plugin admission and PM repair own dependency changes.
  452. """
  453. missing = missing_python_dependencies(manifest)
  454. if not missing:
  455. return
  456. key = manifest_key(manifest)
  457. if installed_in_selected_environment(missing):
  458. logger.warning(
  459. "Plugin %s's Python dependencies were installed after this process started: %s. "
  460. "A running process never switches dependency environments; restart Hermes "
  461. "(hermes gateway restart for the gateway) to load them.",
  462. key, ", ".join(missing),
  463. )
  464. else:
  465. logger.warning(
  466. "Plugin %s declares Python dependencies that are not "
  467. "installed: %s. For an enabled plugin, run hermes pm repair, "
  468. "then restart Hermes. Discovery does not install dependencies.",
  469. key, ", ".join(missing),
  470. )
  471. def _validate_plugin_config_schema(self, manifest: PluginManifest) -> None:
  472. """Warn (never block) on plugins.entries.<id> settings that violate config_schema.
  473. See #64165.
  474. """
  475. if not manifest.config_schema:
  476. return
  477. plugin_id = manifest_key(manifest)
  478. settings: Mapping[str, Any] = {}
  479. try:
  480. from hermes_cli.config import load_config
  481. entry = _plugin_settings_entry(load_config() or {}, plugin_id) or {}
  482. raw = entry.get("settings")
  483. if not isinstance(raw, Mapping):
  484. raw = entry.get("config") # migration fallback mirroring ctx.get_config
  485. settings = raw if isinstance(raw, Mapping) else {}
  486. except Exception:
  487. settings = {}
  488. for warning in validate_config_schema(plugin_id, manifest.config_schema, settings):
  489. logger.warning("Plugin %s config: %s", plugin_id, warning)
  490. def _load_plugin(self, manifest: PluginManifest) -> None:
  491. """Import a plugin module and call its ``register(ctx)`` function."""
  492. with self._discovery_lock, _plugin_home_scope(self.home_path):
  493. self._load_plugin_scoped(manifest)
  494. def _load_plugin_scoped(self, manifest: PluginManifest) -> None:
  495. """Load one plugin with the manager's home bound as current."""
  496. from hermes_cli.plugins import LoadedPlugin, PluginContext, _PLUGINS_DEBUG
  497. loaded = LoadedPlugin(manifest=manifest)
  498. plugin_key = manifest_key(manifest)
  499. logger.debug(
  500. "Loading plugin '%s' (source=%s, kind=%s, path=%s)",
  501. plugin_key, manifest.source, manifest.kind, manifest.path,
  502. )
  503. if manifest.portable:
  504. self._load_portable_plugin(manifest, loaded)
  505. return
  506. # Version gate: skip cleanly (no import, no traceback) on a version mismatch.
  507. reason = hermes_fit_error(manifest)
  508. if reason:
  509. loaded.error = reason
  510. logger.warning("Plugin '%s' skipped: %s", plugin_key, reason)
  511. self._plugins[plugin_key] = loaded
  512. return
  513. registration_start = len(self._registration_order)
  514. module_name = self._policy_module_name(manifest)
  515. self._track_tool_override_policy(manifest, module_name)
  516. ctx = PluginContext(manifest, self)
  517. in_host = self._runs_in_plugin_host(manifest)
  518. def _import_and_register() -> bool:
  519. """Import + register() — the part a plugin controls, so the part the deadline covers."""
  520. # Declared language packs register before any plugin code runs, inside the same ledger slice
  521. # so a failing register() unwinds them too.
  522. self._register_declared_locales(manifest, ctx)
  523. if in_host and not self._is_manifest_only_language_pack(manifest):
  524. self._plugin_host().load(manifest, ctx, module_name=module_name,
  525. entrypoint=manifest.source not in {"user", "project"})
  526. return True
  527. # Reuse a deferred platform's already-imported package so its body doesn't run twice.
  528. # See #78050.
  529. module = self._predeclared_modules.pop(plugin_key, None)
  530. if module is None and manifest.source in {"user", "project", "bundled"}:
  531. if self._is_manifest_only_language_pack(manifest):
  532. return True # pure pack: locales/ is the whole plugin, no register() to run
  533. module = self._load_directory_module(manifest, module_name=module_name)
  534. elif module is None:
  535. module = self._load_entrypoint_module(manifest)
  536. register_fn = None
  537. if module is not None and not isinstance(module, types.ModuleType) and callable(module):
  538. # An entry point declared as ``module:function`` resolves to the function object itself via
  539. # ``ep.load()``, not its module (#72052).
  540. register_fn = module
  541. module = sys.modules.get(getattr(register_fn, "__module__", ""))
  542. loaded.module = module
  543. if register_fn is None:
  544. register_fn = getattr(module, "register", None)
  545. if register_fn is None:
  546. loaded.error = "no register() function"
  547. logger.warning("Plugin '%s' has no register() function", manifest.name)
  548. return False
  549. register_fn(ctx)
  550. return True
  551. try:
  552. if run_with_load_deadline(plugin_key, ctx, _import_and_register):
  553. self._attribute_registrations(loaded, plugin_key, registration_start)
  554. loaded.enabled = True
  555. from hermes_cli.plugins_ledger import _hook_source_of
  556. self._drop_fallback_hooks(_hook_source_of(manifest.name, loaded.module))
  557. except (Exception, SystemExit) as exc:
  558. # SystemExit too: a plugin module with an unguarded ``main()``/``sys.exit()`` must not take the
  559. # whole process (and every other plugin's registry) down with it; KeyboardInterrupt still propagates.
  560. # PluginLoadTimeout lands here as well: the abandoned worker's later registrations are refused
  561. # by ``ctx``, and whatever it registered before hanging is disposed below.
  562. owned = [r for r in self._registration_order if r.plugin_key == plugin_key]
  563. self._dispose_registrations(owned)
  564. self._forget_registrations(owned)
  565. loaded.error = _load_error_text(exc)
  566. # register() may have subscribed before raising; a failed plugin must leave no callable reachable
  567. # from later event dispatch.
  568. self._remove_plugin_subscriptions(plugin_key)
  569. logger.warning("Failed to load plugin '%s': %s", manifest.name, _load_error_text(exc), exc_info=_PLUGINS_DEBUG)
  570. # The failure path swept this plugin's whole ledger (not just the registration_start slice), so
  571. # discovery-time pre-registrations are gone too.
  572. # There is no live tool left to credit — attribution and the registry agree at zero. Only the
  573. # success path pops _predeclared_tools, so drop the entry here rather than let the bookkeeping
  574. # outlive the load attempt (#78050).
  575. if not loaded.enabled:
  576. self._predeclared_tools.pop(plugin_key, None)
  577. self._plugins[plugin_key] = loaded
  578. @staticmethod
  579. def _is_manifest_only_language_pack(manifest: PluginManifest) -> bool:
  580. """A ``provides_locales`` plugin with no ``__init__.py`` is complete without Python — like a
  581. manifest-only desktop plugin, it loads from its declared files alone."""
  582. return bool(manifest.provides_locales and manifest.path
  583. and not (Path(manifest.path) / "__init__.py").is_file())
  584. def _register_declared_locales(self, manifest: PluginManifest, ctx) -> None:
  585. """``provides_locales`` -> ``ctx.register_locale_dir(<plugin>/locales)``; a declared id with no file
  586. is a warning (the pack promised a language it does not ship), never a load failure."""
  587. if not manifest.provides_locales or not manifest.path:
  588. return
  589. locales_dir = Path(manifest.path) / "locales"
  590. handles = ctx.register_locale_dir(locales_dir, metadata=manifest.locale_metadata)
  591. registered = {handle.key.split(".", 1)[0] for handle in handles}
  592. for lang_id in manifest.provides_locales:
  593. if lang_id not in registered:
  594. logger.warning("Plugin '%s' declares provides_locales %r but %s has no %s.yaml",
  595. manifest.name, lang_id, locales_dir, lang_id)
  596. def _runs_in_plugin_host(self, manifest: PluginManifest) -> bool:
  597. """``plugins.isolation: host`` sends every non-bundled Python plugin to the profile's host."""
  598. from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
  599. return manifest.source != "bundled" and isolation_mode() == ISOLATION_HOST
  600. def _plugin_host(self) -> Any:
  601. """This manager's plugin host (one process per profile home), created on first use. Creation
  602. is atomic, so concurrent first callers share one host (which starts its process once); a
  603. failed creation stores nothing, and the next caller tries again."""
  604. host = getattr(self, "_plugin_host_instance", None)
  605. if host is None:
  606. from hermes_cli.plugin_host import PluginHost
  607. with _PLUGIN_HOST_CREATE_LOCK:
  608. host = getattr(self, "_plugin_host_instance", None)
  609. if host is None:
  610. host = self._plugin_host_instance = PluginHost(self)
  611. return host
  612. def _track_tool_override_policy(self, manifest: PluginManifest, module_name: str) -> None:
  613. """Install the plugin's tool-override policy in tools.registry as a ledger-owned lease."""
  614. from hermes_cli.plugins import PluginContext
  615. from tools.registry import registry as _registry
  616. scope = self.scope_key
  617. with replacement_coordinator.transaction():
  618. previous_policy = _registry.snapshot_plugin_override_policy(module_name, scope=scope)
  619. current_policy = _registry.register_plugin_override_policy(
  620. module_name, PluginContext(manifest, self)._tool_override_allowed(""), scope=scope,
  621. )
  622. policy_lease = replacement_coordinator.acquire(
  623. ("tool_override_policy", scope, module_name), current=current_policy,
  624. previous=previous_policy,
  625. restore=lambda replacement: _registry.restore_plugin_override_policy(
  626. module_name, current_policy, replacement, scope=scope,
  627. ),
  628. )
  629. self._track_registration(manifest, "tool_override_policy", module_name, policy_lease.dispose)
  630. def _attribute_registrations(
  631. self, loaded: LoadedPlugin, plugin_key: str, registration_start: int
  632. ) -> None:
  633. """Fill ``loaded.*_registered`` from the ledger slice this plugin's register() produced."""
  634. registrations = [
  635. r for r in self._registration_order[registration_start:]
  636. if r.plugin_key == plugin_key and r.active
  637. ]
  638. def _keys(kind: str) -> list[str]:
  639. return [r.key for r in registrations if r.kind == kind]
  640. # Discovery-time tools predate registration_start; credit them back or `hermes plugins list`
  641. # under-reports once the deferred adapter materializes.
  642. predeclared = [t for t in self._predeclared_tools.pop(plugin_key, []) if t in self._plugin_tool_names]
  643. loaded.tools_registered = predeclared + [k for k in _keys("tool") if k not in predeclared]
  644. loaded.hooks_registered = _keys("hook")
  645. loaded.middleware_registered = _keys("middleware")
  646. loaded.commands_registered = _keys("command")
  647. logger.debug(
  648. " registered: %d tool(s), %d hook(s), %d middleware, %d slash command(s), %d CLI command(s)",
  649. len(loaded.tools_registered), len(loaded.hooks_registered),
  650. len(loaded.middleware_registered), len(loaded.commands_registered),
  651. sum(1 for c in self._cli_commands if c in _keys("cli_command")),
  652. )
  653. def _load_portable_plugin(self, manifest: PluginManifest, loaded: LoadedPlugin) -> None:
  654. """Load validated portable components without importing Python code."""
  655. from hermes_cli.plugins import PluginContext
  656. lookup_key = manifest_key(manifest)
  657. try:
  658. from hermes_cli.agent_plugins import load_agent_plugin
  659. package = load_agent_plugin(
  660. Path(manifest.path), get_hermes_home() / "plugin-data" / manifest.data_namespace)
  661. ctx = PluginContext(manifest, self)
  662. for diagnostic in package.diagnostics:
  663. logger.warning("Agent Plugin '%s' [%s]: %s", lookup_key, diagnostic.scope, diagnostic.message)
  664. for skill in package.skills:
  665. try:
  666. ctx.register_skill(skill.name, skill.skill_md, skill.description, skill.frontmatter)
  667. except Exception as exc:
  668. logger.warning("Agent Plugin '%s' skill '%s' skipped: %s", lookup_key, skill.name, exc)
  669. from hermes_cli.agent_plugins import _clear_liveness, _set_liveness
  670. from hermes_platform import declaration
  671. registered: list[str] = []
  672. try:
  673. for server_name, config in package.mcp_servers.items():
  674. internal_name = portable_mcp_server_name(lookup_key, server_name)
  675. if internal_name in self._portable_mcp_servers:
  676. logger.warning("Agent Plugin '%s' MCP server '%s' skipped: name already taken by plugin '%s'; rename one server",
  677. lookup_key, internal_name, self._portable_mcp_server_plugins.get(internal_name, "?"))
  678. continue
  679. self._portable_mcp_servers[internal_name] = dict(config)
  680. self._portable_mcp_server_plugins[internal_name] = lookup_key
  681. server_decl = package.server_declarations.get(server_name)
  682. if server_decl is not None:
  683. declaration.register(internal_name, server_decl.declaration)
  684. _set_liveness(internal_name, server_decl.liveness)
  685. registered.append(internal_name)
  686. for internal_name in registered:
  687. def release(name: str = internal_name) -> None:
  688. self._portable_mcp_servers.pop(name, None)
  689. self._portable_mcp_server_plugins.pop(name, None)
  690. declaration.unregister(name)
  691. _clear_liveness(name)
  692. self._track_registration(manifest, "portable_mcp", internal_name, release)
  693. loaded.enabled = True
  694. except BaseException:
  695. for internal_name in registered:
  696. self._portable_mcp_servers.pop(internal_name, None)
  697. self._portable_mcp_server_plugins.pop(internal_name, None)
  698. declaration.unregister(internal_name)
  699. _clear_liveness(internal_name)
  700. raise
  701. except (Exception, SystemExit) as exc:
  702. loaded.error = _load_error_text(exc)
  703. logger.warning("Agent Plugin '%s' disabled: %s", lookup_key, loaded.error)
  704. self._plugins[lookup_key] = loaded
  705. def _directory_module_name(self, manifest: PluginManifest) -> str:
  706. """Profile-safe import namespace for a directory plugin: the bare ``hermes_plugins.<slug>`` for the
  707. first scope that claims it, a ``__home_<digest>`` suffix for any other scope."""
  708. slug = manifest_key(manifest).replace("/", "__").replace("-", "_")
  709. bare_name = f"{_NS_PARENT}.{slug}"
  710. with _MODULE_NAMESPACE_LOCK:
  711. if _BARE_MODULE_SCOPE.setdefault(bare_name, self.scope_key) == self.scope_key:
  712. return bare_name
  713. digest = hashlib.sha256(self.scope_key.encode("utf-8")).hexdigest()[:12]
  714. return f"{bare_name}__home_{digest}"
  715. def _policy_module_name(self, manifest: PluginManifest) -> str:
  716. """Return the module prefix whose callbacks inherit plugin policy."""
  717. if manifest.source == "entrypoint" and manifest.path:
  718. module_name = str(manifest.path).partition(":")[0].strip()
  719. if module_name:
  720. return module_name
  721. return self._directory_module_name(manifest)
  722. def _load_directory_module(
  723. self, manifest: PluginManifest, *, module_name: Optional[str] = None,
  724. ) -> types.ModuleType:
  725. """Import a directory plugin as ``hermes_plugins.<slug>`` (slug from ``manifest.key`` so
  726. ``image_gen/openai`` cannot collide with ``tts/openai``)."""
  727. plugin_dir = Path(manifest.path) # type: ignore[arg-type]
  728. init_file = plugin_dir / "__init__.py"
  729. if not init_file.exists():
  730. raise FileNotFoundError(f"No __init__.py in {plugin_dir}")
  731. if _NS_PARENT not in sys.modules:
  732. ns_pkg = types.ModuleType(_NS_PARENT)
  733. ns_pkg.__path__ = [] # type: ignore[attr-defined]
  734. ns_pkg.__package__ = _NS_PARENT
  735. sys.modules[_NS_PARENT] = ns_pkg
  736. module_name = module_name or self._directory_module_name(manifest)
  737. # Evict stale entries for this slug (same slug cached from another Hermes home, or an earlier force
  738. # reload). Replacing only sys.modules[module_name] is not enough: the plugin's relative imports are
  739. # cached as "module_name.sub" and resolve from sys.modules first, so a stale submodule would keep
  740. # serving the previous load's code/state.
  741. _evict_modules(module_name)
  742. spec = importlib.util.spec_from_file_location(
  743. module_name, init_file, submodule_search_locations=[str(plugin_dir)])
  744. if spec is None or spec.loader is None:
  745. raise ImportError(f"Cannot create module spec for {init_file}")
  746. module = importlib.util.module_from_spec(spec)
  747. module.__package__ = module_name
  748. module.__path__ = [str(plugin_dir)] # type: ignore[attr-defined]
  749. sys.modules[module_name] = module
  750. try:
  751. spec.loader.exec_module(module)
  752. except BaseException:
  753. # Don't leave a half-initialized module (or its partially imported relative submodules) cached — a
  754. # retry or a same-slug plugin in another profile would inherit broken state.
  755. _evict_modules(module_name)
  756. raise
  757. return module
  758. def _load_entrypoint_module(self, manifest: PluginManifest) -> types.ModuleType | Callable[..., Any]:
  759. """Load a pip-installed plugin via its entry-point reference: the module for a bare ``module`` target,
  760. the referenced attribute (normally ``register``) for the ``module:function`` form."""
  761. for ep in _select_entry_point_group(importlib.metadata.entry_points(), ENTRY_POINTS_GROUP):
  762. if ep.name == manifest.name:
  763. return ep.load()
  764. raise ImportError(f"Entry point '{manifest.name}' not found in group '{ENTRY_POINTS_GROUP}'")