feat(hermes): add managed tool gateway broker

[shannonsands]

Summary

Adds the Hermes managed-tool gateway broker as a follow-up stacked on #3320 so Nous subscription tools can run through host-managed OAuth without putting raw OAuth secrets in the sandbox. The first pass covers the current managed routes: Firecrawl web, FAL queue image, OpenAI audio TTS/STT, Browser Use, and optional Modal execution.

Changes

• Adds a matrix-driven Hermes managed-tool gateway under agents/hermes/host/, plus a host broker that refreshes via x-nous-refresh-token, injects upstream auth, normalizes decoded responses, and redacts/avoids logging secrets.
• Wires OAuth onboarding to register a separate OpenShell refresh provider for managed tools while keeping API-key mode inference-only.
• Generates Hermes broker-mode config/env from the matrix and adds nous-* policy presets that only allow host.openshell.internal:11436/<service> plus the Browser Use CDP exception.
• Ports Hermes plugin shims for broker availability, Firecrawl path preservation, Browser Use state reset/CDP tunneling, FAL polling URL rewrite, OpenAI audio/STT preference, Modal gateway preference, dotenv hydration, and quiet NemoClaw context.
• Persists selected managed-tool presets through onboarding, rebuild, registry, connect, and status, and documents the new non-interactive env vars.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

Targeted checks run and passed:

• python3 -m py_compile agents/hermes/plugin/__init__.py
• npm run build:cli
• npx vitest run test/hermes-tool-gateway-broker.test.ts test/generate-hermes-config.test.ts test/policies.test.ts src/lib/oauth-device-code.test.ts src/lib/hermes-provider-auth.test.ts test/hermes-provider-foundation.test.ts test/hermes-plugin-handlers.test.ts test/hermes-sandbox-workflow.test.ts test/nemohermes-alias.test.ts src/lib/state/onboard-session.test.ts src/lib/actions/sandbox/status.test.ts
• npx vitest run test/check-env-var-docs.test.ts
• npx vitest run test/onboard.test.ts -t "starts the sandbox step before prompting for the sandbox name"
• npx prek run env-var-docs --files docs/reference/commands.md src/lib/onboard.ts src/lib/core/ports.ts
• git diff --check

The full local test-cli hook was attempted but not claimed here; it still fails in runtime-sensitive/full-suite tests on this machine (credentials, runtime-shell, sandbox-connect-inference, secret-redaction, and related CLI dispatch cases), matching the broader local harness instability rather than this targeted Hermes slice.

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: $(git config user.name) <$(git config user.email)>

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 155d8e5d-cd45-4c67-8261-4779e9904794

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wscurran]

✨ Thanks for submitting this detailed PR about adding the Hermes managed-tool gateway broker. This change aims to improve the integration of Nous subscription tools with NemoClaw by introducing a host-managed OAuth broker.

---

Related open PRs:

• #3320 feat(hermes): add provider onboarding foundation