plugins_ledger.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307
  1. """Registration ownership ledger and unload: every plugin registration is recorded with its inverse so force
  2. reload / targeted unload unwind registries in reverse order. Mixed into :class:`hermes_cli.plugins.PluginManager`.
  3. """
  4. from __future__ import annotations
  5. import logging
  6. from dataclasses import dataclass, field
  7. from pathlib import Path
  8. from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Set, Union
  9. from registration_lifecycle import replacement_coordinator
  10. from hermes_cli.plugins_loader import _plugin_home_scope
  11. from hermes_cli.plugins_manifest import PluginManifest, manifest_key
  12. if TYPE_CHECKING: # pragma: no cover
  13. from hermes_cli.plugins import LoadedPlugin
  14. logger = logging.getLogger("hermes_cli.plugins")
  15. def _hook_source_of(name: str, module: Any) -> Optional[tuple]:
  16. """(plugin name, resolved ``__file__``) identity shared by the general and memory loaders."""
  17. source = getattr(module, "__file__", None)
  18. return (name, str(Path(source).resolve())) if source else None
  19. @dataclass
  20. class PluginRegistration:
  21. """One host-owned registration plus its inverse, so force reload unwinds registries in reverse order
  22. (including restoring the entry an override replaced)."""
  23. kind: str
  24. key: str
  25. release: Callable[[], None]
  26. plugin_key: str = ""
  27. # Process-global host infrastructure (e.g. dashboard-auth providers): kept out of ``_registration_order``
  28. # so unload-all cannot dispose it, but still disposed by a *targeted* unload and evicted on force
  29. # re-discovery when the plugin no longer re-registers it.
  30. # See #91701.
  31. persistent: bool = False
  32. # A ``transform_llm_output`` registration that must see the reply before the user does
  33. # (``register_hook(..., hold_stream=True)``; read by ``PluginDispatchMixin.holds_stream``).
  34. hold_stream: bool = False
  35. _disposed: bool = field(default=False, init=False, repr=False)
  36. _on_dispose: Optional[Callable[[PluginRegistration], None]] = field(default=None, init=False, repr=False)
  37. @property
  38. def active(self) -> bool:
  39. """Whether this handle still owns an active registration."""
  40. return not self._disposed
  41. def dispose(self) -> None:
  42. """Release this registration once; repeated disposal is harmless."""
  43. if self._disposed:
  44. return
  45. self._disposed = True
  46. try:
  47. self.release()
  48. finally:
  49. if self._on_dispose is not None:
  50. self._on_dispose(self)
  51. class PluginLedgerMixin:
  52. def _track_registration(
  53. self, manifest: PluginManifest, kind: str, key: str, release: Callable[[], None], *,
  54. persistent: bool = False,
  55. ) -> PluginRegistration:
  56. """Record one registration under its canonical plugin key. ``persistent`` ones (process-global host
  57. infrastructure) stay in the ownership ledger for attribution but NOT in ``_registration_order``, so a
  58. routine unload cannot dispose them; the handle still releases on explicit ``dispose()``.
  59. See #91701.
  60. """
  61. registration = PluginRegistration(
  62. kind=kind, key=key, release=release, plugin_key=manifest_key(manifest), persistent=persistent)
  63. registration._on_dispose = lambda disposed: self._forget_registrations([disposed])
  64. self._ownership_ledger.setdefault(registration.plugin_key, []).append(registration)
  65. if not persistent:
  66. self._registration_order.append(registration)
  67. return registration
  68. def _track_scoped_registration(
  69. self, manifest: PluginManifest, kind: str, name: str, registry: Any, current: Any,
  70. previous: Any, *, finalize: Optional[Callable[[], None]] = None,
  71. ) -> PluginRegistration:
  72. """Lease one ``(kind, scope, name)`` slot of a scope-keyed process-global registry. Unload calls
  73. ``registry.restore_registration(name, current, replacement, scope=...)`` — identity-conditional, so a
  74. later generation is never removed by an earlier owner."""
  75. scope = self.scope_key
  76. lease = replacement_coordinator.acquire(
  77. (kind, scope, name), current=current, previous=previous,
  78. restore=lambda replacement: registry.restore_registration(name, current, replacement, scope=scope),
  79. finalize=finalize,
  80. )
  81. return self._track_registration(manifest, kind, name, lease.dispose)
  82. def _active_persistent(self) -> list[PluginRegistration]:
  83. """Live persistent registrations across every plugin in the ownership ledger."""
  84. return [r for owned in self._ownership_ledger.values() for r in owned if r.persistent and r.active]
  85. def _evict_stale_persistent_registrations(self) -> None:
  86. """After re-discovery, dispose parked persistent handles whose plugin did not re-register the same
  87. ``(kind, key)``. Re-registered ones are dropped WITHOUT disposing — the same object re-registered would
  88. pass the identity check and evict the live entry.
  89. Persistent registrations (process-global host infrastructure such as dashboard-auth providers)
  90. survive an unload-all by design (#91701); ``_unload_scoped`` parks their handles in
  91. ``_persistent_carryover``. After a re-discovery pass, three cases exist for each parked handle:
  92. """
  93. if not self._persistent_carryover:
  94. return
  95. parked, self._persistent_carryover = self._persistent_carryover, []
  96. current = {(r.kind, r.key) for r in self._active_persistent()}
  97. stale = [r for r in parked if r.active and (r.kind, r.key) not in current]
  98. for registration in stale:
  99. logger.info(
  100. "Evicting persistent registration %s/%s: plugin '%s' no "
  101. "longer supplies it after re-discovery", registration.kind, registration.key, registration.plugin_key,
  102. )
  103. self._dispose_registrations(stale)
  104. @staticmethod
  105. def _remove_identity(values: list, target: Any) -> bool:
  106. """Remove the last exact object match from a registration list."""
  107. index = next((i for i in range(len(values) - 1, -1, -1) if values[i] is target), None)
  108. if index is None:
  109. return False
  110. del values[index]
  111. return True
  112. def _remove_callback(self, mapping: dict[str, list[Callable]], key: str, callback: Callable) -> None:
  113. callbacks = mapping.get(key)
  114. if callbacks is None:
  115. return
  116. self._remove_identity(callbacks, callback)
  117. if not callbacks:
  118. mapping.pop(key, None)
  119. def _restore_mapping(self, mapping: dict[str, Any], key: str, current: Any, previous: Optional[Any]) -> bool:
  120. """Restore a manager-local mapping only when *current* is still present."""
  121. if mapping.get(key) is not current:
  122. return False
  123. if previous is None:
  124. mapping.pop(key, None)
  125. else:
  126. mapping[key] = previous
  127. return True
  128. def _restore_value(self, attribute: str, current: Any, previous: Any) -> bool:
  129. """Restore a manager-local value only when *current* is still active."""
  130. if getattr(self, attribute) is not current:
  131. return False
  132. setattr(self, attribute, previous)
  133. return True
  134. def _remove_name_if_unowned(self, kind: str, names: set[str], name: str) -> None:
  135. """Drop *name* from the manager-local name set once no active ledger entry owns it."""
  136. if not any(r.active and r.kind == kind and r.key == name for r in self._registration_order):
  137. names.discard(name)
  138. def _remove_tool_name_if_unowned(self, name: str) -> None:
  139. self._remove_name_if_unowned("tool", self._plugin_tool_names, name)
  140. def _remove_platform_name_if_unowned(self, name: str) -> None:
  141. self._remove_name_if_unowned("platform", self._plugin_platform_names, name)
  142. def _forget_registrations(self, registrations: list[PluginRegistration]) -> None:
  143. if not registrations:
  144. return
  145. ids = {id(r) for r in registrations}
  146. self._registration_order = [r for r in self._registration_order if id(r) not in ids]
  147. for ledger in (self._ownership_ledger, self._memory_hook_registrations):
  148. for plugin_key, owned in list(ledger.items()):
  149. remaining = [r for r in owned if id(r) not in ids]
  150. if remaining:
  151. ledger[plugin_key] = remaining
  152. else:
  153. ledger.pop(plugin_key, None)
  154. # -- dual-kind hook ownership -------------------------------------------------------------
  155. # A plugin dir loaded by general discovery AND as the configured memory provider calls
  156. # ``register()`` twice against the same manager. General discovery owns the hook group; the
  157. # memory loader's hooks are a fallback group keyed by (name, resolved source path) that is
  158. # dropped once the same source loads through discovery. Groups, not callbacks, are replaced:
  159. # one register() may deliberately create several closures for one hook.
  160. def _drop_fallback_hooks(self, hook_source: Optional[tuple]) -> None:
  161. if hook_source is not None:
  162. for handle in self._memory_hook_registrations.pop(hook_source, []):
  163. handle.dispose()
  164. def _register_fallback_hook(self, context: Any, hook_source: Optional[tuple], hook_name: str,
  165. callback: Callable, *, hold_stream: bool = False) -> PluginRegistration:
  166. """Register ``callback`` unless the same source is already live through general discovery, in
  167. which case return an inert handle so the provider keeps its disposable-handle contract."""
  168. if hook_source is None:
  169. return context.register_hook(hook_name, callback, hold_stream=hold_stream)
  170. owned = any(loaded.enabled and _hook_source_of(loaded.manifest.name, loaded.module) == hook_source
  171. for loaded in self._plugins.values())
  172. handle = (context._track("hook", hook_name, lambda: None) if owned
  173. else context.register_hook(hook_name, callback, hold_stream=hold_stream))
  174. self._memory_hook_registrations.setdefault(hook_source, []).append(handle)
  175. return handle
  176. def _dispose_registrations(self, registrations: list[PluginRegistration]) -> None:
  177. """Dispose registrations in reverse acquisition order, best effort."""
  178. from hermes_cli.plugins import _PLUGINS_DEBUG
  179. for registration in reversed(registrations):
  180. try:
  181. registration.dispose()
  182. except Exception as exc: # pragma: no cover - defensive cleanup
  183. logger.warning(
  184. "Failed to unload plugin registration %s/%s: %s", registration.plugin_key,
  185. registration.key, exc, exc_info=_PLUGINS_DEBUG,
  186. )
  187. @staticmethod
  188. def _resolve_plugin_key(plugin: str | PluginManifest | LoadedPlugin) -> str:
  189. from hermes_cli.plugins import LoadedPlugin
  190. if isinstance(plugin, LoadedPlugin):
  191. return manifest_key(plugin.manifest)
  192. return manifest_key(plugin) if isinstance(plugin, PluginManifest) else str(plugin)
  193. def unload(self, plugin: str | PluginManifest | LoadedPlugin | None = None) -> bool:
  194. """Unload registrations while excluding discovery/deferred loading."""
  195. with self._discovery_lock, _plugin_home_scope(self.home_path):
  196. return self._unload_scoped(plugin)
  197. def _unload_scoped(self, plugin: str | PluginManifest | LoadedPlugin | None = None) -> bool:
  198. """Unload one plugin (or all when ``plugin=None``, as force rediscovery does). Every ledger registration
  199. — including on_unload callbacks and supervised tasks — is disposed in reverse acquisition order with
  200. identity-conditional inverses. Returns ``True`` when anything was found."""
  201. unload_all = plugin is None
  202. if unload_all:
  203. target_keys = set(self._ownership_ledger) | set(self._plugins)
  204. registrations = list(self._registration_order)
  205. else:
  206. target_keys = self._unload_target_keys(self._resolve_plugin_key(plugin))
  207. registrations = [r for r in self._registration_order if r.plugin_key in target_keys]
  208. # Persistent registrations are absent from _registration_order (unload-all keeps them), but a
  209. # *targeted* unload is the disable/uninstall path: a disabled auth plugin's provider must NOT stay
  210. # live process-wide.
  211. # See #91701.
  212. registrations.extend(
  213. r for key in target_keys for r in self._ownership_ledger.get(key, []) if r.persistent and r.active
  214. )
  215. found = bool(target_keys or registrations)
  216. self._dispose_registrations(registrations)
  217. self._forget_registrations(registrations)
  218. if unload_all:
  219. self._reset_after_unload_all(registrations)
  220. else:
  221. for key in target_keys:
  222. self._plugins.pop(key, None)
  223. return found
  224. def _unload_target_keys(self, requested: str) -> set[str]:
  225. """Resolve a targeted-unload request to canonical plugin keys (exact key, else by name)."""
  226. if requested in self._ownership_ledger or requested in self._plugins:
  227. return {requested}
  228. return {key for key, loaded in self._plugins.items() if loaded.manifest.name == requested}
  229. def _reset_after_unload_all(self, registrations: list[PluginRegistration]) -> None:
  230. """Sweep pre-ledger global state and clear every manager-local container."""
  231. # Handles are authoritative for global registries; names present in the manager-local sets without a
  232. # ledger entry (pre-ledger or manually set state) are swept here so they do not survive a force reload
  233. # as zombies.
  234. from gateway.platform_registry import platform_registry
  235. for platform_name in tuple(self._plugin_platform_names):
  236. platform_registry.unregister(platform_name)
  237. # Ledger-owned tool names are excluded: their handles already restored the previous entry, and blanket
  238. # deregistration would remove what the ledger just restored.
  239. ledger_tool_names = {r.key for r in registrations if r.kind == "tool"}
  240. preledger_tools = tuple(n for n in self._plugin_tool_names if n not in ledger_tool_names)
  241. if preledger_tools:
  242. try:
  243. from tools.registry import registry as tool_registry
  244. except Exception as exc: # pragma: no cover - defensive
  245. logger.debug("unload: tools.registry unavailable: %s", exc)
  246. else:
  247. for tool_name in preledger_tools:
  248. try:
  249. tool_registry.deregister(tool_name)
  250. except Exception as exc:
  251. logger.debug("unload: tool deregister %s failed: %s", tool_name, exc)
  252. # Persistent registrations survive unload-all but must not be orphaned by the ledger clear: carry them
  253. # over so force re-discovery can evict the ones whose plugin does not come back.
  254. carryover_ids = {id(r) for r in self._persistent_carryover}
  255. self._persistent_carryover.extend(r for r in self._active_persistent() if id(r) not in carryover_ids)
  256. for container in (
  257. self._ownership_ledger, self._plugins, self._hooks, self._middleware,
  258. self._plugin_tool_names, self._plugin_platform_names, self._cli_commands,
  259. self._plugin_commands, self._plugin_skills, self._automation_blueprints, self._portable_mcp_servers,
  260. self._portable_mcp_server_plugins, self._aux_tasks, self._system_prompt_sections, self._approval_transports,
  261. self._slack_action_handlers, self._predeclared_modules, self._predeclared_tools,
  262. self._platform_handler_factories,
  263. ):
  264. container.clear()
  265. self._context_engine = None
  266. with self._hook_timeout_lock:
  267. self._hook_running_callbacks.clear()
  268. self._hook_abandoned.clear()
  269. self._hook_timeout_suppressed_until.clear()
  270. self._hook_failures_reported.clear()
  271. self._discovered = False