fix(inference): create missing compatible provider

[prekshivyas]

Summary

Fix nemoclaw inference set when a direct compatible provider is absent or its endpoint changes. NemoClaw now inspects the provider binding before route selection, creates and verifies an absent provider before the first route attempt, and commits a verified update for an existing provider after route selection so failures can restore the prior selection.

Related Issue

Fixes #7725

Changes

• Treat the OpenShell 0.0.85 generic provider get missing-entity response as an absent provider only inside the exact-name provider lookup.
• Inspect direct compatible provider bindings before route selection; create and verify absent providers before the first route attempt.
• Update and verify existing direct compatible providers after successful route selection, restoring the previous selection if the provider update fails.
• Retry route selection once only for a correlated provider-not-found result, and remove a newly created provider if route selection fails.
• Keep credential lookup behind an injected resolver so route-containment tests do not depend on the host environment.
• Generalize the provider-binding helper for HTTPS Pin Runtime and direct compatible routes.
• Add regressions for HTTPS IP-literal, DNS-pinned HTTP, generic lookup-miss, and changed existing-provider endpoint behavior.
• Document compatible-provider preparation, retry, rollback, and HTTPS Pin Runtime ordering.
• Align the workflow-boundary Vitest timeout with its existing 30-second child-process budget after the same CI test timed out twice.

The compatibility path is required by #7725 for the inference set consumer running against OpenShell 0.0.85. A global missing-provider parser would be unsafe because route-update output may identify a different provider; exact-name lookup and product-level route tests protect the scoped behavior.

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:
• 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: Codex Desktop exact-head review at 2c31c1a99 passed all nine categories with no findings; endpoint SSRF validation, exact-name provider parsing, host-only credential handling, provider ownership verification, rollback behavior, and mutation locking remain intact, and the final test-timeout-only commit changes no production path
• 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: docs-updated
• Evidence: docs/inference/switch-providers.mdx; verified pre-selection provider creation and verification, correlated one-time retry, created-provider rollback, existing-provider update ordering, DNS-backed HTTPS ordering, generated agent variants, and writing rules at exact head 2c31c1a99. The docs build passed with 0 errors and 2 pre-existing warnings; the automatic main merge preserved the reviewed behavior, the empty E2E-retrigger commit is tree-identical to that reviewed head, the post-merge inference suite passed 177/177, and the timeout-only follow-up changed no user-facing contract, its file passed 33/33, and the affected test passed three consecutive focused runs.
• Agent: Codex Desktop

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

• 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, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — focused inference suite before the main sync: 86 passed; npm run test:changed: 169 passed; post-merge inference suite: 177 passed; workflow-boundary file: 33 passed; exact affected test: 3 consecutive focused passes; npm run typecheck:cli, repository checks, source-shape checks, and test-condition scan passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — not applicable to this scoped inference fix and timeout-budget correction
• 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) — passed with 0 errors and 2 pre-existing warnings
• 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

Summary by CodeRabbit

• New Features
  • Improved compatible inference provider switching, including registering and validating compatible custom endpoints using complete route metadata.
  • Enhanced inference-set provider binding to support direct provider flows alongside HTTPS-pin flows.
• Documentation
  • Updated the “Switch Inference Providers” guide with revised onboarding and clearer “provider not found” behavior and compatible-endpoint requirements.
• Bug Fixes
  • Improved retry and rollback behavior when provider lookup reports a miss, preserving inference selection.
  • Ensures the correct canonical credential environment is exported during shields-down compatible-endpoint flows.
• Tests
  • Expanded coverage for compatible provider create/update and added environment-stub cleanup across tests.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The inference-set flow now supports direct provider bindings, recognizes generic OpenShell lookup misses, retries route configuration after registering absent providers, and updates rollback handling. Tests cover endpoint validation and credential isolation, while documentation describes compatible-endpoint setup and retry behavior.

Changes

Compatible provider inference flow

Layer / File(s)	Summary
Route binding construction src/lib/actions/inference-set-route-containment.ts, src/lib/actions/inference-set-gateway-route-containment.test.ts	Adds shared binding data, direct bindings, and invocation-local credential resolution.
Provider lookup and mutation src/lib/actions/inference-set-provider.ts, src/lib/actions/inference-set-provider.test.ts	Generalizes provider mutation preparation and recognizes generic provider-not-found output from OpenShell.
Inference route retry and rollback src/lib/actions/inference-set.ts	Uses unified provider mutations, retries missing direct providers, and updates commit, rollback, and residual-state handling.
Behavior validation and operator procedure src/lib/actions/inference-set-compatible-provider.test.ts, src/lib/actions/inference-set.test-support.ts, src/lib/actions/inference-set-degraded-state.test.ts, src/lib/actions/inference-set-provider-alias.test.ts, docs/inference/switch-providers.mdx, test/e2e/support/e2e-report-to-pr-workflow-boundary.test.ts	Tests direct endpoint registration, updates, lookup misses, and credential isolation; documents compatible-endpoint setup and retry behavior; corrects the E2E process timeout argument.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant runInferenceSet
  participant finalizeInferenceSetRoute
  participant OpenShell
  runInferenceSet->>finalizeInferenceSetRoute: resolve endpoint and provider bindings
  finalizeInferenceSetRoute-->>runInferenceSet: return directProviderBinding or httpsPinProviderBinding
  runInferenceSet->>OpenShell: set inference route
  OpenShell-->>runInferenceSet: provider not found
  runInferenceSet->>OpenShell: create provider and retry inference set
  OpenShell-->>runInferenceSet: route selection succeeds

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7188: Both modify compatible-endpoint route and provider-binding behavior.
• NVIDIA/NemoClaw#7711: Both modify the inference-set compatible-endpoint action and configuration flow.

Suggested labels: bug, needs: review

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The workflow-boundary test timeout adjustment is unrelated to the compatible-provider fix and appears outside the linked issue scope.	Split the e2e timeout change into a separate PR unless it is required for this issue.
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 (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address #7725 by creating missing compatible providers, scoping not-found handling, and adding the expected regressions.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the main change: creating missing compatible providers during inference set.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7725-compatible-provider

---

_{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 2c31c1a in the codex/7725-compatibl... branch remains at 96%, unchanged from commit 71a7856 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 2c31c1a in the codex/7725-compatibl... branch remains at 81%, unchanged from commit c3ab052 in the main branch.

Show a code coverage summary of the most impacted files.

File	main c3ab052	codex/7725-compatibl... 2c31c1a	+/-
src/lib/onboard...asoning-mode.ts	100%	89%	-11%
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/actions...or-inference.ts	100%	95%	-5%
src/lib/actions...ge-preflight.ts	90%	87%	-3%
src/lib/policy/index.ts	61%	61%	0%
src/lib/sandbox/config.ts	72%	74%	+2%
src/lib/private-networks.ts	88%	93%	+5%
src/lib/actions...ce-set-error.ts	92%	98%	+6%
src/commands/sandbox/mcp.ts	0%	85%	+85%
src/lib/actions...set-provider.ts	0%	96%	+96%

---

_{Updated July 28, 2026 19:41 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7746.docs.buildwithfern.com/nemoclaw

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/lib/actions/inference-set-route-containment.ts (1)

427-450: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Direct process.env read bypasses the adapters layer.

credentialValue is now read straight from process.env[httpsPinCredentialEnv] inside this actions-layer module, rather than through an injected adapter (contrast with options.ensureHttpsPinRuntimeAdapter, which is properly dependency-injected). This couples the direct-binding path to the global process environment, making it harder to fake in tests and mixing a host-boundary read into orchestration code.

Consider threading credential resolution through an injected function (e.g., alongside ensureHttpsPinRuntimeAdapter) so actions compose rather than touch process.env directly.

Based on path instructions: "Host-boundary calls (e.g., OpenShell interactions, process/network/file boundaries) should be isolated behind src/lib/adapters/** so actions/tests can inject fakes... avoid creating new cross-layer dependencies (actions should compose, not call host boundaries directly)."

🤖 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 `@src/lib/actions/inference-set-route-containment.ts` around lines 427 - 450,
Replace the direct process.env access in the finalize flow with an injected
credential-resolution function on options, alongside
ensureHttpsPinRuntimeAdapter. Use that adapter to resolve the credential for
httpsPinCredentialEnv while preserving the existing empty-value fallback and
provider binding behavior; keep host-environment access isolated under the
adapters layer.

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.

Inline comments:
In `@src/lib/actions/inference-set.ts`:
- Around line 876-923: Update the flow around setInferenceRoute and
prepareInferenceSetProviderBinding to converge direct provider bindings before
the first inference:set call, including updating an existing compatible provider
when its endpoint changes. Preserve the existing provider-state validation and
commit behavior, while retaining retry handling for provider-not-found failures.
Add a regression test covering an existing provider whose endpoint is changed
via --endpoint-url.

---

Nitpick comments:
In `@src/lib/actions/inference-set-route-containment.ts`:
- Around line 427-450: Replace the direct process.env access in the finalize
flow with an injected credential-resolution function on options, alongside
ensureHttpsPinRuntimeAdapter. Use that adapter to resolve the credential for
httpsPinCredentialEnv while preserving the existing empty-value fallback and
provider binding behavior; keep host-environment access isolated under the
adapters layer.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: be2972af-2dd9-4c45-8dd1-7c161445667b

📥 Commits

Reviewing files that changed from the base of the PR and between 7f4b490 and 0233eef.

📒 Files selected for processing (6)

• docs/inference/switch-providers.mdx
• src/lib/actions/inference-set-compatible-provider.test.ts
• src/lib/actions/inference-set-provider.test.ts
• src/lib/actions/inference-set-provider.ts
• src/lib/actions/inference-set-route-containment.ts
• src/lib/actions/inference-set.ts

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 fewer 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-inference, cloud-onboard, security-posture, inference-routing, network-policy

1 optional E2E recommendation

• openclaw-inference-switch

Blockers

PRA-1 Blocker — Verify the requested direct-provider endpoint after binding it

• Location: src/lib/actions/inference-set.ts:979
• Category: correctness
• Problem: The route selection runs before an existing direct compatible provider receives its new base URL. OpenShell can verify the old endpoint and then the provider update can replace it with an unreachable requested endpoint.
• Impact: The command can report a successful verified switch while the selected route is unreachable. Conversely, failure of the old endpoint can reject a requested endpoint that is healthy.
• Fix: Update the direct provider binding before the verification that selects the route, or add a verification step that probes the final binding before reporting success. Preserve rollback to the recorded provider and selection if the final-binding verification fails.
• Verification: Inspect the order of `openshellInferenceSetArgs` and `providerMutation.commit()` in `runInferenceSetWithoutHostLock`; use a capture mock that makes health depend on the configured provider base URL.
• Test coverage: Add a direct compatible-provider update test where the old endpoint passes and the requested endpoint fails. Assert the switch fails rather than reporting a verified successful selection, and assert the prior binding and selection are restored or the partial state is reported.
• Evidence: src/lib/actions/inference-set.ts:961-1016 prepares the provider mutation, invokes `inference set`, and only then calls `providerMutation.commit()`. src/lib/actions/inference-set-provider.ts:188-203 applies the direct provider's base URL during `commit()`. src/lib/actions/inference-set-compatible-provider.test.ts adds an endpoint-update test but supplies `noVerify: true`, so it does not exercise normal verification against the final provider binding.

Workflow run details

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

[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.