// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. // SPDX-License-Identifier: Apache-2.0 import { HOSTED_NATIVE_PROVIDERS, nativeHostedAgentConfig, } from "./inference/native-provider/agent-config.ts"; import { customNativeProviderForSelection } from "./inference/native-provider/custom.ts"; import { NVIDIA_HOSTED_NATIVE_ENDPOINT } from "./inference/native-nvidia/contract.ts"; import { nativeLocalCredentialReference, NATIVE_LOCAL_CREDENTIAL_ENV, NATIVE_LOCAL_RUNTIME_REFERENCE_PATTERN, } from "./inference/native-local/agent-config.ts"; import { NATIVE_NVIDIA_SCOPED_HANDLE_PATTERN, managedInferenceApiKey, NVIDIA_INFERENCE_PLACEHOLDER, } from "./inference-credential.ts"; // Shared inference routing replaces this sentinel at egress. Native NVIDIA // routing instead expands the supervisor-issued environment handle. export const HERMES_PROXY_REWRITE_SENTINEL = "sk-OPENSHELL-PROXY-REWRITE"; type HermesManagedProvider = { name: string; api_key: string; discover_models: true; api?: string; base_url?: string; default_model?: string; transport?: string; api_mode?: string; }; export type HermesManagedRouting = { _nemoclaw_upstream: { provider: string; provider_key: string; model: string; }; model: { default: string; provider: "custom"; base_url: string; api_key: string; api_mode?: string; context_length?: number; }; providers: Record; custom_providers: HermesManagedProvider[]; }; export type HermesManagedRoute = { model: string; baseUrl: string; upstreamProvider: string; inferenceApi: string; contextWindow?: number | null; nativeCredentialHandle?: string; }; function isObjectRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } export function hermesApiMode(inferenceApi: string): string | null { switch (inferenceApi) { case "": case "openai-completions": return null; case "anthropic-messages": return "anthropic_messages"; case "openai-responses": return "codex_responses"; default: throw new Error(`Unsupported Hermes inference API: ${inferenceApi}`); } } export function hermesProviderKey(provider: string): string { const normalized = provider .trim() .toLowerCase() .replaceAll(" ", "-") .replace(/[()]/gu, "") .replace(/-+/gu, "-") .replace(/^-|-$/gu, ""); return normalized || "nemoclaw-inference"; } /** Apply the complete NemoClaw-owned Hermes route to an existing config. */ export function applyHermesManagedRoute( config: Record, route: HermesManagedRoute, ): asserts config is Record & HermesManagedRouting { const nativeHosted = nativeHostedAgentConfig(route.upstreamProvider, route.baseUrl); const nativeLocal = nativeLocalCredentialReference(route.upstreamProvider, route.baseUrl); let apiKey = nativeLocal ? `\${${NATIVE_LOCAL_CREDENTIAL_ENV}}` : nativeHosted ? `\${${nativeHosted.credentialEnv}}` : managedInferenceApiKey(route.baseUrl, HERMES_PROXY_REWRITE_SENTINEL); if (route.nativeCredentialHandle !== undefined) { if (nativeLocal) { const match = new RegExp(NATIVE_LOCAL_RUNTIME_REFERENCE_PATTERN).exec( route.nativeCredentialHandle, ); // Require the entire value: JavaScript's `$` also matches before a final newline. if (!match || match[0] !== route.nativeCredentialHandle) { throw new Error("Hermes native local route requires a provider-bound credential handle."); } } else if ( route.upstreamProvider !== "nvidia-prod" || apiKey !== NVIDIA_INFERENCE_PLACEHOLDER || !NATIVE_NVIDIA_SCOPED_HANDLE_PATTERN.test(route.nativeCredentialHandle) ) { throw new Error("Hermes native NVIDIA route requires a provider-bound credential handle."); } apiKey = route.nativeCredentialHandle; } const providerName = route.upstreamProvider || "nemoclaw-inference"; const providerKey = hermesProviderKey(providerName); const apiMode = hermesApiMode(route.inferenceApi); const previousUpstream = isObjectRecord(config._nemoclaw_upstream) ? config._nemoclaw_upstream : {}; const previousProviderKey = typeof previousUpstream.provider_key === "string" ? previousUpstream.provider_key : ""; const modelConfig: Record = { default: route.model, provider: "custom", base_url: route.baseUrl, api_key: apiKey, ...(nativeHosted?.headers ? { default_headers: nativeHosted.headers } : {}), }; if (apiMode) modelConfig.api_mode = apiMode; if (route.contextWindow !== null && route.contextWindow !== undefined) { // Hermes reads context_length before endpoint discovery and model metadata. modelConfig.context_length = route.contextWindow; } const providerConfig: Record = { name: providerName, api: route.baseUrl, api_key: apiKey, ...(nativeHosted?.headers ? { default_headers: nativeHosted.headers } : {}), default_model: route.model, discover_models: true, }; if (apiMode) providerConfig.transport = apiMode; const customProvider: Record = { name: providerName, base_url: route.baseUrl, api_key: apiKey, ...(nativeHosted?.headers ? { default_headers: nativeHosted.headers } : {}), discover_models: true, }; if (apiMode) customProvider.api_mode = apiMode; const providers = isObjectRecord(config.providers) ? { ...config.providers } : {}; if (previousProviderKey && previousProviderKey !== providerKey) { delete providers[previousProviderKey]; } providers[providerKey] = providerConfig; const customProviders = Array.isArray(config.custom_providers) ? config.custom_providers.filter( (entry) => !isObjectRecord(entry) || (entry.name !== previousUpstream.provider && entry.name !== providerName), ) : []; customProviders.push(customProvider); config._nemoclaw_upstream = { provider: providerName, provider_key: providerKey, model: route.model, }; config.model = modelConfig; config.providers = providers; config.custom_providers = customProviders; } /** Refresh an issued managed reference without replacing restored model settings. */ export function refreshHermesNativeLocalCredential( config: Record, route: HermesManagedRoute & { nativeCredentialHandle: string }, options: { recoverStrippedNvidia?: boolean } = {}, ): void { const expected: Record = {}; applyHermesManagedRoute(expected, route); const upstream = isObjectRecord(config._nemoclaw_upstream) ? config._nemoclaw_upstream : {}; const model = isObjectRecord(config.model) ? config.model : {}; const providers = isObjectRecord(config.providers) ? config.providers : {}; const providerKey = hermesProviderKey(route.upstreamProvider); const managed = isObjectRecord(providers[providerKey]) ? providers[providerKey] : {}; const custom = Array.isArray(config.custom_providers) ? config.custom_providers : []; const matches = custom.filter( (entry) => isObjectRecord(entry) && entry.name === route.upstreamProvider, ); const previous = model.api_key; const nvidia = route.upstreamProvider === "nvidia-prod" && managedInferenceApiKey(route.baseUrl, "") === NVIDIA_INFERENCE_PLACEHOLDER; const pattern = nvidia ? NATIVE_NVIDIA_SCOPED_HANDLE_PATTERN : new RegExp(NATIVE_LOCAL_RUNTIME_REFERENCE_PATTERN); const template = nvidia ? NVIDIA_INFERENCE_PLACEHOLDER : `\${${NATIVE_LOCAL_CREDENTIAL_ENV}}`; const reference = pattern.exec(String(previous)); // The sentinel identifies damage, not authority. Only the registered restore // caller may admit it after verifying live identity and provider binding. const recoverStripped = options.recoverStrippedNvidia === true && nvidia && previous === "[STRIPPED_BY_MIGRATION]"; if ( (!nvidia && !nativeLocalCredentialReference(route.upstreamProvider, route.baseUrl)) || upstream.provider !== route.upstreamProvider || upstream.provider_key !== providerKey || upstream.model !== route.model || model.default !== route.model || model.provider !== "custom" || model.base_url !== route.baseUrl || (model.api_mode ?? null) !== (expected.model.api_mode ?? null) || managed.api !== route.baseUrl || managed.default_model !== route.model || (managed.transport ?? null) !== (expected.providers[providerKey].transport ?? null) || matches.length !== 1 || matches[0].base_url !== route.baseUrl || (matches[0].api_mode ?? null) !== (expected.custom_providers[0].api_mode ?? null) || typeof previous !== "string" || managed.api_key !== previous || matches[0].api_key !== previous || (previous !== template && reference?.[0] !== previous && !recoverStripped) ) { throw new Error("Restored Hermes inference configuration does not match its registered route."); } // YAML aliases may share these maps with user settings: replace only owned // credential slots, while retaining the config object's guarded-read digest. config.model = { ...model, api_key: route.nativeCredentialHandle }; config.providers = { ...providers, [providerKey]: { ...managed, api_key: route.nativeCredentialHandle }, }; config.custom_providers = custom.map((entry) => entry === matches[0] ? { ...entry, api_key: route.nativeCredentialHandle } : entry, ); } /** Registered provider and authorized agent endpoint used by archive sanitation. */ export type HermesRegisteredRoute = Readonly<{ provider?: string | null; endpointUrl?: string | null; }>; function hermesArchiveEndpoint(value: string): string { // URL serialization normalizes host spelling and default ports, while retaining // the API path, credentials, query and fragment for the writer's validation. return new URL(value).href.replace(/\/+$/u, ""); } /** Reconcile logical registration with its validated sandbox-facing binding. */ export function hermesRegisteredRoute( selection: Parameters[0], ): HermesRegisteredRoute { const { provider } = selection; try { const custom = customNativeProviderForSelection(selection); const attachment = selection.nativeHostedProviderAttachment; // The binding owner checks the logical endpoint, API and credential name, // then supplies the agent projection (for example /team -> /team/v1). if ( custom && selection.endpointUrl && !nativeHostedAgentConfig(provider, selection.endpointUrl) ) return { provider, endpointUrl: null }; const endpoints = ( custom ? [custom.endpointUrl] : [selection.endpointUrl, attachment?.endpointUrl] ) .filter((endpoint): endpoint is string => endpoint !== null && endpoint !== undefined) .map(hermesArchiveEndpoint); const endpointUrl = endpoints[0]; return { provider, endpointUrl: endpointUrl && endpoints.every((endpoint) => endpoint === endpointUrl) ? endpointUrl : null, }; } catch { return { provider, endpointUrl: null }; } } /** * Resolve the endpoint and environment reference NemoClaw generates for a route. * * A fixed provider has one canonical endpoint, so its reference cannot point at * a different destination. A custom endpoint, or the endpoint an authenticated * Hermes Provider login returned, is chosen outside NemoClaw, so the archived * route must match the authorized agent endpoint. When `registered` is given, the * archived provider must also be the registered one. Pass it when sanitizing an * archive. Omit it only to inspect an archive whose routes sanitation already * verified. */ export function hermesManagedRouteReference( provider: string, baseUrl: unknown, registered?: HermesRegisteredRoute, ): { endpoint: string; template: string } | null { if (registered !== undefined && registered.provider !== provider) return null; if (provider === "nvidia-prod") { return { endpoint: NVIDIA_HOSTED_NATIVE_ENDPOINT, template: NVIDIA_INFERENCE_PLACEHOLDER }; } const fixed = HOSTED_NATIVE_PROVIDERS.find((entry) => entry.logicalProvider === provider); const returnedEndpoint = provider === "hermes-provider" && typeof baseUrl === "string" && baseUrl !== fixed?.endpoint; if (fixed && !returnedEndpoint) { return { endpoint: fixed.endpoint, template: `\${${fixed.credentialEnv}}` }; } if (typeof baseUrl !== "string") return null; try { if (registered !== undefined && registered.endpointUrl !== hermesArchiveEndpoint(baseUrl)) return null; // Reuse the writer's provider and endpoint restrictions. const hosted = nativeHostedAgentConfig(provider, baseUrl); return hosted ? { endpoint: baseUrl, template: `\${${hosted.credentialEnv}}` } : null; } catch { return null; } }