fix(onboard): share providerless lifecycle across supported agents

[apurvvkumaria]

Outcome

External-component providerless onboarding accepts OpenClaw and Hermes through the same existing lifecycle. Each agent retains its managed image, configuration generator, and startup integration. Live qualification remains incomplete, so this PR is a draft.

Reason

The shared onboarding path rejected every agent except OpenClaw. Removing that rejection alone would also let Hermes discover stored messaging credentials during providerless creation.

Related issues

Refs #11548.

Changes

• Share supported-agent validation across initial onboarding, provider selection, and direct sandbox creation. Reject unsupported agents before preflight effects and preserve requested/resolved agent agreement.
• Preserve conflicting provider, model, endpoint, credential, and messaging input rejection. Pass an empty messaging selection for providerless creation to prevent credential discovery.
• Extend the existing OpenClaw/Hermes test matrix for image and registry identity, managed startup configuration, ordinary provider binding, identity and policy failures, and bounded activation outcomes.
• Update the owning external-component guidance. Inference route timing, policy ownership, authentication, and activation failure handling remain unchanged.

Verification

• npx vitest run --project cli src/lib/onboard/machine/core-flow-phases.test.ts src/lib/onboard/machine/final-flow-phases.test.ts src/lib/onboard/machine/initial-flow-phases.test.ts src/lib/onboard/sandbox-agent.test.ts src/lib/onboard/external-component src/lib/onboard/managed-workload/onboard-orchestration.test.ts --project integration test/onboarding/onboard-fresh-create-identity.test.ts --coverage=false — 249 passed.
• npx vitest run --project cli src/lib/onboard/entry-options.test.ts src/lib/onboard/machine/handlers/gateway.test.ts src/lib/onboard/managed-startup-image-runtime-handoff.test.ts --coverage=false — 128 passed.
• After final edits, the 26 creation integration cases and 21 finalization cases passed again. After rebasing onto f267027b9d3d3ce570267a43c118f32c9f25fdaf, the combined commands above passed all 377 tests on commit 31eb6d754554e44b2a79408707eea98097d3a532.
• NODE_OPTIONS=--max-old-space-size=8192 npm run typecheck:cli — passed.
• npm run validate:pr — passed for the rebased commit against canonical base f267027b9d3d3ce570267a43c118f32c9f25fdaf.
• Scoped pre-commit hooks and git diff --check — passed, including formatting, lint, repository checks, and secret scanning. The diff contains no secrets, API keys, or credentials.
• CLI and plugin builds — passed locally and in the Linux test environment.

Local live attempts used base e6068115cc5e02e0d05abdb46ea4509138847617 plus the working changes, with verified OpenShell 0.0.116 release binaries (source d1155aa70042d3e2ee49dbfa15346b108b7c1d92). Both fresh-host runs stopped with endpoint_restricted before component preparation: component configuration requires the Docker network before gateway startup creates it. Each recorded zero preparation and activation requests. This existing ordering issue remains a separate blocker outside this PR.

Ordinary NemoClaw onboarding created the network and started OpenShell, then stopped at provider selection without a supplied credential. An initialized-gateway attempt encountered incomplete host prerequisites and exhausted Docker storage. The disposable test environment was removed.

Neither agent has passing live startup, activation, inference, or allowed/denied request evidence from this change. Deterministic tests do not establish live qualification.

Review notes

Sensitive paths: src/lib/onboard/**. Pre-publication review consists of implementation self-review of NVIDIA/NemoClaw commit 31eb6d754554e44b2a79408707eea98097d3a532, covering all changed files, input rejection, credential discovery, identity agreement, and activation state preservation. The reviewed repository, commit, and paths match this candidate. No independent pre-publication review exists; these paths await independent review. PR #11483 overlaps policy adapters and component activation/finalization and remains open.

No runtime pin, component schema, policy rewriting, provider lifecycle, activation retry, or recovery change is included. There is no CI waiver or merge approval.

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features

  • Providerless onboarding now supports OpenClaw and Hermes.
  • Added validation to ensure supported agents and matching agent identities are used.
  • Providerless setups no longer discover or store messaging-channel credentials when no provider is configured.
  • Improved managed startup configuration, inference routing, workload identity, and generated agent configuration.
  • Added clearer handling for incomplete, timed-out, or failed activation states.

• Documentation

  • Updated onboarding guidance with supported agents, configuration requirements, and validation coverage.

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1711d062-ecef-4e94-9413-20943658d1b7

📥 Commits

Reviewing files that changed from the base of the PR and between c85070d and 31eb6d7.

📒 Files selected for processing (11)

• src/lib/onboard/external-component/README.md
• src/lib/onboard/machine/core-flow-phases.test.ts
• src/lib/onboard/machine/core-flow-phases.ts
• src/lib/onboard/machine/final-flow-phases.test.ts
• src/lib/onboard/machine/initial-flow-phases.test.ts
• src/lib/onboard/machine/initial-flow-phases.ts
• src/lib/onboard/sandbox-agent.test.ts
• src/lib/onboard/sandbox-agent.ts
• src/lib/onboard/sandbox-create/orchestration.ts
• test/helpers/onboard-final-flow-phases.ts
• test/onboarding/onboard-fresh-create-identity.test.ts

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

📝 Walkthrough

Walkthrough

Providerless onboarding now supports validated OpenClaw and Hermes agents. It rejects unsupported or mismatched agents, avoids provider credential discovery, and expands lifecycle and managed-creation test coverage.

Changes

Providerless onboarding

Layer / File(s)	Summary
Agent identity validation src/lib/onboard/sandbox-agent.ts, src/lib/onboard/sandbox-agent.test.ts	Adds assertProviderlessSandboxAgent. Absent agents default to OpenClaw. Only OpenClaw and Hermes are accepted, and requested and resolved names must match.
APF input and channel handling src/lib/onboard/sandbox-create/orchestration.ts	Providerless APF validation receives the resolved-agent assertion and returns an empty channel list when no provider intent exists.
Onboarding phase integration src/lib/onboard/machine/initial-flow-phases.ts, src/lib/onboard/machine/core-flow-phases.ts, src/lib/onboard/machine/*test.ts	Initial and core phases validate providerless agents before preflight, routing, reservation, and sandbox creation. Provider-backed APF intent no longer depends on a non-default agent name.
Lifecycle and managed creation coverage src/lib/onboard/machine/final-flow-phases.test.ts, test/helpers/onboard-final-flow-phases.ts, test/onboarding/onboard-fresh-create-identity.test.ts, src/lib/onboard/external-component/README.md	Tests cover OpenClaw and Hermes lifecycle outcomes, activation timeouts, policy proof, agent-specific images, startup profiles, inference settings, and generated configuration. Documentation records the OpenShell pin and shared validation matrix.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant OnboardingRequest
  participant InitialFlow
  participant CoreFlow
  participant SandboxCreation
  participant ExternalGateway
  OnboardingRequest->>InitialFlow: request providerless APF interceptor
  InitialFlow->>CoreFlow: validate OpenClaw or Hermes agent
  CoreFlow->>SandboxCreation: reserve and create sandbox
  SandboxCreation->>ExternalGateway: prepare and activate external component
  ExternalGateway-->>SandboxCreation: activation result

Loading

Suggested reviewers: ericksoa, sandl99

Merge Risk: ⚪ Minimal · up to c2ec7

No actionable merge-blocking issue remains in the reviewed providerless onboarding changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 10 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: sharing the providerless onboarding lifecycle across the supported agents, OpenClaw and Hermes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 10 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-11548-agent-independent-onboarding

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit c2ec70e in the codex/issue-11548-ag... branch remains at 96%, unchanged from commit 33d5702 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit c2ec70e in the codex/issue-11548-ag... branch remains at 83%, unchanged from commit 33d5702 in the main branch.

Show a line coverage summary of the most impacted files.

File	main 33d5702	codex/issue-11548-ag... c2ec70e	+/-
src/lib/onboard...eway-process.ts	90%	89%	-1%
src/lib/onboard...rchestration.ts	42%	42%	0%
src/lib/onboard...uild-context.ts	74%	75%	+1%
src/lib/actions...-add-restart.ts	30%	31%	+1%
src/lib/domain/...ycle/options.ts	85%	87%	+2%
src/lib/actions...dbox/destroy.ts	89%	92%	+3%
src/lib/actions...oy-execution.ts	91%	94%	+3%
src/lib/onboard...andbox-agent.ts	51%	56%	+5%
src/lib/onboard...outer-python.ts	84%	96%	+12%
src/lib/onboard...uter-command.ts	52%	65%	+13%

---

_{Updated September 11, 2026 22:16 UTC}

[cjagwani]

Reviewed the complete providerless OpenClaw/Hermes onboarding boundary: unsupported and mismatched agents fail before external effects, providerless creation avoids messaging credential discovery, and identity, policy, and bounded activation failure behavior remain enforced. All 26 security-sensitive review packets are clear; the current merge commit preserves the reviewed PR files unchanged; focused validation and all required checks pass; CodeRabbit is clear; and both commits are verified. Per the recorded maintainer decision, #11595, the OpenShell preparation capability, and fresh Linux qualification remain enablement/support gates rather than merge prerequisites for this gated off-default plumbing.