refactor(onboard): add sequence runner adapter

[cv]

Summary

Add a sequence-runner adapter that can migrate the existing rich onboarding phases onto the strict FSM runner. Each phase can return an updated context plus one or more explicit FSM results, while runOnboardMachine() remains responsible for applying and validating transitions.

Changes

• Add runOnboardSequenceWithRunner() and buildOnboardSequenceHandlers().
• Add duplicate phase detection for state-to-handler adapter construction.
• Pass runner guardrails such as maxTransitions and sequenceOwnership through the sequence adapter.
• Align multi-result phase tests with the strict metadata.state sequence contract from refactor(onboard): let FSM handlers return result sequences #4473.
• Add sequence-runner tests covering rich context updates, multi-result provider-style phases, custom sequence ownership, retry, branch, and terminal completion.

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
• npm run typecheck:cli 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

Summary by CodeRabbit

• Tests
  • Added comprehensive test coverage for onboard sequence execution, validating state transitions, phase ordering, and error handling.

[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: b0e45b76-190b-48aa-a67c-efd0eda021cf

📥 Commits

Reviewing files that changed from the base of the PR and between c8be25d and aeced21.

📒 Files selected for processing (2)

• src/lib/onboard/machine/sequence-runner.test.ts
• src/lib/onboard/machine/sequence-runner.ts

---

📝 Walkthrough

Walkthrough

Introduces a typed sequence runner adapter that executes ordered onboard phases through the FSM machine, including phase handler construction with duplicate detection, context flow management, and comprehensive test coverage for standard execution, ownership filtering, and validation.

Changes

Sequence Runner Implementation and Tests

Layer / File(s)	Summary
Type contracts and error definition src/lib/onboard/machine/sequence-runner.ts	Defines OnboardSequencePhase<Context> (target state + async/sync run method), OnboardSequencePhaseResult<Context> (context + FSM result), OnboardSequenceRunnerOptions<Context> with phases, context, runtime, and optional constraints, and DuplicateOnboardSequencePhaseError for preflight validation.
Handler construction and runner implementation src/lib/onboard/machine/sequence-runner.ts	buildOnboardSequenceHandlers validates phase uniqueness and converts phases to per-state FSM handlers that execute, store returned context, and return FSM results. runOnboardSequenceWithRunner initializes mutable pendingContext, builds handlers, and wires them into runOnboardMachine with updateContext callback to maintain context flow through the sequence.
Comprehensive test coverage src/lib/onboard/machine/sequence-runner.test.ts	Test helpers for session state handling and deterministic runtime creation. Three tests: (1) full sequence with multiple phases, branching, and retry paths validates session completion and phase log order; (2) ownership filtering test verifies partial phase execution from finalizing state with correct context output; (3) validation test asserts DuplicateOnboardSequencePhaseError thrown for duplicate phase states.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Track onboard FSM migration stack and resume compatibility #4533: PR implements the concrete sequence-runner adapter (buildOnboardSequenceHandlers / runOnboardSequenceWithRunner) and comprehensive tests as described in the FSM migration stack.

Possibly related PRs

• NVIDIA/NemoClaw#4453: sequence-runner.ts wires phase handler outputs directly into the newly introduced runOnboardMachine FSM runner, using its runtime and context update flow.
• NVIDIA/NemoClaw#4445: sequence-runner implements orchestration of phases returning explicit OnboardStateHandlerResult FSM transitions, aligning with upstream phase handlers updated to return FSM state results.

Suggested labels

refactor, feature

Suggested reviewers

• prekshivyas
• cjagwani
• jyaunches

Poem

🐰 A sequence runner hops through phases true,
Each context updates as handlers brew,
Ownership filters what paths we take,
Duplicates caught before mistakes wake—
FSM's dance, now neatly arranged! ✨

🚥 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 pull request title 'refactor(onboard): add sequence runner adapter' is directly related to the main changes, which introduce a new sequence-runner adapter with runOnboardSequenceWithRunner() and buildOnboardSequenceHandlers() functions.
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 stack/onboard-fsm-sequence-adapter

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e
Optional E2E: onboard-resume-e2e, double-onboard-e2e

Dispatch hint: cloud-onboard-e2e

Auto-dispatched E2E: cloud-onboard-e2e via nightly-e2e.yaml at aeced21cc0cdbf7fab0d01343cb71f3c2eb3d471 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required E2E

• cloud-onboard-e2e (medium): Validates the real non-interactive cloud onboarding path through preflight, gateway, provider/inference setup, sandbox creation, policy application, and final session completion. This is the closest existing merge-blocking E2E for changes under src/lib/onboard/machine.

Optional E2E

• onboard-resume-e2e (medium): Useful adjacent coverage for persisted onboarding machine state and resumed phase execution, especially because the new adapter handles current-state driven phase dispatch and multi-transition sequences.
• double-onboard-e2e (medium): Optional confidence for repeated/re-onboard flows where onboarding phase ordering, retries, and state completion semantics are important.

New E2E recommendations

• onboarding-fsm-sequence-runner (medium): Existing E2E jobs validate the live onboarding entrypoint, but this new sequence-runner adapter appears not to be directly wired into production onboarding yet. Add an E2E once it is integrated that forces a retry/branch sequence across provider_selection -> inference -> sandbox and verifies the persisted machine state reaches complete without losing context.
  • Suggested test: Add a focused onboarding FSM sequence E2E for retry/branch/resume behavior after sequence-runner integration.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: cloud-onboard-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw
Optional scenario E2E: ubuntu-repo-cloud-hermes, gpu-repo-local-ollama-openclaw

Dispatch required scenario E2E:

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

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding machine sequence runner code can affect the standard repo-checkout cloud OpenClaw onboarding path; run the primary Ubuntu baseline onboarding scenario.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional scenario E2E

• ubuntu-repo-cloud-hermes: Optional adjacent coverage for the same onboarding machinery with the Hermes agent path on the default Ubuntu runner.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes
• gpu-repo-local-ollama-openclaw: Optional special-runner coverage for the local Ollama onboarding path if the sequence runner is intended to cover local provider flow as well.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw

Relevant changed files

• src/lib/onboard/machine/sequence-runner.ts

[github-actions]

PR Review Advisor

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

Consider writing more tests for

• **Runtime validation** — runOnboardSequenceWithRunner propagates maxTransitions to runOnboardMachine and rejects an adapter-driven retry loop at the configured limit. The unit coverage is appropriate for the adapter and uses the real FSM runner/runtime harness. Because this adapter is intended to migrate live onboarding phases, targeted runtime validation of the integrated onboarding path would add confidence without changing the code-review verdict.
• **Runtime validation** — runOnboardSequenceWithRunner propagates runner validation errors for multi-result phases with missing metadata.state. The unit coverage is appropriate for the adapter and uses the real FSM runner/runtime harness. Because this adapter is intended to migrate live onboarding phases, targeted runtime validation of the integrated onboarding path would add confidence without changing the code-review verdict.
• **Runtime validation** — buildOnboardSequenceHandlers awaits async phases before updating pending context. The unit coverage is appropriate for the adapter and uses the real FSM runner/runtime harness. Because this adapter is intended to migrate live onboarding phases, targeted runtime validation of the integrated onboarding path would add confidence without changing the code-review verdict.

Workflow run details

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

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 27113803824
Target ref: aeced21cc0cdbf7fab0d01343cb71f3c2eb3d471
Workflow ref: main
Requested jobs: cloud-onboard-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success