refactor(onboard): derive session step mapping from FSM metadata by cv · Pull Request #4363 · NVIDIA/NemoClaw

cv · 2026-05-27T22:31:10Z

Summary

Derive the onboard session-step-to-machine-state mapping from the canonical FSM metadata. This removes another hand-maintained copy of the state vocabulary while keeping the exported mapping and runtime behavior unchanged.

Changes

Update src/lib/onboard/machine/events.ts to build ONBOARD_SESSION_STEP_TO_MACHINE_STATE from state definitions.
Preserve the exported OnboardSessionStepName type from the derived mapping.
Extend machine definition tests to assert the session step mapping matches state 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

Summary by CodeRabbit

Tests
- Added validation ensuring session-step-to-machine-state mapping is correctly derived from definitions.
Refactor
- Onboarding state mapping now automatically derived from definitions rather than maintained separately.

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

copy-pr-bot · 2026-05-27T22:31:14Z

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-27T22:31:17Z

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: 648c3fc6-6de5-436f-a0db-9ed95215ce5c

📥 Commits

Reviewing files that changed from the base of the PR and between c3e4ad6 and bfbdfd7.

📒 Files selected for processing (1)

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

💤 Files with no reviewable changes (1)

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

📝 Walkthrough

Walkthrough

The PR refactors the onboarding session step-to-machine-state mapping from hardcoded values to being derived from ONBOARD_MACHINE_STATE_DEFINITIONS. Type and runtime derivation use definition entries with stepName, and a new test validates the mapping matches the definitions.

Changes

Session step-to-state mapping refactor

Layer / File(s)	Summary
Core refactor: derive mapping from definitions `src/lib/onboard/machine/events.ts`	Replaces hardcoded `ONBOARD_SESSION_STEP_TO_MACHINE_STATE` and `OnboardSessionStepName` with computed versions built from `ONBOARD_MACHINE_STATE_DEFINITIONS` using type-level helpers and `Object.fromEntries`, eliminating manual duplication.
Test validation: verify mapping derivation `src/lib/onboard/machine/definition.test.ts`	Adds import of refactored mapping constant and introduces a test case that verifies the runtime mapping is correctly derived from definitions by reconstructing it independently and comparing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

NVIDIA/NemoClaw#4362: Introduces ONBOARD_MACHINE_STATE_DEFINITIONS with stepName metadata that this PR directly depends on for deriving the session step mapping.

Suggested reviewers

ericksoa
cjagwani

Poem

🐰 A mapping once hardcoded, now it flows,

From definitions true, the data grows,

No duplication haunts the source of truth,

With tests to verify each step's proof! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 objective: deriving the session step-to-machine-state mapping from FSM metadata instead of maintaining it separately.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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-step-mapping

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

github-actions · 2026-05-27T22:32:26Z

E2E Advisor Recommendation

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

Dispatch hint: onboard-resume-e2e

Auto-dispatched E2E: onboard-resume-e2e via nightly-e2e.yaml at 5615d1634c39d857f39f39f3373512fe0d6b9554 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

onboard-resume-e2e (medium (~60 min timeout; live Docker/OpenShell onboarding with NVIDIA_API_KEY)): Required because this PR changes runtime onboarding session step-to-state mapping. The existing onboard resume E2E interrupts onboarding at a named step, verifies persisted session state, then resumes and completes; it is the most targeted live coverage for regressions in derived session step names and machine state mapping.

Optional E2E

cloud-onboard-e2e (medium/high (live cloud onboarding; NVIDIA_API_KEY required)): Useful broader confidence for the full non-interactive cloud onboarding path, including installer, sandbox health, policies, credentials, and inference.local after changing onboard event/session mapping. Optional because onboard-resume-e2e is the narrower regression guard for this PR.
ubuntu-repo-cloud-openclaw-resume (medium (typed scenario dry-run/live path per scenario runner; NVIDIA_API_KEY required)): Scenario-runner equivalent of the resume-after-interrupt OpenClaw onboarding flow; useful if the team prefers typed scenario validation in addition to the legacy script job.

New E2E recommendations

None.

Dispatch hint

Workflow: E2E / Nightly
jobs input: onboard-resume-e2e

github-actions · 2026-05-27T22:32:27Z

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw
Optional scenario E2E: ubuntu-repo-cloud-hermes

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: high

Required scenario E2E

ubuntu-repo-cloud-openclaw: The source change alters onboarding machine event step-to-state mapping derivation. The Ubuntu repo cloud OpenClaw scenario is the smallest standard repo-current onboarding path that exercises the cloud OpenClaw onboarding flow and baseline onboarding validation on an ordinary runner.
- 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/session event surface with the Hermes agent path, in case reviewers want agent-variant confidence beyond the primary OpenClaw path.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Relevant changed files

src/lib/onboard/machine/events.ts

github-actions · 2026-05-27T22:33:34Z

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

Workflow run details

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

…p-mapping # Conflicts: # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts

github-actions · 2026-05-29T19:29:26Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26657441957
Target ref: 88f5fbbf87e9182d970bfc3d261c1af018aca532
Workflow ref: main
Requested jobs: onboard-resume-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-resume-e2e	✅ success

github-actions · 2026-05-29T21:19:00Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26662414810
Target ref: 5615d1634c39d857f39f39f3373512fe0d6b9554
Workflow ref: main
Requested jobs: onboard-resume-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-resume-e2e	✅ success

cjagwani

LGTM

cv added 3 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>

cv self-assigned this May 27, 2026

wscurran added the refactor PR restructures code without intended behavior change label May 27, 2026

cv added the v0.0.55 label May 27, 2026

cv requested a review from ericksoa May 27, 2026 23:07

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

cv added v0.0.56 and removed v0.0.55 labels May 29, 2026

Base automatically changed from stack/onboard-fsm-definition to main May 29, 2026 18:44

Merge remote-tracking branch 'origin/main' into stack/onboard-fsm-ste…

bfbdfd7

…p-mapping # Conflicts: # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts

cv marked this pull request as ready for review May 29, 2026 18:49

Merge branch 'main' into stack/onboard-fsm-step-mapping

88f5fbb

Merge branch 'main' into stack/onboard-fsm-step-mapping

5615d16

cv requested review from cjagwani, jyaunches and prekshivyas May 29, 2026 21:20

cjagwani approved these changes May 29, 2026

View reviewed changes

cv merged commit 8b4f5b2 into main May 29, 2026
27 checks passed

cv deleted the stack/onboard-fsm-step-mapping branch May 29, 2026 21:26

wscurran added the area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow label Jun 3, 2026

wscurran removed the onboarding label Jun 3, 2026

Uh oh!

Conversation

cv commented May 27, 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 27, 2026

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

github-actions Bot commented May 27, 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

Dispatch hint

Uh oh!

github-actions Bot commented May 27, 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 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

github-actions Bot commented May 29, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

github-actions Bot commented May 29, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

cjagwani left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cv commented May 27, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 27, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading