refactor(onboard): extract provider and sandbox FSM phases

[cv]

Summary

Add reusable FSM phase wrappers for provider/inference and sandbox setup. These wrappers support ordered FSM result sequences and sandbox branch results while updating the typed flow context.

Changes

• Add createProviderInferencePhase() for the provider/inference composite phase.
• Add createSandboxPhase() for sandbox setup and branch handoff.
• Add tests for provider context updates, ordered FSM results, sandbox messaging/web-search updates, and branch metadata.

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

• npx prek run --all-files passes
• npm test passes
• 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

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

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bb401b43-10c0-4a39-972c-bbc08a0a271b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/onboard-fsm-provider-sandbox-phases

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: ubuntu-repo-cloud-openclaw
Optional E2E: ubuntu-repo-cloud-hermes, ubuntu-repo-cloud-openclaw-resume

Dispatch hint: ubuntu-repo-cloud-openclaw

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-preflight-gateway-phases
Head: HEAD
Confidence: high

Required E2E

• ubuntu-repo-cloud-openclaw (medium): Canonical scenario exercises the affected provider_selection -> inference -> sandbox -> OpenClaw onboarding path on Ubuntu with Docker, then verifies smoke, cloud inference, and credentials.

Optional E2E

• ubuntu-repo-cloud-hermes (medium): Useful adjacent coverage because the shared sandbox phase can branch toward non-OpenClaw agent setup; validates the same provider/sandbox phase plumbing with Hermes-specific runtime checks.
• ubuntu-repo-cloud-openclaw-resume (medium): Optional confidence for FSM/session continuity if these new phase helpers are used during resumed onboarding.

New E2E recommendations

• onboarding-fsm (medium): Existing scenarios validate end-state behavior, but there is no targeted E2E assertion that provider_selection and sandbox FSM states are persisted with ordered transition metadata during a real onboard run.
  • Suggested test: Add a lightweight scenario assertion that inspects onboarding session state/events after provider_selection and sandbox to verify context merge fields and transition order.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: ubuntu-repo-cloud-openclaw

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/stack/onboard-fsm-preflight-gateway-phases
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario workflow, scenario metadata, scenario runtime, or validation-suite files changed.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 1 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 1 new item found

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• None.

🌱 Nice ideas

• Add explicit branch metadata passthrough coverage (src/lib/onboard/machine/flow-phases/provider-sandbox.test.ts:65): The sandbox phase test verifies that a branch result preserves `next` and `transitionKind`, but it does not include metadata in the `branchTo()` result. If callers rely on sandbox branch metadata for traceability or runtime events, this wrapper should have an explicit regression test showing metadata is passed through unchanged.
  • Recommendation: Change the sandbox test to call `branchTo("openclaw", { metadata: { state: "sandbox", sandboxName: "my-assistant" } })` or equivalent and assert that metadata is preserved in `result.result`.
  • Evidence: The test creates `result: branchTo("openclaw")` and asserts only `{ next: "openclaw", transitionKind: "branch" }`, while the wrapper returns `result.result` unchanged.

Since last review details

Current findings:

• Add explicit branch metadata passthrough coverage (src/lib/onboard/machine/flow-phases/provider-sandbox.test.ts:65): The sandbox phase test verifies that a branch result preserves `next` and `transitionKind`, but it does not include metadata in the `branchTo()` result. If callers rely on sandbox branch metadata for traceability or runtime events, this wrapper should have an explicit regression test showing metadata is passed through unchanged.
  • Recommendation: Change the sandbox test to call `branchTo("openclaw", { metadata: { state: "sandbox", sandboxName: "my-assistant" } })` or equivalent and assert that metadata is preserved in `result.result`.
  • Evidence: The test creates `result: branchTo("openclaw")` and asserts only `{ next: "openclaw", transitionKind: "branch" }`, while the wrapper returns `result.result` unchanged.

Workflow run details

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