Add native Relay and Switchyard activation with fail-closed Hermes readiness
- 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
Assessment
This issue has not been assessed yet.