refactor(onboard): define FSM flow context by cv · Pull Request #4481 · NVIDIA/NemoClaw

cv · 2026-05-29T02:37:00Z

Summary

Introduce a typed flow context for migrating the rich onboard.ts local-variable sequence to FSM phases. The context captures the values that are threaded between onboarding phases today.

Changes

Add OnboardFlowContext for session, agent, sandbox, provider, GPU, messaging, and web-search fields.
Add small helpers to merge context patches and pair context updates with FSM results.
Add tests for context merging and phase result construction.

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 test coverage for onboarding flow context merging and state transitions.
Chores
- Added foundational onboarding flow context and phase-result handling to support onboarding state management.
Style
- Improved readability of sandbox agent list command validation (no user-facing behavior change).

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

copy-pr-bot · 2026-05-29T02:37:03Z

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-29T02:37:06Z

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: 66f6fdfc-bfb2-4316-b8c3-eeb9226cde3b

📥 Commits

Reviewing files that changed from the base of the PR and between 5c7b7ee and abbd8c4.

📒 Files selected for processing (1)

src/commands/sandbox/agents/list.ts

✅ Files skipped from review due to trivial changes (1)

src/commands/sandbox/agents/list.ts

📝 Walkthrough

Walkthrough

Adds an onboarding flow context module with typed OnboardFlowContext and OnboardFlowPhaseResult, plus mergeOnboardFlowContext and onboardFlowPhaseResult helpers; includes tests validating merging and result construction. Also reformats a CLI sandbox name guard for readability.

Changes

Onboard Flow Context and Phase Result Types

Layer / File(s)	Summary
Flow context types and helper functions `src/lib/onboard/machine/flow-context.ts`	`OnboardFlowContext<Agent,Gpu,SandboxGpuConfig>` interface and `OnboardFlowPhaseResult` interface added; `mergeOnboardFlowContext` and `onboardFlowPhaseResult` helpers implemented.
Flow context helper tests `src/lib/onboard/machine/flow-context.test.ts`	Vitest suite adds `baseContext()` fixture and verifies that `mergeOnboardFlowContext` patches fields while preserving others, and `onboardFlowPhaseResult` pairs merged context with the expected FSM transition payload.

CLI Guard Formatting

Layer / File(s)	Summary
sandboxName guard reformat `src/commands/sandbox/agents/list.ts`	Refactors the `sandboxName` validation `if` into a multi-line conditional for readability; the logical checks and behavior remain the same.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

NVIDIA/NemoClaw#4376: Related onboarding flow/phase-result work; both touch onboarding phase result handling and context propagation.

Suggested labels

onboarding

Suggested reviewers

prekshivyas
cjagwani

Poem

🐰 I stitched a context, field by field,
A patch applied, no secrets to shield.
A phase result wrapped, neat and spry,
Tests hop in — they wink, they sigh.
Happy hops for code that’s healed! 🥕

🚥 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 clearly summarizes the main change: introducing a typed OnboardFlowContext for the FSM, which aligns with the primary focus of the PR.
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-flow-context

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

github-actions · 2026-05-29T02:38:21Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No E2E is recommended. The sandbox agents change is formatting-only, and the new onboarding flow-context helper is not integrated into runtime onboarding code yet and is covered by a colocated unit test. These changes cannot affect installer/onboarding execution, sandbox lifecycle, credentials, security boundaries, network policy, inference routing, deployment, or real assistant user flows in this PR.

Optional E2E

None.

New E2E recommendations

None.

github-actions · 2026-05-29T02:38:22Z

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

Required scenario E2E

None. No scenario E2E is recommended: the sandbox agents list change is formatting-only, the new onboard flow-context helper is not referenced by runtime onboarding code, and the added test is a unit test outside test/e2e-scenario/. These changes do not affect dispatchable scenario E2E behavior.

Optional scenario E2E

None.

Relevant changed files

None.

github-actions · 2026-05-29T02:40:02Z

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** — Verify a state handler can return an `onboardFlowPhaseResult` and `runOnboardMachine` applies both the FSM result and the updated context when wired through `updateContext`.. Unit coverage is sufficient for the newly added pure helpers as currently unused scaffolding. Runtime validation will become important when this context is wired into the onboarding runner and session/event boundaries.
**Runtime validation** — Verify nullable flow-context fields such as `credentialEnv`, `endpointUrl`, and `webSearchConfig` preserve `null` as an explicit clear instead of being dropped during session-update conversion.. Unit coverage is sufficient for the newly added pure helpers as currently unused scaffolding. Runtime validation will become important when this context is wired into the onboarding runner and session/event boundaries.
**Runtime validation** — Verify event/logging integration derived from `OnboardFlowContext` emits endpoint origin and credential env name only, not full secret-bearing endpoint URLs or credential values.. Unit coverage is sufficient for the newly added pure helpers as currently unused scaffolding. Runtime validation will become important when this context is wired into the onboarding runner and session/event boundaries.
**Acceptance clause:** `npx prek run --all-files` passes — add test evidence or identify existing coverage. This read-only advisory review did not execute commands or evaluate external CI surfaces.
**Acceptance clause:** `npm test` passes — add test evidence or identify existing coverage. This read-only advisory review did not execute commands or evaluate external CI surfaces.

Workflow run details

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

Signed-off-by: Carlos Villela <cvillela@nvidia.com> # Conflicts: # src/lib/onboard.ts # src/lib/onboard/machine/README.md # src/lib/onboard/machine/definition.test.ts # src/lib/onboard/machine/definition.ts # src/lib/onboard/machine/handlers/preflight.test.ts # src/lib/onboard/machine/handlers/provider-inference.ts # src/lib/onboard/machine/progress.ts # src/lib/onboard/machine/record-only-runner.test.ts # src/lib/onboard/machine/record-only-runner.ts # src/lib/onboard/machine/result.test.ts # src/lib/onboard/machine/result.ts # src/lib/onboard/machine/runner.test.ts # src/lib/onboard/machine/runner.ts # src/lib/onboard/machine/runtime.test.ts # src/lib/onboard/machine/runtime.ts # src/lib/onboard/machine/sequence-runner.test.ts # src/lib/onboard/machine/sequence-runner.ts # src/lib/onboard/runtime-boundary.test.ts # src/lib/onboard/runtime-boundary.ts # src/lib/state/onboard-session.test.ts # src/lib/state/onboard-session.ts

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

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

refactor(onboard): apply explicit state results through runtime

30341b0

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

refactor(onboard): make finalization return FSM result

d4ad2d9

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

refactor(onboard): make agent setup return FSM result

356c947

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

refactor(onboard): make policy setup return FSM result

2296519

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

refactor(onboard): make preflight and gateway return FSM results

67a9a1e

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

refactor(onboard): make sandbox return branch FSM result

46f4a49

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

refactor(onboard): return FSM results from provider inference

9cc15f5

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

refactor(onboard): add FSM runner shell

dbbb273

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

refactor(onboard): consume handler FSM results compatibly

6b27a0b

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

refactor(onboard): allow step recording without machine transitions

44009ad

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

refactor(onboard): plumb step mutation options through runtime

cd6e5f7

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

refactor(onboard): add record-only FSM runner adapter

e266e3b

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

refactor(onboard): return ordered provider FSM results

bf4da0b

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

refactor(onboard): run live sequence with record-only steps

212ff4d

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

refactor(onboard): let FSM handlers return result sequences

f69f60a

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

refactor(onboard): add sequence runner adapter

727ac69

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

refactor(onboard): support FSM runner stop states

75f82f7

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

refactor(onboard): define FSM flow context

59deee6

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

cv self-assigned this May 29, 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

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

cv added the v0.0.62 Release target label Jun 8, 2026

wscurran added the refactor PR restructures code without intended behavior change label Jun 8, 2026

cv added 2 commits June 9, 2026 01:16

merge(onboard): sync flow context with stop states

5900708

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

cv marked this pull request as ready for review June 9, 2026 08:48

Base automatically changed from stack/onboard-fsm-runner-stop-states to main June 9, 2026 13:26

jyaunches and others added 4 commits June 9, 2026 10:00

Merge branch 'main' into stack/onboard-fsm-flow-context

5c7b7ee

Merge branch 'main' into stack/onboard-fsm-flow-context

83c1412

Merge branch 'main' into stack/onboard-fsm-flow-context

23e8577

chore: apply static formatting for FSM flow stack

abbd8c4

cv merged commit 3db6971 into main Jun 9, 2026
112 checks passed

cv deleted the stack/onboard-fsm-flow-context branch June 9, 2026 18:53

Conversation

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

Uh oh!

coderabbitai Bot commented May 29, 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 labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

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

Uh oh!

PR Review Advisor

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cv commented May 29, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 29, 2026 •

edited

Loading

github-actions Bot commented May 29, 2026 •

edited

Loading

github-actions Bot commented May 29, 2026 •

edited

Loading

github-actions Bot commented May 29, 2026 •

edited

Loading