Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion adapters/python/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ harness = HarnessConfig(

Managed native processes use the adapter's launcher to apply explicit instructions and behavioral settings before constructing agents. Explicit enabled tools, including an empty list, override native selection; a nonempty blocked list overrides native exclusions. Unspecified tool policies can differ between SDK and native paths.

The runtime home is `<artifact root>/.fabric/hermes/runtimes/<runtime-id>`. The adapter writes native configuration and optional NeMo Relay plugin configuration there. When native interfaces are enabled, an owner-only `interfaces/agent-config.json` snapshot supplies the constructor mapping and is removed on stop. Model credentials are provided through child environments rather than public attachment metadata.
The default Hermes home is `<artifact root>/.fabric/hermes/runtimes/<runtime-id>`. With `runtime.keep_state`, the adapter uses the agent state folder described in the [Hermes guide](../../../docs/integrations/harness/hermes/hermes.mdx#shared-runtime-home). The adapter writes native configuration and optional NeMo Relay plugin configuration there. When native interfaces are enabled, an owner-only `interfaces/agent-config.json` snapshot supplies the constructor mapping and is removed on stop. Model credentials are provided through child environments rather than public attachment metadata.

The adapter leaves the installed Hermes source unchanged. Independently started processes do not automatically receive its mapping. Refer to [Shared Configuration and Ownership](../../../docs/integrations/harness/hermes/hermes.mdx#shared-configuration-and-ownership) for precedence and managed API gateway scope.

Expand Down
3 changes: 2 additions & 1 deletion adapters/python/hermes/hermes.fabric-adapter.json
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
"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."
"description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: <artifact root>/.fabric/hermes/runtimes/<runtime-id>, or the agent's state folder with runtime.keep_state."
},
"dashboard": {
"type": "object",
Expand Down Expand Up @@ -249,6 +249,7 @@
"models.max_tokens",
"instructions.system",
"runtime.max_turns",
"runtime.keep_state",
"tools.enabled",
"tools.blocked",
"mcp",
Expand Down
43 changes: 32 additions & 11 deletions adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,21 +125,28 @@ async def start(self, payload: dict[str, Any]) -> None:
"hermes_no_execution_path",
"Enable the Hermes SDK or at least one native interface",
)
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
self._hermes_home = (
_artifact_root(runtime_context, common_utils.base_dir(payload))
/ ".fabric"
/ "hermes"
/ "runtimes"
/ runtime_context.runtime_id
self._hermes_home = _hermes_home(
runtime_context, common_utils.base_dir(payload)
)
self._hermes_home.mkdir(parents=True, exist_ok=True)
# An abruptly ended runtime can leave credentials and attachment
# records in a kept Hermes home.
token_path = self._hermes_home / "interfaces" / "api.token"
try:
for name in ("tui.json", "tui.token", "api.token", "agent-config.json"):
token_path.with_name(name).unlink(missing_ok=True)
except OSError as error:
raise lifecycle.LifecycleError(
"hermes_interface_cleanup_failed",
"Hermes interface files could not be removed",
) from error
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()
os.environ["HOME"] = str(self._hermes_home)
os.environ["HERMES_HOME"] = str(self._hermes_home)
os.environ.setdefault("HERMES_YOLO_MODE", "1")
Expand Down Expand Up @@ -262,7 +269,7 @@ async def start(self, payload: dict[str, Any]) -> None:
await self._interfaces.start(
interface_ports,
hermes_home=self._hermes_home,
token_path=self._hermes_home / "interfaces" / "api.token",
token_path=token_path,
timeout=max(
interfaces.startup_timeout(self._settings)
- (asyncio.get_running_loop().time() - started_at),
Expand Down Expand Up @@ -831,6 +838,20 @@ async def stop(self) -> None:
) from errors[0]


def _hermes_home(runtime_context: RuntimeContext, base_dir: str) -> Path:
"""Return the agent's state folder when Fabric keeps state across runtimes,
otherwise this runtime's own folder."""
if runtime_context.state_dir:
return Path(runtime_context.state_dir)
return (
_artifact_root(runtime_context, base_dir)
/ ".fabric"
/ "hermes"
/ "runtimes"
/ runtime_context.runtime_id
)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved


def _artifact_root(runtime_context: RuntimeContext, base_dir: str) -> Path:
root = runtime_context.artifacts.root
if root:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
"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."
"description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: <artifact root>/.fabric/hermes/runtimes/<runtime-id>, or the agent's state folder with runtime.keep_state."
},
"dashboard": {
"type": "object",
Expand Down Expand Up @@ -249,6 +249,7 @@
"models.max_tokens",
"instructions.system",
"runtime.max_turns",
"runtime.keep_state",
"tools.enabled",
"tools.blocked",
"mcp",
Expand Down
9 changes: 1 addition & 8 deletions docs/adapter-contract/tutorials/adapter-descriptor.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,14 +102,7 @@ schema enum for the exact accepted values.
Planning rejects configured normalized behavior outside the declared surface.
NeMo Fabric does not silently remove unsupported fields.

Accept `runtime.keep_state` only when the adapter keeps all of its native
state in `RuntimeContext.state_dir` when that field is present. Every runtime
of the agent then receives the same folder, so a later runtime finds the
earlier runtime's sessions, memory, and other harness files. On Linux and
macOS, the adapter host inherits the folder's lock. Don't leave detached
children that keep inherited file descriptors open: such a child keeps the
agent's state locked after the host exits, and later runtimes of the agent
fail to start.
Accept `runtime.keep_state` only when the adapter keeps all of its native state in `RuntimeContext.state_dir` when that field is present. Every runtime of the agent then receives the same folder, so a later runtime finds the earlier runtime's sessions, memory, and other harness files. On Linux and macOS, the adapter host inherits the folder's lock. Detached children with inherited lock descriptors can keep the state locked after the host exits and prevent later runtimes from starting. A detached child without the lock can outlive the host and access the state folder after another runtime acquires the lock. Ensure that all children stop accessing retained state before the lock is released.

When an adapter accepts `instructions.system`, declare the exact supported
modes in `config.system_instruction_modes`. `replace` discards the harness
Expand Down
4 changes: 3 additions & 1 deletion docs/integrations/harness/hermes/hermes-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,11 @@ This disables embedded SDK execution explicitly. Omit `sdk` to also start the em
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
<artifact root>/.fabric/hermes/runtimes/<runtime-id>/interfaces/api.token
<Hermes home>/interfaces/api.token
```

Before starting Hermes, the adapter removes any API token left by an earlier runtime.

Clients calling the native API must read the generated token file and include `Authorization: Bearer <token>` 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.

This token authenticates access to the API gateway. It is distinct from the model-provider API key and the TUI backend credential used by dashboard and terminal clients. API clients share the per-start token; it does not provide per-user isolation.
Expand Down
6 changes: 4 additions & 2 deletions docs/integrations/harness/hermes/hermes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Use a single `FabricConfig` to define supported settings for all four Hermes pat

NeMo Fabric resolves `FabricConfig` into `AgentConfig`. The adapter translates it into Hermes's native configuration and agent settings, applying the same explicit instructions and behavioral settings to agents in managed native processes.

The adapter writes native `config.yaml` and optional NeMo Relay plugin configuration under the runtime's Hermes home. When native interfaces are enabled, it also writes an owner-only `interfaces/agent-config.json` snapshot for the managed processes.
The adapter writes native `config.yaml` under the Hermes home. When NeMo Relay is enabled, the adapter creates a `relay-config` directory beside the file specified by `FABRIC_RELAY_CONFIG_PATH` and writes `plugins.toml` there. This location follows `FABRIC_RELAY_CONFIG_PATH` even with `runtime.keep_state` enabled. When native interfaces are enabled, it also writes an owner-only `interfaces/agent-config.json` snapshot for the managed processes.

Model credentials are supplied through child process environments, not public attachment metadata. For OpenAI without an explicit base URL, the adapter removes inherited `OPENAI_BASE_URL` from managed children so it cannot redirect the configured credential.

Expand All @@ -120,7 +120,9 @@ Model credentials are supplied through child process environments, not public at

### Shared Runtime Home

The runtime home is `<artifact root>/.fabric/hermes/runtimes/<runtime-id>`. Agents share persisted resources in this directory while retaining separate live conversations. Keeping these files does not establish cross-runtime resume.
The default Hermes home is `<artifact root>/.fabric/hermes/runtimes/<runtime-id>`. With `runtime.keep_state`, the Hermes home is `<artifact root>/.fabric/state/nvidia.fabric.hermes/<agent name>`, so runtimes of the agent share the session database, memory, skills, and logs. The SDK starts a new conversation for each runtime, and earlier sessions remain in the database. The adapter rewrites `config.yaml` at each start.

Startup removes stale `interfaces/api.token`, `interfaces/tui.json`, `interfaces/tui.token`, and `interfaces/agent-config.json` files from the Hermes home. A removal failure stops startup with `hermes_interface_cleanup_failed` before Hermes setup.

### Process Ownership

Expand Down
16 changes: 11 additions & 5 deletions docs/sdk/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -898,11 +898,17 @@ artifact directory, and `metadata.name` and the adapter ID must each be usable
as one folder name on Linux, macOS, and Windows: no `/`, `\`, `<>:"|?*`, or
control characters, no trailing space or `.`, and not a Windows device name such
as `CON` or `NUL`. On Linux and macOS, only the folder's owner can read it.
Only one runtime can use the folder at a time: `Fabric.start_runtime(...)` fails
while another runtime of the agent runs. A service and one runtime connected to
it share the folder; the service holds it until `Service.release()`, even with
no runtime connected. On Linux and macOS, each adapter host inherits a descriptor for the state lock, including a runtime connected to a service. The folder stays locked while any process holds an open descriptor for that lock. A completed stop closes the runtime's descriptors, and the operating system releases the lock after all descriptors close. On Windows, adapter hosts do not inherit the lock, so only the NeMo Fabric process holds the lock. If the NeMo Fabric process exits while an adapter host is still running, the folder becomes available. If all descriptors close while a native process started in a separate session keeps running, the folder becomes available while that native process can still write. Planning fails without an artifact directory, or for an
adapter that doesn't declare `runtime.keep_state`.
Only one runtime can use the folder at a time: `Fabric.start_runtime(...)` fails while another runtime of the agent runs. A service and one connected runtime share the folder. The service holds the lock until `Service.release()`, even with no runtime connected.

The operating system releases the lock after all copies of the lock have closed:

- **Linux and macOS:** Each adapter host inherits a lock descriptor, including a runtime connected to a service. Stopping a standalone runtime normally releases the lock while the application continues running. Killing only the adapter host leaves the application's lock descriptor open.
- **Windows:** Adapter hosts do not inherit the lock. Only the NeMo Fabric process holds the lock, so the folder becomes available if that process exits while an adapter host is still running.
- **Detached processes:** A native process can continue accessing the state folder after all lock descriptors close. A replacement runtime can then acquire the lock while the detached process still writes to the folder.

Planning fails without an artifact directory or for an adapter that doesn't declare `runtime.keep_state`. The Hermes Agent adapter declares `runtime.keep_state`.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

Enabling `runtime.keep_state` preserves earlier Hermes sessions in the database. Each new Hermes SDK runtime starts a fresh conversation.

## Runtime Resource Snapshots

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
"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."
"description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: <artifact root>/.fabric/hermes/runtimes/<runtime-id>, or the agent's state folder with runtime.keep_state."
},
"dashboard": {
"type": "object",
Expand Down Expand Up @@ -249,6 +249,7 @@
"models.max_tokens",
"instructions.system",
"runtime.max_turns",
"runtime.keep_state",
"tools.enabled",
"tools.blocked",
"mcp",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -812,6 +812,7 @@
"models.max_tokens",
"instructions.system",
"runtime.max_turns",
"runtime.keep_state",
"tools.enabled",
"tools.blocked",
"mcp",
Expand Down Expand Up @@ -923,7 +924,7 @@
"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 <artifact root>/.fabric/hermes/runtimes/<runtime-id>/interfaces/api.token.",
"description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: <artifact root>/.fabric/hermes/runtimes/<runtime-id>, or the agent's state folder with runtime.keep_state.",
"properties": {
"enabled": {
"default": true,
Expand Down Expand Up @@ -1078,7 +1079,7 @@
"name": "nemo-fabric-adapters-hermes",
"version": "0.7.0"
},
"sha256": "6b75b6803c8a4fac6cac5b96aa68b32e7a1b058a4c33f24041d22124b9caae85",
"sha256": "d4ffb1125719a5e7ddaf1f58eb45f4f7b10e877288abc2a2abcc848075192301",
"source": "adapters/python/hermes/hermes.fabric-adapter.json"
},
"nvidia.fabric.kilo": {
Expand Down
Loading
Loading