Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
3a49dc0
test(mcp): reproduce Hermes credential revision loss
rsliter Aug 25, 2026
ff64f5c
fix(mcp): preserve Hermes credential revisions
cjagwani Aug 25, 2026
dbdfb29
fix(mcp): align Hermes credential revision contract
prekshivyas Aug 25, 2026
3fa0229
test(mcp): execute Hermes config assertions
apurvvkumaria Aug 25, 2026
8a0127e
merge: refresh from main
apurvvkumaria Aug 25, 2026
0a17735
fix(mcp): preserve revision during teardown rollback
ericksoa Aug 25, 2026
bd3ce57
fix(hermes): avoid duplicate applied anchor writes
prekshivyas Aug 25, 2026
bcf9ebd
fix(mcp): retain scrub rollback revision state
ericksoa Aug 25, 2026
2547e0f
merge: resolve conflicts with main
github-actions[bot] Aug 25, 2026
1692806
fix(mcp): preserve invoked recovery command
apurvvkumaria Aug 25, 2026
98374ee
fix(mcp): reconcile Hermes revision metadata after main merge
prekshivyas Aug 25, 2026
9a4668e
merge: synchronize current main
apurvvkumaria Aug 25, 2026
6c6f0e1
test(mcp): cover Hermes lifecycle rollback revisions
prekshivyas Aug 25, 2026
7d735f9
merge: preserve concurrent PR repairs
apurvvkumaria Aug 25, 2026
6861810
merge: preserve concurrent lifecycle coverage
apurvvkumaria Aug 25, 2026
f445921
merge: synchronize current main
apurvvkumaria Aug 25, 2026
e8c1200
fix(mcp): remove Hermes helper metadata
apurvvkumaria Aug 25, 2026
d4ce801
refactor(mcp): use Hermes branding owner directly
prekshivyas Aug 25, 2026
057e5e8
merge: synchronize current main
apurvvkumaria Aug 25, 2026
f78f84a
refactor(snapshot): inject CLI name into Hermes hint
ericksoa Aug 25, 2026
2f6fc2b
fix(mcp): keep recovery branding within budget
apurvvkumaria Aug 25, 2026
9904cda
merge: preserve concurrent architecture repair
apurvvkumaria Aug 25, 2026
7b45f8a
merge: synchronize current main
apurvvkumaria Aug 25, 2026
78a6282
chore(architecture): lower branding fan-in budget
apurvvkumaria Aug 25, 2026
35ddb05
refactor(mcp): remove recovery command wrapper
apurvvkumaria Aug 25, 2026
594a508
refactor(mcp): inline Hermes recovery branding
prekshivyas Aug 25, 2026
6505f05
merge: preserve contributor architecture repair
apurvvkumaria Aug 25, 2026
302435a
chore(architecture): retain branding fan-in budget
apurvvkumaria Aug 25, 2026
42bc649
docs(mcp): describe Hermes credential revisions
rsliter Aug 25, 2026
1219dc2
fix(mcp): wait for stable credential revision
prekshivyas Aug 25, 2026
4b59c3d
test(mcp): expect stable credential revision
rsliter Aug 25, 2026
e5263dd
Merge branch 'main' into codex/fix-hermes-mcp-runtime-contract-10155
rsliter Aug 26, 2026
4d7ac91
fix(mcp): await exact credential revision
prekshivyas Aug 26, 2026
0cff15f
fix(mcp): keep credential revisions opaque
rsliter Aug 26, 2026
da46392
ci(e2e): reuse exact PR image cohort
ericksoa Aug 26, 2026
f152596
merge: synchronize exact E2E evidence
rsliter Aug 26, 2026
c87835b
ci(e2e): remove temporary exact cohort reuse
rsliter Aug 26, 2026
557b3c6
fix(mcp): fence opaque credential revisions
prekshivyas Aug 26, 2026
f7cf37c
test(mcp): mock credential revision fence
prekshivyas Aug 26, 2026
1613083
merge: synchronize latest main
prekshivyas Aug 26, 2026
286818d
fix(mcp): keep teardown revisions opaque
prekshivyas Aug 26, 2026
cbf312d
docs(mcp): document teardown revision recovery
rsliter Aug 26, 2026
90cc104
Merge remote-tracking branch 'origin/main' into codex/10155-hermes-mc…
prekshivyas Aug 26, 2026
d7a0a6a
test(repository): remove duplicate advisor watch trigger
prekshivyas Aug 26, 2026
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
67 changes: 64 additions & 3 deletions agents/hermes/mcp-config-transaction.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@
ENV_PLACEHOLDER_RE = re.compile(
r"^Bearer openshell:resolve:env:([A-Za-z_][A-Za-z0-9_]{0,127})$"
)
REVISIONED_ENV_PLACEHOLDER_RE = re.compile(
r"^Bearer openshell:resolve:env:v[0-9]{1,20}_([A-Za-z_][A-Za-z0-9_]{0,127})$"
)
OPENSHELL_REVISIONED_CREDENTIAL_NAME_RE = re.compile(r"^v[0-9]+_[A-Za-z0-9_]+$")
BOUNDARY_MANIFEST_NAME = "openshell-child-visible-credentials.v0.0.106.json"
ANSI_ESCAPE_RE = re.compile(
Expand Down Expand Up @@ -453,15 +456,30 @@ def _validate_payload(action: str, payload: dict[str, object]) -> None:
if not isinstance(headers, dict) or set(headers) != {"Authorization"}:
raise ValueError("MCP mutation payload must contain one Authorization header")
authorization = headers.get("Authorization")
authorization_match = (
revisioned_authorization_match = (
REVISIONED_ENV_PLACEHOLDER_RE.fullmatch(authorization)
if isinstance(authorization, str)
else None
)
canonical_authorization_match = (
ENV_PLACEHOLDER_RE.fullmatch(authorization)
if isinstance(authorization, str)
else None
)
authorization_match = (
revisioned_authorization_match or canonical_authorization_match
)
if authorization_match is None:
raise ValueError(
"Hermes MCP Authorization must contain an OpenShell environment placeholder"
)
if action == "add" and revisioned_authorization_match is not None:
credential_name = revisioned_authorization_match.group(1)
expected_child_value = authorization.removeprefix("Bearer ")
if os.environ.get(credential_name) != expected_child_value:
raise ValueError(
"Hermes MCP Authorization revision does not match the OpenShell child environment"
)
if action == "add" and _credential_name_is_reserved(authorization_match.group(1)):
raise ValueError(
"Hermes MCP Authorization uses a reserved credential environment name"
Expand All @@ -484,6 +502,46 @@ def _managed_candidate(payload: dict[str, object]) -> dict[str, object]:
return candidate


def _managed_candidate_matches(
actual: object, expected: dict[str, object], allow_revisioned: bool
) -> bool:
"""Compare managed config with bounded revision equivalence when requested."""
if actual == expected:
return True
if not allow_revisioned or not isinstance(actual, dict):
return False
if set(actual) != set(expected):
return False
for name, value in expected.items():
if name != "headers" and actual.get(name) != value:
return False
actual_headers = actual.get("headers")
expected_headers = expected.get("headers")
if not isinstance(actual_headers, dict) or not isinstance(expected_headers, dict):
return False
if set(actual_headers) != {"Authorization"} or set(expected_headers) != {
"Authorization"
}:
return False
expected_authorization = expected_headers.get("Authorization")
actual_authorization = actual_headers.get("Authorization")
expected_match = (
ENV_PLACEHOLDER_RE.fullmatch(expected_authorization)
if isinstance(expected_authorization, str)
else None
)
actual_match = (
REVISIONED_ENV_PLACEHOLDER_RE.fullmatch(actual_authorization)
if isinstance(actual_authorization, str)
else None
)
return (
expected_match is not None
and actual_match is not None
and actual_match.group(1) == expected_match.group(1)
)


_MANAGED_CANDIDATE_FIELDS = frozenset(
{"url", "enabled", "timeout", "connect_timeout", "tools", "headers"}
)
Expand Down Expand Up @@ -555,7 +613,10 @@ def inspect_managed_config(payload: dict[str, object]) -> dict[str, object]:
absent = payload["absent"]
if not isinstance(present, dict) or not isinstance(absent, list):
raise RuntimeError("Hermes MCP config does not match persisted managed intent")
matches = all(servers.get(name) == expected for name, expected in present.items())
matches = all(
_managed_candidate_matches(servers.get(name), expected, True)
for name, expected in present.items()
)
matches = matches and all(name not in servers for name in absent)
if not matches:
raise RuntimeError("Hermes MCP config does not match persisted managed intent")
Expand Down Expand Up @@ -595,7 +656,7 @@ def _mutate(data: object, action: str, payload: dict[str, object]) -> tuple[dict
return data, False
if payload.get("force") is not True:
current = servers.get(server_name)
if current != _managed_candidate(payload):
if not _managed_candidate_matches(current, _managed_candidate(payload), True):
raise ValueError(
f"Refusing to remove modified Hermes MCP server '{server_name}'. Use --force to remove it."
)
Expand Down
57 changes: 57 additions & 0 deletions src/lib/actions/sandbox/mcp-bridge-adapter-hermes.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import { spawnSync } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";

import { describe, expect, it } from "vitest";

import type { McpBridgeEntry } from "../../state/registry";
Expand All @@ -9,6 +14,10 @@
buildHermesMcpProbeCommand,
buildHermesMcpRegisterCommand,
} from "./mcp-bridge-adapter-hermes";
import {
buildHermesMcpStatusCommand,
HERMES_MCP_TRANSACTION_HELPER,
} from "./mcp-bridge-adapter-status";

const baseEntry: McpBridgeEntry = {
server: "github",
Expand Down Expand Up @@ -64,4 +73,52 @@
"probe",
]);
});

it("projects the readiness-proven credential revision without helper-only metadata (#10155)", () => {
const command = buildHermesMcpRegisterCommand(baseEntry, false, "v12");

expect(JSON.parse(command[3] ?? "{}")).toEqual({
server: "github",
url: "https://api.githubcopilot.com/mcp/",
headers: { Authorization: "Bearer openshell:resolve:env:v12_GITHUB_TOKEN" },
replace_existing: false,
});
});

it("accepts a revision on resumed inspection and rejects a stale exact revision (#10155)", () => {
const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-hermes-mcp-revision-"));
const configPath = path.join(temp, "config.yaml");
const helperPath = path.resolve("agents/hermes/mcp-config-transaction.py");
fs.writeFileSync(
configPath,
JSON.stringify({
mcp_servers: {
github: {
url: baseEntry.url,
enabled: true,
timeout: 120,
connect_timeout: 60,
tools: { resources: true, prompts: true },
headers: { Authorization: "Bearer openshell:resolve:env:v12_GITHUB_TOKEN" },
},
},
}),
);

const inspect = (credentialRevision?: "v11" | "v12") => {
const command = buildHermesMcpStatusCommand(baseEntry, credentialRevision)
.replace("/opt/hermes/.venv/bin/python", "python3")
.replaceAll(HERMES_MCP_TRANSACTION_HELPER, helperPath)
.replaceAll("/sandbox/.hermes/config.yaml", configPath);
return spawnSync("/bin/sh", ["-c", command], { encoding: "utf8" });
Comment thread
github-advanced-security[bot] marked this conversation as resolved.
Fixed
};

try {
expect(inspect().stdout.trim()).toBe("registered");
expect(inspect("v12").stdout.trim()).toBe("registered");
expect(inspect("v11").stdout.trim()).toBe("mismatch");
} finally {
fs.rmSync(temp, { recursive: true, force: true });
}
});
});
31 changes: 23 additions & 8 deletions src/lib/actions/sandbox/mcp-bridge-adapter-hermes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,16 @@ import {
type AdapterRegistrationInspection,
inspectAdapterRegistrationCommand,
} from "./mcp-bridge-adapter-inspection";
import { buildHermesMcpStatusCommand, entryHeaders } from "./mcp-bridge-adapter-status";
import {
buildHermesMcpStatusCommand,
entryHeaders,
HERMES_MCP_TRANSACTION_HELPER,
} from "./mcp-bridge-adapter-status";
import { McpBridgeError } from "./mcp-bridge-contracts";
import { commandOutput, redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
import { executeGatewaySupervisorAction } from "./process-recovery";

const HERMES_MCP_TRANSACTION_HELPER = "/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";
const HERMES_MCP_EXEC_TIMEOUT_SECONDS = 620;
const HERMES_MCP_PROBE_TIMEOUT_SECONDS = 30;
const HERMES_MCP_STARTUP_TIMEOUT_SECONDS = 90;
Expand All @@ -32,11 +36,12 @@ const HERMES_MCP_LIFECYCLE_NOT_READY =
export function buildHermesMcpRegisterCommand(
entry: McpBridgeEntry,
replaceExisting = false,
credentialRevision?: McpAttachedCredentialRevision,
): string[] {
const payload = {
server: entry.server,
url: entry.url,
headers: entryHeaders(entry),
headers: entryHeaders(entry, credentialRevision),
replace_existing: replaceExisting,
};
return [HERMES_MCP_TRANSACTION_HELPER, "add", "--payload", JSON.stringify(payload)];
Expand Down Expand Up @@ -77,8 +82,13 @@ export function buildHermesMcpProbeCommand(): string[] {
export function inspectHermesAdapterRegistration(
sandboxName: string,
entry: McpBridgeEntry,
credentialRevision?: McpAttachedCredentialRevision,
): AdapterRegistrationInspection {
return inspectAdapterRegistrationCommand(sandboxName, entry, buildHermesMcpStatusCommand(entry));
return inspectAdapterRegistrationCommand(
sandboxName,
entry,
buildHermesMcpStatusCommand(entry, credentialRevision),
);
}

function parseLastJsonObject(output: string): Record<string, unknown> | null {
Expand Down Expand Up @@ -267,8 +277,12 @@ function runHermesAdapterCommand(
}
}

function verifyHermesAdapterRegistration(sandboxName: string, entry: McpBridgeEntry): void {
const inspection = inspectHermesAdapterRegistration(sandboxName, entry);
function verifyHermesAdapterRegistration(
sandboxName: string,
entry: McpBridgeEntry,
credentialRevision?: McpAttachedCredentialRevision,
): void {
const inspection = inspectHermesAdapterRegistration(sandboxName, entry, credentialRevision);
if (inspection.state === "registered") return;
const detail = inspection.state === "error" ? inspection.detail : inspection.state;
throw new McpBridgeError(
Expand All @@ -281,15 +295,16 @@ export function registerHermesAdapter(
entry: McpBridgeEntry,
envValues: Record<string, string> = {},
replaceExisting = false,
credentialRevision?: McpAttachedCredentialRevision,
): void {
runHermesAdapterCommand(
sandboxName,
entry,
buildHermesMcpRegisterCommand(entry, replaceExisting),
buildHermesMcpRegisterCommand(entry, replaceExisting, credentialRevision),
`Hermes MCP config registration failed for '${entry.server}'.`,
{ envValues, requireReload: true },
);
verifyHermesAdapterRegistration(sandboxName, entry);
verifyHermesAdapterRegistration(sandboxName, entry, credentialRevision);
}

export function unregisterHermesAdapter(
Expand Down
26 changes: 26 additions & 0 deletions src/lib/actions/sandbox/mcp-bridge-adapter-registration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -154,3 +154,29 @@ describe("OpenClaw MCP adapter registration", () => {
);
});
});

describe("Hermes MCP adapter registration", () => {
beforeEach(() => {
mocks.executeSandboxCommand.mockReset().mockReturnValue(registered);
mocks.runOpenshellProviderCommand.mockReset().mockReturnValue(lifecycleSuccess);
});

it("projects the readiness-proven credential revision into Hermes config (#10155)", () => {
registerAgentAdapter(
"alpha",
"hermes-config",
baseEntry,
{ GITHUB_TOKEN: "host-only-secret" },
{ credentialRevision: "v12" },
);

const transactionArgs = mocks.runOpenshellProviderCommand.mock.calls[0]?.[0] as string[];
const payloadIndex = transactionArgs.indexOf("--payload") + 1;
expect(JSON.parse(transactionArgs[payloadIndex] ?? "{}")).toMatchObject({
headers: { Authorization: "Bearer openshell:resolve:env:v12_GITHUB_TOKEN" },
});
expect(mocks.executeSandboxCommand.mock.calls.at(-1)?.[1]).toContain(
"Bearer openshell:resolve:env:v12_GITHUB_TOKEN",
);
});
});
28 changes: 22 additions & 6 deletions src/lib/actions/sandbox/mcp-bridge-adapter-status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ import {
// state can never be layered over the validated registry projection.
export const DEEPAGENTS_MCP_CONFIG_PATH = "/sandbox/.deepagents/.nemoclaw-mcp.json";
export const DEFAULT_OPENCLAW_CONFIG_DIR = "/sandbox/.openclaw";
export const HERMES_MCP_TRANSACTION_HELPER =
"/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";

/** Resolve Mcporter's project root beneath an OpenClaw agent configuration directory. */
export function openClawMcporterRoot(configDir = DEFAULT_OPENCLAW_CONFIG_DIR): string {
Expand Down Expand Up @@ -109,8 +111,11 @@ export function mcporterHeaderMatcherSource(): string {
return `const mcporterHeadersMatchExpected = ${mcporterHeadersMatchExpected.toString()};`;
}

export function hermesManagedServerConfig(entry: McpBridgeEntry): Record<string, unknown> {
const headers = entryHeaders(entry);
export function hermesManagedServerConfig(
entry: McpBridgeEntry,
credentialRevision?: McpAttachedCredentialRevision,
): Record<string, unknown> {
const headers = entryHeaders(entry, credentialRevision);
return {
url: entry.url,
enabled: true,
Expand Down Expand Up @@ -149,21 +154,32 @@ export function deepAgentsManagedServerConfig(entry: McpBridgeEntry): Record<str
};
}

export function buildHermesMcpStatusCommand(entry: McpBridgeEntry): string {
export function buildHermesMcpStatusCommand(
entry: McpBridgeEntry,
credentialRevision?: McpAttachedCredentialRevision,
): string {
const payload = {
server: entry.server,
expected: hermesManagedServerConfig(entry),
expected: hermesManagedServerConfig(entry, credentialRevision),
allowRevisioned: credentialRevision === undefined,
};
return [
"/opt/hermes/.venv/bin/python - <<'PY'",
"import json, pathlib, yaml",
"import importlib.util, json, pathlib, sys, yaml",
`payload = json.loads(${pythonJsonLiteral(payload)})`,
`module_path = ${JSON.stringify(HERMES_MCP_TRANSACTION_HELPER)}`,
"spec = importlib.util.spec_from_file_location('nemoclaw_hermes_mcp_transaction_inspect', module_path)",
"if spec is None or spec.loader is None:",
" raise RuntimeError('Hermes MCP transaction helper could not be loaded')",
"transaction = importlib.util.module_from_spec(spec)",
"sys.modules[spec.name] = transaction",
"spec.loader.exec_module(transaction)",
'config_path = pathlib.Path("/sandbox/.hermes/config.yaml")',
"data = yaml.safe_load(config_path.read_text(encoding='utf-8')) if config_path.exists() else {}",
"servers = data.get('mcp_servers') if isinstance(data, dict) else None",
"present = isinstance(servers, dict) and payload['server'] in servers",
"server = servers.get(payload['server']) if present else None",
"ok = server == payload['expected']",
"ok = transaction._managed_candidate_matches(server, payload['expected'], payload['allowRevisioned'])",
"print('registered' if ok else ('mismatch' if present else 'absent'))",
"PY",
].join("\n");
Expand Down
8 changes: 7 additions & 1 deletion src/lib/actions/sandbox/mcp-bridge-adapters.ts
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,13 @@ export function registerAgentAdapter(
);
return;
case "hermes-config":
registerHermesAdapter(sandboxName, entry, envValues, options.replaceExisting === true);
registerHermesAdapter(
sandboxName,
entry,
envValues,
options.replaceExisting === true,
options.credentialRevision,
);
return;
case "deepagents-config":
registerDeepAgentsAdapter(
Expand Down
6 changes: 4 additions & 2 deletions src/lib/actions/sandbox/mcp-bridge-hermes-reconciliation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,14 @@ import { runOpenshellProviderCommand } from "../../adapters/openshell/provider-c
import { redactFull } from "../../security/redact";
import type { McpBridgeEntry, SandboxEntry } from "../../state/registry";
import * as registry from "../../state/registry";
import { buildHermesMcpIntentPayload } from "./mcp-bridge-adapter-status";
import {
buildHermesMcpIntentPayload,
HERMES_MCP_TRANSACTION_HELPER,
} from "./mcp-bridge-adapter-status";
import { McpBridgeError } from "./mcp-bridge-contracts";
import { redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
import { sleepMcpBridgeRetry } from "./mcp-bridge/timing";

const HERMES_MCP_TRANSACTION_HELPER = "/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";
const HERMES_MCP_INSPECT_TIMEOUT_SECONDS = 45;
const HERMES_MCP_INSPECT_TIMEOUT_MS = 60_000;
const HERMES_MCP_RECONCILIATION_FAILURE =
Expand Down
Loading
Loading