Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
e3eb9bd
fix: stop agents where group signals are denied
cv Nov 1, 2026
7bb12a1
fix: bound OpenClaw's whole start by one deadline
cv Nov 1, 2026
f638e44
feat: serve OpenClaw's Control UI from managed runtimes
cv Nov 1, 2026
7ed10ce
feat: serve Hermes's API server and dashboard from a runtime
cv Nov 1, 2026
dde1815
test: skip the OpenClaw tests that run the mock script where CI can't
cv Nov 1, 2026
76a81da
Merge branch 'pr/04-openclaw-control-ui' into pr/05-hermes-interfaces
cv Nov 1, 2026
20118ba
fix: probe loopback ports exclusively on Windows
cv Nov 2, 2026
005aa7e
fix: keep Hermes interface start and stop within their limits
cv Nov 2, 2026
075f8c4
docs: correct OpenClaw's dashboard port and token file claims
cv Nov 2, 2026
e9d3336
test: cover a disabled OpenClaw dashboard and token cleanup after fai…
cv Nov 2, 2026
427a3e3
fix: don't signal a child's PID after it exits
cv Nov 2, 2026
532424e
fix: end OpenClaw's readiness check at the startup deadline
cv Nov 2, 2026
4a6009a
docs: describe OpenClaw's startup deadline
cv Nov 2, 2026
0fcad06
Merge branch 'prop/04' into prop/05
cv Nov 2, 2026
f48e793
fix: refuse Hermes interfaces on Windows before any child starts
cv Nov 3, 2026
e395dc9
Merge branch 'main' into pr/04-openclaw-control-ui
cv Nov 4, 2026
00d8427
Merge branch 'main' into pr/05-hermes-interfaces
cv Nov 4, 2026
1b969f9
Merge branch 'main' into pr/04-openclaw-control-ui
cv Nov 5, 2026
f232890
Merge branch 'pr/04-openclaw-control-ui' into pr/05-hermes-interfaces
cv Nov 5, 2026
838f0bc
fix: retry removing the OpenClaw dashboard token after a failed stop
cv Nov 5, 2026
7b70972
test: check Hermes's Windows refusal never spawns an interface
cv Nov 5, 2026
9e867d8
fix: refuse Hermes interfaces on Windows before MCP discovery
cv Nov 5, 2026
45d5c3e
Merge branch 'pr/04-openclaw-control-ui' into pr/05-hermes-interfaces
cv Nov 5, 2026
9855259
chore: separate Hermes interfaces from OpenClaw PR scope
AnuradhaKaruppiah Nov 5, 2026
db99029
fix: apply Fabric behavior to native Hermes agents
AnuradhaKaruppiah Nov 5, 2026
2f6be67
docs: separate Hermes native interface guidance
AnuradhaKaruppiah Nov 5, 2026
8d441be
docs: update Hermes invocation diagram
AnuradhaKaruppiah Nov 5, 2026
597e6b3
docs: clarify native Hermes API client authentication
AnuradhaKaruppiah Nov 5, 2026
6b9e12f
docs: organize Hermes interfaces around user tasks
AnuradhaKaruppiah Nov 5, 2026
bee37b4
docs: remove inline Hermes interfaces table of contents
AnuradhaKaruppiah Nov 5, 2026
aef811f
docs: remove editable diagram sentence
AnuradhaKaruppiah Nov 5, 2026
a4149ce
fix: finalize Relay segments for native Hermes API turns
AnuradhaKaruppiah Nov 5, 2026
8c1bfb7
feat: add native interface example with Relay trajectories
AnuradhaKaruppiah Nov 5, 2026
731b312
fix: preserve native conversation wrapper signature
AnuradhaKaruppiah Nov 5, 2026
b9f300b
docs: record native health and instance discovery gaps
AnuradhaKaruppiah Nov 5, 2026
d288e14
fix: harden Hermes native interface cleanup and configuration
AnuradhaKaruppiah Nov 6, 2026
9974c01
docs: link Hermes testing guidance to interfaces example
AnuradhaKaruppiah Nov 6, 2026
612ad0d
fix: allow a separate Hermes checkout for installation
AnuradhaKaruppiah Nov 6, 2026
b424e2f
docs: keep Hermes example setup focused
AnuradhaKaruppiah Nov 6, 2026
1907d1f
fix: isolate managed Hermes API from messaging platforms
AnuradhaKaruppiah Nov 6, 2026
3ca1de8
docs: mark interfaces example as work in progress
AnuradhaKaruppiah Nov 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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)
Comment thread
AnuradhaKaruppiah marked this conversation as resolved.
Resolved
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
4 changes: 4 additions & 0 deletions adapters/python/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down
52 changes: 52 additions & 0 deletions adapters/python/hermes/hermes.fabric-adapter.json
Original file line number Diff line number Diff line change
Expand Up @@ -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 <artifact root>/.fabric/hermes/runtimes/<runtime-id>/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": [],
Expand Down
88 changes: 60 additions & 28 deletions adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand All @@ -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):
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -181,47 +192,65 @@ 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,
base_url=model_config.base_url,
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
Comment thread
AnuradhaKaruppiah marked this conversation as resolved.
Resolved
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,
)
Comment thread
cv marked this conversation as resolved.
Resolved
self._agent_config = agent_config
self._started = True
except BaseException:
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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"),
Expand Down
Loading
Loading