diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py new file mode 100644 index 000000000..d9e35b0af --- /dev/null +++ b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py @@ -0,0 +1,57 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Helpers for native interfaces that an adapter serves on loopback.""" + +from __future__ import annotations + +import os +import socket +import tempfile +from pathlib import Path + + +def port_available(port: int) -> bool: + """Return whether one loopback TCP port is available.""" + sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + try: + if hasattr(socket, "SO_EXCLUSIVEADDRUSE"): + # On Windows, SO_REUSEADDR lets a bind succeed on a port in use. + sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1) + else: + sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + sock.bind(("127.0.0.1", port)) + return True + except (OSError, OverflowError): + return False + finally: + sock.close() + + +def write_private_file(path: Path, payload: str) -> None: + """Atomically write an owner-only file in an owner-only directory. + + On Windows, chmod sets only the read-only flag, so the file inherits the + directory's permissions. + """ + path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) + os.chmod(path.parent, 0o700) + descriptor, temporary_name = tempfile.mkstemp( + dir=path.parent, + prefix=f".{path.name}.", + ) + try: + if hasattr(os, "fchmod"): + os.fchmod(descriptor, 0o600) + with os.fdopen(descriptor, "w", encoding="utf-8") as stream: + descriptor = -1 + stream.write(payload) + os.replace(temporary_name, path) + except BaseException: + if descriptor >= 0: + os.close(descriptor) + try: + os.unlink(temporary_name) + except FileNotFoundError: + pass + raise diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 2ee52da7a..c8a0a200b 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -7,6 +7,8 @@ SPDX-License-Identifier: Apache-2.0 This adapter runs Hermes Agent through its Python SDK. +Managed API and dashboard children launch through an adapter-owned bootstrap that applies the same behavioral mapping when Hermes constructs native agent instances. Instructions and behavioral settings configured by NeMo Fabric take precedence over native constructor defaults. Explicit tool selection and nonempty blocked-tool policies override native defaults; unspecified tool policies retain native interface defaults. The bootstrap retains native routing, session identity, execution, and transport; it does not modify the installed Hermes source. A mode-`0600` configuration snapshot under the runtime's `interfaces` directory supplies the mapping and is removed on stop. Gateway processes independently started outside this launcher do not receive this guarantee. + ## Runtime Health `Fabric.check()` supports `live`, `active`, and `ready` for a started runtime. @@ -86,6 +88,8 @@ The descriptor validates the following `harness.settings` fields: | `save_trajectories` | boolean | `false` | Enables Hermes-native JSONL conversation trajectory saving. This is separate from normalized NeMo Fabric telemetry. | | `max_tokens` | positive integer | `512` | Limits the number of tokens in each Hermes model response. | | `terminal_timeout` | positive number | `60` | Limits a Hermes terminal operation in seconds. | +| `interfaces.api`, `interfaces.dashboard` | object | None | Serve Hermes's API server or dashboard from a runtime, each with an exact `port` and optional `enabled`; see [Access and Use](../../../docs/integrations/harness/hermes-interfaces.mdx#3-access-and-use). | +| `startup_timeout_seconds` | number, greater than 0 and at most 75 | `60` | Time from the start of the runtime for every enabled interface to pass its health check. | For example: diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index 84af8a6e8..b47657f0e 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py index c43a5088d..3fa9935f1 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -32,11 +32,12 @@ from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle from nemo_fabric_adapters.hermes import configuration +from nemo_fabric_adapters.hermes import interfaces from nemo_fabric_adapters.hermes import telemetry # Default agent loop budget when FabricConfig.runtime.max_turns is unset. # The actual internal hermes default as of v0.21 is `sys.maxsize` -DEFAULT_MAX_ITERATIONS: int = 90 +DEFAULT_MAX_ITERATIONS: int = configuration.DEFAULT_MAX_ITERATIONS LOGGER = logging.getLogger(__name__) hermes_mcp_server_config = configuration.hermes_mcp_server_config @@ -70,6 +71,7 @@ def __init__(self) -> None: self._relay_plugin_config: dict[str, Any] | None = None self._relay_plugin_config_path: Path | None = None self._active_invoke_task: asyncio.Task[tuple[dict[str, Any], str]] | None = None + self._interfaces = interfaces.InterfaceChildren() async def start(self, payload: dict[str, Any]) -> None: if self._started: @@ -79,6 +81,9 @@ async def start(self, payload: dict[str, Any]) -> None: ) self._stopping = False + # startup_timeout_seconds bounds all of start, so Fabric's start limit + # can't expire first. + started_at = asyncio.get_running_loop().time() try: agent_config = payload.get("config") if not isinstance(agent_config, AgentConfig): @@ -102,6 +107,11 @@ async def start(self, payload: dict[str, Any]) -> None: telemetry.validate_hermes_relay_compatibility() self._agent_config = agent_config self._settings = configuration._settings(agent_config) + interface_ports = interfaces.interface_ports(self._settings) + if interface_ports: + # Refuse before Hermes's setup, whose MCP discovery can take + # minutes and outlast the caller's start deadline. + interfaces.require_supported_platform() model_config = configuration._selected_model(agent_config) self._model_config = model_config self._runtime_id = runtime_context.runtime_id @@ -145,6 +155,7 @@ async def start(self, payload: dict[str, Any]) -> None: # Workspace belongs to the per-runtime context, not AgentConfig. workspace=str(runtime_context.environment.workspace or "."), relay_enabled=relay_enabled, + interfaces=interface_ports, ) api_key_env = configuration._api_key_env(model_config) api_key = os.environ.get(api_key_env) @@ -181,19 +192,6 @@ async def start(self, payload: dict[str, Any]) -> None: ) self._session_db = SessionDB() self._conversation_history = None - max_iterations = configuration._max_turns(agent_config) - if max_iterations is None: - max_iterations = DEFAULT_MAX_ITERATIONS - temperature = model_config.temperature - top_p = model_config.top_p - request_overrides = { - name: value - for name, value in ( - ("temperature", temperature), - ("top_p", top_p), - ) - if value is not None - } self._agent = AIAgent( **filter_supported_kwargs( AIAgent, @@ -201,27 +199,58 @@ async def start(self, payload: dict[str, Any]) -> None: api_key=api_key, provider=model_config.provider, model=model_config.model, - max_iterations=int(max_iterations), - enabled_toolsets=self._enabled_toolsets, - disabled_toolsets=configuration.disabled_toolsets(agent_config) - or None, + **configuration.agent_behavior_kwargs( + agent_config, self._enabled_toolsets + ), quiet_mode=True, skip_context_files=True, skip_memory=True, - save_trajectories=bool( - self._settings.get("save_trajectories", False) - ), - max_tokens=model_config.max_tokens - or self._settings.get("max_tokens", 512), - request_overrides=request_overrides or None, - reasoning_config=self._settings.get( - "reasoning_config", {"effort": "none"} - ), platform="fabric", session_id=self._runtime_id, session_db=self._session_db, ) ) + if interface_ports: + if "api" in interface_ports: + from hermes_cli.profile_channels import platform_ids + + # This gateway serves the managed API, not ambient chat bots. + # Explicit disables beat Hermes's credential-based enablement. + self._hermes_config["platforms"] = { + name: {"enabled": False} + for name in platform_ids(self._hermes_home) + if name != "api_server" + } + self._hermes_config["gateway"] = {"multiplex_profiles": False} + self._hermes_config_path.write_text( + common_utils.dump_yaml(self._hermes_config), encoding="utf-8" + ) + environment = dict(os.environ) + if ( + str(model_config.provider or "").lower() == "openai" + and not model_config.base_url + ): + # An ambient endpoint must not redirect the configured key. + environment.pop("OPENAI_BASE_URL", None) + provider_key_env = configuration.PROVIDER_DEFAULT_API_KEY_ENV.get( + str(model_config.provider or "").lower() + ) + if provider_key_env: + # Hermes's own processes read a provider's key from its + # default variable, not from api_key_env. + environment[provider_key_env] = api_key + await self._interfaces.start( + interface_ports, + hermes_home=self._hermes_home, + token_path=self._hermes_home / "interfaces" / "api.token", + timeout=max( + interfaces.startup_timeout(self._settings) + - (asyncio.get_running_loop().time() - started_at), + 0.0, + ), + environment=environment, + agent_config=agent_config, + ) self._agent_config = agent_config self._started = True except BaseException: @@ -596,6 +625,10 @@ async def stop(self) -> None: self._stopping = True active_invoke_task = self._active_invoke_task errors: list[BaseException] = [] + try: + await self._interfaces.stop() + except BaseException as error: + errors.append(error) if active_invoke_task is not None: try: await asyncio.shield(active_invoke_task) @@ -714,7 +747,6 @@ def filter_supported_call_kwargs(func: Any, **kwargs: Any) -> dict[str, Any]: return {key: value for key, value in kwargs.items() if key in supported} - # Selected software reported by the shared lifecycle host; no dependency scan. PROVENANCE_PACKAGES = ( ("adapter", "nemo-fabric-adapters-hermes", "nemo_fabric_adapters.hermes.adapter"), diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py index 39a0244c8..929c10b14 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py @@ -6,6 +6,7 @@ from __future__ import annotations import os +from collections.abc import Collection from pathlib import Path from typing import Any @@ -15,6 +16,7 @@ from nemo_fabric_adapter_contract.models import McpOAuth2Config from nemo_fabric_adapter_contract.models import McpServiceAccountConfig import nemo_fabric_adapters.common.utils as common_utils +from nemo_fabric_adapters.hermes.interfaces import GATEWAY_DRAIN_TIMEOUT_SECONDS PROVIDER_DEFAULT_API_KEY_ENV = { @@ -23,6 +25,27 @@ "openai": "OPENAI_API_KEY", "openrouter": "OPENROUTER_API_KEY", } +DEFAULT_MAX_ITERATIONS = 90 + + +def agent_behavior_kwargs( + config: AgentConfig, enabled_toolsets: list[str] | None +) -> dict[str, Any]: + """Map behavioral settings for embedded and native Hermes agent instances.""" + model = _selected_model(config) + settings = _settings(config) + overrides = common_utils.without_none( + {"temperature": model.temperature, "top_p": model.top_p} + ) + return { + "max_iterations": _max_turns(config) or DEFAULT_MAX_ITERATIONS, + "enabled_toolsets": enabled_toolsets, + "disabled_toolsets": disabled_toolsets(config) or None, + "save_trajectories": bool(settings.get("save_trajectories", False)), + "max_tokens": model.max_tokens or settings.get("max_tokens", 512), + "request_overrides": overrides or None, + "reasoning_config": settings.get("reasoning_config", {"effort": "none"}), + } def _validate_client_secret( @@ -74,11 +97,37 @@ def disabled_toolsets(config: AgentConfig) -> list[str]: return config.tools.blocked if config.tools is not None else [] +def _interface_model(model_config: AgentModelConfig) -> dict[str, Any]: + """Return the model section Hermes's own processes read from config.yaml. + + Fabric's embedded agent receives the endpoint and key as arguments; the + gateway and dashboard read them from config.yaml, where Hermes's ``openai`` + provider ignores ``base_url``. The key stays in the environment. + """ + + provider = str(model_config.provider or "").lower() + if model_config.base_url and provider in {"openai", "custom"}: + return { + "provider": "custom", + "default": model_config.model, + "base_url": model_config.base_url, + "api_key": f"${{{_api_key_env(model_config)}}}", + } + return common_utils.without_none( + { + "provider": model_config.provider, + "default": model_config.model, + "base_url": model_config.base_url, + } + ) + + def build_hermes_config( agent_config: AgentConfig, *, workspace: str, relay_enabled: bool = False, + interfaces: Collection[str] = (), ) -> dict[str, Any]: settings = _settings(agent_config) model_config = _selected_model(agent_config) @@ -110,6 +159,12 @@ def build_hermes_config( ), } + if interfaces: + config["model"] = _interface_model(model_config) + if "api" in interfaces: + config["agent"]["cron_drain_timeout"] = GATEWAY_DRAIN_TIMEOUT_SECONDS + config["agent"]["restart_drain_timeout"] = 0 + if relay_enabled: # Hermes makes an extra model call for titles, which skews Relay telemetry. config["auxiliary"] = {"title_generation": {"enabled": False}} @@ -145,12 +200,14 @@ def write_hermes_config( *, workspace: str, relay_enabled: bool = False, + interfaces: Collection[str] = (), ) -> tuple[Path, dict[str, Any]]: hermes_home.mkdir(parents=True, exist_ok=True) config = build_hermes_config( agent_config, workspace=workspace, relay_enabled=relay_enabled, + interfaces=interfaces, ) config_path = hermes_home / "config.yaml" config_path.write_text(common_utils.dump_yaml(config), encoding="utf-8") diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py new file mode 100644 index 000000000..36f25f52a --- /dev/null +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py @@ -0,0 +1,269 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Serve Hermes's API server and dashboard as children of a managed runtime.""" + +from __future__ import annotations + +import asyncio +import http.client +import json +import logging +import os +import secrets +import signal +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from nemo_fabric_adapter_contract.models import AgentConfig +from nemo_fabric_adapters.common import lifecycle +from nemo_fabric_adapters.common import local_interfaces +from nemo_fabric_adapters.common import utils as common_utils + +HEALTH_PATHS = {"api": "/health", "dashboard": "/api/status"} +LOGGER = logging.getLogger(__name__) +# Children run in their own sessions and stop by process group. +POSIX = os.name != "nt" +DEFAULT_STARTUP_TIMEOUT_SECONDS = 60.0 +# Fabric gives the adapter host 10 s to stop, including this wait. +STOP_GRACE_SECONDS = 5.0 +# Hermes's gateway waits this long for in-flight API runs and cron jobs on +# SIGTERM, so it exits within STOP_GRACE_SECONDS. +GATEWAY_DRAIN_TIMEOUT_SECONDS = 3 + + +def interface_ports(settings: dict[str, Any]) -> dict[str, int]: + """Return the enabled interfaces' loopback ports, keyed by interface name. + + The descriptor's schema has already checked the settings. + """ + return { + name: interface["port"] + for name, interface in settings.get("interfaces", {}).items() + if interface.get("enabled", True) + } + + +def startup_timeout(settings: dict[str, Any]) -> float: + """Return the deadline for every enabled interface to pass its health check.""" + return float( + settings.get("startup_timeout_seconds", DEFAULT_STARTUP_TIMEOUT_SECONDS) + ) + + +def require_supported_platform() -> None: + """Refuse interfaces on a host without POSIX process groups.""" + if not POSIX: + raise lifecycle.LifecycleError( + "hermes_interfaces_unsupported_platform", + "Hermes interfaces require a POSIX host", + metadata={"field": "harness.settings.interfaces"}, + ) + + +@dataclass +class _Child: + name: str + port: int + process: asyncio.subprocess.Process + + +class InterfaceChildren: + """Start, track and stop one runtime's interface processes.""" + + def __init__(self) -> None: + self._children: list[_Child] = [] + self._token_path: Path | None = None + self._agent_config_path: Path | None = None + + async def start( + self, + ports: dict[str, int], + *, + hermes_home: Path, + token_path: Path, + timeout: float, + environment: dict[str, str], + agent_config: AgentConfig, + ) -> None: + """Start the enabled interfaces and write the API token once all pass health.""" + require_supported_platform() + for name, port in ports.items(): + if not local_interfaces.port_available(port): + raise lifecycle.LifecycleError( + "hermes_interface_port_unavailable", + f"Hermes {name} port {port} is already in use", + metadata={ + "field": f"harness.settings.interfaces.{name}.port", + "port": port, + }, + ) + web_dist = _web_dist() if "dashboard" in ports else None + token = secrets.token_urlsafe(32) + log_dir = hermes_home / "logs" + log_dir.mkdir(parents=True, exist_ok=True) + deadline = asyncio.get_running_loop().time() + timeout + try: + config_path = hermes_home / "interfaces" / "agent-config.json" + local_interfaces.write_private_file( + config_path, json.dumps(agent_config.to_mapping()) + ) + self._agent_config_path = config_path + for name, port in ports.items(): + arguments, child_environment = _child_command( + name, port, token=token, web_dist=web_dist, environment=environment + ) + with open(log_dir / f"fabric-interface-{name}.log", "ab") as log: + process = await asyncio.create_subprocess_exec( + sys.executable, + "-m", + "nemo_fabric_adapters.hermes.native", + "--fabric-config", + str(config_path), + *arguments, + env=child_environment, + stdin=asyncio.subprocess.DEVNULL, + stdout=log, + stderr=asyncio.subprocess.STDOUT, + start_new_session=True, + ) + self._children.append(_Child(name, port, process)) + for child in self._children: + await _wait_healthy(child, deadline) + if "api" in ports: + local_interfaces.write_private_file(token_path, token) + self._token_path = token_path + except BaseException: + await self.stop() + raise + + async def stop(self) -> None: + """Remove the API token, then stop every interface process group.""" + self._remove_private_file("_token_path") + running = [ + child for child in self._children if child.process.returncode is None + ] + pending: set[asyncio.Future[int]] = set() + try: + for child in running: + common_utils.signal_process_group(child.process.pid, signal.SIGTERM) + if running: + waits = [ + asyncio.ensure_future(child.process.wait()) for child in running + ] + _, pending = await asyncio.wait(waits, timeout=STOP_GRACE_SECONDS) + finally: + # Runs even when stop is cancelled, so no child outlives the runtime. + for child in running: + common_utils.signal_process_group(child.process.pid, signal.SIGKILL) + self._children = [] + self._remove_private_file("_agent_config_path") + if pending: + await asyncio.wait(pending) + + def _remove_private_file(self, attribute: str) -> None: + path = getattr(self, attribute) + if path is not None: + try: + path.unlink(missing_ok=True) + except OSError: + # Retain the path for retry; cleanup must not prevent child stop. + LOGGER.exception("Could not remove Hermes interface file %s", path) + else: + setattr(self, attribute, None) + + +def _web_dist() -> Path: + configured = os.environ.get("HERMES_WEB_DIST") + if configured: + dist = Path(configured) + else: + import hermes_cli + + dist = Path(hermes_cli.__file__).parent / "web_dist" + if not (dist / "index.html").is_file(): + raise lifecycle.LifecycleError( + "hermes_dashboard_frontend_missing", + f"Hermes's dashboard needs a built frontend at {dist}; set " + "HERMES_WEB_DIST to one", + metadata={"field": "harness.settings.interfaces.dashboard"}, + ) + return dist + + +async def _wait_healthy(child: _Child, deadline: float) -> None: + loop = asyncio.get_running_loop() + while loop.time() < deadline: + if child.process.returncode is not None: + raise lifecycle.LifecycleError( + "hermes_interface_start_failed", + f"Hermes {child.name} exited before passing its health check", + metadata={"interface": child.name}, + ) + if await _http_status(child.port, HEALTH_PATHS[child.name]) == 200: + return + await asyncio.sleep(0.1) + raise lifecycle.LifecycleError( + "hermes_interface_start_timeout", + f"Hermes {child.name} didn't pass its health check before the startup timeout", + retryable=True, + metadata={"interface": child.name}, + ) + + +def _child_command( + name: str, + port: int, + *, + token: str, + web_dist: Path | None, + environment: dict[str, str], +) -> tuple[list[str], dict[str, str]]: + """Return one interface's Hermes CLI arguments and environment.""" + child_environment = { + key: value + for key, value in environment.items() + if not key.startswith("API_SERVER_") + } + if name == "api": + child_environment.update( + API_SERVER_KEY=token, + API_SERVER_HOST="127.0.0.1", + API_SERVER_PORT=str(port), + ) + return ["gateway", "run"], child_environment + child_environment["HERMES_WEB_DIST"] = str(web_dist) + # --isolated keeps one dashboard per runtime instead of attaching to another + # runtime's dashboard on this host. + return [ + "dashboard", + "--host", + "127.0.0.1", + "--port", + str(port), + "--no-open", + "--skip-build", + "--isolated", + ], child_environment + + +async def _http_status(port: int, path: str) -> int | None: + """Return a loopback GET's status, or None when nothing answers. + + ``http.client`` neither follows redirects nor uses a proxy, which can't + reach this process's loopback anyway. + """ + + def get() -> int | None: + connection = http.client.HTTPConnection("127.0.0.1", port, timeout=1.0) + try: + connection.request("GET", path) + return connection.getresponse().status + except (OSError, http.client.HTTPException): + return None + finally: + connection.close() + + return await asyncio.to_thread(get) diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/native.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/native.py new file mode 100644 index 000000000..ff30eabdc --- /dev/null +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/native.py @@ -0,0 +1,101 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Launch a native Hermes child with Fabric's agent-construction settings. + +Hermes v0.22.5's API path does not read all behavioral config from config.yaml. +Install the mapping before loading the CLI; execution and transport stay native. +The replacement is local to this adapter-owned child process. +""" + +from __future__ import annotations + +import argparse +import inspect +import json +import logging +import os +import sys +from pathlib import Path +from typing import Any +from functools import wraps + +from nemo_fabric_adapter_contract.models import AgentConfig +from nemo_fabric_adapters.hermes import configuration +from nemo_fabric_adapters.hermes import telemetry + +LOGGER = logging.getLogger(__name__) + + +def finalize_api_turn(agent: Any) -> None: + """Close the API turn's Relay segment without deleting native conversation state.""" + if agent.platform != "api_server" or not os.environ.get( + "HERMES_NEMO_RELAY_PLUGINS_TOML" + ): + return + try: + telemetry.finalize_native_relay_segment(agent.session_id) + except Exception: + # A telemetry failure must not replace an execution result or its error. + LOGGER.exception("Hermes API turn Relay finalization failed") + + +def configured_kwargs( + config: AgentConfig, native_kwargs: dict[str, Any], native_config: dict[str, Any] +) -> dict[str, Any]: + """Apply Fabric-owned behavior while retaining native routing and identity.""" + enabled = ( + configuration.resolve_hermes_toolsets(config, native_config) + if config.tools is not None and config.tools.enabled is not None + else None + ) + behavior = configuration.agent_behavior_kwargs(config, enabled) + if config.tools is None or config.tools.enabled is None: + behavior.pop("enabled_toolsets") + if config.tools is None or not config.tools.blocked: + behavior.pop("disabled_toolsets") + overrides = { + **(native_kwargs.get("request_overrides") or {}), + **(behavior["request_overrides"] or {}), + } + result = {**native_kwargs, **behavior, "request_overrides": overrides or None} + if config.instructions and config.instructions.system: + result["ephemeral_system_prompt"] = config.instructions.system.content + return result + + +def main() -> None: + parser = argparse.ArgumentParser(add_help=False) + parser.add_argument("--fabric-config", type=Path, required=True) + options, arguments = parser.parse_known_args() + config = AgentConfig.from_mapping(json.loads(options.fabric_config.read_text())) + + import run_agent + from hermes_cli.config import load_config + + native_agent = run_agent.AIAgent + signature = inspect.signature(native_agent) + + class ConfiguredAIAgent(native_agent): + def __init__(self, *args: Any, **kwargs: Any) -> None: + bound = signature.bind(*args, **kwargs) + super().__init__( + **configured_kwargs(config, bound.arguments, load_config()) + ) + + @wraps(native_agent.run_conversation) + def run_conversation(self, *args: Any, **kwargs: Any) -> Any: + try: + return super().run_conversation(*args, **kwargs) + finally: + finalize_api_turn(self) + + run_agent.AIAgent = ConfiguredAIAgent + from hermes_cli.main import main as hermes_main + + sys.argv = ["hermes", *arguments] + hermes_main() + + +if __name__ == "__main__": + main() diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/telemetry.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/telemetry.py index 594a047b6..e3a1a67e9 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/telemetry.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/telemetry.py @@ -43,6 +43,17 @@ def finalize_hermes_relay_session(session_id: str) -> None: subscribers.flush() +def finalize_native_relay_segment(session_id: str) -> None: + """Export a native API turn without firing conversation-end plugin hooks.""" + from agent import relay_runtime + from nemo_relay import subscribers + + relay_runtime.SESSION_COORDINATOR.finalize_conversation( + profile_key=relay_runtime.current_profile_key(), session_id=session_id + ) + subscribers.flush() + + def validate_hermes_telemetry_provider(runtime_context: RuntimeContext) -> None: telemetry = runtime_context.telemetry providers = telemetry.metadata.get("telemetry_providers", []) if telemetry else [] diff --git a/assets/hermes-runtime-invocation.excalidraw b/assets/hermes-runtime-invocation.excalidraw new file mode 100644 index 000000000..0559c4441 --- /dev/null +++ b/assets/hermes-runtime-invocation.excalidraw @@ -0,0 +1,1696 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://app.excalidraw.com", + "elements": [ + { + "id": "hermes-0", + "type": "text", + "x": 60, + "y": 8, + "width": 1200, + "height": 45, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1000, + "version": 2, + "versionNonce": 970466068, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Hermes invocation paths: one Fabric runtime", + "originalText": "Hermes invocation paths: one Fabric runtime", + "fontSize": 30, + "fontFamily": 2, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "a0", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-1", + "type": "rectangle", + "x": 60, + "y": 180, + "width": 1220, + "height": 740, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1001, + "version": 2, + "versionNonce": 159270956, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "a1", + "created": null + }, + { + "id": "hermes-2", + "type": "rectangle", + "x": 80, + "y": 158, + "width": 780, + "height": 45, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#3b424b", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1002, + "version": 2, + "versionNonce": 176857236, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "a2", + "created": null + }, + { + "id": "hermes-3", + "type": "text", + "x": 90, + "y": 166, + "width": 760, + "height": 29, + "angle": 0, + "strokeColor": "#ffffff", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1003, + "version": 2, + "versionNonce": 828138156, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "One Fabric runtime — shared lifecycle ownership", + "originalText": "One Fabric runtime — shared lifecycle ownership", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "a3", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-4", + "type": "rectangle", + "x": 110, + "y": 290, + "width": 490, + "height": 380, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1004, + "version": 2, + "versionNonce": 1796304404, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "a4", + "created": null + }, + { + "id": "hermes-5", + "type": "text", + "x": 130, + "y": 303, + "width": 450, + "height": 45, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1005, + "version": 2, + "versionNonce": 462630188, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "NeMo Fabric adapter host", + "originalText": "NeMo Fabric adapter host", + "fontSize": 24, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "a5", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-6", + "type": "rectangle", + "x": 150, + "y": 385, + "width": 410, + "height": 70, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#e3f8e3", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1006, + "version": 2, + "versionNonce": 2086833044, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "a6", + "created": null + }, + { + "id": "hermes-7", + "type": "text", + "x": 160, + "y": 393, + "width": 390, + "height": 54, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1007, + "version": 2, + "versionNonce": 1502390188, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Hermes adapter", + "originalText": "Hermes adapter", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "a7", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-8", + "type": "rectangle", + "x": 150, + "y": 525, + "width": 410, + "height": 100, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#e3f8e3", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1008, + "version": 2, + "versionNonce": 1353971988, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "a8", + "created": null + }, + { + "id": "hermes-9", + "type": "text", + "x": 160, + "y": 533, + "width": 390, + "height": 84, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1009, + "version": 2, + "versionNonce": 1064489516, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Embedded Hermes AIAgent\nFabric conversation", + "originalText": "Embedded Hermes AIAgent\nFabric conversation", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "a9", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-10", + "type": "rectangle", + "x": 730, + "y": 290, + "width": 490, + "height": 380, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1010, + "version": 2, + "versionNonce": 1132181140, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aA", + "created": null + }, + { + "id": "hermes-11", + "type": "text", + "x": 750, + "y": 303, + "width": 450, + "height": 45, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1011, + "version": 2, + "versionNonce": 204450988, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Managed Hermes Gateway", + "originalText": "Managed Hermes Gateway", + "fontSize": 24, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aB", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-12", + "type": "rectangle", + "x": 770, + "y": 385, + "width": 410, + "height": 70, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1012, + "version": 2, + "versionNonce": 1366279188, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aC", + "created": null + }, + { + "id": "hermes-13", + "type": "text", + "x": 780, + "y": 393, + "width": 390, + "height": 54, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1013, + "version": 2, + "versionNonce": 292370220, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Native API / chat entry points", + "originalText": "Native API / chat entry points", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aD", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-14", + "type": "rectangle", + "x": 770, + "y": 525, + "width": 410, + "height": 100, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#e3f8e3", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1014, + "version": 2, + "versionNonce": 1887838612, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aE", + "created": null + }, + { + "id": "hermes-15", + "type": "text", + "x": 780, + "y": 533, + "width": 390, + "height": 84, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1015, + "version": 2, + "versionNonce": 1536520620, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Gateway-side Hermes AIAgent\nNative conversation(s)", + "originalText": "Gateway-side Hermes AIAgent\nNative conversation(s)", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aF", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-16", + "type": "rectangle", + "x": 140, + "y": 80, + "width": 430, + "height": 65, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1016, + "version": 2, + "versionNonce": 1744097044, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aG", + "created": null + }, + { + "id": "hermes-17", + "type": "text", + "x": 150, + "y": 88, + "width": 410, + "height": 49, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1017, + "version": 2, + "versionNonce": 1506958380, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Application / Fabric SDK", + "originalText": "Application / Fabric SDK", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aH", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-18", + "type": "arrow", + "x": 355, + "y": 145, + "width": 0, + "height": 240, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1018, + "version": 2, + "versionNonce": 674352276, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 240 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aI", + "created": null + }, + { + "id": "hermes-19", + "type": "text", + "x": 170, + "y": 221, + "width": 200, + "height": 35, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1019, + "version": 70, + "versionNonce": 893971628, + "isDeleted": false, + "boundElements": [], + "updated": 1793913757174, + "link": null, + "locked": false, + "text": "Runtime.invoke()", + "originalText": "Runtime.invoke()", + "fontSize": 19, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aJ", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-20", + "type": "arrow", + "x": 355, + "y": 455, + "width": 0, + "height": 70, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1020, + "version": 2, + "versionNonce": 586357268, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 70 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aK", + "created": null + }, + { + "id": "hermes-21", + "type": "arrow", + "x": 600, + "y": 362, + "width": 130, + "height": 0, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1021, + "version": 2, + "versionNonce": 217202988, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 130, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aL", + "created": null + }, + { + "id": "hermes-22", + "type": "text", + "x": 598, + "y": 313.25, + "width": 135, + "height": 47.5, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1022, + "version": 4, + "versionNonce": 1620828692, + "isDeleted": false, + "boundElements": [], + "updated": 1793913767364, + "link": null, + "locked": false, + "text": "owns\n child", + "originalText": "owns\n child", + "fontSize": 19, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aM", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-23", + "type": "arrow", + "x": 975, + "y": 455, + "width": 0, + "height": 70, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1023, + "version": 2, + "versionNonce": 1978219436, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 70 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aN", + "created": null + }, + { + "id": "hermes-24", + "type": "rectangle", + "x": 1380, + "y": 370, + "width": 310, + "height": 90, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1024, + "version": 2, + "versionNonce": 622503188, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aO", + "created": null + }, + { + "id": "hermes-25", + "type": "text", + "x": 1390, + "y": 378, + "width": 290, + "height": 74, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1025, + "version": 2, + "versionNonce": 1260185132, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Native API client", + "originalText": "Native API client", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aP", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-26", + "type": "arrow", + "x": 1380, + "y": 415, + "width": 200, + "height": 0, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1026, + "version": 2, + "versionNonce": 774693524, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -200, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aQ", + "created": null + }, + { + "id": "hermes-27", + "type": "rectangle", + "x": 1380, + "y": 560, + "width": 310, + "height": 90, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#f4f4f4", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1027, + "version": 2, + "versionNonce": 1098334380, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aR", + "created": null + }, + { + "id": "hermes-28", + "type": "text", + "x": 1390, + "y": 568, + "width": 290, + "height": 74, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1028, + "version": 2, + "versionNonce": 622555156, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Stock Hermes TUI\nProposed terminal path", + "originalText": "Stock Hermes TUI\nProposed terminal path", + "fontSize": 21, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aS", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-29", + "type": "arrow", + "x": 1380, + "y": 605, + "width": 220, + "height": 150, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1029, + "version": 2, + "versionNonce": 1621248812, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -70, + 0 + ], + [ + -70, + -120 + ], + [ + -220, + -120 + ], + [ + -220, + -150 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aT", + "created": null + }, + { + "id": "hermes-30", + "type": "rectangle", + "x": 300, + "y": 765, + "width": 740, + "height": 110, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "#f4f4f4", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1030, + "version": 2, + "versionNonce": 702303636, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "aU", + "created": null + }, + { + "id": "hermes-31", + "type": "text", + "x": 310, + "y": 773, + "width": 720, + "height": 94, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1031, + "version": 2, + "versionNonce": 721946028, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Shared Fabric-managed Hermes home\nNative config / workspace / persisted state", + "originalText": "Shared Fabric-managed Hermes home\nNative config / workspace / persisted state", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aV", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-32", + "type": "arrow", + "x": 490, + "y": 625, + "width": 0, + "height": 140, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1032, + "version": 2, + "versionNonce": 1839561492, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aW", + "created": null + }, + { + "id": "hermes-33", + "type": "text", + "x": 326, + "y": 693, + "width": 160, + "height": 30, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1033, + "version": 56, + "versionNonce": 58619436, + "isDeleted": false, + "boundElements": [], + "updated": 1793913760391, + "link": null, + "locked": false, + "text": "reads / writes", + "originalText": "reads / writes", + "fontSize": 19, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aX", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-34", + "type": "arrow", + "x": 890, + "y": 625, + "width": 0, + "height": 140, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1034, + "version": 2, + "versionNonce": 183302292, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "aY", + "created": null + }, + { + "id": "hermes-35", + "type": "text", + "x": 725, + "y": 698, + "width": 160, + "height": 30, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1035, + "version": 25, + "versionNonce": 1899032364, + "isDeleted": false, + "boundElements": [], + "updated": 1793913761974, + "link": null, + "locked": false, + "text": "reads / writes", + "originalText": "reads / writes", + "fontSize": 19, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aZ", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-36", + "type": "text", + "x": 170, + "y": 938, + "width": 1020, + "height": 40, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1036, + "version": 2, + "versionNonce": 1567147540, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Same Hermes loop implementation; separate agent instances and conversations.", + "originalText": "Same Hermes loop implementation; separate agent instances and conversations.", + "fontSize": 22, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "aa", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-37", + "type": "text", + "x": 170, + "y": 985.375, + "width": 1020, + "height": 26.25, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1037, + "version": 11, + "versionNonce": 441814188, + "isDeleted": false, + "boundElements": [], + "updated": 1793913780979, + "link": null, + "locked": false, + "text": "Stopping the Fabric runtime stops both paths and their owned work.", + "originalText": "Stopping the Fabric runtime stops both paths and their owned work.", + "fontSize": 21, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "ab", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-38", + "type": "rectangle", + "x": 580, + "y": 1090, + "width": 500, + "height": 65, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "white", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1038, + "version": 2, + "versionNonce": 1510925204, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "index": "ac", + "created": null + }, + { + "id": "hermes-39", + "type": "text", + "x": 590, + "y": 1098, + "width": 480, + "height": 49, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1039, + "version": 2, + "versionNonce": 1030868908, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Configured model endpoint", + "originalText": "Configured model endpoint", + "fontSize": 23, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "ad", + "created": null, + "labelPosition": null, + "baseFontSize": null + }, + { + "id": "hermes-40", + "type": "arrow", + "x": 200, + "y": 625, + "width": 450, + "height": 465, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1040, + "version": 2, + "versionNonce": 1729450260, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 425 + ], + [ + 450, + 425 + ], + [ + 450, + 465 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "ae", + "created": null + }, + { + "id": "hermes-41", + "type": "arrow", + "x": 1135, + "y": 625, + "width": 125, + "height": 465, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1041, + "version": 2, + "versionNonce": 1014168108, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 425 + ], + [ + -125, + 425 + ], + [ + -125, + 465 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": false, + "index": "af", + "created": null + }, + { + "id": "hermes-42", + "type": "text", + "x": 1360, + "y": 695, + "width": 340, + "height": 100, + "angle": 0, + "strokeColor": "#3b424b", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1042, + "version": 2, + "versionNonce": 871501460, + "isDeleted": false, + "boundElements": [], + "updated": 1793909002299, + "link": null, + "locked": false, + "text": "Native requests bypass\nFabric Runtime.invoke()", + "originalText": "Native requests bypass\nFabric Runtime.invoke()", + "fontSize": 20, + "fontFamily": 2, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "autoResize": false, + "lineHeight": 1.25, + "index": "ag", + "created": null, + "labelPosition": null, + "baseFontSize": null + } + ], + "appState": { + "gridSize": 20, + "gridStep": 5, + "gridModeEnabled": false, + "viewBackgroundColor": "#ffffff", + "lockedMultiSelections": {} + }, + "files": {} +} \ No newline at end of file diff --git a/assets/hermes-runtime-invocation.png b/assets/hermes-runtime-invocation.png new file mode 100644 index 000000000..7b932b7a9 Binary files /dev/null and b/assets/hermes-runtime-invocation.png differ diff --git a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json index 84af8a6e8..b47657f0e 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/docs/index.yml b/docs/index.yml index a54dbeca5..97c5d7d05 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -76,6 +76,8 @@ navigation: path: ./integrations/harness/droid.mdx - page: Hermes Agent path: ./integrations/harness/hermes.mdx + - page: Hermes Native Interfaces + path: ./integrations/harness/hermes-interfaces.mdx - page: LangChain Deep Agents path: ./integrations/harness/deepagents.mdx - page: Kilo Code diff --git a/docs/integrations/harness/hermes-interfaces.mdx b/docs/integrations/harness/hermes-interfaces.mdx new file mode 100644 index 000000000..1fe7c0bfc --- /dev/null +++ b/docs/integrations/harness/hermes-interfaces.mdx @@ -0,0 +1,169 @@ +--- +title: "Hermes Native Interfaces" +description: "Run Hermes native interfaces alongside SDK invocations, with shared configuration and distinct conversations." +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +NVIDIA NeMo Fabric can start Hermes's native API server and dashboard alongside its embedded SDK agent. One NeMo Fabric runtime owns these execution paths, while each retains its own agent instances and conversations. Start with the [Hermes adapter guide](./hermes.mdx) for installation and normalized SDK configuration. + +## 1. Overview + +The following diagram shows the two invocation paths within one runtime. + +![One NeMo Fabric runtime owns an embedded Hermes agent and a managed Hermes Gateway. SDK calls use the embedded agent; native clients use gateway agents with separate conversations. The dashed TUI path is proposed.](../../../assets/hermes-runtime-invocation.png) + +The TUI path is proposed; the adapter currently exposes API and dashboard settings only. + +| Path | Execution | Conversation and result | +| --- | --- | --- | +| `Runtime.invoke()` or `Runtime.invoke_stream()` | The embedded Hermes `AIAgent` in the adapter host | Reuses the NeMo Fabric conversation and produces a normalized NeMo Fabric `RunResult`; for streaming, retrieve it through `stream.result()`. | +| Native API | Hermes creates gateway-side agent instances | Uses native conversations and returns native API responses. | +| Browser chat | Hermes's dashboard and native gateway facilities | Uses native conversation behavior and browser responses. | + +These agents run the same Hermes agent-loop implementation. Sharing a Hermes home gives them access to persisted resources; it does not combine their live state or attach a native conversation to NeMo Fabric's embedded conversation. + +### What NeMo Fabric Normalizes + +| Surface | SDK invocation | Native interfaces | +| --- | --- | --- | +| Configuration | Mapped from `FabricConfig` | Managed child processes receive the same behavioral mapping and generated native configuration. | +| Lifecycle | Managed by the runtime | The adapter starts and stops its child processes. Descendant cleanup and independently started gateways have limits described below. | +| Results | Normalized `RunResult`, including available usage and artifact references | Native responses are not converted into NeMo Fabric `RunResult` objects. | +| Relay evidence | Standard Relay artifacts and invocation telemetry references | Supported native events use Relay's standard formats and native session identities. Emitting those records does not create a normalized invocation result. | +| Session artifacts | Collected through the SDK invocation path | Native session storage is shared, but session-scoped collection into NeMo Fabric's artifact model remains separate work. | + +## 2. Configuration + +### Prerequisites + +Both interfaces are optional and require a POSIX host. The API server needs `aiohttp` from Hermes's `messaging` extra. The dashboard needs a built frontend at `HERMES_WEB_DIST` or `hermes_cli/web_dist`; browser chat also needs Hermes's built terminal UI bundle. The adapter does not build these frontends. Windows startup fails with `hermes_interfaces_unsupported_platform` before native setup. + +### Enable Native Interfaces + +Select interfaces through the Hermes adapter's `harness.settings`: + +```python +from nemo_fabric import HarnessConfig + +harness = HarnessConfig( + adapter_id="nvidia.fabric.hermes", + settings={ + "interfaces": { + "api": {"port": 8642}, + "dashboard": {"port": 9119}, + }, + "startup_timeout_seconds": 60, + }, +) +``` + +Use this harness selection with the rest of your `FabricConfig`. The model, instructions, tools, MCP, skills, workspace, and telemetry remain in their existing normalized configuration fields; do not duplicate them under `interfaces`. + +| Setting | Default | Behavior | +| --- | --- | --- | +| `interfaces.api` | Absent | API settings: required integer `port` from 1 through 65535, optional `enabled` boolean defaulting to `true`. | +| `interfaces.dashboard` | Absent | Dashboard settings with the same `port` and `enabled` requirements. | +| `startup_timeout_seconds` | `60` | Positive budget of at most 75 seconds, counted from the beginning of runtime startup. | + +An absent interface is off. A present interface is on unless `enabled` is `false`; its closed schema currently requires a port even when disabled. Choose distinct, available ports for enabled interfaces. Ports bind to loopback in the adapter environment. No terminal interface setting is implemented yet. + +## 3. Access and Use + +### API Access + +The API server binds to `127.0.0.1` at its configured port. After every enabled interface passes readiness, the adapter writes a per-start bearer token with mode `0600` to: + +```text +/.fabric/hermes/runtimes//interfaces/api.token +``` + +Clients calling the native API must read the generated token file and include `Authorization: Bearer ` in each HTTP request. Only the API gateway child receives it in its environment. Processes running as the runtime's user, including agent tools, can read the token file. + +### Dashboard Access + +Open the configured loopback port in a browser. The dashboard has no sign-in: Hermes embeds its session token in the page, so anyone who can reach that port can use its pages and browser chat. The adapter does not disable individual dashboard pages. + +### Conversations and Responses + +Ordered SDK invocations reuse the embedded agent's conversation. Native clients use Hermes's native session mechanisms and receive native responses; these do not pass through `Runtime.invoke()` or become NeMo Fabric `RunResult` objects. + +The runtime's Hermes home is stored under `/.fabric/hermes/runtimes/`. Sharing that home gives access to persisted resources, but does not select a shared live conversation or establish cross-runtime resume. + +## 4. What NeMo Fabric Manages + +### Configuration Mapping and Precedence + +NeMo Fabric resolves `FabricConfig` into a validated `AgentConfig`. The adapter uses it for the embedded agent and for agent instances created inside managed native processes. Instructions, enabled and blocked toolsets, turn limit, token limit, temperature, top-p, reasoning configuration, and trajectory settings use the same behavioral mapping. + +Instructions and behavioral values configured by NeMo Fabric take precedence over native constructor defaults. Explicit `tools.enabled` (including an empty list) overrides native tool selection; a nonempty `tools.blocked` overrides native exclusions. When these policies are unspecified, native interface tool defaults remain in effect; the embedded SDK path retains its existing CLI defaults. Set both policies explicitly when comparing tool parity. Native routing, conversation identity, execution, and protocol remain Hermes behavior. The model credential is supplied through the child's environment. For OpenAI without an explicit `base_url`, managed children discard inherited `OPENAI_BASE_URL` so it cannot redirect the configured credential. An explicit endpoint uses the generated native model routing. Refer to [Implementation Details](#7-implementation-details) for the generated files and launcher mechanism. + +### Startup, Readiness, and Shutdown + +Startup launches enabled interfaces as child processes on the adapter's interpreter. The API server must pass `GET /health`, and the dashboard must pass `GET /api/status`, within the remaining startup budget. An occupied port, early child exit, or readiness timeout fails startup. Failed startup attempts clean up the children they started. + +Stop removes the API token, sends SIGTERM to running interface process groups, and escalates to SIGKILL after a five-second grace. The API gateway is configured with a three-second drain for API work and cron jobs. The agent configuration snapshot is removed during cleanup, and the adapter closes the embedded agent and session database. If token or snapshot deletion fails, the adapter logs the error and continues stopping children; a later stop retries removal. + +### Relay Evidence and Artifact Boundaries + +Enable Relay through the normal NeMo Fabric telemetry configuration. The embedded and managed native paths receive the generated Relay plugin configuration. Native sessions retain their own trace roots rather than being assigned to the embedded NeMo Fabric invocation. + +For SDK invocations, the adapter finalizes the Hermes Relay session and flushes subscribers before returning, so available ATOF/ATIF artifacts are complete at the invocation boundary. Managed native API turns also finalize and flush a Relay segment when execution returns. This makes ATIF available per turn without deleting the native conversation; subsequent turns can continue it and produce separate segments. Export failures are logged, so consumers must verify artifact contents. With a live Relay runtime, Hermes emits `compaction` when tracked compaction rewrites history or provider state; `compaction.attempt` describes an attempt that is blocked, skipped, fails, or aborts without a rewrite. + +Native API responses remain native responses. Relay's standard artifact format provides common execution evidence, but does not by itself provide NeMo Fabric result normalization, complete usage accounting, or session-scoped collection of native transcripts and generated files. + +## 5. Testing + +See the [Hermes interfaces example](../../../examples/interfaces/README.md) for setup, manual testing, output verification, and Relay trajectory inspection. + +## 6. Limitations and Planned Work + +### Operational Limits + +- Denied process-group signals fall back to the direct child. This does not guarantee that all descendants have stopped. +- The adapter does not restart an interface child after a crash. Dashboard gateway actions can start processes outside the adapter launcher and its configuration mapping. +- Filesystem permission errors can leave the token or configuration snapshot on disk after stop. Child shutdown continues, and removal is retried on a later stop; inspect cleanup errors and remove retained files after correcting permissions. +- Readiness currently checks the HTTP response without verifying that the child owns the listening port. +- NeMo Fabric's `check()` reports embedded SDK agent health and activity only. It does not aggregate native interface health or active native turns. Startup probes check API `/health` and dashboard `/api/status`; the adapter does not monitor child health continuously. +- There is no unified inventory of all agent instances in a runtime. SDK invocation tracking covers SDK requests; native API run status and persisted sessions are exposed through Hermes endpoints. Persisted sessions do not identify all live agent objects, which can exist only for a turn. +- Child processes inherit the embedded adapter's `HERMES_YOLO_MODE` environment setting. Interactive approval behavior requires separate review and validation. +- Native responses and complete usage accounting are not normalized into NeMo Fabric invocation results by these interfaces. + +### Unqualified Paths + +The API configuration-parity tests do not qualify browser interaction, explicit resume, or gateway replacement. Each needs its own behavioral and lifecycle evidence. + +The no-URL OpenAI regression checks child environment isolation with a mocked embedded constructor, not provider authentication or a live request to OpenAI. Hosted-model tests use an explicit OpenAI-compatible endpoint; provider login and fallback routing without an explicit endpoint require separate qualification. + +### Planned Work + +Native TUI support remains proposed and is shown as a dashed path in the diagram. Session-scoped collection of native transcripts and generated files into NeMo Fabric's artifact model remains separate work; standard Relay formatting alone does not provide it. + +Add runtime-wide health and discovery that covers the embedded agent and managed native interfaces. Report process health and readiness separately from active runs and persisted sessions, include child failures and native activity in aggregate status, and provide a way to discover native runs and sessions alongside SDK invocations. Hermes's authenticated `/health/detailed`, `/v1/runs/{run_id}`, and `/api/sessions` endpoints provide native diagnostics today; they do not provide a unified NeMo Fabric inventory. + +Follow-up lifecycle work should verify listener ownership during readiness, strengthen descendant cleanup when process-group signals are denied, and define ownership and configuration guarantees for gateway replacement. Qualify interactive approvals and browser chat separately before extending their support claims. Cross-runtime resume and SDK/native conversation handoff remain deferred. + +## 7. Implementation Details + +### Generated Files and Environment + +The adapter prepares three configuration surfaces from the resolved `AgentConfig` for managed native children: + +| Surface | Contents | Delivery | +| --- | --- | --- | +| Hermes `config.yaml` | Native model routing, workspace, MCP servers, skills, plugins, and toolset configuration | Written in the runtime's Hermes home, selected through `HERMES_HOME`. | +| `interfaces/agent-config.json` | The validated agent configuration, including instructions and behavioral settings | Owner-only snapshot passed by path to the adapter-owned native launcher. Removed on stop. | +| Relay plugin configuration | Resolved Relay components and output configuration | Generated by the adapter; its path is passed through `HERMES_NEMO_RELAY_PLUGINS_TOML`. | + +The model credential value is supplied through the child's environment; the native model configuration references `api_key_env`. + +Children inherit the adapter host's environment after ambient `API_SERVER_*` variables are removed. When the API interface is enabled, the generated configuration explicitly disables other known gateway platforms and profile multiplexing. Inherited settings such as `TELEGRAM_BOT_TOKEN` or `WEBHOOK_ENABLED` therefore do not start messaging adapters or their dependency installers. This restriction applies to the managed runtime home; independently launched gateways outside that home retain their own configuration. + +### Native Launcher and Constructor Mapping + +Hermes v0.22.5's API constructor does not read every behavioral setting from `config.yaml`. The adapter therefore launches managed children through `nemo_fabric_adapters.hermes.native`, which installs a process-local subclass of Hermes's `AIAgent` before entering the native CLI. + +The subclass applies the shared behavioral mapping before calling the native constructor. It preserves native routing and session identity and does not modify the installed Hermes source. + +This mapping applies within adapter-launched processes. A gateway independently spawned by Hermes does not automatically inherit the constructor mapping, even if it uses the same home. Sharing a configuration directory alone does not establish configuration parity. + diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index e0eef5556..ac5306062 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -1,115 +1,101 @@ --- title: "Use the Hermes Agent Adapter" -description: "Install and configure the NeMo Fabric harness integration for Hermes Agent." +description: "Configure Hermes Agent, understand its invocation paths, and serve native interfaces with NeMo Fabric." --- {/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} -The NVIDIA NeMo Fabric `nvidia.fabric.hermes` adapter runs Hermes Agent through -its Python SDK. The adapter maps normalized NeMo Fabric configuration into -Hermes Agent models, tools, skills, Model Context Protocol (MCP) servers, -sessions, and Relay telemetry. +The NVIDIA NeMo Fabric `nvidia.fabric.hermes` adapter runs Hermes Agent through its Python SDK. It maps normalized configuration into an embedded agent, reuses its conversation across ordered invocations, and returns normalized results and telemetry references. + +For native API and browser access, invocation-path diagrams, and shared configuration behavior, see [Hermes native interfaces](./hermes-interfaces.mdx). ## Install the Adapter -The adapter package supports Python 3.11 through 3.14. Use [Hermes Agent v0.22.5](https://github.com/NousResearch/hermes-agent/releases/tag/v0.22.5) with Python 3.14. This release includes dependency security fixes absent from v2026.9.24 and supports Relay telemetry and streaming. Hermes Agent 0.20 and later is not installable from PyPI. Follow the [Hermes Agent installation guide](https://hermes-agent.nousresearch.com/docs/installation) and select v0.22.5. +Use [Hermes Agent v0.22.5](https://github.com/NousResearch/hermes-agent/releases/tag/v0.22.5) with Python 3.14. The adapter package supports Python 3.11 through 3.14, but Hermes Agent must be installed separately from source; versions 0.20 and later are not available from PyPI. Follow the [Hermes Agent installation guide](https://hermes-agent.nousresearch.com/docs/installation) and select v0.22.5. -Install the NeMo Fabric runtime and bare Hermes adapter into the Python -environment that runs Hermes Agent: +Install the runtime and adapter in the environment that runs Hermes: ```bash -pip install "nemo-fabric[hermes-agent]" +python -m pip install "nemo-fabric[hermes-agent]" ``` -These packages do not install Hermes Agent. If a different environment runs -NeMo Fabric, install only the bare adapter in the Hermes Agent environment: - -```bash -python -m pip install nemo-fabric-adapters-hermes -``` +If the application runs NeMo Fabric in a separate environment, install `nemo-fabric-adapters-hermes` in the Hermes environment and set `ADAPTER_PYTHON` in the application's environment to that interpreter. Use matching runtime and adapter release versions unless a different pairing has been validated. -The adapter's `relay` and `full` extras install `nemo-relay>=0.10,<0.11`. Install Hermes Agent separately in the same environment. Keep that environment separate from applications that use Relay 0.11 for other NeMo Fabric adapters. The adapter reports a compatibility error at startup if Relay telemetry is enabled with an unsupported Hermes or Relay installation. +For Relay, install the adapter's `relay` extra in the Hermes environment. It requires `nemo-relay>=0.10,<0.11`; keep this environment separate from applications using Relay 0.11 for other adapters. Startup rejects unsupported Hermes/Relay combinations. -For local NeMo Fabric development, run the following command from the repository root. The recipe checks out Hermes Agent v0.22.5 at commit `bf0203a794a07aac3ff764972ab9087baa4e4f4e` and creates an isolated Python 3.14 environment with the adapter's `relay` extra. Hermes declares its Python package version as `0.0.0`; use the Git tag and commit to identify the release when reviewing scanner results. +For repository development, the following recipe checks out v0.22.5 at `bf0203a794a07aac3ff764972ab9087baa4e4f4e` and prepares an isolated Python 3.14 environment with Relay support: ```bash just install-hermes-agent export ADAPTER_PYTHON="$PWD/.venv-hermes/bin/python" ``` -For separate environments, set `ADAPTER_PYTHON` in the runtime environment to -the adapter environment's Python interpreter. Use -matching NeMo Fabric release versions for the runtime and adapter package -unless a different pairing has been explicitly validated. +The installer preserves local checkout changes and stops rather than overwriting them. Set `HERMES_AGENT_CHECKOUT` to a separate clean checkout or a new directory to install without changing `external/hermes-agent`; the target environment remains `.venv-hermes`. + +Hermes reports its Python package version as `0.0.0`, so use its Git tag and commit to identify the installed release. The pinned release includes dependency security fixes absent from v2026.9.24. ## Configure the Adapter -Select the Hermes Agent harness integration in `HarnessConfig`: +Use normalized `FabricConfig` fields for the model, instructions, tools, skills, MCP servers, workspace, turn limit, and telemetry. Use `harness.settings` for Hermes-specific options and native interface selection. -```python -from nemo_fabric import HarnessConfig +The following example configures an embedded SDK agent with file tools: -harness = HarnessConfig(adapter_id="nvidia.fabric.hermes") +```python +from nemo_fabric import FabricConfig + +config = FabricConfig.from_mapping( + { + "metadata": {"name": "hermes-agent"}, + "harness": { + "adapter_id": "nvidia.fabric.hermes", + }, + "models": { + "default": { + "provider": "openai", + "model": "your-model", + "base_url": "https://MODEL_HOST/v1", + "api_key_env": "MODEL_API_KEY", + "temperature": 0.0, + "top_p": 0.9, + "max_tokens": 1024, + } + }, + "instructions": { + "system": {"mode": "replace", "content": "Help with files in the workspace."} + }, + "tools": {"enabled": ["file"], "blocked": ["terminal"]}, + "runtime": {"max_turns": 8}, + "environment": {"provider": "local", "workspace": "."}, + } +) ``` -Use normalized `FabricConfig` fields to configure the model, workspace, skills, -MCP servers, replacement system instructions, turn limit, and native tool -selectors, and telemetry. The adapter rejects `append` system instructions. - -During run-plan resolution, NeMo Fabric Core validates the -`models..top_p` (from 0 through 1) and positive -`models..max_tokens` fields against the Hermes descriptor before -runtime startup. Hermes reads these prevalidated values from `AgentConfig`. A -model-level `max_tokens` overrides the harness-level default for the selected -model role. +Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter environment before starting. To add native API or browser access, follow the [Hermes native interfaces guide](./hermes-interfaces.mdx). -The Hermes descriptor validates the following `harness.settings` fields: +The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over the harness-level default. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. -| Setting | Type | Default | Description | -| --- | --- | --- | --- | -| `reasoning_config` | object | `{"effort": "none"}` | Configures Hermes model reasoning. The closed object accepts an optional `enabled` boolean and an optional `effort` value of `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. | -| `plugins_enabled` | array of nonempty strings | `[]` | Enables Hermes plugins by identifier. Relay telemetry uses the generated `plugins.toml`; do not list the removed `observability/nemo_relay` plugin. | -| `save_trajectories` | boolean | `false` | Enables Hermes-native JSONL conversation trajectory saving. This is separate from normalized NeMo Fabric telemetry. | -| `max_tokens` | positive integer | `512` | Limits the number of tokens in each Hermes model response. | -| `terminal_timeout` | positive number | `60` | Limits a Hermes terminal operation in seconds. | +### Hermes Settings -For example: +The descriptor uses closed schemas, so unknown settings are rejected. -```python -from nemo_fabric import HarnessConfig - -harness = HarnessConfig( - adapter_id="nvidia.fabric.hermes", - settings={ - "reasoning_config": {"enabled": True, "effort": "medium"}, - "plugins_enabled": ["disk-cleanup"], - "save_trajectories": True, - "max_tokens": 1024, - "terminal_timeout": 90, - }, -) -``` +| Setting | Default | Behavior | +| --- | --- | --- | +| `reasoning_config` | `{"effort": "none"}` | Optional `enabled` boolean and `effort`: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. | +| `plugins_enabled` | `[]` | List of nonempty native plugin identifiers. Relay uses its generated plugin configuration; do not list the removed `observability/nemo_relay` plugin. | +| `save_trajectories` | `false` | Save native JSONL trajectories; separate from normalized telemetry. | +| `max_tokens` | `512` | Positive response-token limit when the selected model has no limit. | +| `terminal_timeout` | `60` | Positive timeout in seconds for a Hermes terminal tool operation; this does not enable a TUI. | -Use `runtime.max_turns` to set the Hermes agent-loop budget. The adapter maps -that normalized field to `AIAgent.max_iterations`; `max_iterations` is not a -Hermes harness setting. +Native interface settings are documented in the [Hermes native interfaces guide](./hermes-interfaces.mdx#enable-native-interfaces). ## Understand the Runtime Lifecycle -Each NeMo Fabric runtime creates one Hermes Agent `AIAgent` and one `SessionDB`. -Ordered invocations reuse those objects and the conversation history until the -runtime stops. The adapter finalizes and flushes Relay subscriber output after -each invocation so ATOF and ATIF artifacts are complete when it returns. - -With a live Relay runtime, Hermes emits `compaction` when a tracked compaction -rewrites history or provider state. It emits `compaction.attempt` when the -attempt is blocked, skipped, fails, or aborts without a rewrite. +Each runtime creates one embedded Hermes `AIAgent` and one `SessionDB`. Ordered SDK invocations reuse these objects and their conversation history until stop closes them. The Hermes home is stored under `/.fabric/hermes/runtimes/`; retaining files does not by itself establish cross-runtime conversation resume. -For the complete configuration and lifecycle reference, refer to the -[Hermes Agent adapter guide](https://github.com/NVIDIA/NeMo-Fabric/tree/main/adapters/python/hermes). +SDK invocations return normalized NeMo Fabric `RunResult` objects. The adapter finalizes the Hermes Relay session and flushes subscribers before returning, so available ATOF/ATIF artifacts are complete at that invocation boundary. Native interface responses follow a different path, described in [What NeMo Fabric Normalizes](./hermes-interfaces.mdx#what-nemo-fabric-normalizes). ## Runtime Health -`Fabric.check()` supports `live`, `active`, and `ready`. The adapter checks native agent and database ownership, the initialized invocation interface, and a fresh `get_activity_summary()` diagnostic response. +`Fabric.check()` supports `live`, `active`, and `ready`. It checks the embedded agent's session/database ownership, invocation interface, and a fresh `get_activity_summary()` diagnostic response. These checks do not establish native interface-child health after startup. -Refer to the [SDK health-check overview](../../sdk/health-checks.mdx) for shared behavior and a comparison of native evidence across adapters. +Refer to the [SDK health-check overview](../../sdk/health-checks.mdx) and the [Hermes adapter reference](https://github.com/NVIDIA/NeMo-Fabric/tree/main/adapters/python/hermes) for additional details. diff --git a/examples/README.md b/examples/README.md index 1165d5868..265d780ba 100644 --- a/examples/README.md +++ b/examples/README.md @@ -48,6 +48,10 @@ Pi's startup `model_redirect` marks are not included in `atof_records`. The [OpenShell Code Review example](code_review_agent/README.md#run-hermes-in-openshell) packages Hermes Agent inside the sandbox and uses the normal SDK/provider lifecycle from the host. It runs two review turns and can collect NeMo Relay evidence. +## Native Interfaces + +[`interfaces`](interfaces/README.md) demonstrates native harness interfaces alongside a Fabric-managed runtime. Start with the Hermes API example: submit a file task through the native API, verify the generated file, and inspect Relay ATOF events and ATIF tool steps. + ## LangGraph Custom Agent [`langgraph_custom_agent`](langgraph_custom_agent/README.md) demonstrates how diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index 84af8a6e8..b47657f0e 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/examples/interfaces/README.md b/examples/interfaces/README.md new file mode 100644 index 000000000..31dea54b8 --- /dev/null +++ b/examples/interfaces/README.md @@ -0,0 +1,96 @@ + + +# NVIDIA NeMo Fabric Native Interface Examples + +This example is a work in progress. Its structure and user experience will be reworked as part of OpenClaw TUI support. + +Use native harness interfaces alongside a NeMo Fabric-managed runtime. Each harness example uses the public Python SDK for configuration and lifecycle, then sends input through the harness's native interface. + +## Hermes API and Relay + +[`hermes.py`](hermes.py) starts one managed Hermes API server, submits a real file task, verifies the generated file, and checks Relay ATOF events and ATIF tool steps. Its API response remains native; the SDK manages the runtime but does not convert this response into a NeMo Fabric `RunResult`. + +### Prepare the Environment + +Follow the [Hermes adapter installation guide](../../docs/integrations/harness/hermes.mdx#install-the-adapter). For source development, run from the repository root: + +```bash +just install-hermes-agent +export ADAPTER_PYTHON="$PWD/.venv-hermes/bin/python" +``` + +This prepares pinned Hermes v0.22.5, the adapter, and Relay 0.10. The application interpreter also needs the NeMo Fabric SDK. The command below uses the prepared Hermes environment for both application and adapter. + +Set your OpenAI-compatible model endpoint, served model name, and credential: + +```bash +export MODEL_BASE_URL="https://MODEL_HOST/v1" +export MODEL_NAME="YOUR_SERVED_MODEL_NAME" +export MODEL_API_KEY="YOUR_MODEL_API_KEY" +``` + +Use HTTPS for remote endpoints that receive credentials. For a local server, use a loopback URL such as `http://127.0.0.1:8000/v1`; an authenticated encrypted tunnel is another option. Use the credential value required by your endpoint. An endpoint without authentication can use a nonempty placeholder credential. To reference an existing credential variable instead, pass its name with `--api-key-env`. + +### Run a Real Task + +Run the example from the repository root: + +```bash +.venv-hermes/bin/python examples/interfaces/hermes.py \ + --base-url "$MODEL_BASE_URL" \ + --model "$MODEL_NAME" \ + --port 8642 +``` + +The example copies sample release notes into a new workspace, asks the native API to read them and write a rollout checklist, and stops the runtime. To use your own notes, add `--input-file /path/to/release-notes.md`. `--output-dir` selects a new evidence directory; the example refuses to overwrite an existing directory. `--keep-running` leaves the API available for additional requests until you press Enter. + +The model and port must be reachable from the adapter environment. The native API binds to loopback and uses a generated bearer token; the example reads the token file and sends the header without printing the token. + +The example prints its evidence directory and checks that: + +- The output file exists and is nonempty. +- ATOF records show `read_file` and `write_file` execution. +- A populated ATIF trajectory contains those tool steps. +- Stop removes the API token. + +It exits unsuccessfully if any check fails. An ATOF file alone does not establish ATIF export. + +### Inspect the Result and Trajectory + +Set `RUN_DIR` to the evidence directory printed by the example: + +```bash +RUN_DIR="outputs/interfaces/" +cat "$RUN_DIR/workspace/rollout-checklist.md" +jq . "$RUN_DIR/summary.json" + +ATIF=$(jq -r '.atif_files[0]' "$RUN_DIR/summary.json") +jq -r '.steps[] | + [.step_id, .source, ((.tool_calls // []) | map(.function_name) | join(","))] | + @tsv' "$ATIF" +``` + +For this task, expect user input, an agent `read_file` step with its observation, an agent `write_file` step with its observation, and a final response. Inspect complete tool arguments and observations with: + +```bash +jq '.steps[] | select(.tool_calls != null) | + {tool_calls, observation}' "$ATIF" +``` + +To inspect the raw event sequence: + +```bash +ATOF=$(jq -r '.atof_files[0]' "$RUN_DIR/summary.json") +jq -r 'select(.kind == "scope" and + (.category == "llm" or .category == "tool")) | + [.timestamp, .scope_category, .category, .name] | @tsv' "$ATOF" +``` + +### ATIF Finalization and Limits + +The pinned Hermes API path leaves its Relay conversation scope open after a turn. ATOF events can therefore exist without ATIF export. The managed native launcher finalizes and flushes an API turn's Relay segment when execution returns, including failed turns. It does not fire native conversation-end plugin hooks or delete conversation state. The conversation can continue; subsequent turns create new Relay segments and ATIF files. Finalization errors are logged without replacing the execution outcome, so consumers should check their artifacts explicitly. + +This example exercises the managed API path. It does not qualify browser chat, TUI, independently restarted gateways, approvals, or complete native-result and artifact normalization. Refer to [Hermes Native Interfaces](../../docs/integrations/harness/hermes-interfaces.mdx) for the configuration and ownership boundaries. diff --git a/examples/interfaces/hermes.py b/examples/interfaces/hermes.py new file mode 100644 index 000000000..8f8a6c8a7 --- /dev/null +++ b/examples/interfaces/hermes.py @@ -0,0 +1,224 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Run a file task through a managed Hermes API and inspect Relay evidence.""" + +from __future__ import annotations + +import argparse +import asyncio +import json +import os +import sys +import uuid +from datetime import datetime, timezone +from pathlib import Path +from urllib.error import URLError +from urllib.request import Request, urlopen + +from nemo_fabric import Fabric +from nemo_fabric import FabricConfig +from nemo_fabric import RelayAtifConfig +from nemo_fabric import RelayAtofConfig +from nemo_fabric import RelayAtofFileSinkConfig +from nemo_fabric import RelayObservabilityConfig + +SAMPLE_NOTES = """Release changes: +- API authentication requires a bearer token. +- Dashboard binds to loopback. +- Runtime restart creates a new API token. +- File tools remain enabled; shell execution is disabled. +""" + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--base-url", default=os.environ.get("MODEL_BASE_URL")) + parser.add_argument("--model", default=os.environ.get("MODEL_NAME")) + parser.add_argument("--api-key-env", default="MODEL_API_KEY") + parser.add_argument("--port", type=int, default=8642) + parser.add_argument( + "--input-file", type=Path, help="Release notes; defaults to a bundled sample" + ) + parser.add_argument( + "--output-dir", type=Path, help="New directory for workspace and evidence" + ) + parser.add_argument( + "--keep-running", + action="store_true", + help="Keep the API open for manual requests until Enter", + ) + args = parser.parse_args() + if not args.base_url or not args.model: + parser.error("set --base-url and --model, or MODEL_BASE_URL and MODEL_NAME") + if not os.environ.get(args.api_key_env): + parser.error( + f"set the model credential environment variable {args.api_key_env}" + ) + if not 1 <= args.port <= 65535: + parser.error("--port must be between 1 and 65535") + return args + + +def call_api(url: str, token: str, prompt: str) -> dict: + request = Request( + url + "/v1/chat/completions", + data=json.dumps( + {"model": "hermes-agent", "messages": [{"role": "user", "content": prompt}]} + ).encode(), + headers={ + "Authorization": f"Bearer {token}", + "Content-Type": "application/json", + }, + ) + with urlopen(request, timeout=180) as response: + return json.load(response) + + +async def run(args: argparse.Namespace) -> None: + run_name = ( + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S") + + "-" + + uuid.uuid4().hex[:8] + ) + output = (args.output_dir or Path("outputs/interfaces") / run_name).resolve() + output.mkdir(parents=True, exist_ok=False) + workspace = output / "workspace" + workspace.mkdir() + source = workspace / "release-notes.md" + source.write_text(args.input_file.read_text() if args.input_file else SAMPLE_NOTES) + checklist = workspace / "rollout-checklist.md" + relay = output / "relay" + config = FabricConfig.from_mapping( + { + "metadata": {"name": "hermes-interfaces-example"}, + "harness": { + "adapter_id": "nvidia.fabric.hermes", + "settings": {"interfaces": {"api": {"port": args.port}}}, + }, + "models": { + "default": { + "provider": "openai", + "model": args.model, + "base_url": args.base_url, + "api_key_env": args.api_key_env, + "temperature": 0.0, + "max_tokens": 2048, + } + }, + "instructions": { + "system": { + "mode": "replace", + "content": "Complete the requested workspace file task using file tools. Read source files before writing the answer file. Do not use shell or web tools. Summarize the actual result briefly.", + } + }, + "tools": {"enabled": ["file"], "blocked": ["terminal"]}, + "runtime": {"max_turns": 8}, + "environment": { + "provider": "local", + "workspace": str(workspace), + "artifacts": str(output / "artifacts"), + }, + } + ) + config.enable_relay( + output_dir=str(relay), + observability=RelayObservabilityConfig( + atof=RelayAtofConfig( + enabled=True, + sinks=[ + RelayAtofFileSinkConfig( + output_directory=str(relay / "atof"), + filename="events.atof.jsonl", + mode="append", + ) + ], + ), + atif=RelayAtifConfig(enabled=True, output_directory=str(relay / "atif")), + ), + ) + prompt = f"Read {source} and create {checklist} containing a concise five-item rollout validation checklist based on the release notes. Use file tools to read and write. Then report the created file path." + api = f"http://127.0.0.1:{args.port}" + print(f"Evidence directory: {output}", flush=True) + print("Starting managed Hermes API (startup budget: 60 seconds)...", flush=True) + async with await Fabric().start_runtime(config, base_dir=output) as runtime: + token_path = ( + output + / "artifacts/.fabric/hermes/runtimes" + / runtime.runtime_id + / "interfaces/api.token" + ) + print(f"API: {api}\nToken file: {token_path}", flush=True) + print("Running the file task (API request timeout: 180 seconds)...", flush=True) + response = await asyncio.to_thread( + call_api, api, token_path.read_text(), prompt + ) + (output / "response.json").write_text(json.dumps(response, indent=2) + "\n") + print(response["choices"][0]["message"]["content"], flush=True) + if args.keep_running: + await asyncio.to_thread( + input, "API remains available. Press Enter to stop: " + ) + + atof_files = sorted(relay.rglob("*.atof.jsonl")) + atif_files = sorted((relay / "atif").rglob("*.json")) + events = [ + json.loads(line) + for path in atof_files + for line in path.read_text().splitlines() + if line.strip() + ] + tools = sorted( + { + event["name"] + for event in events + if event.get("category") == "tool" + and event.get("scope_category") == "start" + } + ) + populated_atif = [ + path for path in atif_files if json.loads(path.read_text()).get("steps") + ] + atif_tools = { + call["function_name"] + for path in populated_atif + for step in json.loads(path.read_text())["steps"] + for call in step.get("tool_calls", []) + } + checks = { + "output_file_written": checklist.is_file() + and bool(checklist.read_text().strip()), + "file_tools_observed": {"read_file", "write_file"}.issubset(tools), + "atof_events_written": bool(events), + "atif_trajectory_written": bool(populated_atif), + "atif_tool_steps_written": {"read_file", "write_file"}.issubset(atif_tools), + "api_token_removed": not token_path.exists(), + } + summary = { + "runtime_id": runtime.runtime_id, + "output_file": str(checklist), + "atof_files": [str(p) for p in atof_files], + "atif_files": [str(p) for p in populated_atif], + "tools": tools, + "checks": checks, + } + (output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n") + print(json.dumps(summary, indent=2), flush=True) + if not all(checks.values()): + raise RuntimeError( + "Example checks failed; inspect summary.json. ATOF alone does not establish ATIF export." + ) + + +def main() -> int: + args = parse_args() + try: + asyncio.run(run(args)) + except (RuntimeError, OSError, URLError) as error: + print(f"Error: {error}", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/justfile b/justfile index c68730115..95eac0d96 100644 --- a/justfile +++ b/justfile @@ -398,7 +398,7 @@ install-hermes-agent: #!/usr/bin/env bash set -euo pipefail hermes_commit="bf0203a794a07aac3ff764972ab9087baa4e4f4e" - hermes_checkout="$REPO_ROOT/external/hermes-agent" + hermes_checkout="${HERMES_AGENT_CHECKOUT:-$REPO_ROOT/external/hermes-agent}" hermes_diff_pathspec=() if [[ -e "$hermes_checkout" && ! -d "$hermes_checkout/.git" ]]; then @@ -419,8 +419,8 @@ install-hermes-agent: if [[ "$hermes_head" != "$hermes_commit" ]]; then if [[ -n "$hermes_head" ]] && { ! git -C "$hermes_checkout" diff --quiet "${hermes_diff_pathspec[@]}" || ! git -C "$hermes_checkout" diff --cached --quiet; }; then echo "ERROR: Hermes Agent checkout has tracked changes at an unpinned revision: $hermes_checkout" >&2 - echo "If these are disposable changes from the old metadata-propagate.patch, run:" >&2 - echo " git -C \"$hermes_checkout\" restore --source=HEAD --staged --worktree -- ." >&2 + echo "Preserve local changes and select a separate checkout:" >&2 + echo ' HERMES_AGENT_CHECKOUT=/path/to/clean/hermes-agent just install-hermes-agent' >&2 exit 1 fi if ! git -C "$hermes_checkout" cat-file -e "$hermes_commit^{commit}" 2>/dev/null; then @@ -430,8 +430,8 @@ install-hermes-agent: fi if ! git -C "$hermes_checkout" diff --cached --quiet || ! git -C "$hermes_checkout" diff --quiet "${hermes_diff_pathspec[@]}"; then echo "ERROR: Hermes Agent checkout has tracked changes: $hermes_checkout" >&2 - echo "To discard only tracked changes that you do not need, run:" >&2 - echo " git -C \"$hermes_checkout\" restore --source=HEAD --staged --worktree -- ." >&2 + echo "Preserve local changes and select a separate checkout:" >&2 + echo ' HERMES_AGENT_CHECKOUT=/path/to/clean/hermes-agent just install-hermes-agent' >&2 exit 1 fi if [[ ! -x "$REPO_ROOT/.venv-hermes/bin/python" ]] || @@ -439,8 +439,12 @@ install-hermes-agent: uv venv --python 3.14 --clear "$REPO_ROOT/.venv-hermes" fi # Use the release lockfile, including upstream's security dependency overrides. + # From the messaging extra, install only aiohttp, which Hermes's API server needs. UV_PROJECT_ENVIRONMENT="$REPO_ROOT/.venv-hermes" uv sync \ - --project "$hermes_checkout" --frozen --no-default-groups --extra mcp \ + --project "$hermes_checkout" --frozen --no-default-groups --extra mcp --extra messaging \ + --no-install-package discord-py --no-install-package python-telegram-bot \ + --no-install-package slack-bolt --no-install-package slack-sdk \ + --no-install-package qrcode --no-install-package brotlicffi \ --config-settings-package hermes-agent:editable_mode=compat uv pip install --python "$REPO_ROOT/.venv-hermes/bin/python" \ --editable "$REPO_ROOT/sdk/python/nemo-fabric-evidence" \ @@ -453,7 +457,7 @@ install-hermes-agent: pytest pytest-asyncio pyyaml test-hermes: install-hermes-agent - .venv-hermes/bin/python -m pytest tests/adapters/test_hermes_adapter.py tests/adapters/test_hermes_config_builder.py tests/adapters/test_hermes_streaming.py tests/adapters/test_hermes_health.py tests/e2e/test_hermes_e2e.py tests/e2e/test_hermes_checks.py -q + .venv-hermes/bin/python -m pytest tests/adapters/test_hermes_adapter.py tests/adapters/test_hermes_config_builder.py tests/adapters/test_hermes_native_config.py tests/adapters/test_hermes_interfaces.py tests/adapters/test_hermes_streaming.py tests/adapters/test_hermes_health.py tests/e2e/test_hermes_e2e.py tests/e2e/test_hermes_checks.py -q # Build the TypeScript contract and adapter packages using their locked dependencies. build-typescript: install-typescript diff --git a/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json b/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json index 29b4508fe..cc44c9096 100644 --- a/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json +++ b/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json @@ -843,6 +843,55 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { + "interfaces": { + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes.", + "properties": { + "api": { + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token.", + "properties": { + "enabled": { + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false.", + "type": "boolean" + }, + "port": { + "description": "Exact loopback port for the API server. Start fails if it is in use.", + "maximum": 65535, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "port" + ], + "type": "object" + }, + "dashboard": { + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST.", + "properties": { + "enabled": { + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false.", + "type": "boolean" + }, + "port": { + "description": "Exact loopback port for the dashboard. Start fails if it is in use.", + "maximum": 65535, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "port" + ], + "type": "object" + } + }, + "type": "object" + }, "max_tokens": { "default": 512, "description": "Maximum number of tokens in each Hermes model response.", @@ -890,6 +939,13 @@ "description": "Whether Hermes saves its native conversation trajectories as JSONL.", "type": "boolean" }, + "startup_timeout_seconds": { + "default": 60, + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit.", + "exclusiveMinimum": 0, + "maximum": 75, + "type": "number" + }, "terminal_timeout": { "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation.", @@ -917,7 +973,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "6539b80cd3dbc76f2db58640bb957dcbe5f9e45421a2d7f9a45785325f354f38", + "sha256": "d69ab9ae7ccc76f30f70f94a924fd2796bcdffcc05560b1ac2c89dc49bf77ab2", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { diff --git a/tests/_utils/mock_api_server.py b/tests/_utils/mock_api_server.py index 020f2a341..65dbb82ea 100644 --- a/tests/_utils/mock_api_server.py +++ b/tests/_utils/mock_api_server.py @@ -1,6 +1,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 +import asyncio import json import threading import time @@ -18,7 +19,8 @@ def mock_api_server(port: int) -> Iterator[str]: Context manager for a mock API server. Use the /_requests endpoint to inspect captured chat-completion payloads after a test action. - Use the /_scenario endpoint to configure a status code or ordered tool calls for subsequent requests. + Use the /_scenario endpoint to configure a status code, a response delay, or ordered tool calls for subsequent requests. + Use the /_chat_authorization_headers endpoint to inspect the Authorization header of each chat-completion request. Use the /_reset endpoint to clear all retained request and scenario state. Args: @@ -33,6 +35,8 @@ def mock_api_server(port: int) -> Iterator[str]: def reset_state() -> None: app.state.requests = [] app.state.status_code = 200 + app.state.delay_seconds = 0.0 + app.state.chat_authorization_headers = [] app.state.tool_calls = [] app.state.tool_call_index = 0 app.state.mcp_authorization_headers = [] @@ -69,6 +73,7 @@ async def scenario(request: Request) -> dict[str, object]: payload = await request.json() app.state.status_code = int(payload.get("status_code", 200)) + app.state.delay_seconds = float(payload.get("delay_seconds", 0.0)) tool_call = payload.get("tool_call") app.state.tool_calls = payload.get("tool_calls") or ( [tool_call] if tool_call is not None else [] @@ -97,6 +102,10 @@ def reset() -> dict[str, str]: reset_state() return {"status": "ok"} + @app.get("/_chat_authorization_headers") + def chat_authorization_headers() -> list[str | None]: + return list(app.state.chat_authorization_headers) + @app.get("/_mcp_authorization_headers") def mcp_authorization_headers() -> list[str | None]: return list(app.state.mcp_authorization_headers) @@ -149,18 +158,26 @@ async def mcp(request: Request): async def chat_completions(request: Request): payload = await request.json() app.state.requests.append(payload) - if app.state.status_code != 200: + app.state.chat_authorization_headers.append( + request.headers.get("authorization") + ) + # Read the scenario before the delay, so a later /_scenario or /_reset + # doesn't change this response. + status_code = app.state.status_code + tool_call = next_tool_call(payload) if status_code == 200 else None + if app.state.delay_seconds: + await asyncio.sleep(app.state.delay_seconds) + if status_code != 200: return JSONResponse( - status_code=app.state.status_code, + status_code=status_code, content={ "error": { - "message": f"configured status {app.state.status_code}", + "message": f"configured status {status_code}", "type": "api_error", } }, ) - tool_call = next_tool_call(payload) if tool_call is not None: if payload.get("stream") is True: return StreamingResponse( diff --git a/tests/adapters/test_hermes_adapter.py b/tests/adapters/test_hermes_adapter.py index 964de3c56..f5041a48c 100644 --- a/tests/adapters/test_hermes_adapter.py +++ b/tests/adapters/test_hermes_adapter.py @@ -106,6 +106,28 @@ def test_validate_hermes_telemetry_provider_rejects_native(): ) +def test_native_relay_segment_does_not_fire_session_end_hooks(monkeypatch): + from agent import relay_runtime + from hermes_cli import lifecycle as hermes_lifecycle + from nemo_relay import subscribers + + coordinator = MagicMock() + finalize_session = MagicMock() + flush = MagicMock() + monkeypatch.setattr(relay_runtime, "SESSION_COORDINATOR", coordinator) + monkeypatch.setattr(relay_runtime, "current_profile_key", lambda: "test-profile") + monkeypatch.setattr(hermes_lifecycle, "finalize_session", finalize_session) + monkeypatch.setattr(subscribers, "flush", flush) + + telemetry.finalize_native_relay_segment("native-session") + + coordinator.finalize_conversation.assert_called_once_with( + profile_key="test-profile", session_id="native-session" + ) + flush.assert_called_once_with() + finalize_session.assert_not_called() + + def test_validate_hermes_telemetry_provider_rejects_mixed_native_and_relay(): with pytest.raises( ValueError, match="only relay telemetry is supported for Hermes" diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py new file mode 100644 index 000000000..67be36680 --- /dev/null +++ b/tests/adapters/test_hermes_interfaces.py @@ -0,0 +1,674 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Tests for Hermes's API server and dashboard served by a managed runtime.""" + +from __future__ import annotations + +import asyncio +import importlib.util +import json +import os +import socket +import sqlite3 +import sys +import time +from pathlib import Path +from unittest.mock import AsyncMock +from unittest.mock import MagicMock + +import pytest +import requests +from nemo_fabric import Fabric +from nemo_fabric import FabricConfig +from nemo_fabric.errors import FabricConfigError +from nemo_fabric_adapter_contract.models import AgentConfig +from nemo_fabric_adapter_contract.models import RuntimeContext + +pytestmark = pytest.mark.usefixtures("requires_hermes_agent") + +if importlib.util.find_spec("run_agent") is not None: + from nemo_fabric_adapters.hermes import adapter + from nemo_fabric_adapters.hermes import configuration + from nemo_fabric_adapters.hermes import interfaces + +MODEL_KEY = "fabric-test-model-key" + + +def _free_port() -> int: + with socket.create_server(("127.0.0.1", 0)) as server: + return server.getsockname()[1] + + +def _agent_config( + settings: dict[str, object], *, base_url: str | None = None +) -> AgentConfig: + model: dict[str, object] = { + "provider": "openai", + "model": "fabric-echo", + "api_key_env": "FABRIC_TEST_MODEL_KEY", + } + if base_url is not None: + model["base_url"] = base_url + return AgentConfig.from_mapping( + {"harness": {"settings": settings}, "models": {"default": model}} + ) + + +def _payload( + tmp_path: Path, settings: dict[str, object], *, base_url: str | None = None +) -> dict[str, object]: + os.environ["FABRIC_TEST_MODEL_KEY"] = MODEL_KEY + context = RuntimeContext.from_mapping( + { + "runtime_id": "runtime-interfaces", + "invocation_id": "invocation-1", + "request_id": "request-1", + "environment": { + "environment_id": "environment-1", + "provider": "test", + "control_location": "in_env_control", + "ownership": "caller_owned", + "workspace": str(tmp_path), + }, + "artifacts": {}, + } + ) + return { + "base_dir": str(tmp_path), + "runtime_context": context.to_mapping(), + "config": _agent_config(settings, base_url=base_url), + } + + +def _token_path(tmp_path: Path) -> Path: + return ( + tmp_path + / "artifacts/.fabric/hermes/runtimes/runtime-interfaces/interfaces/api.token" + ) + + +@pytest.fixture(name="web_dist") +def web_dist_fixture(tmp_path: Path) -> Path: + dist = tmp_path / "web_dist" + dist.mkdir() + (dist / "index.html").write_text( + "fabric-test-dashboard", + encoding="utf-8", + ) + os.environ["HERMES_WEB_DIST"] = str(dist) + return dist + + +def _interface(name: str, **fields: object) -> dict[str, object]: + return {"interfaces": {name: fields}} + + +# Settings that the descriptor's schema rejects during planning. +INVALID_SETTINGS = [ + pytest.param(_interface("terminal"), id="unsupported"), + pytest.param(_interface("api", port=8642, key="x"), id="unknown-field"), + pytest.param(_interface("api"), id="missing-port"), + pytest.param(_interface("dashboard", port=65_536), id="port-too-high"), + pytest.param({"startup_timeout_seconds": 75.5}, id="timeout-too-long"), +] + + +@pytest.mark.parametrize("settings", INVALID_SETTINGS) +def test_hermes_plan_rejects_invalid_settings( + tmp_path: Path, settings: dict[str, object] +): + config = FabricConfig.from_mapping( + { + "metadata": {"name": "hermes-interfaces"}, + "harness": { + "adapter_id": "nvidia.fabric.hermes", + "resolution": "preinstalled", + "settings": settings, + }, + "models": {"default": {"provider": "nvidia", "model": "test-model"}}, + "environment": {"provider": "local", "workspace": "."}, + } + ) + + with pytest.raises(FabricConfigError): + Fabric().plan(config, base_dir=tmp_path) + + +def test_hermes_interfaces_read_the_model_endpoint_and_key_from_config(): + config = configuration.build_hermes_config( + _agent_config({}, base_url="http://127.0.0.1:9/v1"), + workspace=".", + interfaces={"api": 8642}, + ) + + assert config["model"] == { + "provider": "custom", + "default": "fabric-echo", + "base_url": "http://127.0.0.1:9/v1", + "api_key": "${FABRIC_TEST_MODEL_KEY}", + } + assert config["agent"]["cron_drain_timeout"] == 3 + assert config["agent"]["restart_drain_timeout"] == 0 + + +async def test_hermes_gateway_agents_receive_fabric_behavior( + tmp_path: Path, api_server: str +): + port = _free_port() + payload = _payload( + tmp_path, _interface("api", port=port), base_url=f"{api_server}/v1" + ) + config = payload["config"].to_mapping() + config["models"]["default"].update(temperature=0.0, top_p=0.41, max_tokens=128) + config["instructions"] = { + "system": {"mode": "replace", "content": "FABRIC_PARITY_MARKER"} + } + config["tools"] = {"enabled": ["file"], "blocked": ["terminal"]} + payload["config"] = AgentConfig.from_mapping(config) + runtime = adapter.HermesRuntime() + try: + await runtime.start(payload) + config_path = _token_path(tmp_path).with_name("agent-config.json") + assert config_path.stat().st_mode & 0o777 == 0o600 + token = _token_path(tmp_path).read_text() + for number in range(2): + reply = await asyncio.to_thread( + requests.post, + f"http://127.0.0.1:{port}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={ + "model": "hermes-agent", + "messages": [ + {"role": "user", "content": f"fresh conversation {number}"} + ], + }, + timeout=60, + ) + assert reply.status_code == 200, reply.text + captured = await asyncio.to_thread( + requests.get, f"{api_server}/_requests", timeout=5 + ) + # Native session titling may make separate tool-free auxiliary calls. + requests_seen = [request for request in captured.json() if request.get("tools")] + assert len(requests_seen) == 2 + for request in requests_seen: + assert "FABRIC_PARITY_MARKER" in json.dumps(request["messages"]) + assert request["temperature"] == 0.0 + assert request["top_p"] == 0.41 + assert request["max_tokens"] == 128 + assert {tool["function"]["name"] for tool in request["tools"]} == { + "read_file", + "write_file", + "patch", + "search_files", + } + finally: + await runtime.stop() + assert not config_path.exists() + + +async def test_managed_api_does_not_enable_inherited_messaging_platforms( + tmp_path, api_server +): + os.environ["TELEGRAM_BOT_TOKEN"] = "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi" + os.environ["WEBHOOK_ENABLED"] = "true" + os.environ["HERMES_DISABLE_LAZY_INSTALLS"] = "1" + port = _free_port() + runtime = adapter.HermesRuntime() + try: + await runtime.start( + _payload( + tmp_path, _interface("api", port=port), base_url=f"{api_server}/v1" + ) + ) + from gateway.config import Platform, load_gateway_config + + config = load_gateway_config() + assert config.platforms[Platform.TELEGRAM].enabled is False + assert config.platforms[Platform.WEBHOOK].enabled is False + assert config.multiplex_profiles is False + # Only the child receives API_SERVER_KEY; no other platform may connect. + assert set(config.get_connected_platforms()) <= {Platform.API_SERVER} + reply = await asyncio.to_thread( + requests.get, f"http://127.0.0.1:{port}/health", timeout=5 + ) + assert reply.status_code == 200 + log = (runtime._hermes_home / "logs/fabric-interface-api.log").read_text() + assert "attempting install" not in log + assert os.environ["TELEGRAM_BOT_TOKEN"].startswith("123456789:") + finally: + await runtime.stop() + + +async def test_api_turns_export_atif_without_resetting_native_conversation( + tmp_path: Path, api_server: str +): + port = _free_port() + payload = _payload( + tmp_path, _interface("api", port=port), base_url=f"{api_server}/v1" + ) + payload["runtime_context"]["telemetry"] = { + "relay_enabled": True, + "metadata": {"telemetry_providers": ["relay"]}, + } + relay_dir = tmp_path / "relay" + wrapper = tmp_path / "relay.json" + wrapper.write_text( + json.dumps( + { + "relay": { + "config": { + "version": 4, + "atof": { + "enabled": True, + "sinks": [ + { + "type": "file", + "output_directory": str(relay_dir / "atof"), + "filename": "events.atof.jsonl", + } + ], + }, + "atif": { + "enabled": True, + "output_directory": str(relay_dir / "atif"), + }, + } + } + } + ) + ) + os.environ["FABRIC_RELAY_CONFIG_PATH"] = str(wrapper) + runtime = adapter.HermesRuntime() + messages = [{"role": "user", "content": "first native turn"}] + try: + await runtime.start(payload) + token = _token_path(tmp_path).read_text() + for turn in range(2): + reply = await asyncio.to_thread( + requests.post, + f"http://127.0.0.1:{port}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={"model": "hermes-agent", "messages": messages}, + timeout=60, + ) + assert reply.status_code == 200, reply.text + trajectories = list((relay_dir / "atif").rglob("*.json")) + assert len(trajectories) == turn + 1 + assert all(json.loads(path.read_text())["steps"] for path in trajectories) + messages.extend( + [ + reply.json()["choices"][0]["message"], + {"role": "user", "content": "second native turn"}, + ] + ) + captured = await asyncio.to_thread( + requests.get, f"{api_server}/_requests", timeout=5 + ) + model_turns = [request for request in captured.json() if request.get("tools")] + assert len(model_turns) == 2 + history = json.dumps(model_turns[-1]["messages"]) + assert "first native turn" in history + assert "second native turn" in history + connection = sqlite3.connect(runtime._hermes_home / "state.db") + try: + sessions = connection.execute( + "SELECT id FROM sessions WHERE source = 'api_server'" + ).fetchall() + finally: + connection.close() + assert len(sessions) == 1 + finally: + await runtime.stop() + + +@pytest.mark.skipif(sys.platform != "linux", reason="Reads Linux procfs") +async def test_hermes_serves_api_and_dashboard_with_the_configured_model( + tmp_path: Path, api_server: str, web_dist: Path +): + api_port, dashboard_port = _free_port(), _free_port() + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + { + "interfaces": { + "api": {"port": api_port}, + "dashboard": {"port": dashboard_port}, + } + }, + base_url=f"{api_server}/v1", + ) + ) + token_path = _token_path(tmp_path) + try: + token = token_path.read_text(encoding="utf-8") + token_mode = token_path.stat().st_mode & 0o777 + api = f"http://127.0.0.1:{api_port}" + unauthorized = await asyncio.to_thread( + requests.get, f"{api}/v1/models", timeout=10 + ) + reply = await asyncio.to_thread( + requests.post, + f"{api}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={ + "model": "hermes-agent", + "messages": [{"role": "user", "content": "ping"}], + }, + timeout=60, + ) + dashboard = await asyncio.to_thread( + requests.get, f"http://127.0.0.1:{dashboard_port}/", timeout=10 + ) + dashboard_environment = next( + Path(f"/proc/{child.process.pid}/environ").read_bytes() + for child in runtime._interfaces._children + if child.name == "dashboard" + ) + finally: + await runtime.stop() + model_keys = requests.get(f"{api_server}/_chat_authorization_headers", timeout=5) + + assert token_mode == 0o600 + assert unauthorized.status_code == 401 + assert reply.status_code == 200, reply.text + assert "latest=ping" in reply.json()["choices"][0]["message"]["content"] + assert model_keys.json() + assert set(model_keys.json()) == {f"Bearer {MODEL_KEY}"} + assert "fabric-test-dashboard" in dashboard.text + # On loopback, Hermes embeds its session token: the dashboard has no sign-in. + assert "window.__HERMES_SESSION_TOKEN__" in dashboard.text + assert b"API_SERVER_KEY=" not in dashboard_environment + assert not token_path.exists() + + +async def test_hermes_stop_cuts_off_an_in_flight_api_request( + tmp_path: Path, api_server: str +): + requests.post(f"{api_server}/_scenario", json={"delay_seconds": 60}, timeout=5) + api_port = _free_port() + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": api_port}}}, + base_url=f"{api_server}/v1", + ) + ) + token = _token_path(tmp_path).read_text(encoding="utf-8") + in_flight = asyncio.create_task( + asyncio.to_thread( + requests.post, + f"http://127.0.0.1:{api_port}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={ + "model": "hermes-agent", + "messages": [{"role": "user", "content": "slow"}], + }, + timeout=90, + ) + ) + try: + deadline = time.monotonic() + 30 + while not requests.get(f"{api_server}/_requests", timeout=5).json(): + assert time.monotonic() < deadline, ( + "the API request never reached the model" + ) + await asyncio.sleep(0.1) + except BaseException: + await runtime.stop() + in_flight.cancel() + raise + + started = time.monotonic() + await runtime.stop() + elapsed = time.monotonic() - started + in_flight.cancel() + + assert elapsed < 8 + assert not _token_path(tmp_path).exists() + + +async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(interfaces, "POSIX", False) + # start() stops whatever it started when it fails, so check the spawn + # itself rather than the children left afterwards. + spawn = AsyncMock() + monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", spawn) + # Refusing before Hermes's setup keeps MCP discovery, which can take + # minutes, from outlasting a caller's start deadline. + write_config = MagicMock(wraps=configuration.write_hermes_config) + monkeypatch.setattr(configuration, "write_hermes_config", write_config) + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": _free_port()}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interfaces_unsupported_platform" + spawn.assert_not_called() + write_config.assert_not_called() + assert not _token_path(tmp_path).exists() + + +async def test_hermes_interface_port_in_use_fails_start( + tmp_path: Path, api_server: str +): + runtime = adapter.HermesRuntime() + with socket.create_server(("127.0.0.1", 0)) as server: + port = server.getsockname()[1] + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": port}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interface_port_unavailable" + assert caught.value.metadata == { + "field": "harness.settings.interfaces.api.port", + "port": port, + } + assert not _token_path(tmp_path).exists() + + +def test_hermes_disabled_interface_is_not_started(): + settings = { + "interfaces": { + "api": {"port": 8642, "enabled": False}, + "dashboard": {"port": 9119}, + } + } + + assert interfaces.interface_ports(settings) == {"dashboard": 9119} + + +async def test_hermes_interface_startup_timeout_counts_from_the_start_of_start( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + write_hermes_config = configuration.write_hermes_config + timeouts: list[float] = [] + + def slow_write_hermes_config(*args, **kwargs): + time.sleep(0.5) + return write_hermes_config(*args, **kwargs) + + async def record_start(self, ports, *, timeout, **kwargs): + timeouts.append(timeout) + + monkeypatch.setattr(configuration, "write_hermes_config", slow_write_hermes_config) + monkeypatch.setattr(interfaces.InterfaceChildren, "start", record_start) + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + {"startup_timeout_seconds": 5, "interfaces": {"api": {"port": 8642}}}, + base_url=f"{api_server}/v1", + ) + ) + await runtime.stop() + + assert len(timeouts) == 1 + assert timeouts[0] <= 4.5 + + +@pytest.mark.parametrize("explicit_endpoint", [False, True]) +async def test_native_openai_endpoint_does_not_use_ambient_fallback( + tmp_path, api_server, monkeypatch, explicit_endpoint +): + os.environ["OPENAI_BASE_URL"] = "http://ambient.invalid/v1" + import run_agent + + # This test observes child environment construction, not provider login. + monkeypatch.setattr(run_agent, "AIAgent", MagicMock()) + environments = [] + + async def record_start(self, ports, *, environment, **kwargs): + environments.append(environment) + + monkeypatch.setattr(interfaces.InterfaceChildren, "start", record_start) + runtime = adapter.HermesRuntime() + try: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": 8642}}}, + base_url=f"{api_server}/v1" if explicit_endpoint else None, + ) + ) + assert environments[0]["OPENAI_API_KEY"] == MODEL_KEY + if explicit_endpoint: + assert runtime._hermes_config["model"]["base_url"] == f"{api_server}/v1" + else: + assert "OPENAI_BASE_URL" not in environments[0] + assert os.environ["OPENAI_BASE_URL"] == "http://ambient.invalid/v1" + finally: + await runtime.stop() + + +@pytest.mark.parametrize("failed_attribute", ["_token_path", "_agent_config_path"]) +async def test_private_file_removal_failure_still_stops_children_and_retries( + tmp_path, monkeypatch, caplog, failed_attribute +): + children = interfaces.InterfaceChildren() + for attribute in ("_token_path", "_agent_config_path"): + path = tmp_path / attribute + path.write_text("private") + setattr(children, attribute, path) + failed_path = getattr(children, failed_attribute) + process = MagicMock(pid=1234, returncode=None, wait=AsyncMock(return_value=0)) + children._children.append(interfaces._Child("api", 0, process)) + signal_group = MagicMock() + monkeypatch.setattr(interfaces.common_utils, "signal_process_group", signal_group) + unlink = Path.unlink + + def deny_private_file(path, *args, **kwargs): + if path == failed_path: + raise PermissionError("test removal denied") + return unlink(path, *args, **kwargs) + + with monkeypatch.context() as patch: + patch.setattr(Path, "unlink", deny_private_file) + await children.stop() + + assert process.wait.await_count == 1 + assert signal_group.call_count == 2 + assert not children._children + assert getattr(children, failed_attribute) == failed_path + assert "Could not remove Hermes interface file" in caplog.text + await children.stop() + assert not failed_path.exists() + assert children._token_path is None + assert children._agent_config_path is None + + +async def test_hermes_interface_start_timeout_stops_the_started_child( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + create_subprocess_exec = asyncio.create_subprocess_exec + processes: list[asyncio.subprocess.Process] = [] + + async def record_process(*args, **kwargs): + process = await create_subprocess_exec(*args, **kwargs) + processes.append(process) + return process + + monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", record_process) + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + { + "startup_timeout_seconds": 0.001, + "interfaces": {"api": {"port": _free_port()}}, + }, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interface_start_timeout" + assert len(processes) == 1 + assert processes[0].returncode is not None + assert not runtime._interfaces._children + assert not _token_path(tmp_path).exists() + + +@pytest.mark.skipif(sys.platform == "win32", reason="Uses POSIX process groups") +async def test_hermes_cancelled_interface_stop_still_kills_a_child_that_ignores_sigterm(): + process = await asyncio.create_subprocess_exec( + sys.executable, + "-c", + "import signal, time\n" + "signal.signal(signal.SIGTERM, signal.SIG_IGN)\n" + "print('ready', flush=True)\n" + "time.sleep(60)\n", + stdout=asyncio.subprocess.PIPE, + start_new_session=True, + ) + try: + assert await process.stdout.readline() == b"ready\n" + children = interfaces.InterfaceChildren() + children._children.append(interfaces._Child("api", 0, process)) + + stopping = asyncio.create_task(children.stop()) + await asyncio.sleep(0.5) + stopping.cancel() + with pytest.raises(asyncio.CancelledError): + await stopping + + assert await asyncio.wait_for(process.wait(), timeout=2) is not None + finally: + if process.returncode is None: + process.kill() + await process.wait() + + +async def test_hermes_dashboard_without_a_built_frontend_fails_start( + tmp_path: Path, api_server: str +): + os.environ["HERMES_WEB_DIST"] = str(tmp_path / "missing") + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"dashboard": {"port": _free_port()}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_dashboard_frontend_missing" diff --git a/tests/adapters/test_hermes_native_config.py b/tests/adapters/test_hermes_native_config.py new file mode 100644 index 000000000..efb55cac0 --- /dev/null +++ b/tests/adapters/test_hermes_native_config.py @@ -0,0 +1,144 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Fabric behavior survives creation of additional native Hermes agents.""" + +import os +from unittest.mock import MagicMock + +import pytest +from nemo_fabric_adapter_contract.models import AgentConfig +from nemo_fabric_adapters.hermes import configuration +from nemo_fabric_adapters.hermes import native +from nemo_fabric_adapters.hermes.native import configured_kwargs + + +@pytest.mark.parametrize("model_limit", [None, 128]) +def test_native_agents_apply_behavior_without_losing_routing_or_identity(model_limit): + model = { + "provider": "openai", + "model": "configured", + "temperature": 0.0, + "top_p": 0.41, + } + if model_limit is not None: + model["max_tokens"] = model_limit + config = AgentConfig.from_mapping( + { + "models": {"default": model}, + "harness": { + "settings": {"max_tokens": 96, "reasoning_config": {"effort": "none"}} + }, + "runtime": {"max_turns": 2}, + "tools": {"enabled": ["file"], "blocked": ["terminal"]}, + "instructions": { + "system": {"mode": "replace", "content": "Fabric instruction"} + }, + } + ) + native = { + "model": "configured", + "provider": "custom", + "base_url": "http://127.0.0.1:8642/v1", + "session_id": "native-session", + "platform": "api_server", + "enabled_toolsets": ["file", "web"], + "ephemeral_system_prompt": "native override", + "request_overrides": {"temperature": 0.9, "extra_body": {"test": True}}, + } + + result = configured_kwargs(config, native, {}) + + assert result["enabled_toolsets"] == ["file"] + assert result["disabled_toolsets"] == ["terminal"] + assert result["ephemeral_system_prompt"] == "Fabric instruction" + assert result["max_tokens"] == (model_limit or 96) + assert result["max_iterations"] == 2 + assert result["request_overrides"] == { + "temperature": 0.0, + "top_p": 0.41, + "extra_body": {"test": True}, + } + assert result["reasoning_config"] == {"effort": "none"} + for key in ("model", "provider", "base_url", "session_id", "platform"): + assert result[key] == native[key] + assert native["enabled_toolsets"] == ["file", "web"] + assert native["request_overrides"]["temperature"] == 0.9 + + +def test_native_behavior_preserves_native_prompt_when_fabric_has_none(): + config = AgentConfig.from_mapping( + { + "models": {"default": {"provider": "openai", "model": "configured"}}, + "tools": {"enabled": []}, + } + ) + + result = configured_kwargs(config, {"ephemeral_system_prompt": "native"}, {}) + + assert result["ephemeral_system_prompt"] == "native" + assert result["enabled_toolsets"] == [] + assert result["request_overrides"] is None + assert result["max_tokens"] == 512 + assert result["max_iterations"] == configuration.DEFAULT_MAX_ITERATIONS + + +@pytest.mark.parametrize( + "tools,enabled,blocked", + [ + (None, ["native"], ["terminal"]), + ({}, ["native"], ["terminal"]), + ({"enabled": []}, [], ["terminal"]), + ({"blocked": ["web"]}, ["native"], ["web"]), + ], +) +def test_native_tool_defaults_survive_without_explicit_policy(tools, enabled, blocked): + mapping = {"models": {"default": {"provider": "openai", "model": "test"}}} + if tools is not None: + mapping["tools"] = tools + config = AgentConfig.from_mapping(mapping) + result = configured_kwargs( + config, + {"enabled_toolsets": ["native"], "disabled_toolsets": ["terminal"]}, + {}, + ) + + assert result["enabled_toolsets"] == enabled + assert result["disabled_toolsets"] == blocked + + +@pytest.mark.parametrize( + "platform,relay_enabled,expected", + [("api_server", True, True), ("api_server", False, False), ("cli", True, False)], +) +def test_only_relay_enabled_api_turns_finalize( + monkeypatch, platform, relay_enabled, expected +): + if relay_enabled: + os.environ["HERMES_NEMO_RELAY_PLUGINS_TOML"] = "/test/plugins.toml" + else: + os.environ.pop("HERMES_NEMO_RELAY_PLUGINS_TOML", None) + finalize = MagicMock() + monkeypatch.setattr(native.telemetry, "finalize_native_relay_segment", finalize) + agent = MagicMock(platform=platform, session_id="native-session") + + native.finalize_api_turn(agent) + + if expected: + finalize.assert_called_once_with("native-session") + else: + finalize.assert_not_called() + + +def test_api_relay_finalization_failure_is_reported_without_raising( + monkeypatch, caplog +): + os.environ["HERMES_NEMO_RELAY_PLUGINS_TOML"] = "/test/plugins.toml" + finalize = MagicMock(side_effect=RuntimeError("test export failure")) + monkeypatch.setattr(native.telemetry, "finalize_native_relay_segment", finalize) + + native.finalize_api_turn( + MagicMock(platform="api_server", session_id="native-session") + ) + + assert "Hermes API turn Relay finalization failed" in caplog.text