fix(onboard): distinguish Gemini runtime 404 (#9347)

<!-- markdownlint-disable MD041 -->
## Summary

Distinguish a Google Gemini OpenAI-compatible Chat Completions 404 from
native model-catalog validation. The report in #9298 attributes its
failure to `/v1beta/openai/models`, but v0.0.108 and current `main`
already validate Gemini models through `/v1beta/models`; the captured
`Chat Completions API: HTTP 404` instead comes from the separate runtime
route.

This change preserves fail-closed validation. It does not accept native
catalog availability as proof that the OpenAI-compatible route used by
the sandbox can serve the model. A real-key reproduction of the runtime
404 is still needed before this PR can claim to resolve provider
availability.

## Related Issue

Refs #9298

## Changes

- Carry the selected provider into validation as diagnostic-only context
without forwarding it to the network probe.
- Explain an exact Gemini Chat Completions HTTP 404 as a runtime-route
failure, not a native model-catalog failure.
- Add regression tests for provider-context isolation, credential
redaction, and the failure guidance.
- Document the distinction and the reason onboarding stops.

## Type of Change

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

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [ ] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: Pending external review
from @cv.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit: Not applicable
- Station profile/scenario: Not applicable
- Result: Not applicable
- Supporting evidence: Not applicable

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — `npx vitest run --project cli
src/lib/onboard/inference-selection-validation.test.ts
src/lib/onboard/setup-nim-selection.test.ts` (34 passed)
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result: Not applicable; the change
is limited to provider-specific failure diagnostics and wiring.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) — build
succeeded with 0 errors and 2 pre-existing warnings
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

Additional validation: `npm run build:cli`, `npm --prefix nemoclaw run
build`, `npm run typecheck:cli`, and `npm run checks:repository` passed.

---
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

Author: prekshivyas

docs/inference/use-google-gemini.mdx

@@ -74,6 +74,11 @@ Model validation can fail with these messages:
   The validation request failed.
   The output shows the provider, model, and API base URL.
   Compare these values with your configuration.
+- `Validation probe summary: Chat Completions API: HTTP 404.`
+  This result comes from Google's OpenAI-compatible `/v1beta/openai/chat/completions` runtime route, not the native `/v1beta/models` catalog.
+  A model appearing in the native catalog does not prove that the runtime route can serve it.
+  NemoClaw stops because the sandbox uses the Chat Completions route for inference.
+  Retry the request, then verify that the same key and model can invoke Google's OpenAI-compatible Chat Completions endpoint.
 
 ## Related Topics
 

src/lib/onboard/inference-selection-validation.test.ts

@@ -87,6 +87,55 @@ describe("inference selection validation", () => {
     }
   });
 
+  it("distinguishes a Gemini runtime 404 from native model catalog validation (#9298)", async () => {
+    const apiKey = "gemini-test-secret";
+    const probeOpenAiLikeEndpoint = vi.fn(() => ({
+      ok: false,
+      failures: [{ name: "Chat Completions API", httpStatus: 404, curlStatus: 0 }],
+    }));
+    const promptValidationRecovery = vi.fn(async () => "selection" as const);
+    const helpers = createInferenceSelectionValidationHelpers({
+      isNonInteractive: () => false,
+      agentProductName: () => "OpenClaw",
+      getCredential: () => apiKey,
+      probeOpenAiLikeEndpoint,
+      promptValidationRecovery,
+    });
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        helpers.validateOpenAiLikeSelection(
+          "Google Gemini",
+          "https://generativelanguage.googleapis.com/v1beta/openai",
+          "gemini-2.5-flash",
+          "GEMINI_API_KEY",
+          undefined,
+          undefined,
+          { provider: "gemini-api", skipResponsesProbe: true },
+        ),
+      ).resolves.toEqual({ ok: false, retry: "selection" });
+      expect(probeOpenAiLikeEndpoint).toHaveBeenCalledWith(
+        "https://generativelanguage.googleapis.com/v1beta/openai",
+        "gemini-2.5-flash",
+        apiKey,
+        { skipResponsesProbe: true, calibrateTimeouts: true },
+      );
+      const errorOutput = error.mock.calls.map((args) => args.join(" ")).join("\n");
+      expect(errorOutput).toContain(
+        "This 404 came from Google's OpenAI-compatible Chat Completions runtime route, not the native /v1beta/models catalog.",
+      );
+      expect(errorOutput).toContain(
+        "the sandbox uses that Chat Completions route at runtime",
+      );
+      expect(errorOutput).not.toContain(apiKey);
+    } finally {
+      log.mockRestore();
+      error.mockRestore();
+    }
+  });
+
   it("preserves non-zero exit signaling when non-interactive endpoint validation fails (#5721)", async () => {
     const originalExitCode = process.exitCode;
     const error = vi.spyOn(console, "error").mockImplementation(() => {});

src/lib/onboard/inference-selection-validation.ts

@@ -56,6 +56,27 @@ export type EndpointValidationResult =
     }
   | { ok: false; retry: "credential" | "selection" | "retry" | "model"; api?: undefined };
 
+export interface OpenAiSelectionValidationOptions {
+  /** In-memory credential for managed local endpoints; never read from ambient env. */
+  apiKey?: string | null;
+  /** Approved no-DNS endpoint pin; [] also disables ambient proxies for managed IP URLs. */
+  pinnedAddresses?: readonly string[];
+  trustedPrivateCapability?: TrustedPrivateEndpointCapability;
+  authMode?: "bearer" | "query-param";
+  extraHeaders?: readonly string[];
+  requireResponsesToolCalling?: boolean;
+  requireChatCompletionsToolCalling?: boolean;
+  retryChatCompletionsToolReadiness?: boolean;
+  /** Provider identity used only for safe, provider-specific diagnostics. */
+  provider?: string;
+
+  skipResponsesProbe?: boolean;
+  probeStreaming?: boolean;
+  allowHostDockerInternal?: boolean;
+  probeFromDocker?: { expectedPort: number } | null;
+  capabilityCache?: OnboardInferenceCapabilityCache;
+}
+
 export interface InferenceSelectionValidationDeps {
   isNonInteractive(): boolean;
   agentProductName(): string;
@@ -87,24 +108,7 @@ export interface InferenceSelectionValidationHelpers {
     credentialEnv?: string | null,
     retryMessage?: string,
     helpUrl?: string | null,
-    options?: {
-      /** In-memory credential for managed local endpoints; never read from ambient env. */
-      apiKey?: string | null;
-      /** Approved no-DNS endpoint pin; [] also disables ambient proxies for managed IP URLs. */
-      pinnedAddresses?: readonly string[];
-      trustedPrivateCapability?: TrustedPrivateEndpointCapability;
-      authMode?: "bearer" | "query-param";
-      extraHeaders?: readonly string[];
-      requireResponsesToolCalling?: boolean;
-      requireChatCompletionsToolCalling?: boolean;
-      retryChatCompletionsToolReadiness?: boolean;
-
-      skipResponsesProbe?: boolean;
-      probeStreaming?: boolean;
-      allowHostDockerInternal?: boolean;
-      probeFromDocker?: { expectedPort: number } | null;
-      capabilityCache?: OnboardInferenceCapabilityCache;
-    },
+    options?: OpenAiSelectionValidationOptions,
   ): Promise<EndpointValidationResult>;
   validateAnthropicSelectionWithRetryMessage(
     label: string,
@@ -183,6 +187,29 @@ export function createInferenceSelectionValidationHelpers(
     console.error("  Validation details were omitted to avoid exposing credentials.");
   }
 
+  function printGeminiRuntimeNotFoundGuidance(
+    provider: string | undefined,
+    probe: { failures?: unknown[] },
+  ): void {
+    if (provider !== "gemini-api" || !Array.isArray(probe.failures)) return;
+    const chatNotFound = probe.failures.some((failure) => {
+      if (!failure || typeof failure !== "object") return false;
+      const { name, httpStatus } = failure as Record<string, unknown>;
+      return (
+        typeof name === "string" &&
+        name.startsWith("Chat Completions API") &&
+        httpStatus === 404
+      );
+    });
+    if (!chatNotFound) return;
+    console.error(
+      "  This 404 came from Google's OpenAI-compatible Chat Completions runtime route, not the native /v1beta/models catalog.",
+    );
+    console.error(
+      "  NemoClaw cannot continue from catalog availability alone because the sandbox uses that Chat Completions route at runtime.",
+    );
+  }
+
   // DNS-backed SSRF preflight for user-supplied custom endpoints. Resolves the
   // endpoint host and fails closed before any host-side probe curl when it (or
   // a resolved address) is private/reserved, so a public-looking name that
@@ -274,24 +301,9 @@ export function createInferenceSelectionValidationHelpers(
     credentialEnv: string | null = null,
     retryMessage = "Please choose a provider/model again.",
     helpUrl: string | null = null,
-    options: {
-      apiKey?: string | null;
-      pinnedAddresses?: readonly string[];
-      trustedPrivateCapability?: TrustedPrivateEndpointCapability;
-      authMode?: "bearer" | "query-param";
-      extraHeaders?: readonly string[];
-      requireResponsesToolCalling?: boolean;
-      requireChatCompletionsToolCalling?: boolean;
-      retryChatCompletionsToolReadiness?: boolean;
-
-      skipResponsesProbe?: boolean;
-      probeStreaming?: boolean;
-      allowHostDockerInternal?: boolean;
-      probeFromDocker?: { expectedPort: number } | null;
-      capabilityCache?: OnboardInferenceCapabilityCache;
-    } = {},
+    options: OpenAiSelectionValidationOptions = {},
   ): Promise<EndpointValidationResult> {
-    const { apiKey: explicitApiKey, ...probeOptions } = options;
+    const { apiKey: explicitApiKey, provider, ...probeOptions } = options;
     const apiKey =
       explicitApiKey !== undefined
         ? explicitApiKey
@@ -305,6 +317,7 @@ export function createInferenceSelectionValidationHelpers(
     if (!probe.ok) {
       probeOptions.capabilityCache?.invalidate();
       printValidationFailure(label, probe);
+      printGeminiRuntimeNotFoundGuidance(provider, probe);
       if (deps.isNonInteractive()) {
         exitNonInteractiveValidationFailure();
       }

src/lib/onboard/setup-nim-selection.test.ts

@@ -221,4 +221,61 @@ describe("createRemoteModelValidator", () => {
     assert.equal(state.model, "nvidia/local-nim");
     assert.equal(state.nimContainer, "nemoclaw-nim-test");
   });
+
+  it("passes the selected provider only as validation context (#9298)", async () => {
+    const state = makeState();
+    state.provider = "gemini-api";
+    state.endpointUrl = "https://generativelanguage.googleapis.com/v1beta/openai";
+    state.model = "gemini-2.5-flash";
+    let receivedOptions: unknown;
+    const { validateSelectedRemoteModel } = createRemoteModelValidator({
+      OPENAI_ENDPOINT_URL: "https://default-openai.example/v1",
+      ANTHROPIC_ENDPOINT_URL: "https://default-anthropic.example/v1",
+      requireValue,
+      isBackToSelection: (_value): _value is never => false,
+      validateCustomOpenAiLikeSelection: async () => ({ ok: false, retry: "selection" }),
+      validateCustomAnthropicSelection: async () => ({ ok: false, retry: "selection" }),
+      validateAnthropicSelectionWithRetryMessage: async () => ({
+        ok: false,
+        retry: "selection",
+      }),
+      validateOpenAiLikeSelection: async (
+        _label,
+        _endpointUrl,
+        _model,
+        _credentialEnv,
+        _retryMessage,
+        _helpUrl,
+        options,
+      ) => {
+        receivedOptions = options;
+        return { ok: true, api: "openai-completions" };
+      },
+      shouldRequireResponsesToolCalling: () => true,
+      shouldSkipResponsesProbe: () => true,
+      getProbeAuthMode: () => undefined,
+    });
+
+    assert.equal(
+      await validateSelectedRemoteModel({
+        selected: { key: "gemini" },
+        remoteConfig: {
+          label: "Google Gemini",
+          endpointUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+          helpUrl: null,
+        },
+        state,
+        selectedCredentialEnv: "GEMINI_API_KEY",
+      }),
+      "selected",
+    );
+    assert.deepEqual(receivedOptions, {
+      provider: "gemini-api",
+      requireResponsesToolCalling: true,
+      skipResponsesProbe: true,
+      authMode: undefined,
+      extraHeaders: [],
+      capabilityCache: undefined,
+    });
+  });
 });

src/lib/onboard/setup-nim-selection.ts

@@ -206,6 +206,7 @@ type ProbeOptions = {
   authMode?: ProbeAuthMode;
   extraHeaders?: readonly string[];
   capabilityCache?: OnboardInferenceCapabilityCache;
+  provider?: string;
 };
 
 type ValidationResult =
@@ -425,6 +426,7 @@ export function createRemoteModelValidator(deps: RemoteModelValidatorDeps): {
         retryMessage,
         remoteConfig.helpUrl,
         {
+          provider: state.provider,
           requireResponsesToolCalling: deps.shouldRequireResponsesToolCalling(state.provider),
           skipResponsesProbe: deps.shouldSkipResponsesProbe(state.provider),
           authMode: deps.getProbeAuthMode(state.provider),