fix(hermes): accept Langfuse credential placeholders

[prekshivyas]

Summary

Hermes 0.18.0 rejects NemoClaw's safe OpenShell credential placeholders before its Langfuse plugin can create the client. This change lets the pinned Hermes plugin accept only the exact public and secret Langfuse placeholders while keeping raw keys outside the sandbox and preserving Hermes's existing raw-key prefix checks.

Related Issue

Refs #7446

Scope

This is a narrow prerequisite for the already pinned Hermes runtime. It does not add a Langfuse SDK dependency, endpoint policy, CLI flag, managed onboarding flow, or canonical supported-integration documentation. Issue #7446 remains open for the supported integration contract and tracks removal of this patch when pinned Hermes provides equivalent exact-name placeholder support upstream.

Changes

• Patch the Langfuse validator bundled with pinned Hermes v2026.7.1 / 0.18.0 during the NemoClaw image build.
• Bind HERMES_LANGFUSE_PUBLIC_KEY only to LANGFUSE_PUBLIC_KEY and HERMES_LANGFUSE_SECRET_KEY only to LANGFUSE_SECRET_KEY.
• Accept unversioned placeholders and OpenShell's bounded 1–20 digit versioned placeholder form.
• Install the patcher through the current Hermes runtime payload, verify its SHA-256 digest before execution, and keep it root-owned and read-only.
• Fail the image build if the pinned upstream source shape changes, and smoke-test accepted and rejected values during the build.
• Cover raw keys, exact placeholders, malformed or swapped placeholders, idempotence, source drift, image placement, integrity, and final permissions.

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)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This repairs an internal pinned-runtime validator and does not add a supported Langfuse setup or onboarding flow. Existing credential-boundary and Hermes plugin guidance remains accurate.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — exact-head nine-category security review: PASS, no findings
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Reviewed all seven changed files against WRITING.md and docs/CONTRIBUTING.md. This pinned-Hermes image-build compatibility patch changes no command, configuration schema, API, policy, or supported workflow. Existing docs already classify Hermes Langfuse settings as startup-only configuration. Comments and test titles clearly state the fail-closed and credential-binding contracts. Targeted tests passed 3/3 and 80/80; git diff --check passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

Not applicable — scripts/prepare-dgx-station-host.sh is unchanged.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed
• Targeted behavior tests pass for the current change set — five focused files, 83 tests passed
• npm run typecheck:cli passed
• git diff --check origin/main...HEAD passed
• Applicable broad gate passed — not required for this bounded image-build compatibility patch; trusted CI provides the broad matrix
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run 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: Prekshi Vyas prekshiv@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a fail-closed Hermes Langfuse credential patcher, runs it during image builds, verifies raw and OpenShell placeholder credentials, and extends end-to-end, integrity, provisioning, replay, and permission coverage.

Changes

Hermes Langfuse credential handling

Layer / File(s)	Summary
Credential validator patcher agents/hermes/patch-langfuse-credentials.mts	Defines exact replacements, occurrence checks, idempotent patching, and a CLI for updating Hermes’s bundled Langfuse plugin.
Hermes image integration agents/hermes/Dockerfile, test/hermes-final-image-layout.test.ts	Copies, hashes, and hardens the patcher, executes it during image builds, and validates credential behavior.
Patch behavior and runtime validation test/e2e/support/hermes-langfuse-credential-patch.test.ts	Tests accepted credentials, idempotency, fail-closed source drift handling, duplicate-block detection, and runtime execution.
Hermes artifact hardening coverage test/hermes-doctor-config-hash.test.ts, test/sandbox-provisioning.test.ts, test/sandbox-rlimit-hooks.test.ts	Stages the patcher in Hermes fixtures and verifies read-only permissions across locking, provisioning, and replay flows.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DockerBuild
  participant CredentialPatcher
  participant HermesLangfuse
  participant PythonContract
  DockerBuild->>CredentialPatcher: Verify SHA256 and execute patch
  CredentialPatcher->>HermesLangfuse: Rewrite bundled validator
  DockerBuild->>HermesLangfuse: Import patched module
  HermesLangfuse->>PythonContract: Validate raw and resolver credentials

Loading

Suggested labels: integration: hermes, area: security, bug-fix

Suggested reviewers: ericksoa

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: Hermes now accepts Langfuse credential placeholders.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7446-hermes-langfuse-credentials

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 529a2a3 in the codex/7446-hermes-la... branch remains at 96%, unchanged from commit 8fcd69c in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 529a2a3 in the codex/7446-hermes-la... branch remains at 80%, unchanged from commit 8fcd69c in the main branch.

Show a code coverage summary of the most impacted files.

File	main 8fcd69c	codex/7446-hermes-la... 529a2a3	+/-
src/lib/state/m...-acquisition.ts	89%	87%	-2%
src/lib/sandbox...rce-identity.ts	87%	87%	0%

---

_{Updated July 24, 2026 18:49 UTC}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

agents/hermes/Dockerfile (1)

141-160: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Integrity-pin the patcher before executing it.

This security-policy patcher is only made read-only, then executed at Lines 218-220. A modified build-context script can alter validator behavior before the later hash gates run. Add a dedicated SHA-256 check immediately after copying it and before invoking Node.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@agents/hermes/Dockerfile` around lines 141 - 160, In the Hermes Dockerfile
setup, add a dedicated SHA-256 integrity check for
patch-hermes-langfuse-credentials.mts immediately after it is copied and before
the Node invocation around the patcher execution. Validate it against the
approved pinned digest and fail the image build on mismatch, before any later
hash gates run.

Source: Path instructions

🧹 Nitpick comments (1)

test/e2e/support/hermes-langfuse-credential-patch.test.ts (1)

84-97: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Verify the CLI result through validator behavior.

The token-presence assertion can pass even if the written validator is semantically wrong. Read the patched file and run the same acceptance/rejection assertions through runPython instead.

As per path instructions, “Prefer observable outcomes through the public boundary over source-text … assertions.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/e2e/support/hermes-langfuse-credential-patch.test.ts` around lines 84 -
97, Update the test case around the patcher CLI invocation to validate behavior
through the public validator boundary: read the patched fixture, execute it with
runPython, and assert the expected acceptance and rejection outcomes instead of
checking for the _LANGFUSE_OPENSHELL_KEYS token in source text. Preserve the
existing runtime and patching assertions.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@agents/hermes/Dockerfile`:
- Around line 141-160: In the Hermes Dockerfile setup, add a dedicated SHA-256
integrity check for patch-hermes-langfuse-credentials.mts immediately after it
is copied and before the Node invocation around the patcher execution. Validate
it against the approved pinned digest and fail the image build on mismatch,
before any later hash gates run.

---

Nitpick comments:
In `@test/e2e/support/hermes-langfuse-credential-patch.test.ts`:
- Around line 84-97: Update the test case around the patcher CLI invocation to
validate behavior through the public validator boundary: read the patched
fixture, execute it with runPython, and assert the expected acceptance and
rejection outcomes instead of checking for the _LANGFUSE_OPENSHELL_KEYS token in
source text. Preserve the existing runtime and patching assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 24039e3a-e59e-4de0-b716-572a357c5fe7

📥 Commits

Reviewing files that changed from the base of the PR and between fe56943 and 5c7ed7d.

📒 Files selected for processing (3)

• agents/hermes/Dockerfile
• agents/hermes/patch-langfuse-credentials.mts
• test/e2e/support/hermes-langfuse-credential-patch.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 more blocker, the same number of warnings, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, credential-sanitization, full-e2e, hermes-e2e, security-posture

2 optional E2E recommendations

• rebuild-hermes-stale-base
• network-policy

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[ericksoa]

Requesting changes on exact head 5c7ed7d87caca81dadd2de16ccfcfa5c7e8bdb75.

Two blockers:

1. The new chmod 444 /usr/local/lib/nemoclaw/patch-hermes-langfuse-credentials.mts target is not staged by the Dockerfile replay fixtures. Exact-head CI shards 3, 5, and 7 fail, and focused local validation reproduced the same three failures in test/hermes-doctor-config-hash.test.ts, test/sandbox-rlimit-hooks.test.ts, and test/sandbox-provisioning.test.ts. Please create and remap the new helper fixture in all three tests.

2. The linked issue still says Langfuse support is pending maintainer scope approval and calls for a managed base-URL / endpoint-policy path plus live authentication, trace-ingestion, and credential-sanitization proof. This PR modifies every shipped Hermes image but explicitly omits that supported path, and Fixes #7446 would close the unresolved integration issue. Please record an explicit maintainer decision accepting this narrow prerequisite and keep #7446 open for the remaining contract, or complete the supported integration and live evidence before shipping the image patch.

Positive evidence: the exact-name placeholder validation is narrowly bound and fail-closed, the focused patch tests pass 3/3 on Node 22.23.1, and the actual amd64/arm64 sandbox image builds pass. No raw credentials or new dependencies were introduced.

[ericksoa]

Follow-up on exact head ed94c081c3da5bf20a6e9c22ce1b8df5239a92bb:

The original review findings are addressed. The normal CI matrix, self-hosted image/E2E checks, CodeQL, CodeRabbit, and both advisor lanes are clean; the canonical advisor ledger has 0 blockers, 0 warnings, and 0 suggestions.

The required credentialed E2E evidence run remains blocking for shared runner/performance reasons:

• hermes-e2e and Hermes security-posture stopped before the changed runtime path: the runner created a 32 GiB swapfile but reported 0 of 34359738368 bytes active, then cleanup failed with Operation not permitted.
• OpenClaw full-e2e missed the existing cold-onboard threshold: 259 s observed vs 228 s allowed.
• cloud-onboard, credential-sanitization, and OpenClaw security-posture passed.

These signatures reproduce the earlier evidence run and are outside this credentials patch. I have not added an unrelated runner/bootstrap workaround here. Approval remains withheld because the required Hermes live path never reached the code under review.

[prekshivyas]

@ericksoa Re-review requested for exact head dd1f7a8f42edc5508fb981b7ad6c924c2d8f8cd5.

Both requested-change blockers are addressed:

1. The Hermes Dockerfile replay fixtures now stage/remap patch-hermes-langfuse-credentials.mts and assert its read-only image mode. The patcher is SHA-256 pinned before execution, and the CLI test validates behavior through the Python validator boundary.
2. Your explicit narrow-scope maintainer decision is recorded on [Hermes] Langfuse plugin cannot use OpenShell-managed credentials #7446; the issue remains open and this PR uses Refs #7446. The final follow-up also names [Hermes] Langfuse plugin cannot use OpenShell-managed credentials #7446 as the removal tracker and ties the bounded revision form to NemoClaw existing OpenShell observation contract.

Exact-head evidence:

• focused patch tests: 3/3 passed
• replay/image-layout integration tests: 79/79 passed
• npm run typecheck:cli, diff check, pre-commit, commit-msg, and pre-push hooks passed
• trusted CI matrix: green
• CodeRabbit: green; primary PR Review Advisor: 0 blockers
• credentialed E2E: cloud-onboard, credential-sanitization, and OpenClaw security-posture passed

The required E2E gate remains red only on the previously documented external signatures: both Hermes lanes fail before Hermes starts because the hosted runner reports 0/32 GiB swap active and cannot remove the swapfile; OpenClaw full-e2e records 253 s versus the existing 228 s cold-onboard budget. I did not add an unrelated runner or timing workaround. Please re-review the requested changes and decide whether to record a maintainer waiver or require a fresh run on an E2E-capable runner.

[prekshivyas]

Exact-head Hermes E2E + security posture: PASS

Tested PR head: dd1f7a8f42edc5508fb981b7ad6c924c2d8f8cd5

I ran the live Hermes E2E target locally on Docker Desktop arm64 with the pinned OpenShell 0.0.85 CLI/gateway and mock OpenAI-compatible inference:

npx tsx tools/e2e/live-vitest-invocation.mts run --test-path test/e2e/live/hermes-e2e.test.ts

Because the published pinned Hermes base is amd64-only, the supported changed-input path built agents/hermes/Dockerfile.base from this exact checkout and tagged it nemoclaw-hermes-sandbox-base-local:dd1f7a8f. The resulting image is arm64 and carries the expected com.nvidia.nemoclaw.base-build-provenance label.

Result: 1 passed, 0 failed, 0 skipped, 0 pending, 0 unhandled errors in 8m52s.

Passed boundaries:

• install.sh --non-interactive --fresh and Hermes onboarding
• sandbox layout, health, policy, and unintended-egress denial
• Hermes gateway restart/supervision and raw-secret restart refusal/recovery
• hosted-adapter and inference.local routes
• CLI manifest and locked-config behavior
• complete sandbox, OpenShell sandbox, and gateway cleanup

The risk signal records expectedSha == testedSha == dd1f7a8f42edc5508fb981b7ad6c924c2d8f8cd5.

I then reran the same exact-head target in the dedicated workflow posture mode:

• E2E_TARGET_ID=security-posture
• NEMOCLAW_E2E_SECURITY_POSTURE=1
• NEMOCLAW_E2E_EXPECT_NON_ROOT_HOST=1

Result: 1 passed, 0 failed, 0 skipped, 0 pending, 0 unhandled errors in 3m55s. The target result records securityPostureChecked: true, configureGuard: true, hostNonRoot: true, rcFilesLocked: true, runtimeProxyEnvLocked: true, and startupLogClean: true; cleanup also passed. Its risk signal independently records the same exact expected/tested SHA.

Both local runs used mock inference. The normal run covers the functional Hermes path; the posture run matches the dedicated lane's posture flags but does not substitute for its hosted-inference execution.

This adds exact-head functional evidence but does not replace the required hosted gate. The hosted Hermes lanes still fail before Vitest while provisioning swap on the runner. Dependency #7444 moved setup to the trusted workflow and added five bounded post-activation observations, but its latest exact-head hosted child still could not see active swap after all five attempts. E2E_LARGER_RUNNER_LABEL is currently unset, so the remaining hosted boundary needs a configured larger runner or another supported capacity path. Once that capacity/dependency lands, this PR still needs to sync main and rerun the hosted gate.

@ericksoa the requested Hermes functional and dedicated posture-mode E2E are now green on the exact PR head; the remaining red required check is the hosted runner-capacity dependency above.

[prekshivyas]

Security review — PASS

Exact head: 80c8af2e02e36a1365a629a3bd3e3dd084387fae

1. Secrets and credentials: PASS — raw Langfuse values remain outside the sandbox; only exact same-name OpenShell resolver placeholders are accepted.
2. Input validation: PASS — public and secret names cannot be swapped, revision digits are bounded to 1–20, malformed or prefixed placeholders are rejected, and upstream source drift fails closed.
3. Authentication and authorization: PASS — no auth or permission model changes.
4. Dependencies: PASS — no dependency changes; the patch targets the already pinned Hermes runtime.
5. Errors and logging: PASS — patch failures stop the image build and do not log credential material.
6. Cryptography and data protection: PASS — the patcher is SHA-256 checked before execution and installed read-only; no cryptographic algorithm changes.
7. Configuration security: PASS — no endpoint, network-policy, CLI, or supported onboarding surface is added.
8. Security testing: PASS — behavior tests cover raw keys, exact placeholders, swapped/malformed values, bounded revisions, idempotence, source drift, duplicate source blocks, image runtime execution, integrity, and final modes.
9. System security: PASS — runtime privileges and image ownership are unchanged; the merge resolution preserves the current BuildKit runtime-payload boundary.

Overall verdict: PASS, with no security findings. The narrow product-scope decision and removal condition remain tracked in #7446.

[prekshivyas]

Exact-head finish-line evidence for 80c8af2e02e36a1365a629a3bd3e3dd084387fae:

• PR is conflict-free and GitHub reports MERGEABLE.
• All trusted CI, both image builds, self-hosted smoke/isolation, CodeQL, CodeRabbit, and the primary advisor are green.
• Exact-head security review: PASS, no findings.
• Credentialed selected run 30111882383: hermes-e2e, Hermes security-posture, credential-sanitization, cloud-onboard, and OpenClaw security-posture all passed.
• The first full-e2e attempt failed only the known cold-onboard performance guard: 255s vs 228s overall; sandbox phase 206,776ms vs 171,000ms. Functional child commands and cleanup exited cleanly.
• A bounded same-run retry did not reproduce that assertion; it continued past the first attempt failure point and was terminated with exit 143 after about 20 minutes while its onboarding child remained active. No product assertion or fix(hermes): accept Langfuse credential placeholders #7447 credential-path failure was reported.

This PR does not touch OpenClaw onboarding or the shared performance budget. The changed Hermes credential path and both credential/security boundaries are green on the exact head. I have not changed or suppressed the performance guard.

@ericksoa please re-review the stale requested-changes state. The original code/scope findings are addressed; the remaining red required check is the unrelated full-E2E performance/runner signal above.

[prekshivyas]

Exact-head finish-line evidence for 529a2a31100affee3f3e1f15333ef3ab6192aeba against base 8fcd69c5aea8360d6f46f68b402cea16098c5443:

• The branch includes current main, is conflict-free, and the merge commit is GitHub Verified.
• All ordinary CI, both sandbox image builds, self-hosted smoke/isolation, CodeQL, CodeRabbit, both advisor lanes, DCO, and the documentation-writer receipt pass.
• Focused local verification after the merge passed 83/83 tests; git diff --check and pre-push hooks passed.
• Credentialed E2E run 30118700018 passed hermes-e2e, Hermes security-posture, credential-sanitization, cloud-onboard, and OpenClaw security-posture.
• The first OpenClaw posture attempt ended on a hosted-runner shutdown; the bounded failed-job retry passed it.
• full-e2e failed only the existing cold-onboard performance guard on both attempts: 270s and 269s versus the 228s overall budget, with sandbox phases 214,722ms and 214,954ms versus 171,000ms. Both attempts completed their child commands and cleanup without a product assertion outside that budget.

This PR does not change OpenClaw onboarding or the shared performance budget. The changed Hermes credential path and both credential/security boundaries are green on the exact head. I did not change or suppress the unrelated performance guard.

@ericksoa please re-review the stale requested-changes state and either approve the addressed code/scope findings or record a maintainer waiver for the remaining unrelated full-e2e performance result.

[ericksoa]

Approved on exact head 529a2a31100affee3f3e1f15333ef3ab6192aeba against base 8fcd69c5aea8360d6f46f68b402cea16098c5443.

The original requested changes are addressed. Ordinary CI, image/self-hosted checks, CodeQL, CodeRabbit, and the canonical advisor ledger are clean. In selected E2E run 30118700018, hermes-e2e, Hermes security-posture, credential-sanitization, cloud-onboard, and OpenClaw security-posture passed.

The remaining required-check failure is OpenClaw full-e2e cold-onboard performance (269s versus the existing 228s budget on the retry), outside this PR’s seven Hermes-only files. This approval covers the reviewed code and scope; it does not waive the required check or authorize merge.