plugin_host_child.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614
  1. """The plugin host process: imports third-party plugins and serves their callbacks to Hermes.
  2. Started by :class:`hermes_cli.plugin_host.PluginHost` as ``python -m hermes_cli.plugin_host_child``
  3. (optionally under ``plugins.host.launcher``, e.g. a sandbox runner) with the profile's environment.
  4. Plugins get a :class:`RemotePluginContext` that looks like ``PluginContext``: registrations and
  5. queries are forwarded to Hermes, callables and provider objects stay here and are invoked by
  6. reference. Nothing in this module is imported by the Hermes process itself.
  7. stdin/stdout carry the protocol, so the real file descriptors are duplicated for the channel and
  8. fd 0/1 are pointed at /dev/null and stderr before any plugin code runs: a stray ``print()`` in a
  9. plugin lands in the host log instead of corrupting the wire.
  10. """
  11. from __future__ import annotations
  12. import asyncio
  13. import functools
  14. import importlib
  15. import importlib.metadata
  16. import importlib.util
  17. import inspect
  18. import itertools
  19. import logging
  20. import os
  21. import sys
  22. import threading
  23. import types
  24. from pathlib import Path
  25. from typing import Any, Callable, Dict, List, Optional
  26. from hermes_cli.plugin_host_wire import (
  27. Channel, Opaque, PROTOCOL_VERSION, PluginHostUnsupported, bind_serving_request, declared_member, decode,
  28. describe_signature, encode, is_async_callable, restore_arguments, serving_request,
  29. )
  30. logger = logging.getLogger("hermes_cli.plugin_host_child")
  31. _ENTRY_POINTS_GROUP = "hermes_agent.plugins"
  32. class RemoteRegistration:
  33. """Child-side twin of ``PluginRegistration``: ``dispose()`` releases the Hermes-side entry."""
  34. def __init__(self, runtime: HostRuntime, handle_id: int, kind: str, key: str):
  35. self._runtime, self._id, self.kind, self.key = runtime, handle_id, kind, key
  36. self._disposed = False
  37. @property
  38. def active(self) -> bool:
  39. return not self._disposed
  40. def dispose(self) -> None:
  41. if self._disposed:
  42. return
  43. self._disposed = True
  44. self._runtime.channel.call("dispose", {"handle": self._id})
  45. class RemoteFacade:
  46. """``ctx.state`` / ``ctx.llm`` / ...: every method call runs on the Hermes-side facade."""
  47. def __init__(self, runtime: HostRuntime, plugin_key: str, name: str):
  48. self._runtime, self._plugin_key, self._name = runtime, plugin_key, name
  49. self._methods: dict[str, bool] = {} # method name -> is a coroutine function in Hermes
  50. def __getattr__(self, attr: str) -> Any:
  51. if attr.startswith("_"):
  52. raise AttributeError(attr)
  53. if attr not in self._methods:
  54. value = self._runtime.facade_call(self._plugin_key, self._name, attr, _probe=True)
  55. if not (isinstance(value, dict) and value.get("__method__")):
  56. return value # a plain attribute (``ctx.state.data_dir``): read fresh every time
  57. self._methods[attr] = bool(value.get("async"))
  58. call = functools.partial(self._runtime.facade_call, self._plugin_key, self._name, attr)
  59. if not self._methods[attr]:
  60. return call
  61. async def remote(*args: Any, **kwargs: Any) -> Any: # ``await ctx.llm.acomplete(...)``
  62. return await asyncio.to_thread(call, *args, **kwargs)
  63. remote.__name__ = attr
  64. return remote
  65. class RemotePluginContext:
  66. """What ``register(ctx)`` receives inside the host. Mirrors ``PluginContext``'s public surface as
  67. announced by Hermes at load, so ``hasattr(ctx, "register_x")`` answers the same as in-process."""
  68. def __init__(self, runtime: HostRuntime, plugin_key: str, info: dict[str, Any]):
  69. self._runtime, self._plugin_key = runtime, plugin_key
  70. self._methods = set(info.get("ctx_methods") or ())
  71. self._facades: dict[str, RemoteFacade] = {}
  72. self.manifest = types.SimpleNamespace(**(info.get("manifest") or {}))
  73. self.plugin_id = info.get("plugin_id") or plugin_key
  74. self.profile_name = info.get("profile_name")
  75. def __getattr__(self, name: str) -> Any:
  76. if name.startswith("_"):
  77. raise AttributeError(name)
  78. from hermes_cli.plugin_isolation import (
  79. HOST_REMOTE_FACADES, HOST_SKIPPED_CTX_METHODS, HOST_UNSUPPORTED_CTX_METHODS,
  80. )
  81. if name in HOST_UNSUPPORTED_CTX_METHODS:
  82. def unsupported(*_args: Any, **_kwargs: Any) -> Any:
  83. raise PluginHostUnsupported(
  84. f"ctx.{name}() cannot run in the plugin host: {HOST_UNSUPPORTED_CTX_METHODS[name]}")
  85. return unsupported
  86. if name in HOST_SKIPPED_CTX_METHODS:
  87. def skipped(*_args: Any, **_kwargs: Any) -> None:
  88. logger.warning("Plugin '%s': ctx.%s() is skipped in the plugin host (%s)",
  89. self.manifest.name, name, HOST_SKIPPED_CTX_METHODS[name])
  90. return skipped
  91. if name in HOST_REMOTE_FACADES:
  92. return self._facades.setdefault(name, RemoteFacade(self._runtime, self._plugin_key, name))
  93. if name not in self._methods:
  94. raise AttributeError(f"'PluginContext' object has no attribute {name!r}")
  95. return functools.partial(self._runtime.ctx_call, self._plugin_key, name)
  96. def on_unload(self, callback: Callable[[], Any]) -> None:
  97. if not callable(callback):
  98. raise TypeError("on_unload() callback must be callable")
  99. self._runtime.unload_callbacks.setdefault(self._plugin_key, []).append(callback)
  100. def spawn_task(self, coro: Any, *, name: Optional[str] = None) -> Any:
  101. return self._runtime.spawn(coro, name=name)
  102. class HostRuntime:
  103. """Reference tables, the asyncio loop for async plugin code, and the request handler."""
  104. def __init__(self, reader, writer):
  105. self.refs: dict[int, Any] = {}
  106. self.owners: dict[int, str] = {}
  107. self._ids = itertools.count(1)
  108. self._lock = threading.Lock()
  109. self.unload_callbacks: dict[str, list[Callable[[], Any]]] = {}
  110. self.modules: dict[str, str] = {}
  111. self.asgi_apps: dict[str, Any] = {}
  112. self.profiles: dict[str, dict[str, Any]] = {}
  113. self.instance_modules: dict[str, Any] = {}
  114. self.stopped = threading.Event()
  115. self.loop = asyncio.new_event_loop()
  116. threading.Thread(target=self.loop.run_forever, name="plugin-host-loop", daemon=True).start()
  117. self.channel = Channel(reader, writer, self.handle, name="plugin-host",
  118. on_close=lambda _reason: self.stopped.set())
  119. # -- references -----------------------------------------------------------------------------
  120. def _remember(self, plugin_key: str, value: Any) -> int:
  121. with self._lock:
  122. ref = next(self._ids)
  123. self.refs[ref] = value
  124. self.owners[ref] = plugin_key
  125. return ref
  126. def ref_for(self, plugin_key: str, value: Any, *, allow_objects: bool) -> Optional[dict]:
  127. if isinstance(value, type):
  128. return None
  129. if callable(value) and not (allow_objects and _is_provider_object(value)):
  130. return {"__callable__": self._remember(plugin_key, value), "async": is_async_callable(value),
  131. "sig": describe_signature(value), "name": getattr(value, "__name__", "callback"),
  132. "qualname": getattr(value, "__qualname__", None),
  133. "module": getattr(value, "__module__", None)}
  134. if allow_objects and _is_provider_object(value):
  135. return self._describe_object(plugin_key, value)
  136. return None
  137. def _describe_object(self, plugin_key: str, obj: Any) -> dict:
  138. """Method table + attribute plan for a provider object; every method runs here, in the host."""
  139. methods: dict[str, Any] = {}
  140. instance = sorted(k for k in vars(obj) if not k.startswith("_")) if hasattr(obj, "__dict__") else []
  141. live: list[str] = list(instance)
  142. for name in dir(obj):
  143. if name.startswith("_") or name in instance:
  144. continue
  145. raw = inspect.getattr_static(obj, name, None)
  146. if isinstance(raw, property) or type(raw).__name__ == "cached_property":
  147. live.append(name)
  148. continue
  149. value = getattr(obj, name, None)
  150. if callable(value):
  151. methods[name] = {"async": is_async_callable(value), "sig": describe_signature(value)}
  152. else:
  153. # Class-level defaults too: an engine that sets ``context_length`` only later in
  154. # ``update_model()`` must not read as the base-class default forever in Hermes.
  155. live.append(name)
  156. return {"__object__": self._remember(plugin_key, obj), "methods": methods, "live": live,
  157. "type": type(obj).__name__}
  158. def resolve_from_parent(self, ref: dict) -> Any:
  159. if "__handle__" in ref:
  160. return RemoteRegistration(self, int(ref["__handle__"]), str(ref.get("kind") or ""),
  161. str(ref.get("key") or ""))
  162. return Opaque("callable" if "__callable__" in ref else "object")
  163. # -- outgoing ---------------------------------------------------------------------------------
  164. def _send_call(self, method: str, plugin_key: str, payload: dict[str, Any], *, allow_objects: bool) -> Any:
  165. refs = functools.partial(self.ref_for, plugin_key, allow_objects=allow_objects)
  166. payload = {**payload, "plugin": plugin_key,
  167. "args": encode(list(payload.pop("args", ())), refs),
  168. "kwargs": encode(dict(payload.pop("kwargs", {})), refs)}
  169. return decode(self.channel.call(method, payload), self.resolve_from_parent)
  170. def ctx_call(self, plugin_key: str, method: str, *args: Any, **kwargs: Any) -> Any:
  171. from hermes_cli.plugin_isolation import HOST_OBJECT_BASES
  172. return self._send_call("ctx", plugin_key, {"method": method, "args": args, "kwargs": kwargs},
  173. allow_objects=method in HOST_OBJECT_BASES)
  174. def facade_call(self, plugin_key: str, facade: str, method: str, *args: Any, _probe: bool = False,
  175. **kwargs: Any) -> Any:
  176. return self._send_call("facade", plugin_key, {"facade": facade, "method": method, "probe": _probe,
  177. "args": args, "kwargs": kwargs}, allow_objects=False)
  178. def spawn(self, coro: Any, *, name: Optional[str] = None) -> Any:
  179. if not inspect.iscoroutine(coro):
  180. raise TypeError("spawn_task() requires a coroutine object")
  181. return asyncio.run_coroutine_threadsafe(_on_behalf_of(coro, serving_request()), self.loop)
  182. # -- incoming ---------------------------------------------------------------------------------
  183. def handle(self, method: str, params: dict[str, Any], _origin: Optional[int]) -> Any:
  184. handler = _HANDLERS.get(method)
  185. if handler is None:
  186. raise ValueError(f"unknown plugin host request {method!r}")
  187. return handler(self, params)
  188. def _run(self, result: Any) -> Any:
  189. """Await plugin coroutines on the host loop, still attributed to the request being served
  190. (their ``ctx`` calls then run in that caller's session, not a bare context)."""
  191. if inspect.isawaitable(result):
  192. return asyncio.run_coroutine_threadsafe(_on_behalf_of(result, serving_request()), self.loop).result()
  193. return result
  194. def _encode_result(self, plugin_key: str, value: Any) -> Any:
  195. def refs(obj: Any) -> Optional[dict]:
  196. if _provider_base(obj) is not None: # e.g. the engine ``clone_for_agent`` returns
  197. return self._describe_object(plugin_key, obj)
  198. return self.ref_for(plugin_key, obj, allow_objects=False)
  199. return encode(value, refs)
  200. def _decode_args(self, params: dict[str, Any]):
  201. return decode(params.get("args") or [], None), decode(params.get("kwargs") or {}, None)
  202. def op_hello(self, _params: dict[str, Any]) -> dict[str, Any]:
  203. return {"protocol": PROTOCOL_VERSION, "pid": os.getpid(), "python": sys.version.split()[0]}
  204. def op_load(self, params: dict[str, Any]) -> dict[str, Any]:
  205. plugin_key = str(params["plugin_key"])
  206. target = _import_plugin(params)
  207. register = target if callable(target) and not isinstance(target, types.ModuleType) \
  208. else getattr(target, "register", None)
  209. if not callable(register):
  210. raise AttributeError(f"Plugin '{params.get('name')}' has no register() function")
  211. module_name = getattr(target, "__name__", None) or getattr(register, "__module__", None)
  212. self.modules[plugin_key] = str(module_name or "")
  213. self._run(register(RemotePluginContext(self, plugin_key, params)))
  214. return {"module": module_name}
  215. def op_load_instance(self, params: dict[str, Any]) -> Any:
  216. """Category plugins (memory provider, context engine, cron scheduler): import the directory,
  217. run ``register(ctx)`` capturing the one ``capture`` registration, else instantiate the first
  218. subclass of ``base``. Other registrations reach Hermes only when it bound a ctx for them."""
  219. plugin_key = str(params["plugin_key"])
  220. # Hermes asks for a fresh instance many times (agent cache, doctor, dashboard); like the
  221. # in-process loader, the module body runs once per host and only the instance is new.
  222. module = self.instance_modules.get(str(params["path"]))
  223. if module is None:
  224. module = self.instance_modules[str(params["path"])] = _import_plugin(params)
  225. self.modules[plugin_key] = module.__name__
  226. base = _import_base(str(params["base"]))
  227. capture = str(params["capture"])
  228. captured: list[Any] = []
  229. register = getattr(module, "register", None)
  230. if callable(register):
  231. ctx = _CapturingContext(self, plugin_key, params, capture, base, captured,
  232. forward=bool(params.get("forward")))
  233. try:
  234. self._run(register(ctx))
  235. except Exception as exc:
  236. if not captured:
  237. logger.debug("register() failed for %s: %s", params.get("name"), exc)
  238. if not captured:
  239. for attr in dir(module):
  240. value = getattr(module, attr, None)
  241. if isinstance(value, type) and issubclass(value, base) and value is not base:
  242. try:
  243. captured.append(value())
  244. break
  245. except Exception:
  246. continue
  247. if not captured:
  248. return None
  249. return self._describe_object(plugin_key, captured[0])
  250. def op_profile_call(self, params: dict[str, Any]) -> Any:
  251. """Run one overridden method (or callable field) of a model-provider profile, loading the
  252. plugin on first use in this host process. Addressed by name, so it survives host restarts."""
  253. profiles = self.profiles.get(str(params["path"]))
  254. if profiles is None:
  255. profiles = self.profiles[str(params["path"])] = {
  256. p.name: p for p in capture_profiles(str(params["path"]), str(params["module_name"]))}
  257. target = getattr(profiles[str(params["profile"])], str(params["attr"]))
  258. args, kwargs = self._decode_args(params)
  259. return encode(self._run(target(*args, **kwargs)))
  260. def op_asgi(self, params: dict[str, Any]) -> Any:
  261. """Serve one dashboard API request with the plugin's FastAPI ``router`` (loaded once)."""
  262. api_path = Path(str(params["dashboard_dir"])) / str(params["api_file"])
  263. app = self.asgi_apps.get(str(api_path))
  264. if app is None:
  265. from fastapi import FastAPI
  266. module_name = f"hermes_dashboard_plugin_{params['plugin']}"
  267. spec = importlib.util.spec_from_file_location(module_name, api_path)
  268. if spec is None or spec.loader is None:
  269. raise ImportError(f"cannot load dashboard api {api_path}")
  270. module = importlib.util.module_from_spec(spec)
  271. sys.modules[module_name] = module
  272. spec.loader.exec_module(module)
  273. router = getattr(module, "router", None)
  274. if router is None:
  275. raise AttributeError(f"dashboard api {api_path.name} has no 'router'")
  276. app = FastAPI()
  277. app.include_router(router)
  278. self.asgi_apps[str(api_path)] = app
  279. async def request() -> dict[str, Any]:
  280. import httpx
  281. from hermes_cli.plugin_host_http_auth import with_hosted_admission
  282. transport = httpx.ASGITransport(app=with_hosted_admission(app, params.get("authenticated")))
  283. async with httpx.AsyncClient(transport=transport, base_url="http://plugin-host") as client:
  284. response = await client.request(
  285. str(params["method"]), str(params["path"]), params=str(params.get("query") or ""),
  286. headers=[tuple(h) for h in params.get("headers") or []],
  287. content=decode(params.get("body")) or b"")
  288. return {"status": response.status_code, "headers": list(response.headers.multi_items()),
  289. "body": response.content}
  290. return encode(self._run(request()))
  291. def op_invoke(self, params: dict[str, Any]) -> Any:
  292. ref = int(params["ref"])
  293. fn = self.refs.get(ref)
  294. if fn is None:
  295. raise LookupError(f"plugin host callable {ref} was released")
  296. args, kwargs = self._decode_args(params)
  297. return self._encode_result(self.owners.get(ref, ""), self._run(fn(*args, **kwargs)))
  298. def op_obj_invoke(self, params: dict[str, Any]) -> Any:
  299. ref = int(params["ref"])
  300. obj = self.refs.get(ref)
  301. if obj is None:
  302. raise LookupError(f"plugin host object {ref} was released")
  303. method = str(params["method"])
  304. if method.startswith("_"):
  305. raise AttributeError(method)
  306. args, kwargs = self._decode_args(params)
  307. base = _provider_base(obj)
  308. if base is not None: # the ABC's annotations say what Hermes passed (``home_path: Path``)
  309. args, kwargs = restore_arguments(declared_member(base, method), args, kwargs)
  310. return self._encode_result(self.owners.get(ref, ""), self._run(getattr(obj, method)(*args, **kwargs)))
  311. def op_obj_getattr(self, params: dict[str, Any]) -> Any:
  312. obj = self.refs.get(int(params["ref"]))
  313. name = str(params["name"])
  314. if obj is None:
  315. raise LookupError(f"plugin host object {params['ref']} was released")
  316. if name.startswith("_") or not hasattr(obj, name):
  317. return {"__missing__": name}
  318. return self._encode_result(self.owners.get(int(params["ref"]), ""), getattr(obj, name))
  319. def op_release(self, params: dict[str, Any]) -> None:
  320. """Drop objects whose Hermes-side proxies were garbage-collected."""
  321. with self._lock:
  322. for ref in params.get("refs") or ():
  323. self.refs.pop(int(ref), None)
  324. self.owners.pop(int(ref), None)
  325. def op_config_schema(self, params: dict[str, Any]) -> Any:
  326. """A memory provider's ``config_schema.py`` ``CONFIG_SCHEMA`` (user code: it runs here)."""
  327. path = Path(str(params["path"]))
  328. spec = importlib.util.spec_from_file_location(f"_hermes_memory_config_schema.{path.parent.name}", path)
  329. if spec is None or spec.loader is None:
  330. raise ImportError(f"cannot load {path}")
  331. module = importlib.util.module_from_spec(spec)
  332. spec.loader.exec_module(module)
  333. return encode(getattr(module, "CONFIG_SCHEMA", None))
  334. def op_obj_setattr(self, params: dict[str, Any]) -> None:
  335. obj = self.refs.get(int(params["ref"]))
  336. name = str(params["name"])
  337. if obj is None or name.startswith("_"):
  338. raise AttributeError(name)
  339. setattr(obj, name, decode(params.get("value"), None))
  340. def op_unload(self, params: dict[str, Any]) -> dict[str, Any]:
  341. plugin_key = str(params["plugin_key"])
  342. errors = []
  343. for callback in reversed(self.unload_callbacks.pop(plugin_key, [])):
  344. try:
  345. self._run(callback())
  346. except Exception as exc:
  347. errors.append(f"{type(exc).__name__}: {exc}")
  348. with self._lock:
  349. for ref in [r for r, owner in self.owners.items() if owner == plugin_key]:
  350. self.refs.pop(ref, None)
  351. self.owners.pop(ref, None)
  352. module_name = self.modules.pop(plugin_key, "")
  353. if module_name:
  354. for name in [m for m in sys.modules if m == module_name or m.startswith(module_name + ".")]:
  355. sys.modules.pop(name, None)
  356. return {"errors": errors}
  357. def op_shutdown(self, _params: dict[str, Any]) -> None:
  358. for plugin_key in list(self.unload_callbacks):
  359. self.op_unload({"plugin_key": plugin_key})
  360. self.stopped.set()
  361. _HANDLERS: dict[str, Callable[[HostRuntime, dict[str, Any]], Any]] = {
  362. "hello": HostRuntime.op_hello, "load": HostRuntime.op_load, "load_instance": HostRuntime.op_load_instance,
  363. "asgi": HostRuntime.op_asgi, "profile_call": HostRuntime.op_profile_call,
  364. "invoke": HostRuntime.op_invoke,
  365. "obj_invoke": HostRuntime.op_obj_invoke, "obj_getattr": HostRuntime.op_obj_getattr,
  366. "obj_setattr": HostRuntime.op_obj_setattr, "unload": HostRuntime.op_unload,
  367. "release": HostRuntime.op_release, "config_schema": HostRuntime.op_config_schema,
  368. "shutdown": HostRuntime.op_shutdown,
  369. }
  370. class _CapturingContext(RemotePluginContext):
  371. """``register(ctx)`` for a category plugin: the category's own registration is kept here; the rest
  372. forward to Hermes when it bound a context (memory providers), else are no-ops."""
  373. def __init__(self, runtime: HostRuntime, plugin_key: str, info: dict[str, Any], capture: str,
  374. base: type, captured: list[Any], *, forward: bool):
  375. super().__init__(runtime, plugin_key, info)
  376. self._capture, self._base, self._captured, self._forward = capture, base, captured, forward
  377. def __getattr__(self, name: str) -> Any:
  378. if name == self._capture:
  379. def capture(obj: Any, *_args: Any, **_kwargs: Any) -> None:
  380. if isinstance(obj, self._base) and not self._captured:
  381. self._captured.append(obj)
  382. return capture
  383. if not self._forward and (name.startswith("register_") or name in {"subscribe"}):
  384. return lambda *_args, **_kwargs: None
  385. return super().__getattr__(name)
  386. def _import_base(ref: str) -> type:
  387. module, attr = ref.split(":")
  388. return getattr(importlib.import_module(module), attr)
  389. def _provider_base(value: Any) -> Optional[type]:
  390. """The provider ABC (``HOST_OBJECT_BASES``) ``value`` implements. Only an already-imported base
  391. can match: a plugin object subclassing it imported it."""
  392. from hermes_cli.plugin_isolation import HOST_OBJECT_BASES
  393. for ref in HOST_OBJECT_BASES.values():
  394. module, attr = ref.split(":")
  395. base = getattr(sys.modules.get(module), attr, None)
  396. if isinstance(base, type) and isinstance(value, base):
  397. return base
  398. return None
  399. def _is_provider_object(value: Any) -> bool:
  400. """A plugin-defined instance (provider/engine), as opposed to a function or bound method."""
  401. return not isinstance(value, (types.FunctionType, types.MethodType, types.BuiltinFunctionType,
  402. functools.partial, type)) and type(value).__module__ != "builtins"
  403. async def _on_behalf_of(awaitable: Any, origin: Optional[int]) -> Any:
  404. bind_serving_request(origin) # this task's context only; tasks it spawns inherit it
  405. return await awaitable
  406. def _import_plugin(params: dict[str, Any]) -> Any:
  407. """Import a directory plugin under the module name Hermes assigned, or resolve an entry point."""
  408. if params.get("entrypoint"):
  409. for ep in importlib.metadata.entry_points().select(group=_ENTRY_POINTS_GROUP):
  410. if ep.name == params.get("name"):
  411. return ep.load()
  412. raise ImportError(f"Entry point '{params.get('name')}' not found in group '{_ENTRY_POINTS_GROUP}'")
  413. plugin_dir = Path(str(params["path"]))
  414. init_file = plugin_dir / "__init__.py"
  415. if not init_file.exists():
  416. raise FileNotFoundError(f"No __init__.py in {plugin_dir}")
  417. module_name = str(params["module_name"])
  418. parts = module_name.split(".")[:-1]
  419. for i in range(1, len(parts) + 1): # synthetic parent packages (hermes_plugins, _hermes_user_memory)
  420. parent = ".".join(parts[:i])
  421. if parent not in sys.modules:
  422. ns_pkg = types.ModuleType(parent)
  423. ns_pkg.__path__ = [] # type: ignore[attr-defined]
  424. ns_pkg.__package__ = parent
  425. sys.modules[parent] = ns_pkg
  426. spec = importlib.util.spec_from_file_location(module_name, init_file,
  427. submodule_search_locations=[str(plugin_dir)])
  428. if spec is None or spec.loader is None:
  429. raise ImportError(f"Cannot create module spec for {init_file}")
  430. module = importlib.util.module_from_spec(spec)
  431. module.__package__ = module_name
  432. module.__path__ = [str(plugin_dir)] # type: ignore[attr-defined]
  433. sys.modules[module_name] = module
  434. try:
  435. spec.loader.exec_module(module)
  436. except BaseException:
  437. for name in [m for m in sys.modules if m == module_name or m.startswith(module_name + ".")]:
  438. sys.modules.pop(name, None)
  439. raise
  440. return module
  441. def _take_protocol_streams():
  442. """Duplicate stdin/stdout for the channel, then point fd 0 at /dev/null and fd 1 at stderr."""
  443. reader = os.fdopen(os.dup(0), "rb") # windows-footgun: ok — binary protocol stream
  444. writer = os.fdopen(os.dup(1), "wb") # windows-footgun: ok — binary protocol stream
  445. devnull = os.open(os.devnull, os.O_RDONLY)
  446. os.dup2(devnull, 0)
  447. os.close(devnull)
  448. os.dup2(2, 1)
  449. sys.stdin = open(os.devnull, encoding="utf-8-sig")
  450. sys.stdout = sys.stderr
  451. return reader, writer
  452. def capture_profiles(path: str, module_name: str) -> list[Any]:
  453. """Import a model-provider plugin and return the profiles it passes to ``register_provider``."""
  454. import providers
  455. providers.list_providers() # bundled + known profiles register before the capture window
  456. captured: list[Any] = []
  457. original = providers.register_provider
  458. providers.register_provider = captured.append # type: ignore[assignment]
  459. try:
  460. _import_plugin({"path": path, "module_name": module_name, "name": Path(path).name})
  461. finally:
  462. providers.register_provider = original # type: ignore[assignment]
  463. return captured
  464. def _host_unsupported_reason(profile: Any) -> str | None:
  465. """Why *profile* cannot run behind the plugin host (it then loads in-process), or None."""
  466. from providers.base import ProviderProfile
  467. if type(profile).create_client is not ProviderProfile.create_client:
  468. return "it overrides create_client(), which returns a live SDK client"
  469. return None
  470. def _extraction_entry(profile: Any) -> dict[str, Any]:
  471. reason = _host_unsupported_reason(profile)
  472. if reason is not None:
  473. return {"name": profile.name, "in_process": reason}
  474. return describe_profile(profile)
  475. def describe_profile(profile: Any) -> dict[str, Any]:
  476. """Profile data (instance fields) plus the methods and callable fields that must run here."""
  477. from providers.base import ProviderProfile
  478. fields: dict[str, Any] = {}
  479. calls: dict[str, Any] = {}
  480. for name, value in vars(profile).items():
  481. if name.startswith("_"):
  482. continue
  483. if callable(value):
  484. calls[name] = {"async": is_async_callable(value), "sig": describe_signature(value), "field": True}
  485. else:
  486. fields[name] = encode(value)
  487. for name in dir(type(profile)):
  488. if name.startswith("_") or name in fields or name in calls:
  489. continue
  490. attr = getattr(type(profile), name)
  491. if attr is getattr(ProviderProfile, name, object()):
  492. continue
  493. if isinstance(inspect.getattr_static(profile, name), property) or not callable(attr):
  494. fields[name] = encode(getattr(profile, name))
  495. continue
  496. calls[name] = {"async": is_async_callable(attr), "sig": describe_signature(getattr(profile, name)),
  497. "field": False}
  498. return {"name": profile.name, "type": type(profile).__name__, "fields": fields, "calls": calls}
  499. def extract_profiles_main(path: str, module_name: str) -> int:
  500. """``--extract-profiles``: one-shot, credential-free; prints the profiles as JSON on stdout."""
  501. import json
  502. reader, writer = _take_protocol_streams()
  503. del reader
  504. import hermes_bootstrap
  505. try:
  506. payload = {"profiles": [_extraction_entry(p) for p in capture_profiles(path, module_name)]}
  507. except Exception as exc:
  508. payload = {"error": f"{type(exc).__name__}: {exc}"}
  509. writer.write(json.dumps(payload).encode("utf-8"))
  510. writer.flush()
  511. return 0
  512. def main() -> int:
  513. reader, writer = _take_protocol_streams()
  514. import hermes_bootstrap
  515. logging.basicConfig(stream=sys.stderr, level=os.environ.get("HERMES_PLUGIN_HOST_LOG_LEVEL", "WARNING"),
  516. format="%(levelname)s %(name)s: %(message)s")
  517. runtime = HostRuntime(reader, writer)
  518. runtime.channel.start()
  519. runtime.stopped.wait()
  520. runtime.channel.close("host shutdown")
  521. return 0
  522. if __name__ == "__main__":
  523. code = (extract_profiles_main(sys.argv[2], sys.argv[3]) if sys.argv[1:2] == ["--extract-profiles"]
  524. else main())
  525. sys.stderr.flush()
  526. # A plugin thread stuck in a handler must not keep the host alive once Hermes has gone.
  527. os._exit(code)