NVIDIA / NVIDIA/NemoClaw

Add native Relay and Switchyard activation with fail-closed Hermes readiness

Open
#8,886 3 comments 0 reactions 1 assignee Claimed by @cjagwani View on GitHub
area: routing area: sandbox integration: hermes
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

Parent Epic: #7937

Canonical NemoClaw scope was accepted in #7937 on 2026-08-13. Active dependency selection and merge remain blocked on the released compatibility set from #8885.

## Outcome

An explicitly enabled NemoClaw-managed Hermes sandbox loads native NeMo Relay and the nvidia.switchyard plugin once in the normal supervised Hermes process, using one root-owned Relay plugin-activation file and one separate root-owned Switchyard version-1 deployment file. No Relay or Switchyard sidecar is started, and requested-but-inactive routing cannot reach any model provider.

## Current upstream gate — 2026-08-25

Switchyard #528 remains open, review-required, and targets Relay 0.8.0-rc.3. Its current README and implementation now use the same manifest-backed dynamic record consumed by Hermes and derive plugin identity from relay-plugin.toml. That source-level configuration mismatch is resolved; a stable release, immutable plugin bundles, and a Hermes-style activation/readiness test are still required before NemoClaw freezes a production selector.

Stable Relay remains 0.7.3, while Hermes Agent 0.20.5 still locks Relay 0.7.2 and requires Relay below 0.8. Draft NemoClaw #9012's published head models the older #270 embedded configuration and is lifecycle reference material only. Its local V5 successor implements the current two-file shape while deliberately selecting or activating no unreleased runtime artifact.

## Canonical file boundary

The released path consumes exactly two upstream-owned configuration contracts:

1. **Relay plugin activation file**
- one plugins.dynamic record;
- immutable installed manifest path;
- plugin config containing only priority and switchyard_config_path;
- explicit activation consent for the manifest whose defaults remain disabled.

2. **Switchyard deployment file**
- schema version 1;
- llm_clients, targets, and routes;
- the exact route ID requested by Hermes;
- released algorithm fields and target/client references;
- endpoint and raw-key environment names derived from accepted OpenShell provider evidence.

A NemoClaw-internal secret-free binding receipt may attest how those files were derived, but it is not a third Relay/Switchyard configuration language.

## Scope

- Generate the manifest-backed Relay dynamic-plugin record accepted by the exact released Hermes/Relay loader.
- Generate the separate Switchyard version-1 deployment accepted by the released switchyard-runner.
- Never emit the old embedded version-2 #270 configuration or plugin_id as a substitute for the manifest path.
- Set HERMES_NEMO_RELAY_PLUGINS_TOML only when routing is explicitly enabled.
- Bind Hermes model selection to the configured Switchyard route ID. Because an unknown route deliberately continues through Relay unchanged, route-ID mismatch must fail preflight/readiness rather than silently bypass Switchyard.
- Bind activation to the supervised Hermes process and persist it across restart/rebuild.
- Include every activation-affecting input in the configuration/state identity: released artifact identities, architecture, manifest/schema/library digests, Relay range/native API, both generated file bytes, route ID, algorithm, provider attestations, policy, and credential-placeholder revisions.
- Validate the plugin manifest, library digest, native API, Relay range, architecture, deployment schema, algorithm, route ID, client, target, and credential references before Hermes readiness.
- Resolve active plugin ownership through Relay structured discovery fields: plugin ID, kind, component ordinal, and local name. Do not construct, persist, or compare Relay versioned effective component names.
- Require the expected Relay runtime and nvidia.switchyard component to be loaded, active, and ready before admitting any Hermes turn or allowing bootstrap, judge, weak, or strong provider execution.
- Override upstream fail-open behavior at the NemoClaw readiness boundary: invalid configuration or missing Relay/plugin support must produce actionable failure, not a healthy unrouted Hermes agent.
- Preserve ordinary Hermes behavior exactly when routing is disabled.
- Prove one supervised Hermes process owns Relay and Switchyard and that Relay/Switchyard sidecar count is zero.
- Retain only the release-independent lifecycle ideas from draft #9012: typed disabled-default profile input, atomic root-owned file promotion, exact-byte replay verification, stale-artifact removal, and rejection of missing, extra, raw, or mixed-revision placeholders.

## Acceptance

- [ ] Routing-disabled sandboxes behave exactly as before and do not contain active Switchyard configuration.
- [ ] The Relay activation file parses through the exact released Hermes loader path; plugin_id and unknown fields are rejected.
- [ ] The Switchyard deployment parses through the exact released runner and rejects unknown fields, algorithms, routes, clients, targets, or dangling references.
- [ ] Routing-enabled sandboxes report active native Relay and structured nvidia.switchyard ownership before readiness.
- [ ] The observed plugin manifest, schema, native library, Relay version, native API, architecture, route ID, and both generated file digests match the expected immutable tuple.
- [ ] Hermes requests the configured Switchyard route ID; a mismatched or unknown route cannot fall through to direct provider execution.
- [ ] Missing, unreadable, malformed, incompatible, disabled, or rejected activation/deployment state fails preflight/readiness before any provider request.
- [ ] The active supervised Hermes PID owns Relay/plugin activation and no Relay CLI, switchyard-server, Relay sidecar, or Switchyard sidecar exists.
- [ ] Restart and rebuild restore the same attested activation and deployment state without accepting stale or mixed-generation files.
- [ ] Generated configuration, receipts, readiness output, and diagnostics contain no raw provider credential.
- [ ] Removal or disablement deletes stale activation/deployment artifacts and restores ordinary unrouted Hermes behavior only after the requested routing state is explicitly disabled.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.