__init__.py 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936
  1. """Provider module registry.
  2. Provider profiles can live in three places:
  3. 1. Bundled plugins: ``plugins/model-providers/<name>/`` (shipped with hermes-agent)
  4. 2. User plugins: ``$HERMES_HOME/plugins/model-providers/<name>/``
  5. 3. Pip-installed plugins: distributions exposing a ``hermes_agent.plugins``
  6. entry point (``module:func`` callable or a self-registering ``module``)
  7. Each plugin directory contains:
  8. - ``__init__.py`` — calls ``register_provider(profile)`` at import
  9. - ``plugin.yaml`` — manifest (name, kind: model-provider, version, description)
  10. Discovery is lazy: the first call to ``get_provider_profile()`` or
  11. ``list_providers()`` imports the bundled and pip-installed plugins once per
  12. process; the ``$HERMES_HOME`` plugins of the profile home bound at lookup time
  13. load into that home's own layer, so one process serving several profiles
  14. (multiplex gateway, Desktop ``serve``) resolves each profile's installs. User
  15. plugins override bundled plugins on name collision, so third parties can
  16. monkey-patch or replace any built-in profile without editing the repo.
  17. For backward compatibility, ``providers/*.py`` files (other than ``base.py``
  18. and ``__init__.py``) are still discovered via ``pkgutil.iter_modules``.
  19. This lets out-of-tree users drop a single-file profile into an editable
  20. install without the plugin dir structure. New profiles should prefer the
  21. plugin layout.
  22. Usage::
  23. from providers import get_provider_profile
  24. profile = get_provider_profile("nvidia") # ProviderProfile or None
  25. profile = get_provider_profile("kimi") # checks name + aliases
  26. """
  27. from __future__ import annotations
  28. import hashlib
  29. import importlib
  30. import importlib.util
  31. import logging
  32. import os
  33. import sys
  34. import threading
  35. import time
  36. from contextvars import ContextVar
  37. from dataclasses import dataclass, field
  38. from pathlib import Path
  39. from typing import Any
  40. from providers.base import ProviderProfile
  41. logger = logging.getLogger(__name__)
  42. # Process-wide layer: bundled plugins, pip entry points, legacy ``providers/<name>.py``.
  43. _REGISTRY: dict[str, ProviderProfile] = {}
  44. _ALIASES: dict[str, str] = {}
  45. # Where the CURRENT registration of each name came from: "bundled" / "user" (a
  46. # ``$HERMES_HOME`` plugin dir) / "runtime" (entry point, legacy module, direct call).
  47. _SOURCES: dict[str, str] = {}
  48. _current_source: str | None = None
  49. _PROVIDER_LIST_CACHE: list[ProviderProfile] | None = None
  50. # Bumped by every registration (process-wide or per-home layer): memos over the registry key on it.
  51. _REGISTRY_GENERATION = 0
  52. _discovered = False
  53. _discovering = False
  54. _PLUGIN_DIR_STAMP_TTL_SECONDS = 1.0
  55. # Widest directory mtime granularity in use (FAT rounds to 2 s, HFS+ to 1 s; a kernel without
  56. # fine-grained timestamps stamps every change within one ~4 ms clock tick alike).
  57. _PLUGIN_DIR_MTIME_TICK_NS = 2_000_000_000
  58. @dataclass
  59. class _HomeLayer:
  60. """The ``$HERMES_HOME/plugins`` providers of ONE profile home.
  61. One process serves many profiles (multiplex gateway, Desktop ``serve``) and each profile installs
  62. its own plugins, so user plugins are keyed by the home bound at lookup time instead of the home
  63. that happened to be bound at first discovery — that made a plugin installed in a secondary
  64. profile ``Unknown provider`` in Desktop while the same profile worked in a terminal (#88143).
  65. ``stamps`` are the plugin dirs' mtimes: a directory added by ``hermes plugins install`` while the
  66. process runs changes them, and the next lookup imports it without a restart.
  67. """
  68. registry: dict[str, ProviderProfile] = field(default_factory=dict)
  69. aliases: dict[str, str] = field(default_factory=dict)
  70. stamps: tuple = ()
  71. stamp_checked_at: float | None = None
  72. # name -> when its miss last forced a stamp check (see ``_miss_recheck_due``)
  73. misses: dict[str, float] = field(default_factory=dict)
  74. # plugin dir name -> the error its import raised (``plugin_load_error``), until an import succeeds
  75. errors: dict[str, str] = field(default_factory=dict)
  76. # module names of plugins whose profiles this layer already holds as plugin-host proxies: the
  77. # hosted path's ``sys.modules`` check, so a rescan never re-imports, re-warns or swaps proxies
  78. hosted: set[str] = field(default_factory=set)
  79. _HOME_LAYERS: dict[str, _HomeLayer] = {}
  80. _HOME_LAYERS_LOCK = threading.Lock()
  81. # The layer a ``$HERMES_HOME`` plugin import registers into. A ContextVar, not a module global:
  82. # two turn threads scanning two profile homes at once must not cross-register. Never a lock held
  83. # across the import itself — a thread mid-``import hermes_cli.auth`` (whose import calls
  84. # ``list_providers()``) would block on it while the scanning thread waits on that module's import lock.
  85. _REGISTRATION_TARGET: ContextVar[_HomeLayer | None] = ContextVar("_provider_registration_target", default=None)
  86. # Set by :func:`bundled_profiles`: registrations made in this context are collected, nothing else.
  87. _COLLECT: ContextVar[list | None] = ContextVar("_provider_collect", default=None)
  88. # Profile names an in-process import may register (None = all). Set while a hosted plugin's
  89. # profiles that cannot cross the host boundary are imported here: its hosted siblings stay hosted.
  90. _REGISTRATION_ONLY: ContextVar[frozenset[str] | None] = ContextVar("_provider_registration_only", default=None)
  91. # Repo-root ``plugins/model-providers/`` — populated at discovery time.
  92. _BUNDLED_PLUGINS_DIR = (
  93. Path(__file__).resolve().parent.parent / "plugins" / "model-providers"
  94. )
  95. def _sync_auth_registry() -> None:
  96. """Mirror profiles into the ``hermes_cli`` snapshots (auth registry, picker catalog) that are loaded.
  97. ``hermes_cli.auth`` takes its own snapshot of ``list_providers()`` when it is imported. If a
  98. plugin's imports pull that module in while :func:`_discover_providers` is still running, the
  99. snapshot is partial and later plugins never reach the auth registry ("Unknown provider",
  100. #102123). Calling back into auth once discovery is complete closes that window. Looked up via
  101. ``sys.modules`` on purpose: this layer must never import ``hermes_cli`` (that would run auth's
  102. top-level code mid-scan and risk a circular import). Never raises: registration must not fail
  103. because of the auth mirror.
  104. """
  105. for module, attr in (
  106. ("hermes_cli.auth", "sync_plugin_provider_registry"),
  107. ("hermes_cli.models_catalog_static", "sync_plugin_provider_catalog"),
  108. ("hermes_cli.config_provider_env", "sync_registered_providers"),
  109. ):
  110. sync = getattr(sys.modules.get(module), attr, None)
  111. if sync is None:
  112. continue
  113. try:
  114. sync()
  115. except Exception as exc: # pragma: no cover — never break discovery
  116. logger.debug("%s sync skipped: %s", module, exc)
  117. def register_provider(profile: ProviderProfile) -> None:
  118. """Register a provider profile by name and aliases.
  119. Later registrations with the same name replace earlier ones — so user
  120. plugins under ``$HERMES_HOME/plugins/model-providers/`` can override
  121. bundled profiles without editing repo code. A registration made while a
  122. ``$HERMES_HOME`` plugin is being imported lands in that home's layer.
  123. """
  124. global _PROVIDER_LIST_CACHE, _REGISTRY_GENERATION
  125. collect = _COLLECT.get()
  126. if collect is not None:
  127. collect.append(profile)
  128. return
  129. only = _REGISTRATION_ONLY.get()
  130. if only is not None and profile.name not in only:
  131. return
  132. _REGISTRY_GENERATION += 1
  133. layer = _REGISTRATION_TARGET.get()
  134. if layer is not None:
  135. layer.registry[profile.name] = profile
  136. for alias in profile.aliases:
  137. layer.aliases[alias] = profile.name
  138. else:
  139. _REGISTRY[profile.name] = profile
  140. _SOURCES[profile.name] = _current_source or "runtime"
  141. for alias in profile.aliases:
  142. _ALIASES[alias] = profile.name
  143. _PROVIDER_LIST_CACHE = None
  144. if _discovered and not _discovering: # post-discovery registration: mirror it immediately
  145. _sync_auth_registry()
  146. def provider_source(name: str) -> str | None:
  147. """Discovery source of the profile currently registered under *name* (see ``_SOURCES``), or None.
  148. ``"user"`` is what lets a ``$HERMES_HOME`` plugin re-registering a bundled name win in
  149. ``hermes_cli.auth.PROVIDER_REGISTRY`` too — a bundled profile never rewrites a built-in row.
  150. """
  151. layer = _home_layer()
  152. canonical = layer.aliases.get(name) or _ALIASES.get(name, name)
  153. if canonical in layer.registry:
  154. return "user"
  155. return _SOURCES.get(canonical)
  156. # ``has_named_custom_provider`` walks the provider registry (``_shadowed_by_builtin`` →
  157. # ``resolve_provider``, which formats an AuthError for unregistered names) and loads config
  158. # on every call — ~2.5 ms per miss (Enough1122's profile on #120901, 40-50x the old miss
  159. # path). This sits on the profile-miss path that ``model_metadata._strip_provider_prefix``
  160. # reaches per model/prefix, so it must not be paid per iteration. Memo per home keyed on
  161. # the config file's ``file_signature`` — the same invalidation signal ``load_config`` uses —
  162. # so an edit re-arms the next lookup, and multiplex homes never borrow each other's answers.
  163. _NAMED_CUSTOM_MEMO: dict[str, dict[str, bool]] = {}
  164. _NAMED_CUSTOM_MEMO_SIG: dict[str, Any] = {}
  165. _NAMED_CUSTOM_MEMO_NO_SIG = object()
  166. def _has_named_custom_provider(name: str, home: Path | None, hkey: str) -> bool:
  167. """``has_named_custom_provider`` memoized on the home's config cache version."""
  168. from hermes_cli.config_backend import config_cache_version
  169. try:
  170. sig = config_cache_version(home / "config.yaml") if home is not None else None
  171. except OSError:
  172. sig = None # no readable config: nothing configured, stable until one appears
  173. memo = _NAMED_CUSTOM_MEMO.get(hkey)
  174. if memo is None or _NAMED_CUSTOM_MEMO_SIG.get(hkey, _NAMED_CUSTOM_MEMO_NO_SIG) != sig:
  175. memo = {}
  176. _NAMED_CUSTOM_MEMO[hkey] = memo
  177. _NAMED_CUSTOM_MEMO_SIG[hkey] = sig
  178. if name in memo:
  179. return memo[name]
  180. from hermes_cli.runtime_provider_custom import has_named_custom_provider
  181. memo[name] = has_named_custom_provider(name)
  182. return memo[name]
  183. def get_provider_profile(name: str) -> ProviderProfile | None:
  184. """Look up a provider profile by name or alias.
  185. Returns None if the provider has no profile (falls back to generic).
  186. """
  187. from agent.safe_worker_policy import safe_worker_enabled
  188. if safe_worker_enabled():
  189. return None
  190. if not _discovered:
  191. _discover_providers()
  192. layer, home, key = _bound_home_layer()
  193. checked = _refresh_home_layer(layer, home, key)
  194. def lookup(n: str) -> ProviderProfile | None:
  195. canonical = layer.aliases.get(n) or _ALIASES.get(n, n)
  196. return layer.registry.get(canonical) or _REGISTRY.get(canonical)
  197. profile = lookup(name)
  198. # A newly installed provider is normally first requested by its new name, so a miss
  199. # re-checks the plugin dirs now (unless this call just did) instead of waiting for the
  200. # periodic check. ``custom:<route>`` misses resolve to the generic profile below and the
  201. # picker asks for them once per model, so they wait for the periodic check.
  202. is_custom_route = isinstance(name, str) and name.lower().startswith("custom:")
  203. if profile is None and not is_custom_route and not checked and _miss_recheck_due(layer, name):
  204. if _refresh_home_layer(layer, home, key, force=True):
  205. profile = lookup(name)
  206. # Named custom routes share the generic wire policy unless a plugin
  207. # explicitly registered that route. Other names retain exact lookup.
  208. if profile is None and is_custom_route:
  209. profile = lookup("custom")
  210. # Bare named custom providers (not ``custom:<name>``) that are configured in
  211. # ``providers:`` / ``custom_providers:`` but lack an explicit profile entry
  212. # also share the generic wire policy. The helper is memoized (see
  213. # ``_has_named_custom_provider``) so the miss path stays cheap for per-model loops.
  214. if profile is None and isinstance(name, str) and not is_custom_route:
  215. if _has_named_custom_provider(name, home, key):
  216. profile = lookup("custom")
  217. return profile
  218. def _miss_recheck_due(layer: _HomeLayer, name: str) -> bool:
  219. """Whether a miss for *name* may force a plugin-dir check now: once per name per stamp TTL.
  220. Registry ids with no profile (``openai-api``, ``xai-oauth`` …) are looked up on every request;
  221. re-statting for each defeated the TTL. A new name still forces at once, so a just-installed
  222. provider is found on its first request; a repeat miss waits for the periodic check.
  223. """
  224. now = time.monotonic()
  225. last = layer.misses.get(name)
  226. if last is not None and now - last < _PLUGIN_DIR_STAMP_TTL_SECONDS:
  227. return False
  228. if len(layer.misses) >= 512:
  229. layer.misses.clear()
  230. layer.misses[name] = now
  231. return True
  232. def routed_model_rejects_vision_tool_messages(provider: str, model: str) -> bool:
  233. """Whether an active route or its aggregator-targeted model rejects image tool parts.
  234. Routing aggregators such as ``openrouter`` send vendor-prefixed model IDs
  235. (for example, ``xiaomi/mimo-v2.5``), but their own profile cannot describe
  236. every routed provider's tool-message compatibility. Preserve the transport
  237. profile as the default and consult a registered target profile only for
  238. routing aggregators. Missing or unrecognized identities deliberately fail open.
  239. """
  240. provider_name = str(provider or "").strip().lower()
  241. profile = get_provider_profile(provider_name)
  242. if profile is not None and profile.supports_vision_tool_messages is False:
  243. return True
  244. # Routing aggregators accept a ``vendor/model`` identifier while the request is sent
  245. # to the aggregator; the target provider can have stricter message-shape support than
  246. # the aggregator's generic OpenAI-compatible transport profile.
  247. from hermes_cli.providers import is_routing_aggregator
  248. if not is_routing_aggregator(provider_name):
  249. return False
  250. target_name, separator, _ = str(model or "").strip().partition("/")
  251. if not separator or not target_name:
  252. return False
  253. target_profile = get_provider_profile(target_name.strip().lower())
  254. return target_profile is not None and target_profile.supports_vision_tool_messages is False
  255. _HOST_PROFILE_MEMO: dict[tuple, tuple[tuple, ProviderProfile | None]] = {}
  256. def registry_generation() -> int:
  257. """Counter bumped by every provider registration; key memos of profile answers on it."""
  258. return _REGISTRY_GENERATION
  259. def bound_registry_key() -> tuple[str, int]:
  260. """``(bound home key, registry generation)`` after the periodic plugin-dir check.
  261. Key for per-home memos of profile-derived answers: each profile home has its own plugins, and
  262. any registration (a plugin installed while the process runs) moves the generation.
  263. """
  264. if not _discovered:
  265. _discover_providers()
  266. layer, home, key = _bound_home_layer()
  267. _refresh_home_layer(layer, home, key)
  268. return key, _REGISTRY_GENERATION
  269. def _host_claims(host: str, claimed: str) -> bool:
  270. claimed = str(claimed or "").strip().lower().rstrip(".")
  271. return bool(claimed) and (host == claimed or host.endswith("." + claimed))
  272. def profile_for_host(url: str, *, metadata: bool = False) -> ProviderProfile | None:
  273. """The registered profile whose declared ``hostnames`` match *url*'s host (exact or subdomain).
  274. *metadata* also matches ``metadata_hostnames``. Resolved against the bound home's providers, so a
  275. ``$HERMES_HOME`` plugin installed after import (or in another profile) is seen; memoized per
  276. (home, host) until the registry changes, because wire paths ask on every request.
  277. """
  278. from agent.safe_worker_policy import safe_worker_enabled
  279. from utils import base_url_hostname
  280. host = base_url_hostname(url) if url else ""
  281. if not host or safe_worker_enabled():
  282. return None
  283. if not _discovered:
  284. _discover_providers()
  285. layer, home, key = _bound_home_layer()
  286. _refresh_home_layer(layer, home, key)
  287. token = (_REGISTRY_GENERATION, id(_REGISTRY), len(_REGISTRY), len(layer.registry))
  288. memo_key = (key, host, metadata)
  289. cached = _HOST_PROFILE_MEMO.get(memo_key)
  290. if cached is not None and cached[0] == token:
  291. return cached[1]
  292. found = None
  293. for profile in list_providers():
  294. hosts = (*profile.hostnames, *profile.metadata_hostnames) if metadata else profile.hostnames
  295. if any(_host_claims(host, claimed) for claimed in hosts):
  296. found = profile
  297. break
  298. _HOST_PROFILE_MEMO[memo_key] = (token, found)
  299. return found
  300. def list_providers() -> list[ProviderProfile]:
  301. """Return all registered provider profiles (one per canonical name); the bound home's
  302. ``$HERMES_HOME`` plugins shadow process-wide profiles of the same name."""
  303. from agent.safe_worker_policy import safe_worker_enabled
  304. if safe_worker_enabled():
  305. return []
  306. global _PROVIDER_LIST_CACHE
  307. if not _discovered:
  308. _discover_providers()
  309. layer = _home_layer()
  310. if _PROVIDER_LIST_CACHE is None:
  311. # Deduplicate: _REGISTRY has canonical names; _ALIASES points to same objects
  312. seen: set[int] = set()
  313. cache: list[ProviderProfile] = []
  314. for profile in _REGISTRY.values():
  315. if id(profile) not in seen:
  316. seen.add(id(profile))
  317. cache.append(profile)
  318. _PROVIDER_LIST_CACHE = cache
  319. result = [p for p in _PROVIDER_LIST_CACHE if p.name not in layer.registry]
  320. result.extend({id(p): p for p in layer.registry.values()}.values())
  321. return result
  322. def unlisted_provider_names() -> set[str]:
  323. """Registered profiles that discovery surfaces (provider pickers, setup lists, the accounts tab)
  324. must not offer: pre-release ones the user has not opted into.
  325. Resolution never consults this: an unlisted profile still resolves, authenticates and serves
  326. turns by name. A raising ``listed()`` counts as unlisted, because a broken gate must never
  327. advertise a dark launch.
  328. """
  329. hidden: set[str] = set()
  330. for profile in list_providers():
  331. try:
  332. if not profile.listed():
  333. hidden.add(profile.name)
  334. except Exception:
  335. logger.debug("provider %s listed() raised; hiding it", profile.name, exc_info=True)
  336. hidden.add(profile.name)
  337. return hidden
  338. def bound_profile_resolver():
  339. """``resolve(name) -> (home plugin profile, process-wide profile)`` for the home bound now.
  340. *name* may be an alias. For process-wide mirrors read per home (``hermes_cli.auth``'s
  341. ``PROVIDER_REGISTRY``), so cheap enough per lookup: no discovery, no miss re-scan; only the
  342. periodic plugin-dir stamp check, skipped mid-scan so a plugin reading the mirror while it imports
  343. cannot re-enter its own scan.
  344. """
  345. layer = _bound_home_layer()[0] if _discovering else _home_layer()
  346. def resolve(name: str) -> tuple[ProviderProfile | None, ProviderProfile | None]:
  347. shared = _ALIASES.get(name, name)
  348. return layer.registry.get(layer.aliases.get(name) or shared), _REGISTRY.get(shared)
  349. return resolve
  350. def _home_layer(*, force_stamp_check: bool = False) -> _HomeLayer:
  351. """The layer for the home bound right now, importing plugin dirs it has not seen yet."""
  352. layer, home, key = _bound_home_layer()
  353. _refresh_home_layer(layer, home, key, force=force_stamp_check)
  354. return layer
  355. def refresh_bound_home() -> None:
  356. """Re-scan the bound home's plugin dirs now and forget its remembered misses: a plugin was just
  357. installed there, and the periodic check (or a name's miss back-off) would hide it for up to a TTL."""
  358. _home_layer(force_stamp_check=True).misses.clear()
  359. def _bound_home_layer() -> tuple[_HomeLayer, Path | None, str]:
  360. try:
  361. from hermes_constants import get_hermes_home, hermes_home_key
  362. home = Path(get_hermes_home())
  363. key = hermes_home_key(home)
  364. except Exception:
  365. home, key = None, ""
  366. with _HOME_LAYERS_LOCK:
  367. layer = _HOME_LAYERS.get(key)
  368. if layer is None:
  369. layer = _HOME_LAYERS[key] = _HomeLayer()
  370. return layer, home, key
  371. def _refresh_home_layer(layer: _HomeLayer, home: Path | None, key: str, *, force: bool = False) -> bool:
  372. """Re-stat the layer's plugin dirs when due (or *force*d); True when it stat'ed this call.
  373. Stamps are read before the scan: a plugin that lands mid-scan changes them and the next
  374. check picks it up. Checking on a short cadence keeps a newly installed plugin discoverable
  375. without making every model lookup perform two filesystem stats.
  376. """
  377. now = time.monotonic()
  378. from agent.safe_worker_policy import safe_worker_enabled
  379. # Safe mode fires zero user customization: same gate as ``_discover_providers``.
  380. if home is None or safe_worker_enabled() or not (
  381. force
  382. or layer.stamp_checked_at is None
  383. or now - layer.stamp_checked_at >= _PLUGIN_DIR_STAMP_TTL_SECONDS
  384. ):
  385. return False
  386. stamps = _plugin_dir_stamps(home)
  387. if stamps != layer.stamps:
  388. # Judge the stamps' age before scanning: a slow scan must not let a stamp read before it
  389. # look settled afterwards and get remembered over an install that landed mid-scan.
  390. settled = _plugin_dir_stamps_settled(stamps)
  391. _scan_home_layer(layer, key)
  392. # A stamp still inside its mtime tick may not move for an install landing in that same
  393. # tick, which would hide the plugin until some later change: keep it unremembered so the
  394. # next periodic check scans again, until the stamps settle.
  395. layer.stamps = stamps if settled else ()
  396. # Publish the completed layer -- stamps AND check time -- before auth
  397. # sync: it calls list_providers(), which re-enters this function. An
  398. # unpublished stamp rescanned forever; an unpublished check time
  399. # re-stats the plugin dirs inside the TTL.
  400. layer.stamp_checked_at = now
  401. if _discovered and not _discovering:
  402. _sync_auth_registry()
  403. layer.stamp_checked_at = now
  404. return True
  405. def _plugin_dir_stamps(home: Path) -> tuple:
  406. """mtimes of ``plugins/`` and ``plugins/model-providers/``: they change when a child is added."""
  407. def stamp(path: Path):
  408. try:
  409. return os.stat(path).st_mtime_ns
  410. except OSError:
  411. return None
  412. return (stamp(home / "plugins"), stamp(home / "plugins" / "model-providers"))
  413. def _plugin_dir_stamps_settled(stamps: tuple) -> bool:
  414. """Whether every stamp is at least one mtime tick away from now (either side: clock skew)."""
  415. now = time.time_ns()
  416. return all(s is None or abs(now - s) >= _PLUGIN_DIR_MTIME_TICK_NS for s in stamps)
  417. def _user_plugins_dir() -> Path | None:
  418. """Return ``$HERMES_HOME/plugins/model-providers/`` if it exists."""
  419. try:
  420. from hermes_constants import get_hermes_home
  421. d = get_hermes_home() / "plugins" / "model-providers"
  422. return d if d.is_dir() else None
  423. except Exception:
  424. return None
  425. def _installed_plugins_dir() -> Path | None:
  426. """Return ``$HERMES_HOME/plugins/`` if it exists.
  427. This is where ``hermes plugins install`` clones a plugin — flat, one
  428. directory per plugin, NOT under ``model-providers/``. See
  429. :func:`_discover_installed_provider_plugins`.
  430. """
  431. try:
  432. from hermes_constants import get_hermes_home
  433. d = get_hermes_home() / "plugins"
  434. return d if d.is_dir() else None
  435. except Exception:
  436. return None
  437. def _declares_model_provider_kind(plugin_dir: Path) -> bool:
  438. """Whether ``plugin_dir``'s manifest declares ``kind: model-provider``.
  439. Only that kind is imported from the flat install directory — every other
  440. plugin there belongs to ``PluginManager``, which owns its lifecycle and
  441. consent flow. Parsed with ruamel.yaml when available, falling back to a line
  442. scan so provider discovery never hard-depends on it.
  443. """
  444. for filename in ("plugin.yaml", "plugin.yml"):
  445. manifest = plugin_dir / filename
  446. if not manifest.is_file():
  447. continue
  448. try:
  449. text = manifest.read_text(encoding="utf-8", errors="replace")
  450. except Exception:
  451. return False
  452. try:
  453. from utils import fast_safe_load
  454. data = fast_safe_load(text)
  455. if isinstance(data, dict):
  456. return str(data.get("kind", "")).strip() == "model-provider"
  457. except Exception:
  458. pass
  459. for line in text.splitlines():
  460. stripped = line.strip()
  461. if stripped.startswith("#") or ":" not in stripped:
  462. continue
  463. key, _, value = stripped.partition(":")
  464. if key.strip() == "kind":
  465. return value.strip().strip("\"'") == "model-provider"
  466. return False
  467. return False
  468. def _scan_home_layer(layer: _HomeLayer, key: str) -> None:
  469. """Import the bound home's not-yet-imported provider plugins into *layer*.
  470. ``$HERMES_HOME/plugins/model-providers/<name>/`` first, then plugins cloned flat by
  471. ``hermes plugins install`` into ``$HERMES_HOME/plugins/<name>/`` that declare
  472. ``kind: model-provider`` (PluginManager owns every other kind there). Per-home module names
  473. let two profiles carry the same plugin without aliasing each other's registrations.
  474. """
  475. global _discovering
  476. token, prior_discovering = _REGISTRATION_TARGET.set(layer), _discovering
  477. _discovering = True
  478. try:
  479. user_dir = _user_plugins_dir()
  480. if user_dir is not None:
  481. for child in sorted(user_dir.iterdir()):
  482. if child.is_dir() and not child.name.startswith(("_", ".")):
  483. _import_plugin_dir(child, "user", home_key=key)
  484. installed_dir = _installed_plugins_dir()
  485. if installed_dir is not None:
  486. for child in sorted(installed_dir.iterdir()):
  487. if not child.is_dir() or child.name.startswith(("_", ".")) or child.name == "model-providers":
  488. continue
  489. if _declares_model_provider_kind(child):
  490. _import_plugin_dir(child, "user", home_key=key)
  491. finally:
  492. _REGISTRATION_TARGET.reset(token)
  493. _discovering = prior_discovering
  494. def _user_module_name(plugin_dir: Path, home_key: str) -> str:
  495. digest = hashlib.sha1(home_key.encode("utf-8")).hexdigest()[:10]
  496. return f"_hermes_user_provider_{digest}_{plugin_dir.name.replace('-', '_')}"
  497. def _import_plugin_dir(plugin_dir: Path, source: str, *, home_key: str = "") -> None:
  498. """Import a single plugin directory so it self-registers.
  499. ``source`` is "bundled" or "user"; it is recorded per registered profile (``_SOURCES``).
  500. """
  501. if not (plugin_dir / "__init__.py").exists():
  502. return
  503. if source != "bundled":
  504. from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
  505. if isolation_mode() == ISOLATION_HOST: # the plugin's code runs in the plugin host
  506. _import_hosted_plugin_dir(plugin_dir, source, _user_module_name(plugin_dir, home_key))
  507. return
  508. # Give bundled plugins a stable import path (``plugins.model_providers.<name>``)
  509. # so relative imports within the plugin work. User plugins load via
  510. # ``importlib.util.spec_from_file_location`` under a per-home module name so
  511. # multiple HERMES_HOME profiles don't alias each other.
  512. if source == "bundled":
  513. module_name = f"plugins.model_providers.{plugin_dir.name.replace('-', '_')}"
  514. else:
  515. module_name = _user_module_name(plugin_dir, home_key)
  516. _exec_plugin_module(plugin_dir, source, module_name)
  517. def _import_hosted_plugin_dir(plugin_dir: Path, source: str, module_name: str) -> None:
  518. """Register a plugin's profiles as plugin-host proxies; a profile that cannot cross the host
  519. boundary (e.g. it overrides ``create_client``) is imported in-process ALONE, with a warning,
  520. so it never takes its hosted siblings down with it."""
  521. global _current_source
  522. from hermes_cli.plugin_host_profiles import load_hosted_profiles
  523. layer = _REGISTRATION_TARGET.get()
  524. if layer is not None and module_name in layer.hosted:
  525. return # already imported into this home's layer
  526. _current_source = source
  527. try:
  528. hosted, in_process = load_hosted_profiles(plugin_dir, module_name)
  529. for profile in hosted:
  530. register_provider(profile)
  531. except Exception as exc: # health: allow BLE001 -- plugin load boundary (moved from _import_plugin_dir): one broken plugin never breaks discovery
  532. logger.warning("Failed to load user provider plugin %s in the plugin host: %s", plugin_dir.name, exc)
  533. _note_load_result(plugin_dir, exc)
  534. return
  535. finally:
  536. _current_source = None
  537. if in_process:
  538. for name, reason in in_process.items():
  539. logger.warning("Provider plugin %s: profile %r cannot run in the plugin host (%s); loading it "
  540. "in-process, NOT isolated by plugins.isolation: host", plugin_dir.name, name, reason)
  541. token = _REGISTRATION_ONLY.set(frozenset(in_process))
  542. try:
  543. _exec_plugin_module(plugin_dir, source, module_name)
  544. finally:
  545. _REGISTRATION_ONLY.reset(token)
  546. if module_name not in sys.modules:
  547. return # the in-process import failed: the next scan retries the plugin
  548. if layer is not None:
  549. layer.hosted.add(module_name)
  550. def _exec_plugin_module(plugin_dir: Path, source: str, module_name: str) -> None:
  551. global _current_source
  552. if module_name in sys.modules:
  553. return # already imported
  554. _current_source = source
  555. try:
  556. spec = importlib.util.spec_from_file_location(
  557. module_name, plugin_dir / "__init__.py", submodule_search_locations=[str(plugin_dir)]
  558. )
  559. if spec is None or spec.loader is None:
  560. return
  561. module = importlib.util.module_from_spec(spec)
  562. sys.modules[module_name] = module
  563. spec.loader.exec_module(module)
  564. _note_load_result(plugin_dir, None)
  565. except Exception as exc: # health: allow BLE001 -- plugin import boundary (moved from _import_plugin_dir): one broken plugin never breaks discovery
  566. logger.warning(
  567. "Failed to load %s provider plugin %s: %s", source, plugin_dir.name, exc
  568. )
  569. sys.modules.pop(module_name, None)
  570. _note_load_result(plugin_dir, exc)
  571. finally:
  572. _current_source = None
  573. def _note_load_result(plugin_dir: Path, exc: BaseException | None) -> None:
  574. """Record (or clear) a ``$HERMES_HOME`` plugin's import error on the home layer importing it: the
  575. general plugin manager lists a model-provider dir with no error, so this is the only record of why it
  576. registered nothing."""
  577. layer = _REGISTRATION_TARGET.get()
  578. if layer is None: # bundled: process-wide, never a home's plugin
  579. return
  580. if exc is None:
  581. layer.errors.pop(plugin_dir.name, None)
  582. else:
  583. layer.errors[plugin_dir.name] = f"{type(exc).__name__}: {exc}"
  584. def plugin_load_error(plugin: str) -> str:
  585. """The error the bound home's provider plugin dir *plugin* raised on its last import, else ``""``."""
  586. return _home_layer().errors.get(plugin, "")
  587. def _discover_entry_point_providers() -> None:
  588. """Import pip-installed provider plugins via the ``hermes_agent.plugins``
  589. entry-point group so they self-register.
  590. A distribution ships::
  591. [project.entry-points."hermes_agent.plugins"]
  592. acme-inference = "acme_hermes_plugin:register"
  593. The target may be either a **callable** (``module:func`` — invoked with no
  594. args; typically calls ``register_provider(profile)``) or a **module**
  595. (``module`` — imported for its module-level ``register_provider`` side
  596. effect, mirroring the directory-plugin ``__init__.py`` contract).
  597. Gating and safety:
  598. * **Opt-in.** Entry-point plugins are subject to the same
  599. ``plugins.enabled`` allow-list (and ``plugins.disabled`` deny-list) the
  600. general PluginManager enforces — a pip package is never imported just
  601. because it is installed. An entry point whose name is not enabled is
  602. skipped without loading.
  603. * **Provider targets only.** The ``hermes_agent.plugins`` group is shared
  604. with general plugins whose target is ``register(ctx)``. Callables that
  605. require arguments are skipped here (the PluginManager owns them);
  606. provider registration hooks take no arguments by contract.
  607. Failures are swallowed per-entry (a broken third-party package must not
  608. break provider discovery) and logged at warning level. This scan runs
  609. first, so filesystem plugins (bundled + ``$HERMES_HOME``) keep their
  610. documented override precedence via last-writer-wins in
  611. ``register_provider()`` — a pip package cannot hijack a first-party
  612. provider name.
  613. """
  614. try:
  615. import importlib.metadata as _md
  616. except Exception: # pragma: no cover — importlib.metadata always present ≥3.8
  617. return
  618. # Same opt-in gate as the general PluginManager: only entry points named
  619. # in ``plugins.enabled`` load, and ``plugins.disabled`` always wins.
  620. try:
  621. from hermes_cli.plugins import _get_disabled_plugins, _get_enabled_plugins
  622. enabled = _get_enabled_plugins() # None = nothing enabled yet (opt-in default)
  623. disabled = _get_disabled_plugins()
  624. except Exception: # pragma: no cover — config layer unavailable
  625. enabled, disabled = None, set()
  626. if not enabled:
  627. return
  628. group = "hermes_agent.plugins"
  629. try:
  630. eps = _md.entry_points()
  631. # Python 3.10+ exposes .select(); older returns a dict-like mapping.
  632. if hasattr(eps, "select"):
  633. group_eps = list(eps.select(group=group))
  634. else: # pragma: no cover — legacy interpreters
  635. group_eps = list(eps.get(group, [])) # type: ignore[attr-defined]
  636. except Exception as exc:
  637. logger.debug("entry-point provider scan skipped: %s", exc)
  638. return
  639. for ep in group_eps:
  640. if ep.name not in enabled or ep.name in disabled:
  641. logger.debug(
  642. "entry-point provider %r skipped: not enabled in config", ep.name
  643. )
  644. continue
  645. from hermes_cli.plugin_isolation import in_process_import_refusal
  646. refusal = in_process_import_refusal(f"pip-installed model-provider plugin {ep.name!r}")
  647. if refusal:
  648. logger.warning("%s", refusal)
  649. continue
  650. try:
  651. loaded = ep.load()
  652. except Exception as exc:
  653. logger.warning(
  654. "Failed to load entry-point provider plugin %r: %s", ep.name, exc
  655. )
  656. continue
  657. # ``module:func`` → callable we invoke; bare ``module`` → import side
  658. # effect already happened during load(). Only call when it's callable
  659. # AND zero-arg: general plugins in this shared group expose
  660. # ``register(ctx)`` (requires an argument) and belong to the
  661. # PluginManager, not the provider registry.
  662. if callable(loaded):
  663. if _requires_arguments(loaded):
  664. logger.debug(
  665. "entry-point %r skipped by provider scan: target requires "
  666. "arguments (general plugin owned by PluginManager)",
  667. ep.name,
  668. )
  669. continue
  670. try:
  671. loaded()
  672. except Exception as exc:
  673. logger.warning(
  674. "Entry-point provider plugin %r raised on invocation: %s",
  675. ep.name,
  676. exc,
  677. )
  678. def _requires_arguments(fn) -> bool:
  679. """True when ``fn`` cannot be called with zero arguments.
  680. Used to distinguish provider registration hooks (zero-arg by contract)
  681. from general plugin hooks (``register(ctx)``) sharing the same entry-point
  682. group. Unintrospectable callables (C extensions) are treated as zero-arg
  683. and left to the per-entry exception guard.
  684. """
  685. import inspect
  686. try:
  687. sig = inspect.signature(fn)
  688. except (TypeError, ValueError): # pragma: no cover — builtins/C callables
  689. return False
  690. for param in sig.parameters.values():
  691. if param.kind in (
  692. inspect.Parameter.POSITIONAL_ONLY,
  693. inspect.Parameter.POSITIONAL_OR_KEYWORD,
  694. inspect.Parameter.KEYWORD_ONLY,
  695. ) and param.default is inspect.Parameter.empty:
  696. return True
  697. return False
  698. def bundled_profiles() -> list[ProviderProfile]:
  699. """Every bundled provider profile, one per name (the last registration wins, in discovery
  700. order), WITHOUT config and without touching the registry: each bundled plugin is executed into
  701. a private module whose registrations are collected. For descriptive catalogs, which must not
  702. depend on config or on discovery having run."""
  703. from agent.safe_worker_policy import safe_worker_enabled
  704. if safe_worker_enabled(): # a safe worker loads no plugin code, bundled included (as list_providers)
  705. return []
  706. collected: list[ProviderProfile] = []
  707. token = _COLLECT.set(collected)
  708. try:
  709. for child in sorted(_BUNDLED_PLUGINS_DIR.iterdir()) if _BUNDLED_PLUGINS_DIR.is_dir() else ():
  710. init = child / "__init__.py"
  711. if not child.is_dir() or child.name.startswith(("_", ".")) or not init.exists():
  712. continue
  713. name = f"_hermes_provider_catalog_{child.name.replace('-', '_')}"
  714. spec = importlib.util.spec_from_file_location(name, init, submodule_search_locations=[str(child)])
  715. if spec is None or spec.loader is None:
  716. continue
  717. module = importlib.util.module_from_spec(spec)
  718. sys.modules[name] = module # relative imports inside the plugin
  719. try:
  720. spec.loader.exec_module(module)
  721. except Exception as exc: # health: allow BLE001 -- one broken plugin never breaks the catalog
  722. logger.debug("provider catalog skipped %s: %s", child.name, exc)
  723. finally:
  724. _COLLECT.reset(token)
  725. return list({p.name: p for p in collected}.values())
  726. def _discover_providers() -> None:
  727. """Populate the process-wide registry by importing every provider plugin.
  728. Order:
  729. 1. Bundled plugins at ``<repo>/plugins/model-providers/<name>/``
  730. 2. Legacy per-file modules at ``providers/<name>.py`` (back-compat)
  731. Each step imports its plugins, which call ``register_provider()`` at
  732. module-level. Later steps win on name collision. ``$HERMES_HOME`` plugins are
  733. per profile home and load through :func:`_home_layer` at lookup time.
  734. """
  735. from agent.safe_worker_policy import safe_worker_enabled
  736. if safe_worker_enabled():
  737. return
  738. global _discovered, _discovering
  739. if _discovered:
  740. return
  741. _discovered = True
  742. _discovering = True
  743. try:
  744. _run_discovery_steps()
  745. finally:
  746. _discovering = False
  747. # hermes_cli.auth may have been imported by a plugin during discovery and snapshotted a
  748. # partial profile list — hand it the complete one (no-op unless auth is already loaded).
  749. _sync_auth_registry()
  750. def _run_discovery_steps() -> None:
  751. """The discovery passes, in precedence order (see :func:`_discover_providers`)."""
  752. # 0. Pip-installed plugins — entry points in the ``hermes_agent.plugins``
  753. # group (the same group the general PluginManager uses). The manager
  754. # records model-provider manifests for introspection but deliberately
  755. # does NOT import them — provider lifecycle is owned here — so without
  756. # this step a ``pip install``ed provider never calls
  757. # ``register_provider()`` and is never selectable.
  758. #
  759. # Discovered FIRST, i.e. lowest precedence: because
  760. # ``register_provider()`` is last-writer-wins, running this before the
  761. # filesystem steps means a bundled or ``$HERMES_HOME`` profile of the
  762. # same name always overrides a pip-installed one. That prevents a
  763. # third-party package from silently hijacking a first-party provider
  764. # name (e.g. ``openrouter``) while still letting pip packages add
  765. # genuinely new providers.
  766. _discover_entry_point_providers()
  767. # 1. Bundled plugins — shipped with hermes-agent.
  768. if _BUNDLED_PLUGINS_DIR.is_dir():
  769. for child in sorted(_BUNDLED_PLUGINS_DIR.iterdir()):
  770. if not child.is_dir() or child.name.startswith(("_", ".")):
  771. continue
  772. _import_plugin_dir(child, "bundled")
  773. # 2. Legacy single-file profiles at providers/<name>.py. Kept for
  774. # back-compat — if someone drops a ``providers/foo.py`` into an
  775. # editable install, it still works without the plugin layout.
  776. try:
  777. import pkgutil
  778. import providers as _pkg
  779. for _importer, modname, _ispkg in pkgutil.iter_modules(_pkg.__path__):
  780. if modname.startswith("_") or modname == "base":
  781. continue
  782. try:
  783. importlib.import_module(f"providers.{modname}")
  784. except ImportError as exc:
  785. logger.warning(
  786. "Failed to import legacy provider module %s: %s", modname, exc
  787. )
  788. except Exception:
  789. pass
  790. # (Pip entry-point providers are discovered in step 0, before the
  791. # filesystem plugins, so first-party profiles always win on name
  792. # collision — see _discover_entry_point_providers.)