refactor(onboard): derive progress labels from FSM metadata by cv · Pull Request #4364 · NVIDIA/NemoClaw

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

Summary

Move onboard progress label lookup behind machine metadata. The skip/resume banner path now reads progress labels from a small FSM progress helper instead of a hand-maintained table in src/lib/onboard.ts.

Changes

Add src/lib/onboard/machine/progress.ts to expose onboarding progress-step metadata derived from state definitions plus the existing messaging pseudo-step.
Replace ONBOARD_STEP_INDEX in src/lib/onboard.ts with getOnboardProgressStep().
Add progress metadata tests that preserve the existing eight-step labels and verify state-backed labels come from FSM definitions.

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
- Onboarding now derives and displays step numbers/totals from a central progress source and applies a product-specific title for one step.
Bug Fixes
- Fixed progress labeling and moved a setup progress indicator to the correct onboarding step.
Tests
- Added tests validating onboarding progress metadata, label mappings, and lookup behavior.

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

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

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:30Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

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: f0f22770-19c9-47ee-a6bf-d69d81a900d4

📥 Commits

Reviewing files that changed from the base of the PR and between e48c014 and 9b9646b.

📒 Files selected for processing (1)

src/lib/onboard.ts

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

src/lib/onboard.ts

📝 Walkthrough

Walkthrough

Centralizes onboarding progress metadata in a new module, moves a progress entry from agent_setup to openclaw, updates skippedStepMessage to use dynamic lookup instead of a hardcoded mapping, and adds tests validating progress-step consistency.

Changes

Onboarding progress centralization

Layer / File(s)	Summary
Progress metadata contract and centralized lookup `src/lib/onboard/machine/progress.ts`	Introduces `OnboardProgressStep` (number/total/title); derives step-name types from machine definitions plus a `"messaging"` pseudo-step; builds `ONBOARD_PROGRESS_STEPS` from machine-state `progress` entries merged with `EXTRA_PROGRESS_STEPS`; exports `getOnboardProgressStep(stepName: string)` returning the step or `null`.
State machine progress reassignment `src/lib/onboard/machine/definition.ts`	Removes `progress` from the `agent_setup` state and adds the same `progress` metadata to the `openclaw` state in `ONBOARD_MACHINE_STATE_DEFINITIONS`, causing the progress-aware state type to exclude `agent_setup`.
Integrate progress lookup into skipped-step messaging `src/lib/onboard.ts`	Imports `getOnboardProgressStep` and refactors `skippedStepMessage` to fetch step number/total/title dynamically (with a special-case `openclaw` title override) instead of using `ONBOARD_STEP_INDEX`, then calls `step()` when step info exists while preserving skip-log formatting and optional detail.
Progress metadata validation tests `src/lib/onboard/machine/progress.test.ts`	Adds Vitest suite checking that machine-definition progress entries match `ONBOARD_PROGRESS_STEPS`, asserting the exact eight-step labels mapping, and testing `getOnboardProgressStep` for known and unknown step names.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

NVIDIA/NemoClaw#4362: Modifies the same ONBOARD_MACHINE_STATE_DEFINITIONS progress entries; related to this PR's progress-step lookup.
NVIDIA/NemoClaw#3873: Refactors skipped messaging for OpenClaw/agent setup in src/lib/onboard.ts; overlaps on the skip flow and messaging.

Suggested reviewers

ericksoa
jyaunches
prekshivyas
cjagwani

Poem

🐇 I hopped through code to tidy the map,
Steps gathered neatly — no more mishap.
From agent to OpenClaw the numbers now flow,
A lookup that guides where next we should go.
Hooray — progress blooms, steady and slow!

🚥 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 summarizes the main change: refactoring onboard progress labels to derive from FSM metadata instead of hardcoded mappings.
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-progress-metadata

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

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

E2E Advisor Recommendation

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

Dispatch hint: cloud-onboard-e2e,onboard-resume-e2e

Auto-dispatched E2E: cloud-onboard-e2e, onboard-resume-e2e via nightly-e2e.yaml at 9b9646baad9e8c7d863ea3cbef0ce5f8be6e115b — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

cloud-onboard-e2e (high): Validates a full non-interactive cloud onboarding run through install, sandbox creation, policy setup, security checks, and inference.local after changing core onboarding progress/state metadata.
onboard-resume-e2e (high): Directly exercises interrupted onboarding followed by --resume, including the skip messages that now depend on getOnboardProgressStep and the derived 8-step progress map.

Optional E2E

onboard-repair-e2e (high): Additional confidence for resume repair/invalidation paths that share resume skip handling and session-state assumptions touched by the progress/state-machine refactor.
double-onboard-e2e (high): Useful adjacent coverage for repeated onboarding/reuse behavior, where user-facing step progress and skip/reuse messaging may be affected by the new centralized progress mapping.

New E2E recommendations

onboarding-progress-output (medium): Existing E2E coverage exercises onboarding and resume, but does not appear to explicitly assert the canonical visible [n/8] progress labels for fresh onboard and skipped resume/reuse steps. This refactor specifically moves that mapping into a new helper, so a focused output assertion would catch regressions missed by functional-only E2E.
- Suggested test: Add an onboarding progress output E2E/assertion that verifies fresh onboard emits the expected eight labels and resume/reuse skip paths use the same [n/8] totals.

Dispatch hint

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

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

E2E Scenario Advisor Recommendation

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

Dispatch required scenario E2E:

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

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

ubuntu-repo-cloud-openclaw-resume: Changes refactor onboarding progress metadata and skipped-step progress rendering, including resume/reuse skip output. The resume-after-interrupt OpenClaw scenario is the smallest routed scenario that exercises the affected resume onboarding surface on the standard Ubuntu runner.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume

Optional scenario E2E

ubuntu-repo-cloud-openclaw: Optional baseline coverage for the normal cloud OpenClaw onboarding path after centralizing progress-step metadata; useful if extra confidence is desired beyond the resume path.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
ubuntu-repo-cloud-hermes: Optional adjacent coverage for the alternate Hermes agent onboarding path, which can expose regressions in agent-specific progress titles, but it is not the primary changed surface.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Relevant changed files

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

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

PR Review Advisor

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

Review findings

🛠️ Needs attention

None.

🔎 Worth checking

Source-of-truth review needed: src/lib/onboard/machine/progress.ts EXTRA_PROGRESS_STEPS: The advisor marked localized patch analysis as needs_followup.
- Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
- Evidence: `EXTRA_PROGRESS_STEPS` adds `messaging`, and `ONBOARD_PROGRESS_STEPS` appends extras after state-derived entries.
Guard the messaging pseudo-step from masking future FSM metadata (src/lib/onboard/machine/progress.ts:31): The new progress map appends the legacy `messaging` pseudo-step after state-derived entries. That preserves today's visible labels, but it also means a future real FSM-backed `messaging` state could be silently overridden by the compatibility entry if the stale pseudo-step is not removed at the same time. This weakens the intended single source of truth for progress metadata during the migration.
- Recommendation: Add an explicit duplicate/override guard or test that fails if any `EXTRA_PROGRESS_STEPS` stepName appears in `ONBOARD_MACHINE_STATE_DEFINITIONS`. That makes the removal condition enforceable when messaging becomes a real FSM state.
- Evidence: `ONBOARD_PROGRESS_STEPS` is built with `...ONBOARD_MACHINE_STATE_DEFINITIONS...` followed by `...EXTRA_PROGRESS_STEPS...`, and the comment says the extra `messaging` entry should be removed only when messaging becomes FSM-backed.

🌱 Nice ideas

None.

Since last review details

Current findings:

Source-of-truth review needed: src/lib/onboard/machine/progress.ts EXTRA_PROGRESS_STEPS: The advisor marked localized patch analysis as needs_followup.
- Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
- Evidence: `EXTRA_PROGRESS_STEPS` adds `messaging`, and `ONBOARD_PROGRESS_STEPS` appends extras after state-derived entries.
Guard the messaging pseudo-step from masking future FSM metadata (src/lib/onboard/machine/progress.ts:31): The new progress map appends the legacy `messaging` pseudo-step after state-derived entries. That preserves today's visible labels, but it also means a future real FSM-backed `messaging` state could be silently overridden by the compatibility entry if the stale pseudo-step is not removed at the same time. This weakens the intended single source of truth for progress metadata during the migration.
- Recommendation: Add an explicit duplicate/override guard or test that fails if any `EXTRA_PROGRESS_STEPS` stepName appears in `ONBOARD_MACHINE_STATE_DEFINITIONS`. That makes the removal condition enforceable when messaging becomes a real FSM state.
- Evidence: `ONBOARD_PROGRESS_STEPS` is built with `...ONBOARD_MACHINE_STATE_DEFINITIONS...` followed by `...EXTRA_PROGRESS_STEPS...`, and the comment says the extra `messaging` entry should be removed only when messaging becomes FSM-backed.

Workflow run details

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

…gress-metadata # Conflicts: # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts

github-actions · 2026-05-29T21:59:40Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26664305858
Target ref: stack/onboard-fsm-progress-metadata
Workflow ref: main
Requested jobs: onboard-resume-e2e
Summary: 0 passed, 0 failed, 0 skipped

Job	Result
onboard-resume-e2e	⚠️ cancelled

github-actions · 2026-05-29T22:11:28Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26664370934
Target ref: 4cd1e54ea78ae84a9091c174faf648cdd5ef6a70
Workflow ref: main
Requested jobs: onboard-resume-e2e,onboard-repair-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
onboard-repair-e2e	✅ success
onboard-resume-e2e	✅ success

cv · 2026-05-29T22:12:41Z

@coderabbitai review

coderabbitai · 2026-05-29T22:13:41Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

github-actions · 2026-05-29T22:26:03Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26665126534
Target ref: 6edc70a7a5cbaa84d1d5bf9144e49346bf5b8232
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-30T20:15:29Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26693706450
Target ref: e48c0148f82fda1398443fc6afe1b6e314215729
Workflow ref: main
Requested jobs: onboard-resume-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-resume-e2e	✅ success

github-actions · 2026-06-01T16:32:47Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26767613399
Target ref: 0cd29af4c5095698b75d096722b8792c73ce8200
Workflow ref: main
Requested jobs: onboard-resume-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-resume-e2e	✅ success

cjagwani

Approving. Clean refactor — replacing the hand-maintained ONBOARD_STEP_INDEX with FSM-derived lookup eliminates the drift risk between FSM state metadata and the step display.

The progress.test.ts snapshot of all 8 labels (including "Setting up agent inside sandbox" for openclaw) means any future divergence between the FSM and the visible step text fails the test. Removing the duplicated progress from agent_setup is right — openclaw is the canonical owner of step 7.

The messaging EXTRA_PROGRESS_STEPS pseudo-step is well-flagged with a migration comment for when it becomes a real FSM state. macos-e2e, test-e2e-sandbox, test-e2e-gateway-isolation, and test-e2e-port-overrides all passed.

github-actions · 2026-06-01T19:14:29Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26775888915
Target ref: 9b9646baad9e8c7d863ea3cbef0ce5f8be6e115b
Workflow ref: main
Requested jobs: cloud-onboard-e2e,onboard-resume-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-resume-e2e	✅ success

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

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

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

Open

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

Base automatically changed from stack/onboard-fsm-step-mapping to main May 29, 2026 21:26

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

4cd1e54

…gress-metadata # Conflicts: # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts

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

cv marked this pull request as ready for review May 29, 2026 21:56

Merge branch 'main' into stack/onboard-fsm-progress-metadata

6edc70a

Merge branch 'main' into stack/onboard-fsm-progress-metadata

e48c014

Merge branch 'main' into stack/onboard-fsm-progress-metadata

0cd29af

cv added v0.0.57 Release target and removed v0.0.56 Release target labels Jun 1, 2026

cjagwani approved these changes Jun 1, 2026

View reviewed changes

Merge branch 'main' into stack/onboard-fsm-progress-metadata

9b9646b

cv merged commit 957ec4c into main Jun 1, 2026
30 checks passed

cv deleted the stack/onboard-fsm-progress-metadata branch June 1, 2026 19:20

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

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!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

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

🛠️ Needs attention

🔎 Worth checking

🌱 Nice ideas

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!

cv commented May 29, 2026

Uh oh!

coderabbitai Bot commented May 29, 2026

Uh oh!

github-actions Bot commented May 29, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

github-actions Bot commented May 30, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

github-actions Bot commented Jun 1, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

cjagwani left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 1, 2026

Selective E2E Results — ✅ All requested jobs passed

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