Slice 2: Move remaining fixed hosted providers to native inference #12589

Problem Statement

The remaining fixed hosted providers use the workspace-wide inference.local route. OpenShell 0.1.x retires that route. These selections need native provider access before the dependency upgrade.

Part of epic #12558, capability Slice 2.

Desired Behavior

Move OpenAI, Anthropic, Gemini's existing OpenAI-compatible surface, OpenRouter, and Hermes Provider to native OpenShell providers attached to the selected sandbox.

For example, an OpenAI selection changes from:

agent → inference.local → shared OpenShell route → OpenAI

to:

agent → api.openai.com → sandbox-attached OpenShell provider → OpenAI

Existing commands, model choices, supported agent/provider combinations, and login methods remain available. Changing one sandbox's selection must not change another sandbox's provider access.

Scope and Exclusions

Use Slice 1's minimum profile, provider, attachment, and observation mechanism already merged through #12562. This slice depends on that foundation, not Slices 3 or 4.

Implement this plan fresh from main in one new PR. The tasks below are internal checkpoints, not separate PRs.

Included:

• NemoClaw-owned, workspace-scoped profiles for the five existing hosted selections.
• Provider creation or reuse, attachment, native agent configuration, and selection changes.
• Inspection, restart, and directly affected recovery and credential cleanup.
• OpenRouter's required headers and Hermes Provider's existing API-key/OAuth behavior, including safe binding to its authenticated returned endpoint.

Excluded:

• New providers, agents, models, platforms, or supported combinations.
• User-supplied endpoint migration, including custom compatible and Bedrock workflows, owned by Slice 3.
• Host-local provider migration, owned by Slice 4.
• Global retirement of the shared route, owned by Slice 5.
• OpenShell dependency upgrades, automatic migration of existing beta sandboxes, generic provider frameworks, and unrelated repairs.

Every changed file must support an acceptance criterion below. A requirement outside this boundary needs a separate scope decision.

Ongoing Ownership

The epic names @rsliter as accountable maintainer. @deepujain owns this implementation and PR follow-up.

Placement and Support Expectations

Core NemoClaw, under the epic's accepted product decision. Extend the existing inference, onboarding, agent configuration, status, and recovery owners. Preserve the repository-defined support surface.

Dependencies and Fresh Checkout

Slice 1, PR #12562, is merged. This slice does not depend on Slices 3 or 4.

Use an isolated worktree from verified canonical main. Deliver one new PR. Do not reuse superseded branches, patch chains, or qualification results.

Research and Evidence Boundaries

Inspect current provider selection, native lifecycle, agent configuration, and adjacent tests on the repository's current OpenShell pin.

Verify OpenRouter header propagation and safe binding to Hermes Provider's authenticated returned endpoint. Source support does not prove runtime behavior. A historical candidate's tests or live result do not qualify the new candidate.

Implementation Tasks

• 1. Confirm provider contracts and behavior owners. Record endpoint, protocol, credential binding, headers, model handling, and supported agents for all five selections. Use the existing inference configuration, provider selection, and agent configuration owners.
• 2. Extend the native provider lifecycle. Add restricted profiles and extend Slice 1's ensure, attach, and observation behavior. Refuse ownership collisions. Reconcile ambiguous operations before another mutation. Keep credential values out of returned or persisted state.
• 3. Wire onboarding and switching. Attach only the selected provider to the intended sandbox. Verify attachment before declaring success. Preserve other sandboxes and recovery state when a switch fails. Do not fall back to the shared route.
• 4. Preserve agent and authentication behavior. Configure native endpoints, supported models, API formats, timeouts, and required compatibility. Preserve OpenRouter headers and both Hermes login methods. Bind Hermes credentials and profile restrictions to the authenticated endpoint.
• 5. Update inspection and affected recovery. Make inference get, status, health, connect, start/restart, and directly affected recovery/cleanup use recorded native authority. Preserve unrelated resources and ownership records.
• 6. Complete acceptance coverage and owning guidance. Add deterministic coverage in existing test owners. Use existing live-test owners for distinct protocol and credential shapes. Update directly affected repository guidance.

Delivery checkpoint

Implementation tasks 1–5 are complete in PR #12886, evaluated at 892770dd9b1219e5cdd73cab4d74175cc01d5826. Task 6 remains open: deterministic coverage and owning guidance are complete, but real-provider API-key smoke and interactive Hermes OAuth qualification have not run. Acceptance boxes below remain open pending the complete evidence review; implementation completion does not claim live qualification.

The approved review-handoff exception records these live gaps and the resulting Advisor aggregate failure. It permits human-review handoff after the other required checks settle; it does not approve the code or authorize merge. This issue retains the outstanding acceptance work.

Required restart regression

Task 5 includes a restart regression requirement: the public start/restart path must derive native selection from validated persisted attachment records. Its invocation probe must use the selected endpoint, protocol, and credential headers. Test all five hosted selections, native NVIDIA compatibility, legacy selections, and missing, malformed, or mismatched authority. A logical provider name alone does not prove ownership.

Validate this restart requirement against the fresh implementation. Historical patches and live results do not qualify the new candidate.

Validation Plan

Local checkpoints

These checkpoints do not require separate pushes. Combine connected changes and run focused tests when the behavior is ready.

Publication checks

Confirm selectors against the completed diff. Use normal hooks and required hosted workflows.

• Local hooks: formatting, lint, secrets, commit messages, repository rules, and applicable growth limits.
• Publication: builds and committed-diff validation owned by the normal pre-push hook. Do not duplicate validate:pr immediately before a normal push.
• Hosted CI: applicable static, compilation, type/package, installer, dependency audit, CLI/plugin coverage, and aggregate checks.
• Managed images and Pi qualification: stabilize image inputs before qualification. Use the supported source-publication and receipt-refresh sequence. Record genuine AMD64 and ARM64 receipts from the same successful qualification run and verify source parity.
• Governance and review: DCO, title, signatures, contributor limits, maintainer-edit eligibility, security checks, Advisor, and automated review for the published commit.
• Conditional checks: YAML/schema/generated configuration, CLI documentation parity, documentation build/links, live assertion budgets, rootless Podman, portable Linux, catalog verification, or Windows qualification when their selectors apply.

Do not run broad suites repeatedly after every task. Repeat affected checks when inputs change, a failure requires diagnosis, or a broader boundary needs evidence. Local passing tests do not replace required hosted or live evidence.

Acceptance evidence

• Every in-scope hosted selection uses its selected sandbox's native provider.
• Existing commands, supported agent behavior, models, protocols, and login methods are preserved.
• A fresh agent process completes native inference with the selected model through existing live-test owners.
• Each distinct protocol and credential shape has evidence without a new provider-by-agent-by-platform matrix.
• Status, health, and restart assess the same native path used by the agent.
• A profile or provider ownership collision causes no mutation of user-owned resources.
• Invalid endpoint bindings fail before profile or provider activation.
• Credentials remain absent from arguments, logs, state, artifacts, and model-visible output.
• Ambiguous mutations trigger observation before retry; failed native inference cannot report success or use shared-route fallback.
• Failed operations preserve recoverable state; cleanup affects only resources with proven NemoClaw ownership.

Compatibility Requirements

Use the repository's current OpenShell pin and existing supported agent/provider/platform combinations. Preserve Gemini's existing OpenAI-compatible API surface. Retain shared-route behavior for selections outside this slice until their owning slices migrate them.

Security or Privacy Impact

OpenShell stores provider credentials for the provider lifetime. Sandboxes receive opaque placeholders. Profiles restrict endpoints, request surfaces, and executable paths.

NemoClaw must verify provider ownership and sandbox identity before detaching or deleting resources. Owned detachment or deletion removes provider access. Failed lookups and uncertain mutations must preserve recovery evidence and must not authorize unrelated cleanup.

Repository Workflow and Continuity

Use current trusted AGENTS.md, applicable component instructions, CONTRIBUTING.md, WRITING.md, and affected test/development guidance.

Required repository skills:

• Plan issue
• Contributor setup
• Implement issue
• Create PR and follow up

Use nemoclaw-maintainer-e2e for authorized live evidence. Use nemoclaw-maintainer-audit-e2e-assertions before E2E diagnosis, repair, or expensive reruns.

Keep one durable work record outside the contribution diff. Record branch/base/commit, task state, acceptance evidence, commands/results, image receipts, finding dispositions, run IDs, retry counts, owned resources, blockers, and the next action. Resume from valid evidence after interruption.

Authority, review, and time limit

Implementation and a delivery goal are authorized. Standing authority covers in-scope implementation, checks, ordinary publication, valid repairs, supported retries, qualification receipt refreshes, draft promotion, and reviewer invitation. New evidence does not require new task authorization.

Verify an apparent blocker against the current candidate, run, permissions, and supported recovery before escalating. Ask only when the remaining action requires a decision, scope, resource, cost, or credential authority outside the agreed boundary. Continue independent authorized work.

• Draft exit: Applicable required CI and scheduled draft-time reviews finish on the unchanged candidate. Findings are classified. No unresolved candidate-owned defect or mandatory failure remains.
• Ready for review: Promote through the supported workflow. Settle applicable post-promotion automation. Require current-commit checks, scheduled reviews, image/security/governance/live evidence, signatures/DCO, and mergeability.
• Reviewer invitation: Request @rsliter only when ready for human review. Check for an existing request first and verify the request after writing.
• Follow-up: Monitor the new PR. Batch valid in-scope reviewer repairs, rerun affected checks, and restore review readiness independently within the execution window.
• Merge: Not authorized.

The original execution window ran from 2026-10-09 04:25:00 UTC to 2026-10-09 16:25:00 UTC. The user explicitly resumed work after that deadline and authorized continued implementation and review follow-up. Continue through review readiness, request @rsliter, and address valid in-scope feedback until reviewer approval applies to the latest commit. Preserve checkpoint and retry records. Merge remains unauthorized.

Category

Provider