refactor(onboard): introduce explicit state result types by cv · Pull Request #4375 · NVIDIA/NemoClaw

cv · 2026-05-28T00:29:03Z

Summary

Introduce explicit result types and helpers for future onboarding state handlers. This prepares handlers to return transition, completion, and failure decisions without changing live orchestration yet.

Changes

Add src/lib/onboard/machine/result.ts with transition, complete, and failed state-result types.
Add helper constructors for advance, retry, branch, complete, and failed results.
Add tests for the result helper shapes and metadata/update preservation.

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

Summary by CodeRabbit

New Features
- Introduced a structured onboarding result API: typed non-terminal transition kinds (advance/retry/branch), helpers for creating transitions, and explicit terminal outcomes (complete/failed) with optional session updates and metadata.
Tests
- Added test suite validating transition builders, transition kinds, terminal results, and compile-time usage constraints.

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

copy-pr-bot · 2026-05-28T00:29:07Z

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 · 2026-05-28T00:29:10Z

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: b7440caf-10cb-4d5f-809e-bb5a53eae228

📥 Commits

Reviewing files that changed from the base of the PR and between 46864ad and 97a87a2.

📒 Files selected for processing (2)

src/lib/onboard/machine/result.test.ts
src/lib/onboard/machine/result.ts

🚧 Files skipped from review as they are similar to previous changes (2)

src/lib/onboard/machine/result.test.ts
src/lib/onboard/machine/result.ts

📝 Walkthrough

Walkthrough

Adds typed result contracts and factory helpers for the onboarding state machine (transition, complete, failed) and a Vitest suite validating runtime shapes and TypeScript-level constraints for those helpers.

Changes

Onboarding Machine Result Model and Builders

Layer / File(s)	Summary
Result interfaces and factory builders `src/lib/onboard/machine/result.ts`	Exports `OnboardStateResultTransitionKind`, shared transition option types, discriminated result interfaces (`transition`, `complete`, `failed`) and union `OnboardStateResult`. Implements `transitionTo`, `advanceTo`, `retryTo`, `branchTo`, `completeOnboardMachine`, and `failOnboardMachine` with defaults and typed options.
Result builder test suite `src/lib/onboard/machine/result.test.ts`	Vitest tests validate `transitionTo` returns a `transition` result with `next` plus optional `updates`/`metadata` and undefined `transitionKind`, enforce that `transitionTo` accepts only non-terminal states, confirm `advanceTo`/`retryTo`/`branchTo` set `transitionKind` correctly, check helper option typings, and verify `completeOnboardMachine`/`failOnboardMachine` produce expected terminal results.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

onboarding, enhancement: feature

Suggested reviewers

prekshivyas
cjagwani

Poem

🐰 I hop through states with a cheerful twirl,
advance, retry, or branch — watch the flags unfurl.
Complete with metadata, or fail with a note,
builders stitch the path where the user will float.
Hooray for clean results — a rabbit's small gloat!

🚥 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 and concisely summarizes the main change: introducing explicit state result types for the onboarding machine.
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-state-results

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

github-actions · 2026-05-28T00:31:07Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: ubuntu-repo-cloud-openclaw, onboard-resume-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No merge-blocking E2E is recommended because the new onboarding FSM result helper is not imported by runtime onboarding code yet; current behavior is covered by the added unit test and existing type checks/builds.

Optional E2E

ubuntu-repo-cloud-openclaw (medium): Optional smoke confidence for the main cloud OpenClaw onboarding path if maintainers want to validate adjacent onboarding behavior, though the new helper is not yet used by live flows.
onboard-resume-e2e (medium): Optional regression coverage for persisted onboarding session/resume behavior, relevant to the future consumer of these result/update helpers but not merge-blocking for this unreferenced scaffolding change.

New E2E recommendations

onboarding-fsm (medium): When state handlers begin returning OnboardStateResult objects and OnboardRuntime applies them, add an E2E that asserts transition metadata, safe session updates, and terminal complete/failed handling are reflected in session state and redacted machine events.
- Suggested test: onboarding-fsm-result-application-e2e

github-actions · 2026-05-28T00:31:08Z

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required scenario E2E

None. No scenario E2E is recommended: the PR adds onboarding state-result helper code plus unit tests, but the new helper is not referenced by the existing onboarding flow or scenario runtime, so it should not affect scenario E2E behavior.

Optional scenario E2E

None.

Relevant changed files

src/lib/onboard/machine/result.ts

github-actions · 2026-05-28T00:32:09Z

PR Review Advisor

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

Workflow run details

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

wscurran · 2026-05-28T17:53:03Z

✨ Thanks for submitting this detailed PR that refactors the onboard state handlers to introduce explicit result types and helpers, which proposes a way to improve the onboarding experience by preparing handlers to return transition, completion, and failure decisions. This refactor adds result helper shapes and metadata/update preservation tests to ensure the new behavior works as expected.

…te-results # Conflicts: # src/lib/onboard.ts # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts # src/lib/onboard/machine/progress.ts # src/lib/onboard/machine/runtime.test.ts # src/lib/onboard/machine/runtime.ts # src/lib/onboard/runtime-boundary.ts

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

cv added 7 commits May 27, 2026 15:18

docs(onboard): document FSM migration target

6b753bf

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

refactor(onboard): centralize machine state metadata

fb1b32d

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

refactor(onboard): derive session step mapping from FSM metadata

c3e4ad6

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

refactor(onboard): derive progress labels from FSM metadata

603832c

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

fix(onboard): emit lifecycle events for onboarding start

4fad8e7

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

fix(onboard): emit machine events for resume conflicts

f99e9cb

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

refactor(onboard): introduce explicit state result types

2b60df4

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

cv self-assigned this May 28, 2026

wscurran added enhancement: feature refactor PR restructures code without intended behavior change labels May 28, 2026

cv added the onboarding label May 29, 2026

cv mentioned this pull request May 29, 2026

Track onboard FSM migration stack and resume compatibility #4533

Closed

Base automatically changed from stack/onboard-fsm-resume-conflict-events to main June 2, 2026 04:55

wscurran added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow feature PR adds or expands user-visible functionality labels Jun 3, 2026

cv marked this pull request as ready for review June 3, 2026 07:18

fix(onboard): constrain FSM transition results

46864ad

wscurran removed enhancement: feature labels Jun 3, 2026

cv requested review from cjagwani and prekshivyas June 3, 2026 17:20

cv added 2 commits June 3, 2026 10:21

Merge branch 'main' into stack/onboard-fsm-state-results

c9db096

fix(onboard): tighten transition helper option types

97a87a2

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

cv added the v0.0.58 Release target label Jun 3, 2026

cv merged commit 777cecd into main Jun 3, 2026
30 checks passed

cv deleted the stack/onboard-fsm-state-results branch June 3, 2026 20:34

wscurran removed the feature PR adds or expands user-visible functionality label Jun 9, 2026

coderabbitai Bot mentioned this pull request Jun 9, 2026

refactor(onboard): define FSM flow context #4481

Merged

12 tasks

Conversation

cv commented May 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented May 28, 2026

Uh oh!

coderabbitai Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Scenario Advisor Recommendation

E2E Scenario Advisor

Required scenario E2E

Optional scenario E2E

Relevant changed files

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

wscurran commented May 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cv commented May 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading