refactor(onboard): centralize flow context refinements

[cv]

Summary

Continue the #5518 onboarding nullability series by centralizing how core onboarding phases refine flow context after provider selection and sandbox creation. The provider and sandbox phases now use typed merge helpers instead of hand-built spread objects, so provider/model and sandbox-created state are captured as explicit refined context shapes.

Related Issue

Refs #5518

Changes

• Add ProviderModelSelectedOnboardFlowContext plus typed update shapes for provider/model-selected and sandbox-created context updates.
• Add mergeProviderModelSelectedContext and mergeSandboxCreatedContext helpers in src/lib/onboard/machine/flow-context.ts.
• Use the helpers in src/lib/onboard/machine/core-flow-phases.ts to build provider and sandbox phase context updates.
• Add unit coverage for the new context merge helpers.

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)

Verification

• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Release Notes

• Refactor

  • Improved the onboarding flow's context management with specialized merge helpers for provider selection and sandbox configuration, enhancing code organization and maintainability.

• Tests

  • Added comprehensive test coverage for the new context merge helpers used during onboarding phases.

[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: 68f7563b-4c79-46b6-8ecc-fd8b5dd72799

📥 Commits

Reviewing files that changed from the base of the PR and between ca229cb and 5e1f2bf.

📒 Files selected for processing (3)

• src/lib/onboard/machine/core-flow-phases.ts
• src/lib/onboard/machine/flow-context.test.ts
• src/lib/onboard/machine/flow-context.ts

---

📝 Walkthrough

Walkthrough

Introduces ProviderModelSelectedOnboardFlowContext type and two update interfaces (ProviderModelSelectedContextUpdate, SandboxCreatedContextUpdate) in flow-context.ts, adds corresponding merge helper functions, then refactors core-flow-phases.ts to use those helpers instead of manual object spreading. New unit tests cover both merge helpers.

Changes

Onboard Flow Phase Context Merge Helpers

Layer / File(s)	Summary
New types and update interfaces src/lib/onboard/machine/flow-context.ts	Introduces ProviderModelSelectedOnboardFlowContext type carrying model and provider, refactors ProviderSelectedOnboardFlowContext to compose it with a non-nullable sandboxGpuConfig, and adds ProviderModelSelectedContextUpdate and SandboxCreatedContextUpdate interfaces describing phase-specific update field shapes.
Merge helper functions src/lib/onboard/machine/flow-context.ts	Adds mergeProviderModelSelectedContext and mergeSandboxCreatedContext exported functions that apply the new update interfaces and return the appropriately narrowed context types.
core-flow-phases refactored to use merge helpers src/lib/onboard/machine/core-flow-phases.ts	Expands the flow-context import to include the new merge helpers, then replaces manual { ...context, ...fields } spreading in the provider inference and sandbox setup phase run methods with mergeProviderModelSelectedContext and mergeSandboxCreatedContext calls; removes the webSearchConfig ?? null normalization.
Unit tests for merge helpers src/lib/onboard/machine/flow-context.test.ts	Imports both new merge helpers and adds tests verifying that mergeProviderModelSelectedContext correctly updates sandboxName, provider, model, and credentialEnv, and that mergeSandboxCreatedContext correctly updates sandboxName, selectedMessagingChannels, and webSearchSupported.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5559: Directly modifies ProviderSelectedOnboardFlowContext in flow-context.ts, core-flow-phases.ts, and flow-context.test.ts — the same three files changed in this PR, at the same type and phase context level.

Suggested labels

refactor, area: onboarding

Poem

🐇 Hop hop, no more spreads so wide,
The merge helpers now take the ride.
model and provider neatly placed,
Sandbox context cleanly graced.
Typed patches keep the context right —
This bunny's code is clean tonight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
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 (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main refactoring: centralizing flow context refinements by introducing typed merge helpers to replace manual context spreading.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/onboard-flow-context-merge-helpers

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the refactor/onboard-flo... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	refactor/onboard-flo... 5e1f2bf	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/li...bprocess-env.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the refactor/onboard-flo... branch is 46%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	refactor/onboard-flo... 5e1f2bf	+/-
src/lib/state/o...oard-session.ts	—	90%	—
src/lib/inference/local.ts	—	76%	—
src/lib/sandbox/config.ts	—	72%	—
src/lib/actions...dbox/rebuild.ts	—	67%	—
src/lib/onboard/preflight.ts	—	64%	—
src/lib/actions...licy-channel.ts	—	56%	—
src/lib/state/sandbox.ts	—	55%	—
src/lib/policy/index.ts	—	49%	—
src/lib/onboard...er-gpu-patch.ts	—	44%	—
src/lib/onboard.ts	—	18%	—

---

_{Updated June 20, 2026 16:33 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

E2E Advisor Recommendation

Required E2E: full-e2e-vitest, onboard-resume-vitest
Optional E2E: onboard-repair-vitest

Dispatch hint: full-e2e-vitest,onboard-resume-vitest

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• full-e2e-vitest (medium-high; live sandbox plus NVIDIA inference secret): Runs the full live user journey through install/onboard, provider selection, sandbox creation, sandbox verification, and live inference. This directly validates the core flow context changes in the normal onboarding path.
• onboard-resume-vitest (medium-high; live sandbox plus NVIDIA inference secret): The changed code is in the onboard machine phase/context boundary and compatibility slice area. The resume scenario is a high-signal guard that persisted session/context state still resumes correctly across provider selection and sandbox phases.

Optional E2E

• onboard-repair-vitest (medium-high; live sandbox): Useful adjacent coverage for repair/re-entry behavior through the onboard machine and sandbox phase, but less directly targeted than the normal full flow and resume flow.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/e2e-vitest-scenarios.yaml
• jobs input: full-e2e-vitest,onboard-resume-vitest

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-openclaw
Optional Vitest E2E scenarios: ubuntu-repo-docker-post-reboot-recovery

Dispatch required Vitest E2E scenarios:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• ubuntu-repo-cloud-openclaw: The PR changes core onboarding flow context merging across provider/model selection and sandbox creation. The live-supported ubuntu-repo-cloud-openclaw typed scenario exercises the normal cloud OpenClaw onboarding path through provider_selection and sandbox setup.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

• ubuntu-repo-docker-post-reboot-recovery: Optional adjacent coverage: this live-supported scenario also performs cloud OpenClaw onboarding before its post-reboot recovery lifecycle, providing an additional check that the provider/sandbox context changes do not regress lifecycle-backed runs.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-docker-post-reboot-recovery

Relevant changed files

• src/lib/onboard/machine/core-flow-phases.ts
• src/lib/onboard/machine/flow-context.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Top item: No actionable code findings

Consider writing more tests for

• **Runtime validation** — Provider phase applies every `handleProviderInferenceState` returned context field through `mergeProviderModelSelectedContext`, preserves unrelated base context fields, and returns `stateResults`.. The added unit tests cover the new helper happy paths, and existing guard negative tests remain. Because these helpers are now used in onboarding runtime/sandbox phase glue, targeted phase-level runtime validation would increase confidence that handler results are propagated exactly as before.
• **Runtime validation** — Sandbox phase applies returned `session`, `sandboxName`, `webSearchConfig`, `selectedMessagingChannels`, and `webSearchSupported`, including the behavior when `webSearchConfig` is `null`.. The added unit tests cover the new helper happy paths, and existing guard negative tests remain. Because these helpers are now used in onboarding runtime/sandbox phase glue, targeted phase-level runtime validation would increase confidence that handler results are propagated exactly as before.
• **Runtime validation** — Sandbox phase rejects an incomplete provider-selected context before calling `handleSandboxState`.. The added unit tests cover the new helper happy paths, and existing guard negative tests remain. Because these helpers are now used in onboarding runtime/sandbox phase glue, targeted phase-level runtime validation would increase confidence that handler results are propagated exactly as before.
• **Acceptance clause:** Refs Refactor nullable TypeScript state into constrained internal types #5518 — add test evidence or identify existing coverage. The deterministic validation context did not include linked issue Refactor nullable TypeScript state into constrained internal types #5518 text or comments, so issue-specific acceptance clauses could not be mapped.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.