plugins_discovery.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. """Plugin discovery: directory scanning, entry-point manifests, and the enable/disable gate.
  2. Split out of :mod:`hermes_cli.plugins`. Names that tests patch on the origin
  3. (``get_bundled_plugins_dir``, ``_env_enabled``) are looked up lazily through it.
  4. """
  5. from __future__ import annotations
  6. import contextlib
  7. import contextvars
  8. import importlib.metadata
  9. import logging
  10. from dataclasses import dataclass
  11. from pathlib import Path
  12. from typing import Any, Dict, List, Optional, Set
  13. from hermes_constants import get_hermes_home
  14. from hermes_cli.config import cfg_get
  15. from hermes_cli.plugin_capabilities import VALID_CAPABILITY_IDS
  16. from hermes_cli.plugin_capabilities import parse_declared_capabilities as _parse_declared_capabilities
  17. from hermes_cli.plugins_manifest import (
  18. PluginManifest, _detect_kind_from_source, manifest_key, _resolve_module_source,
  19. parse_manifest_file, portable_plugin_manifest,
  20. )
  21. from hermes_cli.relay_plugin_cutover import LEGACY_RELAY_PLUGIN_KEYS, RELAY_PLUGINS_CONFIG_ENV
  22. logger = logging.getLogger("hermes_cli.plugins")
  23. ENTRY_POINTS_GROUP = "hermes_agent.plugins"
  24. ENTRY_POINT_CAPABILITIES_GROUP = "hermes_agent.plugin_capabilities"
  25. # Per-harness manifest directories plugin repos ship for OTHER agent harnesses (e.g. obra/superpowers keeps one
  26. # plugin.json per harness). Their plugin.json is not an Agent Plugins v1 manifest and can never validate, so
  27. # parsing it on every discovery pass only spams warnings (#101962).
  28. _FOREIGN_HARNESS_MANIFEST_DIRS = frozenset({
  29. ".claude-plugin", ".codex-plugin", ".cursor-plugin", ".devin-plugin", ".kimi-plugin",
  30. })
  31. # Set while a caller reads a profile's config WITHOUT wanting that profile's plugins in this process:
  32. # the multiplex preflight loads a PARKED profile's gateway config for the duplicate-credential guard,
  33. # and ``load_gateway_config`` discovers plugins in the scope it runs under. Importing them runs their
  34. # ``register()`` (threads, DB handles) for a profile the operator took out of the host (#123386).
  35. # A contextvar, not an env flag: it must not leak to other threads or outlive the read.
  36. _discovery_suppressed: contextvars.ContextVar[bool] = contextvars.ContextVar(
  37. "hermes_plugin_discovery_suppressed", default=False)
  38. @contextlib.contextmanager
  39. def suppress_plugin_discovery():
  40. """``discover_plugins()`` is a no-op inside; the scope's manager stays undiscovered, so the
  41. first real consumer after the block still loads its plugins."""
  42. token = _discovery_suppressed.set(True)
  43. try:
  44. yield
  45. finally:
  46. _discovery_suppressed.reset(token)
  47. def plugin_discovery_suppressed() -> bool:
  48. return _discovery_suppressed.get()
  49. def _select_entry_point_group(entry_points: Any, group: str) -> list:
  50. """Return one metadata entry-point group across supported Python APIs."""
  51. if hasattr(entry_points, "select"):
  52. return list(entry_points.select(group=group))
  53. if isinstance(entry_points, dict):
  54. return list(entry_points.get(group, []))
  55. return [ep for ep in entry_points if ep.group == group]
  56. def discover_entrypoint_manifests() -> list[PluginManifest]:
  57. """Return metadata-only manifests for installed entry-point plugins. Kind comes from an import-free source
  58. scan (memory/model providers route to their own discovery). Capabilities come from the companion
  59. ``hermes_agent.plugin_capabilities`` group (``<plugin-id>.<capability-id>`` entries pointing at the same
  60. object), so consent works without importing plugin code. Failures are isolated per entry point."""
  61. manifests: list[PluginManifest] = []
  62. try:
  63. eps = importlib.metadata.entry_points()
  64. group_eps = _select_entry_point_group(eps, ENTRY_POINTS_GROUP)
  65. capability_eps = _select_entry_point_group(eps, ENTRY_POINT_CAPABILITIES_GROUP)
  66. except Exception as exc:
  67. logger.debug("Entry-point scan failed: %s", exc)
  68. return manifests
  69. for ep in group_eps:
  70. try:
  71. declared = {d.name for d in capability_eps if d.value == ep.value}
  72. capabilities = [c for c in VALID_CAPABILITY_IDS if f"{ep.name}.{c}" in declared]
  73. dist = getattr(ep, "dist", None)
  74. metadata = getattr(dist, "metadata", None)
  75. manifests.append(PluginManifest(
  76. name=ep.name, version=str(getattr(dist, "version", "") or ""),
  77. description=str(metadata.get("Summary", "") or "") if metadata is not None else "",
  78. source="entrypoint", path=ep.value, key=ep.name,
  79. kind=_classify_entrypoint_value_kind(ep.value),
  80. capabilities=_parse_declared_capabilities(capabilities, ep.name),
  81. ))
  82. except Exception as exc:
  83. logger.debug("Entry-point manifest for %r skipped: %s", getattr(ep, "name", "?"), exc)
  84. return manifests
  85. def _classify_entrypoint_value_kind(value: str) -> str:
  86. """Classify an entry-point target by import-free source scan (unresolvable -> standalone)."""
  87. try:
  88. module_name = str(value).split(":", 1)[0].strip()
  89. return (_detect_kind_from_source(_resolve_module_source(module_name)) if module_name else None) or "standalone"
  90. except Exception:
  91. return "standalone"
  92. def _get_disabled_plugins() -> set:
  93. """Read ``plugins.disabled`` — a deny-list that wins over ``plugins.enabled``."""
  94. try:
  95. from hermes_cli.config import load_config
  96. disabled = cfg_get(load_config(), "plugins", "disabled", default=[])
  97. return set(disabled) if isinstance(disabled, list) else set()
  98. except Exception:
  99. return set()
  100. def _get_enabled_plugins() -> Optional[set]:
  101. """Read the ``plugins.enabled`` allow-list (plugins are opt-in). ``None`` = key missing/malformed ("nothing
  102. enabled yet"; the first ``migrate_config`` run grandfathers installed user plugins); ``set()`` = explicitly
  103. empty; else the allow-list."""
  104. try:
  105. from hermes_cli.config import load_config
  106. enabled = cfg_get(load_config(), "plugins", "enabled")
  107. return set(enabled) if isinstance(enabled, list) else None
  108. except Exception:
  109. return None
  110. def is_skipped_plugin_dir(name: str) -> bool:
  111. """True for directory names discovery never treats as plugins. Cache/dunder dirs (__pycache__,
  112. __MACOSX__, …) can raise PermissionError when walked and take down every later tool call
  113. (#86996); foreign-harness dirs hold another tool's manifest convention."""
  114. return (name.startswith("__") and name.endswith("__")) or name in _FOREIGN_HARNESS_MANIFEST_DIRS
  115. def scan_directory(
  116. path: Path, source: str, *, skip_names: Optional[set[str]] = None, prefix: str = "", depth: int = 0
  117. ) -> list[PluginManifest]:
  118. """Read manifests under *path*: flat ``<root>/<name>/plugin.yaml`` (key ``name``) or category
  119. ``<root>/<cat>/<name>/plugin.yaml`` (key ``cat/name``; a manifest-less directory recurses one level, depth
  120. capped at two). *skip_names* ignores top-level names; portable ``plugin.json`` packages are accepted
  121. alongside YAML manifests."""
  122. manifests: list[PluginManifest] = []
  123. if not path.is_dir():
  124. return manifests
  125. try:
  126. children = sorted(path.iterdir())
  127. except OSError as exc:
  128. logger.warning("Skipping unreadable plugin directory %s: %s", path, exc)
  129. return manifests
  130. for child in children:
  131. if is_skipped_plugin_dir(child.name):
  132. logger.debug("Skipping %s (dunder or foreign-harness manifest dir)", child)
  133. continue
  134. # pathlib.Path.is_dir() swallows OSError, but injected Path-likes
  135. # and test doubles can still raise. Fail closed per child.
  136. try:
  137. if not child.is_dir() or (depth == 0 and skip_names and child.name in skip_names):
  138. continue
  139. manifest_file = next((f for f in (child / "plugin.yaml", child / "plugin.yml") if f.exists()), None)
  140. portable_file = child / "plugin.json"
  141. has_portable = portable_file.exists() or portable_file.is_symlink()
  142. except OSError as exc:
  143. # stat() raises (not "False") on an unsearchable directory — Windows ACLs (WinError 5) or a
  144. # mode-000 dir; one such plugin must not abort discovery for every other plugin (#111804).
  145. logger.warning("Skipping unreadable plugin directory %s: %s", child, exc)
  146. continue
  147. if manifest_file is not None:
  148. manifest = parse_manifest_file(manifest_file, child, source, prefix)
  149. if manifest is not None:
  150. manifests.append(manifest)
  151. elif has_portable:
  152. try:
  153. manifests.append(portable_plugin_manifest(child, source, prefix))
  154. except Exception as exc:
  155. logger.warning("Failed to parse %s: %s", portable_file, exc)
  156. elif depth >= 1:
  157. logger.debug("Skipping %s (no plugin.yaml, depth cap reached)", child)
  158. else:
  159. sub_prefix = f"{prefix}/{child.name}" if prefix else child.name
  160. manifests.extend(scan_directory(child, source, prefix=sub_prefix, depth=depth + 1))
  161. return manifests
  162. def collect_directory_manifests() -> list[PluginManifest]:
  163. """Read directory manifests in full-discovery order (bundled top-level, bundled/platforms, user, opt-in
  164. project) without loading or mutating anything, so startup probes share the exact precedence/containment
  165. rules of the real discovery sweep."""
  166. from hermes_cli import plugins as _origin # patched names resolve through the origin
  167. manifests: list[PluginManifest] = []
  168. def _scan(label: str, directory: Path, source: str, skip_names: Optional[set[str]] = None) -> None:
  169. found = scan_directory(directory, source, skip_names=skip_names)
  170. logger.debug(" %s: %d manifest(s)", label, len(found))
  171. manifests.extend(found)
  172. # Excluded bundled top-level categories have their own discovery. ``platforms/`` is an ordinary category
  173. # dir: the recursion keys its adapters ``platforms/<dir>`` like every other category (``web/firecrawl``),
  174. # which is the key `hermes plugins enable/disable` and the dashboard write (#27548); the manifest name
  175. # (``photon-platform``) stays an accepted alias through ``gate_manifest``.
  176. repo_plugins = _origin.get_bundled_plugins_dir()
  177. logger.debug("Scanning bundled plugins: %s", repo_plugins)
  178. _scan("bundled (top-level)", repo_plugins, "bundled",
  179. {"memory", "context_engine", "model-providers", "cron_providers", "computer_use", "config_backends"})
  180. user_dir = get_hermes_home() / "plugins"
  181. logger.debug("Scanning user plugins: %s", user_dir)
  182. _scan("user", user_dir, "user")
  183. if _origin._env_enabled("HERMES_ENABLE_PROJECT_PLUGINS"):
  184. project_dir = Path.cwd() / ".hermes" / "plugins"
  185. logger.debug("Scanning project plugins: %s", project_dir)
  186. _scan("project", project_dir, "project")
  187. else:
  188. logger.debug("Project plugins disabled (set HERMES_ENABLE_PROJECT_PLUGINS=1 to enable)")
  189. return manifests
  190. def resolve_manifest_winners(manifests: list[PluginManifest]) -> dict[str, PluginManifest]:
  191. """Later sources win on key collision (project > user > bundled): a same-named copy under
  192. ``~/.hermes/plugins/<name>`` is the documented way to override a bundled plugin, and is logged. A flat
  193. user/project manifest that claims a bundled key from a *differently named* directory is an impostor, not
  194. an override (``impostor_dir/plugin.yaml`` with ``name: kanban``): it is skipped with a warning so
  195. ``hermes plugins enable kanban`` never activates unrelated code under the bundled name."""
  196. winners: dict[str, PluginManifest] = {}
  197. for manifest in manifests:
  198. key = manifest_key(manifest)
  199. shadowed = winners.get(key)
  200. if shadowed is not None and shadowed.source == "bundled" and manifest.source in {"user", "project"}:
  201. own_dir = Path(manifest.path).name if manifest.path else ""
  202. bundled_dir = Path(shadowed.path).name if shadowed.path else ""
  203. if own_dir and bundled_dir and own_dir != bundled_dir:
  204. logger.warning(
  205. "Ignoring %s plugin at %s: its manifest name '%s' is a bundled plugin's key but the "
  206. "directory is named '%s'; rename the directory to '%s' to override the bundled plugin",
  207. manifest.source, manifest.path, key, own_dir, bundled_dir,
  208. )
  209. continue
  210. logger.info("Plugin '%s' at %s (%s) shadows the bundled copy at %s", key, manifest.path,
  211. manifest.source, shadowed.path)
  212. winners[key] = manifest
  213. return winners
  214. @dataclass(frozen=True)
  215. class ManifestGate:
  216. """Routing verdict for one winning manifest (see :func:`gate_manifest`)."""
  217. action: str # "load" (dependency-ordered pass) | "placeholder" | "load_now" | "defer"
  218. enabled: bool = False
  219. error: Optional[str] = None
  220. log: Optional[tuple] = None # (level, message, *args)
  221. IN_BOTH_LISTS = "listed in both plugins.enabled and plugins.disabled — disabled wins"
  222. def plugins_in_both_lists() -> list[str]:
  223. """Keys of the plugins the loader skips because both lists name them, by the loader's own
  224. config read and name matching (path key, bare leaf, manifest name)."""
  225. winners = resolve_manifest_winners(collect_directory_manifests())
  226. disabled, enabled = _get_disabled_plugins(), _get_enabled_plugins()
  227. return [key for key, manifest in winners.items() if gate_manifest(manifest, disabled, enabled).error == IN_BOTH_LISTS]
  228. def gate_manifest(
  229. manifest: PluginManifest, disabled: set[str], enabled: Optional[set[str]]
  230. ) -> ManifestGate:
  231. """Decide how one winning manifest is handled. Gate order matters: legacy relay refusal, explicit disable,
  232. category-owned kinds (exclusive / model-provider), bundled auto-loads (backend now, platform deferred),
  233. then ``plugins.enabled`` opt-in (path-derived key or legacy bare name)."""
  234. lookup_key = manifest_key(manifest)
  235. from hermes_cli.left_core_migration import legacy_plugin_keys
  236. # A bundled key that left core (``observability/langfuse``) keeps selecting its catalog plugin.
  237. names = {lookup_key, manifest.name, *legacy_plugin_keys(lookup_key)}
  238. def _placeholder(error: Optional[str], level: int, message: str, *args, enabled: bool = False) -> ManifestGate:
  239. return ManifestGate("placeholder", enabled=enabled, error=error, log=(level, message, lookup_key, *args))
  240. # Relay lifecycle is core-owned; an old plugin copy would compete for its registries.
  241. if names & LEGACY_RELAY_PLUGIN_KEYS:
  242. error = (
  243. "removed — Relay lifecycle is owned by Hermes core; configure a standard user or system Relay "
  244. f"plugins.toml, or use {RELAY_PLUGINS_CONFIG_ENV} for an explicit user-file override"
  245. )
  246. return _placeholder(error, logging.WARNING, "Refusing to load removed Hermes Relay plugin '%s'; %s", error)
  247. if names & disabled:
  248. if enabled and names & enabled:
  249. # Contradictory config (#131980): the disable wins, but a silent DEBUG skip hides the
  250. # conflict — the plugin "loads nowhere" while plugins.enabled still lists it. Fail loud.
  251. return _placeholder(
  252. IN_BOTH_LISTS,
  253. logging.WARNING,
  254. "Plugin '%s' is listed in both plugins.enabled and plugins.disabled; the disable "
  255. "wins and it will not load — remove it from one of the two lists",
  256. )
  257. return _placeholder("disabled via config", logging.DEBUG, "Skipping disabled plugin '%s'")
  258. # Exclusive plugins (memory providers) have their own activation path; record only.
  259. if manifest.kind == "exclusive":
  260. return _placeholder(
  261. "exclusive plugin — activate via <category>.provider config", logging.DEBUG,
  262. "Skipping '%s' (exclusive, handled by category discovery)",
  263. )
  264. # Model providers load via providers/__init__.py; a second import here would create two ProviderProfile
  265. # instances and break the bundled-vs-user "last writer wins" override.
  266. if manifest.kind == "model-provider":
  267. return _placeholder(
  268. None, logging.DEBUG, "Skipping '%s' (model-provider, handled by providers/ discovery)", enabled=True)
  269. if manifest.source == "bundled":
  270. # Bundled backends auto-load; selection among them is ``<category>.provider`` config.
  271. if manifest.kind == "backend":
  272. return ManifestGate("load_now")
  273. # Bundled platforms register LAZILY: eagerly importing ~20 heavy SDKs added seconds to every `hermes`
  274. # invocation. A deferred loader keeps every platform available on first use.
  275. if manifest.kind == "platform":
  276. return ManifestGate("defer")
  277. if enabled is None or not names & enabled:
  278. return _placeholder(
  279. f"not enabled in config (run `hermes plugins enable {lookup_key}` to activate)", logging.DEBUG,
  280. "Skipping '%s' (not in plugins.enabled)",
  281. )
  282. if manifest.source != "bundled":
  283. # The catalog kill list is enforced at install; a plugin recalled AFTER it was installed must not keep
  284. # loading. Offline check (in-tree list + cached live copy), honours an explicit install-time bypass.
  285. from hermes_cli.plugins_cmd_catalog import installed_plugin_removal
  286. removed = installed_plugin_removal(manifest.name, manifest.path)
  287. if removed is not None:
  288. error = f"removed from the Hermes plugin catalog: {removed.reason or 'no reason recorded'}"
  289. return _placeholder(error, logging.WARNING, "Refusing to load plugin '%s' — %s; run `hermes plugins remove`",
  290. error)
  291. return ManifestGate("load")