relay_runtime.py 64 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440
  1. """Profile-scoped NeMo Relay runtimes owned by the Hermes agent core."""
  2. from __future__ import annotations
  3. import atexit
  4. import asyncio
  5. import contextlib
  6. import contextvars
  7. import functools
  8. import importlib
  9. import inspect
  10. import logging
  11. import os
  12. import threading
  13. import tomllib
  14. import uuid
  15. from concurrent.futures import TimeoutError as FuturesTimeoutError
  16. from dataclasses import dataclass, field
  17. from enum import Enum
  18. from pathlib import Path
  19. from typing import Any, Callable
  20. from hermes_constants import get_hermes_home
  21. from hermes_cli.relay_plugin_cutover import (RELAY_PLUGINS_CONFIG_ENV, configured_legacy_relay_env_vars)
  22. logger = logging.getLogger(__name__)
  23. SESSION_SCOPE = "hermes.session"
  24. TURN_SCOPE = "hermes.turn"
  25. LOGICAL_LLM_SCOPE = "hermes.logical_llm_call"
  26. RUNTIME_SCHEMA_KEY = "hermes.relay.schema_version"
  27. RUNTIME_SCHEMA_VERSION = "hermes.relay.runtime.v1"
  28. RUNTIME_INSTANCE_KEY = "hermes.relay.runtime_instance"
  29. RELAY_PLUGINS_EXECUTION_CONSUMER = "hermes.nemo_relay.plugins"
  30. _PROFILE_KEY_CACHE: dict[str, str] = {}
  31. # Bound for native scope ops gating turn/session completion: a wedged pipeline costs one
  32. # lost span, never a blocked agent.
  33. SCOPE_OP_TIMEOUT = 10.0
  34. class _Lazy:
  35. """Double-checked, thread-safe once-only factory; ``reset()`` re-arms it (tests)."""
  36. def __init__(self, factory: Callable[[], Any]) -> None:
  37. self._factory, self._value, self._lock = factory, None, threading.Lock()
  38. def get(self) -> Any:
  39. if self._value is None:
  40. with self._lock:
  41. if self._value is None:
  42. self._value = self._factory()
  43. return self._value
  44. def reset(self) -> None:
  45. self._value = None
  46. def _new_scope_op_executor() -> Any:
  47. # Daemon workers: a wedged call abandoned at timeout cannot block interpreter exit;
  48. # ``Future.result(timeout=...)`` still bounds callers when every worker is wedged.
  49. from tools.daemon_pool import DaemonThreadPoolExecutor
  50. return DaemonThreadPoolExecutor(max_workers=8, thread_name_prefix="relay-scope-op")
  51. _SCOPE_OP_EXECUTOR = _Lazy(_new_scope_op_executor)
  52. _scope_op_executor = _SCOPE_OP_EXECUTOR.get
  53. def runtime_metadata(runtime_id: str, **extra: Any) -> dict[str, Any]:
  54. """Return the scope metadata that stamps every Hermes-owned Relay scope."""
  55. return {RUNTIME_SCHEMA_KEY: RUNTIME_SCHEMA_VERSION, RUNTIME_INSTANCE_KEY: runtime_id, **extra}
  56. def _scope_input(cwd: Any = None) -> dict[str, str]:
  57. """Return Relay scope input for a known logical working directory."""
  58. return {"cwd": cwd.strip()} if isinstance(cwd, str) and cwd.strip() else {}
  59. def _run_on_daemon_thread(
  60. fn: Callable[[], Any], *, name: str, timeout: float | None = None, timeout_message: str = ""
  61. ) -> Any:
  62. """Run ``fn`` on a fresh daemon thread; re-raise its error or return its result.
  63. With ``timeout`` a still-running worker is abandoned with ``TimeoutError`` (daemon: cannot block exit)."""
  64. outcome: dict[str, Any] = {}
  65. def _target() -> None:
  66. try:
  67. outcome["result"] = fn()
  68. except BaseException as exc:
  69. outcome["error"] = exc
  70. worker = threading.Thread(target=_target, daemon=True, name=name)
  71. worker.start()
  72. worker.join(timeout)
  73. if worker.is_alive():
  74. raise TimeoutError(timeout_message)
  75. if "error" in outcome:
  76. raise outcome["error"]
  77. return outcome.get("result")
  78. def pop_relay_scope(relay: Any, handle: Any, *, output: Any = None, metadata: Any = None, timestamp: Any = None) -> Any:
  79. """Pop a Relay scope, forwarding only the kwargs the live binding accepts.
  80. ``scope.pop`` gained ``metadata`` in nemo-relay 0.4+; older wheels raise TypeError."""
  81. pop = relay.scope.pop
  82. kwargs = {k: v for k, v in (("output", output), ("metadata", metadata), ("timestamp", timestamp)) if v is not None}
  83. try:
  84. params = inspect.signature(pop).parameters
  85. except (TypeError, ValueError):
  86. params = {}
  87. if params and not any(param.kind == inspect.Parameter.VAR_KEYWORD for param in params.values()):
  88. kwargs = {key: value for key, value in kwargs.items() if key in params}
  89. return pop(handle, **kwargs)
  90. def pop_relay_scope_if_top(relay: Any, handle: Any, *, output: Any = None, metadata: Any = None) -> bool:
  91. """Pop ``handle`` only while it is the top of the scope stack; return whether it was popped.
  92. Two concurrent Hermes turns in one session share a physical stack, so the first turn to
  93. finish may find the sibling's live scope above its own. Popping through it would close the
  94. sibling's scope and letting the binding raise ("scope handle is not at the top of the
  95. stack") logs a traceback per overlap (#115471). The skipped scope is reclaimed by the
  96. session-close drain in ``_close_scope_handle``.
  97. """
  98. top = _current_top(relay)
  99. if top is not None and not _same_handle(top, handle):
  100. return False
  101. pop_relay_scope(relay, handle, output=output, metadata=metadata)
  102. return True
  103. def _current_top(relay: Any) -> Any:
  104. """Return the current top-of-stack scope handle, or None."""
  105. # Prefer scope.get_handle(): get_scope_stack() may return a native ScopeStack that scope.pop rejects.
  106. get_handle = getattr(getattr(relay, "scope", None), "get_handle", None)
  107. if callable(get_handle):
  108. with contextlib.suppress(Exception):
  109. return get_handle()
  110. top = relay.get_scope_stack()
  111. # Some builds return the live stack (list), others the top handle: only unwrap real lists.
  112. return (top[-1] if top else None) if isinstance(top, list) else top
  113. def _same_handle(a: Any, b: Any) -> bool:
  114. # Native ScopeHandle has no value __eq__; compare by uuid when both expose one.
  115. if a is None or b is None:
  116. return a is b
  117. a_uuid = getattr(a, "uuid", None)
  118. return a is b or a == b or (a_uuid is not None and a_uuid == getattr(b, "uuid", None))
  119. # Process-wide plugin-configuration result shared by every currently hosted profile.
  120. _RelayPluginConfigurationState = Enum(
  121. "_RelayPluginConfigurationState", "UNINITIALIZED DISABLED ACTIVE FOREIGN FAILED"
  122. )
  123. class _RelayPluginConfigurationLoadError(RuntimeError):
  124. """An explicitly selected Relay plugin configuration could not be loaded."""
  125. def _activation_requires_managed_execution(activation: Any) -> bool:
  126. """Return whether Relay activated any static or dynamic plugin behavior."""
  127. try:
  128. report = getattr(activation, "report", None)
  129. except Exception:
  130. report = None
  131. return _report_requires_managed_execution(report)
  132. def _activation_config_paths(activation: Any) -> list[str]:
  133. """Return the plugins.toml files an activation loaded, lowest precedence first."""
  134. try:
  135. paths = getattr(activation, "report", {}).get("config_paths")
  136. except Exception:
  137. return []
  138. return [str(path) for path in paths] if isinstance(paths, list) else []
  139. def _report_requires_managed_execution(report: Any) -> bool:
  140. """Return whether a Relay plugin-host report enables any static or dynamic plugin.
  141. Relay owns the report contract. An unfamiliar report stays fail-safe by
  142. retaining Hermes managed execution instead of silently bypassing plugins.
  143. """
  144. def keep_enabled() -> bool:
  145. logger.warning(
  146. "Hermes could not determine whether the Relay plugin configuration is empty; keeping managed "
  147. "execution enabled"
  148. )
  149. return True
  150. if not isinstance(report, dict):
  151. return keep_enabled()
  152. resolved = report.get("resolved_config")
  153. dynamic_plugins = report.get("dynamic_plugins")
  154. if not isinstance(resolved, dict) or not isinstance(dynamic_plugins, list):
  155. return keep_enabled()
  156. components = resolved.get("components")
  157. if not isinstance(components, list):
  158. return keep_enabled()
  159. for component in components:
  160. if not isinstance(component, dict):
  161. return keep_enabled()
  162. enabled = component.get("enabled")
  163. if not isinstance(enabled, bool):
  164. return keep_enabled()
  165. if enabled:
  166. return True
  167. for plugin in dynamic_plugins:
  168. if not isinstance(plugin, dict) or "selected" not in plugin:
  169. return keep_enabled()
  170. selected = plugin["selected"]
  171. if not isinstance(selected, bool):
  172. return keep_enabled()
  173. if selected:
  174. return True
  175. return False
  176. @dataclass
  177. class RelaySession:
  178. """One isolated Relay scope stack owned by a Hermes session."""
  179. session_id: str
  180. parent_session_id: str = ""
  181. lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
  182. closing: bool = False
  183. handle: Any = None
  184. context: contextvars.Context | None = None
  185. # Segmentation: rotation closes the session scope and pushes segment N+1 at a turn
  186. # boundary (the only LIFO-safe point). Flags are set by compaction, consumed at that boundary.
  187. segment: int = 0 # index of the CURRENT session scope (0 = first)
  188. segment_turns: int = 0 # turns completed within the current segment
  189. rotate_pending: bool = False # consumed at next begin_turn
  190. close_pending: bool = False # rotating compaction hit a live turn; end_turn consumes it
  191. cwd: str = "" # latest logical working directory; reused when a session segment rotates
  192. def _load_segments_config() -> dict[str, Any]:
  193. """gateway.telemetry.session_segments; both defaults OFF => rotation never fires."""
  194. on_compaction = False
  195. max_turns = 0
  196. try:
  197. # Never import gateway.run here: its import-time env setup (_HERMES_GATEWAY, HERMES_QUIET,
  198. # TERMINAL_CWD := home) rebinds a CLI/TUI/cron host — hung approvals (#87183), `hermes -z`
  199. # running in $HOME without the launch dir's AGENTS.md (#95577). Same reader it delegates to.
  200. from hermes_cli.config_effective import load_user_config_effective
  201. telemetry = (load_user_config_effective().get("gateway") or {}).get("telemetry") or {}
  202. segments = telemetry.get("session_segments") or {}
  203. on_compaction = bool(segments.get("on_compaction", False))
  204. try:
  205. max_turns = max(0, int(segments.get("max_turns", 0) or 0))
  206. except (TypeError, ValueError):
  207. max_turns = 0
  208. except Exception:
  209. pass
  210. return {"on_compaction": on_compaction, "max_turns": max_turns}
  211. _SEGMENTS_CONFIG = _Lazy(_load_segments_config) # cached at first read
  212. _segments_config = _SEGMENTS_CONFIG.get
  213. _reset_segments_config_for_tests = _SEGMENTS_CONFIG.reset
  214. class RelayOperationLease:
  215. """Keep process-wide Relay plugins alive across a deferred operation."""
  216. def __init__(self, runtime: RelayRuntime) -> None:
  217. self._lock, self._runtime = threading.Lock(), runtime
  218. def run_in_session(self, session: RelaySession, callback: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
  219. """Run cleanup while this lease still owns the runtime lifetime."""
  220. with self._lock:
  221. if self._runtime is None:
  222. raise RuntimeError("Hermes Relay operation lease is released")
  223. return self._runtime._run_in_session_untracked(session, callback, *args, **kwargs)
  224. def release(self) -> None:
  225. """Release this lease exactly once."""
  226. with self._lock:
  227. runtime, self._runtime = self._runtime, None
  228. if runtime is not None:
  229. runtime._end_operation()
  230. class _ProcessRelayPluginConfiguration:
  231. """Own one Relay plugin configuration across profile-scoped hosts."""
  232. def __init__(self) -> None:
  233. self._lock = threading.RLock()
  234. self._owners: set[int] = set()
  235. self._state = _RelayPluginConfigurationState.UNINITIALIZED
  236. self._relay: Any = None # set while a Hermes-owned configuration is active
  237. self._activation: Any = None
  238. def acquire(self, owner: Any, relay: Any) -> _RelayPluginConfigurationState:
  239. """Join the process configuration, initializing it for the first host."""
  240. with self._lock:
  241. if not self._owners:
  242. # First host decides for the whole process; later hosts just join.
  243. self._state = self._preflight(relay) or self._activate(relay)
  244. if self._state is _RelayPluginConfigurationState.ACTIVE:
  245. logger.info(
  246. "The Relay plugin host is active process-wide and applies to all profiles hosted by this "
  247. "Hermes process. Configuration files: %s",
  248. "; ".join(_activation_config_paths(self._activation)) or "none reported",
  249. )
  250. self._owners.add(id(owner))
  251. return self._state
  252. def _activate(self, relay: Any) -> _RelayPluginConfigurationState:
  253. try:
  254. if not self._initialize(relay):
  255. return _RelayPluginConfigurationState.DISABLED
  256. except Exception as exc:
  257. self._activation = None
  258. if _is_relay_host_conflict(exc):
  259. logger.warning(
  260. "A process-global Relay plugin configuration is already active outside Hermes native "
  261. "ownership; leaving it unchanged and disabling Hermes-managed Relay middleware for this process"
  262. )
  263. return _RelayPluginConfigurationState.FOREIGN
  264. logger.warning("Hermes Relay plugin initialization failed: %s", exc, exc_info=True)
  265. return _RelayPluginConfigurationState.FAILED
  266. self._relay = relay
  267. return _RelayPluginConfigurationState.ACTIVE
  268. def _preflight(self, relay: Any) -> _RelayPluginConfigurationState | None:
  269. """Return a terminal state when the process cannot take ownership; None to proceed."""
  270. if self._relay is not None and not self._clear_active():
  271. logger.warning(
  272. "Hermes Relay plugin cleanup is still pending; refusing to replace the process-global configuration"
  273. )
  274. return _RelayPluginConfigurationState.FAILED
  275. return None
  276. def _initialize(self, relay: Any) -> bool:
  277. """Initialize Relay and report whether the resolved configuration needs managed execution."""
  278. config_path = _configured_plugin_inputs()
  279. # An explicit file replaces Relay's user file; its system file always remains above either source.
  280. activation = _resolve_plugin_awaitable(relay.plugin.initialize({}, additional_plugins_toml=config_path))
  281. if activation is None:
  282. raise RuntimeError("NeMo Relay plugin initialization returned no activation handle")
  283. self._activation = activation
  284. self._relay = relay
  285. return _activation_requires_managed_execution(activation)
  286. def release(self, owner: Any) -> None:
  287. """Release one host and clear Relay after the final host exits."""
  288. with self._lock:
  289. if id(owner) in self._owners:
  290. self._owners.remove(id(owner))
  291. self.retry_pending_cleanup()
  292. def reset_for_tests(self) -> None:
  293. """Clear process-global state left by directly constructed test hosts."""
  294. with self._lock:
  295. self._owners.clear()
  296. self.retry_pending_cleanup()
  297. def retry_pending_cleanup(self) -> None:
  298. """Retry a failed final cleanup without disrupting live owners."""
  299. with self._lock:
  300. if not self._owners and self._clear_active():
  301. self._state = _RelayPluginConfigurationState.UNINITIALIZED
  302. def _clear_active(self) -> bool:
  303. relay, activation = self._relay, self._activation
  304. if relay is None:
  305. return True
  306. def close_configuration() -> Any:
  307. if callable(close := getattr(activation, "close", None)):
  308. return _resolve_plugin_awaitable(close())
  309. raise RuntimeError("NeMo Relay plugin activation has no close method")
  310. for what, step in (
  311. ("subscriber flush", lambda: _resolve_plugin_awaitable(relay.subscribers.flush_async())),
  312. ("configuration cleanup", close_configuration),
  313. ):
  314. try:
  315. step()
  316. except Exception:
  317. logger.warning("Hermes Relay plugin %s failed", what, exc_info=True)
  318. return False
  319. self._relay = self._activation = None
  320. return True
  321. _PLUGIN_CONFIGURATION = _ProcessRelayPluginConfiguration()
  322. atexit.register(_PLUGIN_CONFIGURATION.retry_pending_cleanup)
  323. class RelayRuntime:
  324. """Own Relay session scopes and the process plugin configuration."""
  325. def __init__(self, relay: Any = None, *, profile_key: str | None = None) -> None:
  326. self.relay = relay or _load_nemo_relay()
  327. self.profile_key = profile_key or current_profile_key()
  328. self.runtime_id = uuid.uuid4().hex
  329. self._sessions_lock, self._execution_consumers_lock = threading.RLock(), threading.RLock()
  330. self._sessions: dict[str, RelaySession] = {}
  331. self._subagent_parents: dict[str, str] = {}
  332. self._subagent_parent_handles: dict[str, Any] = {}
  333. self._execution_consumers: set[str] = set()
  334. # Outputs of scopes that finished under a concurrent scope (pop_relay_scope_if_top said no),
  335. # keyed by handle uuid: the drain that later reclaims the scope closes it with this output.
  336. self._deferred_scope_outputs: dict[str, dict[str, Any]] = {}
  337. self._deferred_scope_outputs_lock = threading.Lock()
  338. self._closing = self._shutdown_started = False
  339. self._shutdown_complete, self._operations_idle = threading.Event(), threading.Event()
  340. self._operations_idle.set()
  341. self._active_operations = 0
  342. self._plugin_configuration_state = _PLUGIN_CONFIGURATION.acquire(self, self.relay)
  343. # Cleared (with the atexit hook) by the first successful _finish_shutdown.
  344. self._plugin_configuration_registered = True
  345. if self._plugins_active():
  346. self.retain_managed_execution(RELAY_PLUGINS_EXECUTION_CONSUMER)
  347. atexit.register(self.shutdown)
  348. def _plugins_active(self) -> bool:
  349. return self._plugin_configuration_state is _RelayPluginConfigurationState.ACTIVE
  350. def defer_scope_output(self, handle: Any, output: dict[str, Any]) -> None:
  351. """Keep the real output of a finished scope that could not be popped yet because a
  352. concurrent scope sits above it; the orphan drain closes it with this instead."""
  353. key = getattr(handle, "uuid", None)
  354. if key is not None:
  355. with self._deferred_scope_outputs_lock:
  356. self._deferred_scope_outputs[str(key)] = output
  357. def _take_deferred_scope_output(self, handle: Any) -> dict[str, Any] | None:
  358. key = getattr(handle, "uuid", None)
  359. if key is None:
  360. return None
  361. with self._deferred_scope_outputs_lock:
  362. return self._deferred_scope_outputs.pop(str(key), None)
  363. def retain_managed_execution(self, consumer: str) -> None:
  364. """Keep managed LLM and tool execution active for one consumer."""
  365. if not consumer:
  366. raise ValueError("Relay managed-execution consumer must not be empty")
  367. with self._execution_consumers_lock:
  368. self._execution_consumers.add(consumer)
  369. def release_managed_execution(self, consumer: str) -> None:
  370. """Release a consumer's managed-execution requirement."""
  371. with self._execution_consumers_lock:
  372. self._execution_consumers.discard(consumer)
  373. def managed_execution_enabled(self) -> bool:
  374. """Return whether a Hermes-managed consumer needs the Relay pipeline."""
  375. with self._execution_consumers_lock:
  376. return bool(self._execution_consumers)
  377. def _open_session_scope(
  378. self, session: RelaySession, scope_metadata: dict[str, Any], *, resolve_parent: bool,
  379. exit_fallback: bool = False, **push_kwargs: Any,
  380. ) -> None:
  381. """Push a fresh SESSION_SCOPE for ``session`` (bounded by ``SCOPE_OP_TIMEOUT``); record handle + context.
  382. Subagents parent under their spawning turn/session handle (``resolve_parent`` creates the parent when
  383. unknown). ``exit_fallback``: at interpreter shutdown the executor refuses futures; push synchronously."""
  384. parent_handle = None
  385. if session.parent_session_id:
  386. with self._sessions_lock:
  387. parent_handle = self._subagent_parent_handles.get(session.session_id)
  388. if parent_handle is None and resolve_parent:
  389. parent = self.ensure_session({"session_id": session.parent_session_id})
  390. if parent is not None:
  391. parent_handle = parent.handle
  392. scope_metadata["nemo_relay_scope_role"] = "subagent"
  393. context = contextvars.Context()
  394. args = (self.relay.scope.push, SESSION_SCOPE, self.relay.ScopeType.Agent)
  395. push_kwargs.update(handle=parent_handle, metadata=scope_metadata, input=_scope_input(session.cwd))
  396. try:
  397. future = _scope_op_executor().submit(context.run, *args, **push_kwargs)
  398. except RuntimeError:
  399. if not exit_fallback:
  400. raise
  401. session.handle = context.run(*args, **push_kwargs)
  402. else:
  403. # future.result() re-raises push's own RuntimeError; keeping it outside the
  404. # except prevents a real push failure from retrying via the exit fallback.
  405. session.handle = future.result(timeout=SCOPE_OP_TIMEOUT)
  406. session.context = context
  407. def ensure_session(
  408. self,
  409. event: dict[str, Any],
  410. *,
  411. data: Any = None,
  412. metadata: dict[str, Any] | None = None,
  413. cwd: str | None = None,
  414. ) -> RelaySession | None:
  415. """Return the existing session scope or create it once."""
  416. session_id = _session_id(event)
  417. if not session_id:
  418. return None
  419. with self._sessions_lock:
  420. if self._closing:
  421. return None
  422. session = self._sessions.get(session_id)
  423. if session is None:
  424. session = self._sessions[session_id] = RelaySession(
  425. session_id=session_id, parent_session_id=self._subagent_parents.get(session_id, "")
  426. )
  427. with session.lock:
  428. if session.closing:
  429. return None
  430. if cwd is not None:
  431. session.cwd = _scope_input(cwd).get("cwd", "")
  432. if session.handle is None:
  433. self._open_session_scope(
  434. session, {**(metadata or {}), **runtime_metadata(self.runtime_id)},
  435. resolve_parent=True, data=data, exit_fallback=True,
  436. )
  437. return session
  438. def rotate_session_scope(self, session: RelaySession, *, reason: str) -> None:
  439. """Close the current session scope and open the next segment (turn boundary ONLY: LIFO).
  440. Bookkeeping advances even when a native call fails so a degraded rotation cannot retry every turn."""
  441. with session.lock:
  442. if session.closing or session.handle is None:
  443. return
  444. old_handle = session.handle
  445. # Bookkeeping FIRST: a failed native call must not leave rotate_pending set.
  446. session.segment += 1
  447. session.segment_turns = 0
  448. session.rotate_pending = False
  449. try:
  450. self.run_in_session(
  451. session, self.relay.scope.pop, old_handle, output={"hermes.session.segment_reason": reason},
  452. metadata=runtime_metadata(self.runtime_id), timeout=SCOPE_OP_TIMEOUT,
  453. )
  454. except Exception:
  455. logger.warning(
  456. "Hermes Relay segment close failed (session=%s segment=%d); abandoning the old segment span",
  457. session.session_id, session.segment - 1, exc_info=True,
  458. )
  459. scope_metadata = runtime_metadata(
  460. self.runtime_id, **{"hermes.session.segment": session.segment, "hermes.session.segment_reason": reason},
  461. )
  462. try:
  463. self._open_session_scope(session, scope_metadata, resolve_parent=False)
  464. except Exception:
  465. logger.warning(
  466. "Hermes Relay segment open failed (session=%s segment=%d); keeping the prior scope handle",
  467. session.session_id, session.segment, exc_info=True,
  468. )
  469. def register_subagent(
  470. self, event: dict[str, Any], *, metadata: dict[str, Any] | None = None,
  471. cwd: str | None = None,
  472. ) -> RelaySession | None:
  473. """Open a child Agent scope under its spawning turn when available."""
  474. parent_session_id = str(event.get("parent_session_id") or "")
  475. child_session_id = str(event.get("child_session_id") or "")
  476. if not parent_session_id or not child_session_id or parent_session_id == child_session_id:
  477. return None
  478. parent = self.ensure_session({"session_id": parent_session_id})
  479. parent_handle = None if parent is None else parent.handle
  480. turn = active_turn(parent_session_id) # already proved liveness and (RelayRuntime host) an open session
  481. if turn is not None and turn.handle is not None and turn.lease.host is self:
  482. parent_handle = turn.handle
  483. with self._sessions_lock:
  484. if self._closing:
  485. return None
  486. self._subagent_parents[child_session_id] = parent_session_id
  487. if parent_handle is not None:
  488. self._subagent_parent_handles[child_session_id] = parent_handle
  489. return self.ensure_session({"session_id": child_session_id}, metadata=metadata, cwd=cwd)
  490. def unregister_subagent(self, event: dict[str, Any]) -> None:
  491. """Close a delegated session and forget its parent relationship."""
  492. child_session_id = str(event.get("child_session_id") or "")
  493. if child_session_id:
  494. self.close_session({"session_id": child_session_id})
  495. self._forget_subagent(child_session_id)
  496. def _forget_subagent(self, session_id: str) -> None:
  497. with self._sessions_lock:
  498. self._subagent_parents.pop(session_id, None)
  499. self._subagent_parent_handles.pop(session_id, None)
  500. def _lookup(self, session_id: str) -> RelaySession | None:
  501. """Registry lookup (closing sessions included) without creating one."""
  502. with self._sessions_lock:
  503. return self._sessions.get(session_id)
  504. def get_session(self, session_id: str) -> RelaySession | None:
  505. """Return an active Hermes Relay session without creating one."""
  506. with self._sessions_lock:
  507. session = None if self._closing else self._sessions.get(str(session_id or ""))
  508. if session is None:
  509. return None
  510. with session.lock:
  511. return None if session.closing else session
  512. def _session_context(self, session: RelaySession, *, allow_closing: bool) -> contextvars.Context:
  513. """Copy the current context and overlay the session's saved Relay vars (a copy: re-entrant from callbacks)."""
  514. with session.lock:
  515. if session.closing and not allow_closing:
  516. raise RuntimeError("Hermes Relay session is closing")
  517. if session.context is None or session.handle is None:
  518. raise RuntimeError("Hermes Relay session context is unavailable")
  519. relay_context = session.context.copy()
  520. context = contextvars.copy_context()
  521. for variable, value in relay_context.items():
  522. context.run(variable.set, value)
  523. return context
  524. def run_in_session(
  525. self, session: RelaySession, callback: Callable[..., Any], *args: Any,
  526. allow_closing: bool = False, timeout: float | None = None, **kwargs: Any,
  527. ) -> Any:
  528. """Run a Relay operation against a session's isolated scope stack.
  529. ``timeout`` bounds the native call on the daemon executor (``TimeoutError`` on breach); ``None``
  530. runs synchronously. Lifecycle ops pass ``SCOPE_OP_TIMEOUT``: a wedged pipeline costs one span."""
  531. with self._operation():
  532. return self._run_in_session_untracked(
  533. session, callback, *args, allow_closing=allow_closing, timeout=timeout, **kwargs
  534. )
  535. def _run_in_session_untracked(
  536. self, session: RelaySession, callback: Callable[..., Any], *args: Any,
  537. allow_closing: bool = False, timeout: float | None = None, **kwargs: Any,
  538. ) -> Any:
  539. """Run inside a session whose host-level lifetime is already held."""
  540. context = self._session_context(session, allow_closing=allow_closing)
  541. def invoke() -> Any:
  542. self.relay.get_scope_stack()
  543. return callback(*args, **kwargs)
  544. if timeout is None:
  545. return context.run(invoke)
  546. exceeded = f"Relay scope operation exceeded {timeout}s"
  547. try:
  548. future = _scope_op_executor().submit(context.run, invoke)
  549. except RuntimeError:
  550. # Interpreter shutdown: the executor refuses futures but the atexit close path must
  551. # still flush — still bounded so a wedged call cannot block exit.
  552. return _run_on_daemon_thread(
  553. lambda: context.run(invoke), name="relay-scope-op-exit", timeout=timeout,
  554. timeout_message=f"{exceeded} during interpreter shutdown; abandoning the native "
  555. "call so process exit can proceed",
  556. )
  557. try:
  558. return future.result(timeout=timeout)
  559. except FuturesTimeoutError as exc:
  560. raise TimeoutError(
  561. f"{exceeded} (session={session.session_id}); abandoning the native call "
  562. "so the agent can continue — the span for this scope is lost"
  563. ) from exc
  564. async def run_in_session_async(
  565. self, session: RelaySession, callback: Callable[..., Any], *args: Any,
  566. allow_closing: bool = False, **kwargs: Any,
  567. ) -> Any:
  568. """Create and await an operation inside the session's saved context."""
  569. with self._operation():
  570. context = self._session_context(session, allow_closing=allow_closing)
  571. async def invoke() -> Any:
  572. self.relay.get_scope_stack()
  573. result = callback(*args, **kwargs)
  574. return await result if inspect.isawaitable(result) else result
  575. return await context.run(asyncio.create_task, invoke())
  576. def _begin_operation(self) -> None:
  577. """Admit one Relay call while keeping process plugins alive."""
  578. with self._sessions_lock:
  579. if self._closing:
  580. raise RuntimeError("Hermes Relay runtime is shutting down")
  581. self._active_operations += 1
  582. self._operations_idle.clear()
  583. def _end_operation(self) -> None:
  584. with self._sessions_lock:
  585. self._active_operations -= 1
  586. if self._active_operations == 0:
  587. self._operations_idle.set()
  588. @contextlib.contextmanager
  589. def _operation(self):
  590. """``_begin_operation`` / ``_end_operation`` around one tracked Relay call."""
  591. self._begin_operation()
  592. try:
  593. yield
  594. finally:
  595. self._end_operation()
  596. def acquire_operation_lease(self) -> RelayOperationLease:
  597. """Retain plugin lifetime for work that outlives one Relay await."""
  598. self._begin_operation()
  599. return RelayOperationLease(self)
  600. def apply_tool_request_intercepts(self, *, session_id: str, tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
  601. """Apply Relay request rewriting before Hermes authorizes a tool call."""
  602. request_intercepts = getattr(getattr(self.relay, "tools", None), "request_intercepts", None)
  603. managed = self.managed_execution_enabled() and callable(request_intercepts)
  604. session = self.ensure_session({"session_id": session_id}) if managed else None
  605. if session is None:
  606. return args
  607. result = self.run_in_session(session, request_intercepts, tool_name, args)
  608. return result if isinstance(result, dict) else args
  609. def _pop_with_drain(
  610. self, handle: Any, *, output: dict[str, Any], metadata: dict[str, Any], session_root: Any, drain_limit: int,
  611. ) -> BaseException | None:
  612. """Pop ``handle``; if that fails, drain orphans above it and retry once; return the retry's error.
  613. Must run inside ONE ``run_in_session`` callback so ContextVar stack views stay consistent."""
  614. with contextlib.suppress(Exception):
  615. pop_relay_scope(self.relay, handle, output=output, metadata=metadata)
  616. return None
  617. drained = 0
  618. for _ in range(drain_limit):
  619. top = _current_top(self.relay)
  620. if top is None or _same_handle(top, handle):
  621. break
  622. # Never pop the session root while draining for a nested handle.
  623. if session_root is not None and _same_handle(top, session_root) and handle is not session_root:
  624. break
  625. try:
  626. orphan_output = self._take_deferred_scope_output(top) or {
  627. "outcome": "cancelled", "hermes.orphan_drain": True,
  628. }
  629. pop_relay_scope(self.relay, top, output=orphan_output, metadata=metadata)
  630. drained += 1
  631. except Exception:
  632. logger.warning("Hermes Relay orphaned scope drain failed", exc_info=True)
  633. break
  634. if drained:
  635. logger.warning("Hermes Relay drained %d orphaned scope(s) before closing %s", drained, handle)
  636. try:
  637. pop_relay_scope(self.relay, handle, output=output, metadata=metadata)
  638. return None
  639. except Exception as retry_exc:
  640. return retry_exc
  641. def _close_scope_handle(
  642. self, session: RelaySession, handle: Any, *, output: dict[str, Any] | None = None, allow_closing: bool = False,
  643. failure_label: str = "scope close failed", drain_limit: int = 32, operation_already_held: bool = False,
  644. ) -> str | None:
  645. """Pop ``handle``, draining orphaned children in the same session context; failure string or None.
  646. Relay scopes are strict LIFO; empty-stream retries + interrupt can abandon a physical LLM scope
  647. above TURN/SESSION. Drain+close is bounded so a wedged pipeline never blocks completion."""
  648. if handle is None:
  649. return None
  650. run_in_session = (self._run_in_session_untracked if operation_already_held else self.run_in_session)
  651. try:
  652. failure = run_in_session(
  653. session, self._pop_with_drain, handle, output=output or {},
  654. metadata=runtime_metadata(self.runtime_id), session_root=session.handle,
  655. drain_limit=drain_limit, allow_closing=allow_closing, timeout=SCOPE_OP_TIMEOUT,
  656. )
  657. except Exception as exc:
  658. failure = exc
  659. return None if failure is None else f"{failure_label}: {failure}"
  660. def close_session(self, event: dict[str, Any]) -> None:
  661. """Close one session scope and remove it from the core registry (no-op once shutting down)."""
  662. with contextlib.suppress(RuntimeError), self._operation(): # _close_session itself never raises
  663. self._close_session(event)
  664. def _close_session(self, event: dict[str, Any]) -> None:
  665. """Close one session already admitted by the host lifecycle gate."""
  666. session_id = _session_id(event)
  667. session = self._lookup(session_id)
  668. if session is None:
  669. self._forget_subagent(session_id)
  670. return
  671. failure = None
  672. with session.lock:
  673. if session.closing:
  674. return
  675. session.closing = True
  676. if session.handle is not None:
  677. failure = self._close_scope_handle(
  678. session, session.handle, output={}, allow_closing=True,
  679. failure_label="session scope close failed", operation_already_held=True,
  680. )
  681. # No subscriber flush here: process-wide, may wait on other sessions and deadlock an asyncio
  682. # loop; final plugin teardown flushes once.
  683. with self._sessions_lock:
  684. if self._sessions.get(session_id) is session:
  685. del self._sessions[session_id]
  686. self._forget_subagent(session_id)
  687. if failure:
  688. logger.warning("Hermes Relay session %s closed with errors: %s", session_id, failure)
  689. def shutdown(self) -> None:
  690. """Close core scopes and release process plugin configuration."""
  691. with self._sessions_lock:
  692. if self._shutdown_started:
  693. return
  694. self._shutdown_started = self._closing = True
  695. has_active_operations = self._active_operations > 0
  696. if not has_active_operations:
  697. self._finish_shutdown()
  698. return
  699. thread = threading.Thread(
  700. target=lambda: (self._operations_idle.wait(), self._finish_shutdown()),
  701. name=f"hermes-nemo-relay-shutdown-{self.runtime_id[:8]}", daemon=True,
  702. )
  703. try:
  704. thread.start()
  705. except Exception:
  706. with self._sessions_lock:
  707. self._shutdown_started = False
  708. logger.warning("Hermes Relay deferred shutdown could not start", exc_info=True)
  709. def _finish_shutdown(self) -> None:
  710. try:
  711. with self._sessions_lock:
  712. session_ids = list(self._sessions)
  713. for session_id in session_ids:
  714. _warn_on_error("runtime operation", self._close_session, {"session_id": session_id})
  715. if self._plugin_configuration_registered:
  716. if self._plugins_active():
  717. self.release_managed_execution(RELAY_PLUGINS_EXECUTION_CONSUMER)
  718. _PLUGIN_CONFIGURATION.release(self)
  719. self._plugin_configuration_registered = False
  720. with contextlib.suppress(Exception):
  721. atexit.unregister(self.shutdown)
  722. except Exception:
  723. with self._sessions_lock:
  724. self._shutdown_started = False
  725. logger.warning("Hermes Relay shutdown failed", exc_info=True)
  726. return
  727. with self._sessions_lock:
  728. self._shutdown_complete.set()
  729. @dataclass(frozen=True)
  730. class NoopRelayRuntime:
  731. """Explicit reduced-capability host for platforms without Relay wheels."""
  732. profile_key: str
  733. reason: str
  734. def apply_tool_request_intercepts(self, *, session_id: str, tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
  735. return args
  736. @staticmethod
  737. def retain_managed_execution(consumer: str) -> None:
  738. pass
  739. release_managed_execution = retain_managed_execution
  740. managed_execution_enabled = staticmethod(lambda: False)
  741. shutdown = staticmethod(lambda: None) # no resources are allocated on unsupported platforms
  742. RelayHost = RelayRuntime | NoopRelayRuntime
  743. class RelayHostRegistry:
  744. """Own exactly one Relay host for each canonical Hermes profile."""
  745. def __init__(self) -> None:
  746. self._lock = threading.RLock()
  747. self._hosts: dict[str, RelayHost] = {}
  748. def for_profile(self, profile_key: str | None = None, *, create: bool = True) -> RelayHost | None:
  749. key = profile_key or current_profile_key()
  750. with self._lock:
  751. host = self._hosts.get(key)
  752. if host is not None or not create:
  753. return host
  754. try:
  755. host = RelayRuntime(profile_key=key)
  756. except Exception as exc:
  757. logger.warning("Hermes Relay runtime initialization failed", exc_info=True)
  758. host = NoopRelayRuntime(profile_key=key, reason=str(exc))
  759. self._hosts[key] = host
  760. return host
  761. def shutdown_all(self) -> None:
  762. with self._lock:
  763. hosts, self._hosts = list(self._hosts.values()), {}
  764. for host in hosts:
  765. host.shutdown()
  766. HOST_REGISTRY = RelayHostRegistry()
  767. @dataclass
  768. class ConversationLease:
  769. """A resumable reference to one profile-scoped conversation scope."""
  770. profile_key: str
  771. session_id: str
  772. platform: str
  773. host: RelayHost
  774. session: RelaySession | None
  775. parent_session_id: str = ""
  776. released: bool = False
  777. turn_cwd: str = ""
  778. def live_runtime(self) -> RelayRuntime | None:
  779. """Return the real Relay host when this lease owns an open session."""
  780. return self.host if isinstance(self.host, RelayRuntime) and self.session is not None else None
  781. @dataclass
  782. class RelayTurnContext:
  783. """Runtime-only context for one Hermes turn or top-level task."""
  784. lease: ConversationLease
  785. turn_id: str
  786. task_id: str
  787. handle: Any = None
  788. logical_llm_calls: dict[str, Any] = field(default_factory=dict, repr=False)
  789. logical_llm_lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
  790. finalize_lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
  791. _previous_turn: RelayTurnContext | None = field(default=None, repr=False)
  792. _active_registered: bool = field(default=False, repr=False)
  793. relay_enabled: bool = True
  794. closed: bool = False
  795. _CURRENT_TURN: contextvars.ContextVar[RelayTurnContext | None] = contextvars.ContextVar(
  796. "hermes_relay_turn", default=None
  797. )
  798. # >0 while the native pipeline is mid-dispatch of a Hermes tool/LLM callback. Nested managed
  799. # execution there is structurally broken (the pipeline binds its Futures to the OUTER call's
  800. # loop, blocked inside the synchronous callback), so resolve_execution_context() bypasses Relay.
  801. # A ContextVar so the marker follows copy_context() into worker threads / per-thread loops.
  802. _MANAGED_CALLBACK_DEPTH: contextvars.ContextVar[int] = contextvars.ContextVar(
  803. "hermes_relay_managed_callback_depth", default=0
  804. )
  805. @contextlib.contextmanager
  806. def managed_callback_guard():
  807. """Mark the current context as inside a managed Relay callback: everything the wrapped ``invoke()``
  808. transitively calls (incl. work forwarded via copy_context()) runs unmanaged."""
  809. token = _MANAGED_CALLBACK_DEPTH.set(_MANAGED_CALLBACK_DEPTH.get() + 1)
  810. try:
  811. yield
  812. finally:
  813. _MANAGED_CALLBACK_DEPTH.reset(token)
  814. def _warn_on_error(what: str, callback: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
  815. """Run fail-open telemetry work: log ``Hermes Relay <what> failed`` and return None on error."""
  816. try:
  817. return callback(*args, **kwargs)
  818. except Exception:
  819. logger.warning("Hermes Relay %s failed", what, exc_info=True)
  820. return None
  821. def _fail_open(what: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
  822. """Decorator form of ``_warn_on_error`` for telemetry hooks that must never block the caller."""
  823. def wrap(fn: Callable[..., Any]) -> Callable[..., Any]:
  824. @functools.wraps(fn)
  825. def guarded(*args: Any, **kwargs: Any) -> Any:
  826. return _warn_on_error(what, fn, *args, **kwargs)
  827. return guarded
  828. return wrap
  829. def _flag_open_session(session: RelaySession, flag: str) -> None:
  830. """Set a pending-rotation/close flag unless the session is already closing."""
  831. with session.lock:
  832. if not session.closing:
  833. setattr(session, flag, True)
  834. class RelaySessionCoordinator:
  835. """Own semantic conversation and turn lifetimes for Hermes core."""
  836. def __init__(self, registry: RelayHostRegistry = HOST_REGISTRY) -> None:
  837. self.registry = registry
  838. self._initializer_lock = threading.RLock()
  839. self._session_initializers: dict[str, Callable[[RelayRuntime, dict[str, Any]], None]] = {}
  840. self._active_turns_lock = threading.RLock()
  841. self._active_turns: dict[tuple[str, str], set[int]] = {}
  842. def register_session_initializer(self, name: str, callback: Callable[[RelayRuntime, dict[str, Any]], None]) -> None:
  843. """Register idempotent profile/session preparation before scope creation."""
  844. with self._initializer_lock:
  845. self._session_initializers[name] = callback
  846. def _prepare_session(self, host: RelayRuntime, context: dict[str, Any]) -> None:
  847. with self._initializer_lock:
  848. initializers = list(self._session_initializers.items())
  849. for name, callback in initializers:
  850. try:
  851. callback(host, context)
  852. except Exception:
  853. logger.warning("Hermes Relay session initializer failed: %s", name, exc_info=True)
  854. def acquire_conversation(
  855. self,
  856. *,
  857. profile_key: str,
  858. session_id: str,
  859. platform: str,
  860. parent_session_id: str = "",
  861. model: str = "",
  862. session_cwd: str | None = None,
  863. turn_cwd: str | None = None,
  864. ) -> ConversationLease:
  865. host = self.registry.for_profile(profile_key) or NoopRelayRuntime(profile_key, "Relay host creation was disabled")
  866. session = None
  867. if isinstance(host, RelayRuntime):
  868. context = {
  869. "profile_key": profile_key, "session_id": session_id, "platform": platform,
  870. "parent_session_id": parent_session_id, "model": model, "cwd": session_cwd,
  871. }
  872. session = _warn_on_error("conversation initialization", self._open_conversation_session, host, context)
  873. if turn_cwd is not None:
  874. effective_turn_cwd = _scope_input(turn_cwd).get("cwd", "")
  875. elif session_cwd is not None:
  876. effective_turn_cwd = _scope_input(session_cwd).get("cwd", "")
  877. elif session is not None:
  878. with session.lock:
  879. effective_turn_cwd = session.cwd
  880. else:
  881. effective_turn_cwd = ""
  882. return ConversationLease(
  883. profile_key=profile_key, session_id=session_id, platform=platform, host=host,
  884. session=session, parent_session_id=parent_session_id, turn_cwd=effective_turn_cwd,
  885. )
  886. def _open_conversation_session(self, host: RelayRuntime, context: dict[str, Any]) -> RelaySession | None:
  887. self._prepare_session(host, context)
  888. session_id, parent_session_id = context["session_id"], context["parent_session_id"]
  889. metadata = {"hermes.execution_surface": context["platform"] or "unknown"}
  890. cwd = context.get("cwd")
  891. if parent_session_id and parent_session_id != session_id:
  892. event = {"parent_session_id": parent_session_id, "child_session_id": session_id}
  893. return host.register_subagent(event, metadata=metadata, cwd=cwd)
  894. return host.ensure_session({"session_id": session_id}, metadata=metadata, cwd=cwd)
  895. def begin_turn(
  896. self,
  897. lease: ConversationLease,
  898. *,
  899. turn_id: str,
  900. task_id: str,
  901. metadata: dict[str, Any] | None = None,
  902. ) -> RelayTurnContext:
  903. if lease.released:
  904. raise RuntimeError("Hermes Relay conversation lease is released")
  905. turn = RelayTurnContext(lease=lease, turn_id=turn_id, task_id=task_id)
  906. key = (lease.profile_key, lease.session_id)
  907. with self._active_turns_lock:
  908. if self._active_turns.get(key):
  909. # One physical scope stack per session; concurrent turns' sibling scopes would not close LIFO.
  910. turn.relay_enabled = False
  911. logger.warning(
  912. "Skipping Relay instrumentation for concurrent Hermes turn %s in session %s",
  913. turn_id, lease.session_id,
  914. )
  915. else:
  916. self._active_turns[key] = {id(turn)}
  917. turn._active_registered = True
  918. host = lease.live_runtime() if turn.relay_enabled else None
  919. if host is not None:
  920. # Rotation happens HERE: no live turn scope on the stack, so the session scope can close/reopen LIFO.
  921. _warn_on_error("segment rotation", self._maybe_rotate_segment, host, lease.session)
  922. turn_metadata = dict(metadata or {})
  923. turn_metadata.update(
  924. runtime_metadata(
  925. host.runtime_id,
  926. **{"hermes.execution_surface": lease.platform or "unknown"},
  927. )
  928. )
  929. turn.handle = _warn_on_error(
  930. "turn initialization", host.run_in_session, lease.session, host.relay.scope.push,
  931. TURN_SCOPE, host.relay.ScopeType.Function, handle=lease.session.handle,
  932. input=_scope_input(lease.turn_cwd),
  933. metadata=turn_metadata,
  934. timeout=SCOPE_OP_TIMEOUT,
  935. )
  936. turn._previous_turn = _CURRENT_TURN.get()
  937. _CURRENT_TURN.set(turn)
  938. return turn
  939. @staticmethod
  940. def _maybe_rotate_segment(host: RelayRuntime, session: RelaySession) -> None:
  941. """Rotate the session scope when compaction flagged it or the turn cap is hit."""
  942. config = _segments_config()
  943. cap = config["max_turns"]
  944. compaction = config["on_compaction"] and session.rotate_pending
  945. if compaction or (cap > 0 and session.segment_turns >= cap):
  946. host.rotate_session_scope(session, reason="compaction" if compaction else "max_turns")
  947. def end_turn(self, turn: RelayTurnContext, *, outcome: str) -> None:
  948. with turn.finalize_lock:
  949. if turn.closed:
  950. self._reset_turn_context(turn)
  951. return
  952. turn.closed = True
  953. lease = turn.lease
  954. host = lease.live_runtime()
  955. try:
  956. if host is not None:
  957. self._close_turn_scope(host, turn, outcome=outcome)
  958. finally:
  959. if turn._active_registered and host is not None:
  960. with contextlib.suppress(Exception), lease.session.lock: # accounting never blocks
  961. lease.session.segment_turns += 1 # max_turns rotation trigger
  962. try:
  963. # Delegated agents own one turn: close their conversation while the active-turn
  964. # guard is held so a parent timeout fallback cannot race it.
  965. if lease.parent_session_id and isinstance(lease.host, RelayRuntime):
  966. _warn_on_error(
  967. "child conversation finalization", lease.host.unregister_subagent,
  968. {"child_session_id": lease.session_id},
  969. )
  970. finally:
  971. self._unregister_active_turn(turn)
  972. self._reset_turn_context(turn)
  973. self._consume_deferred_close(lease)
  974. def _close_turn_scope(self, host: RelayRuntime, turn: RelayTurnContext, *, outcome: str) -> None:
  975. """Pop the turn's logical LLM children, then the turn scope itself (LIFO)."""
  976. self._finish_logical_calls(turn, outcome=outcome)
  977. failure = host._close_scope_handle(
  978. turn.lease.session, turn.handle, output={"outcome": outcome}, failure_label="turn scope close failed",
  979. )
  980. if failure:
  981. logger.warning("Hermes Relay turn finalization failed: %s", failure)
  982. @_fail_open("deferred session close")
  983. def _consume_deferred_close(self, lease: ConversationLease) -> None:
  984. """Close a session whose rotating-compaction close was deferred (``close_pending``).
  985. The last live turn consumes it after its own scope popped and it left the active-turn table."""
  986. host = lease.live_runtime()
  987. if host is None:
  988. return
  989. with lease.session.lock:
  990. pending = lease.session.close_pending and not lease.session.closing
  991. if pending and not self.has_active_turn(profile_key=lease.profile_key, session_id=lease.session_id):
  992. host.close_session({"session_id": lease.session_id})
  993. @_fail_open("compaction notification")
  994. def notify_session_compacted(self, *, profile_key: str, session_id: str, old_session_id: str = "") -> None:
  995. """React to a completed compaction, per compaction mode; unknown sessions / disabled config are no-ops.
  996. In-place (``old_session_id`` empty/equal): flag rotation for the next turn boundary — never rotate
  997. immediately, a live turn under it breaks LIFO. Rotating (ids differ): the next turn gets a fresh
  998. session under the new id, so close the OLD session now or its scope stays an unexported orphan."""
  999. if not _segments_config()["on_compaction"]:
  1000. return
  1001. host = self.registry.for_profile(profile_key)
  1002. if not isinstance(host, RelayRuntime):
  1003. return
  1004. if old_session_id and old_session_id != session_id:
  1005. # A LIVE turn on the old session: closing now would pop under it (LIFO).
  1006. old_session = host._lookup(old_session_id)
  1007. if old_session is not None and self.has_active_turn(profile_key=profile_key, session_id=old_session_id):
  1008. _flag_open_session(old_session, "close_pending")
  1009. else:
  1010. host.close_session({"session_id": old_session_id})
  1011. return
  1012. session = host._lookup(session_id)
  1013. if session is not None:
  1014. _flag_open_session(session, "rotate_pending")
  1015. def has_active_turn(self, *, profile_key: str, session_id: str) -> bool:
  1016. """Return whether a turn is still running for one profile/session."""
  1017. with self._active_turns_lock:
  1018. return bool(self._active_turns.get((profile_key, session_id)))
  1019. def _unregister_active_turn(self, turn: RelayTurnContext) -> None:
  1020. if not turn._active_registered:
  1021. return
  1022. key = (turn.lease.profile_key, turn.lease.session_id)
  1023. with self._active_turns_lock:
  1024. active = self._active_turns.get(key)
  1025. if active is not None:
  1026. active.discard(id(turn))
  1027. if not active:
  1028. del self._active_turns[key]
  1029. turn._active_registered = False
  1030. def finish_logical_calls(self, turn: RelayTurnContext, *, outcome: str) -> None:
  1031. """Close logical LLM children before sibling task aggregation scopes."""
  1032. with turn.finalize_lock:
  1033. if not turn.closed:
  1034. self._finish_logical_calls(turn, outcome=outcome)
  1035. @staticmethod
  1036. def _finish_logical_calls(turn: RelayTurnContext, *, outcome: str) -> None:
  1037. lease = turn.lease
  1038. host = lease.live_runtime()
  1039. if host is None:
  1040. return
  1041. with turn.logical_llm_lock:
  1042. logical_calls = list(turn.logical_llm_calls.items())
  1043. turn.logical_llm_calls.clear()
  1044. while logical_calls:
  1045. _request_id, logical_handle = logical_calls[-1]
  1046. failure = host._close_scope_handle(
  1047. lease.session, logical_handle, output={"outcome": outcome},
  1048. failure_label="logical LLM scope close failed",
  1049. )
  1050. if failure is None:
  1051. logical_calls.pop()
  1052. continue
  1053. with turn.logical_llm_lock:
  1054. # Stack-owned: if the newest handle cannot close even after drain, older ones cannot either.
  1055. for pending_request_id, pending_handle in logical_calls:
  1056. turn.logical_llm_calls.setdefault(pending_request_id, pending_handle)
  1057. logger.warning("Hermes Relay logical LLM finalization failed: %s", failure)
  1058. break
  1059. @staticmethod
  1060. def _reset_turn_context(turn: RelayTurnContext) -> None:
  1061. """Unwind ``turn`` without disturbing a newer context-local turn."""
  1062. if _CURRENT_TURN.get() is not turn:
  1063. return
  1064. previous, seen = turn._previous_turn, {id(turn)}
  1065. while previous is not None and previous.closed and id(previous) not in seen:
  1066. seen.add(id(previous))
  1067. previous = previous._previous_turn
  1068. if previous is not None and previous.closed: # cycle: no live ancestor
  1069. previous = None
  1070. _CURRENT_TURN.set(previous)
  1071. @staticmethod
  1072. def release_conversation(lease: ConversationLease) -> None:
  1073. """Release a caller lease without closing a resumable conversation."""
  1074. lease.released = True
  1075. def finalize_conversation(self, *, profile_key: str, session_id: str) -> None:
  1076. host = self.registry.for_profile(profile_key, create=False)
  1077. if isinstance(host, RelayRuntime):
  1078. host.close_session({"session_id": session_id})
  1079. SESSION_COORDINATOR = RelaySessionCoordinator()
  1080. def current_turn() -> RelayTurnContext | None:
  1081. """Return the turn context inherited by current async and thread work."""
  1082. return _CURRENT_TURN.get()
  1083. def relay_instrumentation_enabled() -> bool:
  1084. """Return whether this inherited turn may create Relay instrumentation."""
  1085. turn = current_turn()
  1086. return turn is None or (turn.relay_enabled and not turn.closed)
  1087. def active_turn(session_id: str | None = None) -> RelayTurnContext | None:
  1088. """Return a live turn only when it belongs to the active profile/session."""
  1089. turn = current_turn()
  1090. if turn is None or not turn.relay_enabled or turn.closed or turn.lease.released:
  1091. return None
  1092. lease = turn.lease
  1093. if lease.profile_key != current_profile_key() or (session_id is not None and lease.session_id != session_id):
  1094. return None
  1095. if isinstance(lease.host, RelayRuntime) and (
  1096. lease.session is None or lease.host.get_session(lease.session_id) is not lease.session
  1097. ):
  1098. return None
  1099. return turn
  1100. def resolve_execution_context(session_id: str) -> tuple[RelayRuntime | None, RelaySession | None, Any]:
  1101. """Resolve one active turn/session parent for managed Relay execution."""
  1102. # Nested managed execution is impossible (see _MANAGED_CALLBACK_DEPTH); the outer scope
  1103. # still records the tool-level event.
  1104. if _MANAGED_CALLBACK_DEPTH.get() > 0 or not relay_instrumentation_enabled():
  1105. # A managed Relay callback is already executing on this logical call path (e.g. the native
  1106. # ``tools.execute`` pipeline is mid-dispatch of a Hermes tool). Nested managed execution here is
  1107. # structurally impossible: the native pipeline binds its Futures to the OUTER call's event loop,
  1108. # which is blocked inside the synchronous tool callback until the tool returns. A nested managed LLM
  1109. # call (the vision_analyze auxiliary path) therefore awaits a foreign-loop Future that can never
  1110. # complete — "attached to a different loop" at best, deadlock at worst, and "Event loop is closed"
  1111. # during shutdown when the orphaned Future is completed late (#77244).
  1112. return None, None, None
  1113. turn = active_turn(session_id)
  1114. host = turn.lease.live_runtime() if turn is not None else None
  1115. if host is not None:
  1116. session = turn.lease.session
  1117. return host, session, turn.handle or session.handle
  1118. # Consumers retain the profile host before reaching an out-of-turn adapter; never
  1119. # initialize Relay for the default no-consumer path.
  1120. runtime = get_runtime(create=False)
  1121. if runtime is None or not runtime.managed_execution_enabled():
  1122. return None, None, None
  1123. session = runtime.get_session(session_id) or runtime.ensure_session({"session_id": session_id})
  1124. return runtime, session, None if session is None else session.handle
  1125. def apply_tool_request_intercepts(*, session_id: str, tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
  1126. """Return Relay-rewritten arguments at Hermes's authorization boundary."""
  1127. runtime = get_runtime(create=False) if session_id else None
  1128. if runtime is None:
  1129. return args
  1130. return runtime.apply_tool_request_intercepts(session_id=session_id, tool_name=tool_name, args=args)
  1131. def _is_relay_wrapped_callback_error(relay_error: BaseException, callback_error: BaseException) -> bool:
  1132. """Match Relay's native callback wrapper without masking policy errors."""
  1133. if relay_error is callback_error:
  1134. return True
  1135. if not isinstance(relay_error, RuntimeError):
  1136. return False
  1137. kind = type(callback_error)
  1138. type_names = {kind.__name__, kind.__qualname__, f"{kind.__module__}.{kind.__qualname__}"}
  1139. return any(str(relay_error).startswith(f"internal error: {name}: {callback_error}") for name in type_names)
  1140. def get_runtime(*, create: bool = True, profile_key: str | None = None) -> RelayRuntime | None:
  1141. """Return the Relay host for the active Hermes profile."""
  1142. host = HOST_REGISTRY.for_profile(profile_key, create=create)
  1143. return host if isinstance(host, RelayRuntime) else None
  1144. def current_profile_key() -> str:
  1145. """Return the canonical profile identity used for runtime isolation."""
  1146. home = get_hermes_home().expanduser()
  1147. if not home.is_absolute():
  1148. return str(home.resolve())
  1149. return _PROFILE_KEY_CACHE.get(str(home)) or _PROFILE_KEY_CACHE.setdefault(str(home), str(home.resolve()))
  1150. def _load_nemo_relay() -> Any:
  1151. """Load the binding only when a producer or consumer needs Relay."""
  1152. return importlib.import_module("nemo_relay")
  1153. def _configured_plugin_inputs() -> Path | None:
  1154. """Return the parseable explicit override, or ``None`` to use Relay discovery."""
  1155. config_path = _explicit_plugins_toml()
  1156. if config_path is None and (legacy_vars := configured_legacy_relay_env_vars(os.environ)):
  1157. logger.warning(
  1158. "Legacy NeMo Relay exporter variables are set but no %s was provided. %s no longer configure "
  1159. "Relay exporters; any standard user or system plugins.toml still applies. Run `hermes migrate "
  1160. "relay` (or `hermes update`, which runs it for every profile) to generate %s and select it in .env.",
  1161. RELAY_PLUGINS_CONFIG_ENV,
  1162. ", ".join(legacy_vars),
  1163. get_hermes_home() / "relay-plugins.toml",
  1164. )
  1165. return config_path
  1166. def _explicit_plugins_toml() -> Path | None:
  1167. """Return the file selected by ``HERMES_NEMO_RELAY_PLUGINS_TOML`` after checking that it parses."""
  1168. configured = os.environ.get(RELAY_PLUGINS_CONFIG_ENV, "").strip()
  1169. if not configured:
  1170. return None
  1171. config_path = Path(configured).expanduser()
  1172. try:
  1173. with config_path.open("rb") as config_file:
  1174. config = tomllib.load(config_file)
  1175. if "dynamic_plugins" in config:
  1176. raise ValueError("Hermes [[dynamic_plugins]] records are unsupported; use Relay [[plugins.dynamic]] records")
  1177. return config_path
  1178. except Exception as exc:
  1179. raise _RelayPluginConfigurationLoadError(
  1180. f"Hermes Relay plugin configuration could not be loaded from {config_path}; continuing without Relay plugins"
  1181. ) from exc
  1182. @dataclass(frozen=True)
  1183. class RelayPluginSources:
  1184. """The plugin configuration Relay resolves for this process, as its validator reports it."""
  1185. config_paths: tuple[str, ...] # lowest precedence first
  1186. enabled: bool # whether any static component or dynamic plugin is switched on
  1187. errors: tuple[str, ...] # initialization would refuse the configuration
  1188. warnings: tuple[str, ...]
  1189. def resolve_plugin_sources(relay: Any = None) -> RelayPluginSources:
  1190. """Resolve the plugins.toml layers this process would load, without loading plugin code.
  1191. Relay's validator reads the same layers as initialization but does not take the process-wide host.
  1192. Raises when a file cannot be read or parsed.
  1193. """
  1194. relay = relay or _load_nemo_relay()
  1195. report = relay.plugin.validate({}, additional_plugins_toml=_explicit_plugins_toml())
  1196. diagnostics = [d for d in (report.get("config") or {}).get("diagnostics") or [] if isinstance(d, dict)]
  1197. return RelayPluginSources(
  1198. config_paths=tuple(str(path) for path in report.get("config_paths") or []),
  1199. enabled=_report_requires_managed_execution(report),
  1200. errors=tuple(str(d.get("message")) for d in diagnostics if d.get("level") == "error"),
  1201. # Relay adds one "configuration_inherited" note per discovered file; config_paths already names them.
  1202. warnings=tuple(
  1203. str(d.get("message")) for d in diagnostics
  1204. if d.get("level") == "warning" and d.get("code") != "plugin.configuration_inherited"
  1205. ),
  1206. )
  1207. # Relay 0.9 exposes no active-host query; only initialize's two Conflict messages signal one.
  1208. _RELAY_HOST_CONFLICT_MESSAGES = frozenset(
  1209. {
  1210. "conflict: a static plugin configuration is already active; to combine static and dynamic plugins, "
  1211. "provide the static components as the base configuration to dynamic plugin activation before calling "
  1212. "plugin initialization",
  1213. "conflict: plugin configuration is owned by an active dynamic plugin host",
  1214. }
  1215. )
  1216. def _is_relay_host_conflict(exc: BaseException) -> bool:
  1217. return isinstance(exc, RuntimeError) and str(exc) in _RELAY_HOST_CONFLICT_MESSAGES
  1218. def _resolve_plugin_awaitable(value: Any) -> Any:
  1219. """Resolve Relay's async plugin API from synchronous host construction."""
  1220. if not inspect.isawaitable(value):
  1221. return value
  1222. # Only the "no running loop" probe is guarded: a RuntimeError raised by the awaitable itself
  1223. # (re-raised from the daemon thread) must propagate, not fall through to a second asyncio.run.
  1224. try:
  1225. asyncio.get_running_loop()
  1226. except RuntimeError:
  1227. return asyncio.run(value)
  1228. return _run_on_daemon_thread(lambda: asyncio.run(value), name="hermes-nemo-relay-plugin-lifecycle")
  1229. def _session_id(event: dict[str, Any]) -> str:
  1230. return str(event.get("session_id") or "")
  1231. def _reset_for_tests() -> None:
  1232. """Reset all profile-scoped Relay hosts for isolated tests."""
  1233. with SESSION_COORDINATOR._active_turns_lock:
  1234. SESSION_COORDINATOR._active_turns.clear()
  1235. HOST_REGISTRY.shutdown_all()
  1236. _PLUGIN_CONFIGURATION.reset_for_tests()
  1237. _PROFILE_KEY_CACHE.clear()