refactor(onboard): make policy setup return FSM result by cv · Pull Request #4445 · NVIDIA/NemoClaw

cv · 2026-05-28T16:46:02Z

Summary

Make the policy setup handler return its explicit FSM transition result. The handler now reports the policies -> finalizing transition and carries applied policy preset metadata for future machine-driven orchestration.

Changes

Add stateResult to PoliciesStateResult.
Return advanceTo("finalizing") with policy preset metadata.
Extend policy handler tests for the returned FSM result.

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

Refactor
- Improved onboarding state management to ensure the system correctly transitions through workflow phases after policy selections. Policy configurations are now properly tracked throughout the entire onboarding process.

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

copy-pr-bot · 2026-05-28T16:46: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-28T16:46:12Z

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: a7dc8cb3-5272-4192-babd-779214918c6e

📥 Commits

Reviewing files that changed from the base of the PR and between 9b303b5 and c512de5.

📒 Files selected for processing (2)

src/lib/onboard/machine/handlers/policies.test.ts
src/lib/onboard/machine/handlers/policies.ts

📝 Walkthrough

Walkthrough

This PR updates the policies handler to return an explicit state transition result. The handlePoliciesState function now calls advanceTo("finalizing", ...) with effective policy preset metadata, and the result type is updated accordingly. Tests verify the transition behavior in two scenarios.

Changes

Policies Handler State Transition Integration

Layer / File(s)	Summary
Handler contract and state transition implementation `src/lib/onboard/machine/handlers/policies.ts`	The `PoliciesStateResult` interface adds a `stateResult` field of type `OnboardStateTransitionResult`. Imports include `advanceTo` and the transition result type. `handlePoliciesState` returns a transition result that advances to the finalizing state with metadata containing the effective `policyPresets`.
Test assertions for state transition `src/lib/onboard/machine/handlers/policies.test.ts`	Tests now capture the result from `handlePoliciesState` and add assertions verifying that `stateResult` represents an advance transition to finalizing with correct policy preset metadata in the "runs compatible endpoint smoke" and "resumes policies when all recorded presets" scenarios.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly Related PRs

NVIDIA/NemoClaw#4375: Introduces the explicit transition-result helper types (advanceTo and OnboardStateTransitionResult) that this PR now uses in the policies handler.
NVIDIA/NemoClaw#4376: Adds validation and application of explicit state transition results via OnboardRuntime.applyResult(...), which will consume the transition results now returned by this PR's updated handler.

Suggested Reviewers

prekshivyas
cjagwani
jyaunches

Poem

A handler hops to the finalizing state,
With presets bundled, transitions ornate,
Tests verify each transition with care,
The policies machine bounds forward with flair! 🐰✨

🚥 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: making the policy setup handler return an FSM (Finite State Machine) result instead of a plain object.
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-policies-result

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

github-actions · 2026-05-28T16:47:57Z

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, onboard-resume-e2e, network-policy-e2e
Optional E2E: ubuntu-repo-cloud-openclaw-custom-policies, ubuntu-repo-cloud-openclaw-resume

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

Auto-dispatched E2E: cloud-onboard-e2e, onboard-resume-e2e, network-policy-e2e via nightly-e2e.yaml at c512de56620622120e1b2be1936cc24910101413 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

cloud-onboard-e2e (moderate): Exercises the normal non-interactive cloud onboarding path with custom policy presets, ensuring the policies handler advances into finalization and produces a usable sandbox.
onboard-resume-e2e (moderate): Covers the resume branch touched by the new policies stateResult return, validating interrupted/resumed onboarding still proceeds past policies to finalization.
network-policy-e2e (moderate): Validates that policy preset setup still enforces the expected network policy/security boundary after changes in the core policy onboarding handler.

Optional E2E

ubuntu-repo-cloud-openclaw-custom-policies (moderate): Typed scenario coverage for custom policy onboarding plus onboarding-state assertions; useful additional confidence for the new state transition contract but overlaps with cloud-onboard-e2e.
ubuntu-repo-cloud-openclaw-resume (moderate): Typed scenario coverage for resume-after-interrupt behavior; useful if validating through the newer scenario runner in addition to the nightly resume script.

New E2E recommendations

None.

Dispatch hint

Workflow: nightly-e2e.yaml
jobs input: cloud-onboard-e2e,onboard-resume-e2e,network-policy-e2e

github-actions · 2026-05-28T16:47:58Z

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw
Optional scenario E2E: ubuntu-repo-cloud-openclaw-resume, 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: Changes the onboarding policies state handler, including the state-machine transition returned after policy setup. The standard Ubuntu repo cloud OpenClaw scenario exercises the primary onboarding path through policies and finalization on the default runner.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional scenario E2E

ubuntu-repo-cloud-openclaw-resume: Optional coverage for the resume-after-interrupt onboarding profile, since the policies handler also changed the result returned on the resume/skip path.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume
ubuntu-repo-cloud-hermes: Optional adjacent coverage for the same policies onboarding state with the Hermes agent profile; useful because the handler normalizes/forwards agent information into policy selection.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Relevant changed files

src/lib/onboard/machine/handlers/policies.ts

github-actions · 2026-05-28T16:48:53Z

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: PR review advisor unavailable

Review findings

🛠️ Needs attention

None.

🔎 Worth checking

PR review advisor unavailable: The automated advisor could not complete: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt
- Recommendation: Re-run the PR Review Advisor or perform a manual review.
- Evidence: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt

🌱 Nice ideas

None.

Consider writing more tests for

**Mocked behavioral coverage** — Add or confirm behavioral tests with mocked filesystem/network/process boundaries.. Changed code has I/O, state, credentials, provider, or config behavior that should be covered with behavioral mocks: src/lib/onboard/machine/handlers/policies.ts.

Workflow run details

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

github-actions · 2026-06-04T20:09:10Z

Selective E2E Results — ✅ All requested jobs passed

Run: 26975999639
Target ref: c512de56620622120e1b2be1936cc24910101413
Workflow ref: main
Requested jobs: cloud-onboard-e2e,onboard-resume-e2e,network-policy-e2e
Summary: 3 passed, 0 failed, 0 skipped

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

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

cv self-assigned this May 28, 2026

wscurran added enhancement: policy 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

wscurran added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: policy Network policy, egress rules, presets, or sandbox policy feature PR adds or expands user-visible functionality and removed enhancement: policy labels Jun 3, 2026

cv added 3 commits June 3, 2026 17:40

merge(onboard): update finalization FSM stack branch

beb2579

merge(onboard): update agent setup FSM stack branch

dba1644

merge(onboard): update policy setup FSM stack branch

66acf40

Base automatically changed from stack/onboard-fsm-agent-setup-result to main June 4, 2026 19:54

Merge branch 'main' into stack/onboard-fsm-policies-result

c512de5

cv marked this pull request as ready for review June 4, 2026 19:54

cv merged commit 79972bb into main Jun 4, 2026
32 of 34 checks passed

cv deleted the stack/onboard-fsm-policies-result branch June 4, 2026 20:15

This was referenced Jun 5, 2026

refactor(onboard): consume handler FSM results compatibly #4454

Merged

refactor(onboard): add sequence runner adapter #4475

Merged

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

This was referenced Jun 9, 2026

refactor(onboard): define FSM flow context #4481

Merged

refactor(onboard): extract agent policy finalization FSM phases #4484

Merged

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

Possibly Related PRs

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

Dispatch hint

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

🛠️ Needs attention

🔎 Worth checking

🌱 Nice ideas

Uh oh!

github-actions Bot commented Jun 4, 2026

Selective E2E Results — ✅ All requested jobs passed

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