Skip to content

feat(onboard): add agents.yaml declarative manifest - #5440

Merged
cv merged 16 commits into
mainfrom
feat/agents-manifest
Jun 17, 2026
Merged

feat(onboard): add agents.yaml declarative manifest#5440
cv merged 16 commits into
mainfrom
feat/agents-manifest

Conversation

@laitingsheng

@laitingsheng laitingsheng commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Summary

Add nemoclaw onboard --agents <agents.yaml> to bake a declarative manifest into the sandbox image at build time, and nemoclaw <name> agents apply -f <agents.yaml> to reconcile the manifest against an already-running sandbox without a rebuild. The manifest schema mirrors OpenClaw's own agents.list[] field names verbatim, and per-agent model overrides fan out into models.providers[<onboard-provider>].models[] automatically.

Related Issue

Resolves #2853

Complements #2854 (host-side OpenClaw agent lifecycle commands): the manifest is the fixed checked-in path that bakes a layout into the image, while the nemoclaw <sandbox> agents add|delete|list lifecycle commands cover ad-hoc edits inside an existing sandbox. The two paths share the same agents.list[] semantics and OpenClaw-native field vocabulary, and the new agents apply verb sits on top of agents add|delete to drive declarative roster reconciliation from the same manifest the build path consumes.

This PR extends the NEMOCLAW_EXTRA_AGENTS_JSON bake path introduced in #4653. While extending it, the previous validator was found to accept subagents.maxSpawnDepth per-agent and to allow value 0. OpenClaw's per-agent zod schema is .strict() and never accepted that field, and the global default schema requires min(1).max(5). Any non-empty NEMOCLAW_EXTRA_AGENTS_JSON_B64 payload would have tripped OpenClaw's runtime parser. This PR strict-rejects per-agent maxSpawnDepth with a migration hint pointing at the top-level defaults.subagents.maxSpawnDepth.

Changes

  • scripts/generate-openclaw-config.mts: accept either the legacy bare-array payload or a new {agents, defaults?, main?} object. Extend the per-agent allowlist with model; replace ALLOWED_SUBAGENTS_KEYS with OpenClaw-native fields {delegationMode, allowAgents, model, thinking, requireAgentId}. Strict-reject per-agent maxSpawnDepth with a clear migration hint. Add validateAgentsDefaults and validateMainOverrides so defaults.subagents.maxSpawnDepth and main.{tools, subagents} bake into the canonical places. Widen providers[<onboard-provider>].models[] with one entry per unique referenced provider/model ref; reject cross-provider refs.
  • src/lib/onboard/agents-manifest.ts (new): YAML loader that parses the manifest, auto-fills canonical workspace/agentDir paths from id, and sets NEMOCLAW_EXTRA_AGENTS_JSON for the downstream Dockerfile patcher. Includes a defence-in-depth credential-name denylist (apiKey, token, secret, etc.) before the payload reaches the staged Dockerfile/build context.
  • src/lib/onboard/command-support.ts, src/lib/onboard/legacy-command.ts: thread --agents <file> through the oclif flag definition, legacy-args parser, OnboardCommandOptions.agentsManifest, and runOnboardCommand (invokes applyAgentsManifestEnv before dispatching to the underlying runOnboard).
  • src/lib/actions/sandbox/agents/apply.ts (new), src/commands/sandbox/agents/apply.ts (new): in-sandbox agents apply verb. Lists current agents via openclaw agents list --json, diffs against the manifest, runs openclaw agents add|delete per item. Per-agent model, subagents.*, top-level defaults, and main overrides require a rebuild and are reported as warnings before exit. Confirmation gates: --yes to apply, --non-interactive to fail fast when --yes is absent.
  • test/generate-openclaw-config.test.ts, test/generate-openclaw-config-agents-manifest.test.ts (new): drop the per-agent maxSpawnDepth fixture; add coverage in the dedicated file for the new payload object shape, per-agent model accept + provider-prefix reject, allowAgents round-trip, delegationMode enum rejection, defaults.subagents.maxSpawnDepth range, main.{subagents, tools} merge, multi-model provider expansion, and the per-agent maxSpawnDepth strict-reject with migration hint. Split keeps the original file under the legacy size budget.
  • test/agents-manifest-policy-conformance.test.ts (new): policy mirror of OpenClaw's resolveSubagentTargetPolicy against the baked agents.list[].subagents.allowAgents shape — covers configured target allow, unlisted target deny, wildcard "*" + unknown target deny, and self-only default.
  • src/lib/onboard/agents-manifest.test.ts (new), src/lib/onboard/agents-manifest-credential-denylist: 12 cases for the YAML loader plus the credential denylist matrix.
  • src/lib/onboard/legacy-command.test.ts, src/lib/onboard/legacy-command-agents.test.ts (new): --agents lifecycle moved into the focused file (parse, missing-path / missing-value rejection, env-var application before runOnboard).
  • src/lib/actions/sandbox/agents/apply.test.ts (new): diff computation + rebuild-only warning + --yes / --non-interactive gating + no-op when roster matches.
  • src/lib/onboard/dockerfile-patch-extra-agents.test.ts: rotate the fixture from subagents: { maxSpawnDepth: 0 } to subagents: { allowAgents: ["analyst"] }.
  • docs/inference/declarative-agents-manifest.mdx (new), docs/reference/commands.mdx, docs/reference/commands-nemohermes.mdx, docs/index.yml: user-facing reference for the manifest schema, the main / defaults / agents blocks, the OpenClaw-native sub-agent fields, the multi-model bake semantics, a manager-worker walkthrough, the new agents apply verb, and the --agents onboard flag listing.

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

  • Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
  • Targeted tests pass for changed behavior
  • Full npm test passes (broad runtime changes only)
  • 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

Release Notes

  • New Features
    • Added --agents <agents.yaml> to onboarding (including compatibility aliases).
    • Added sandbox <name> agents apply to reconcile a sandbox’s agents from a manifest, with rebuild-required warnings.
  • Documentation
    • Added an Inference navigation entry and a task-specific manifest setup guide.
    • Updated command reference pages for onboarding and apply (including nemohermes).
  • Tests
    • Expanded coverage for agents manifest parsing/validation, config generation, and sandbox apply diff/rebuild-only behavior.

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…sed file

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
@coderabbitai

coderabbitai Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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
📝 Walkthrough

Walkthrough

Introduces a declarative agents.yaml manifest for NemoClaw multi-agent OpenClaw sandboxes. A new --agents CLI flag is added to the onboard command, backed by a YAML loader that validates and sets NEMOCLAW_EXTRA_AGENTS_JSON. The config generator is extended with structured ExtraAgentsPayload validation, provider-scoped model deduplication, and main/defaults override baking. A new sandbox agents apply command reconciles live rosters against manifests without rebuild. Comprehensive test coverage including policy conformance validation and detailed documentation are included.

Changes

Declarative Multi-Agent Manifest Feature

Layer / File(s) Summary
AgentsManifest loader, validator, and env helper
src/lib/onboard/agents-manifest.ts, src/lib/onboard/agents-manifest.test.ts
New module defines AgentsManifestPayload, loadAgentsManifest (YAML parse with top-level key validation, per-agent workspace/agentDir defaults, credential-field denylist scan), and applyAgentsManifestEnv (serializes payload into NEMOCLAW_EXTRA_AGENTS_JSON). Tests cover empty manifests, manager-worker parsing with computed/preserved fields, defaults/main pass-through, and error cases including missing files and nested credential keys.
--agents CLI flag, command parsing, and env application
src/lib/onboard/command-support.ts, src/lib/onboard/legacy-command.ts, src/lib/onboard/legacy-command-agents.test.ts, src/lib/onboard/legacy-command.test.ts, src/lib/onboard/dockerfile-patch-extra-agents.test.ts
OnboardFlags and OnboardCommandOptions gain agents/agentsManifest fields. parseOnboardArgs validates YAML path and resolves to absolute path; runOnboardCommand calls applyAgentsManifestEnv before invoking runOnboard. Usage, examples, and flag definitions updated. Existing tests add agentsManifest: null assertions; new dedicated suite covers --agents lifecycle including parsing, validation, and environment propagation.
ExtraAgentsPayload structured validation and model baking
scripts/generate-openclaw-config.mts
New validators (validateModelRef, validateSubagentsBlock, validateAgentsDefaults, validateMainOverrides) replace legacy subagents validation. validateExtraAgents returns structured ExtraAgentsPayload with agents, defaults, main. buildAgentsList accepts mainOverrides and merges into primary agent. Provider models list built from deduplicated array spanning primary and all secondary agent/subagent model refs. agents.defaults.subagents conditionally wired from payload.
Config generator test suites
test/generate-openclaw-config-agents-manifest.test.ts, test/generate-openclaw-config.test.ts, ci/test-file-size-budget.json
New comprehensive suite validates object-shaped payload, unknown-key rejection, per-agent model provider matching/deduplication, subagents.allowAgents baking, delegationMode enum enforcement, maxSpawnDepth range (1..5), main override merging, and main allowlist rejection. Existing suite updated: fixtures drop subagents default, tests cover optional subagents, migration hints for per-agent maxSpawnDepth, shape validation, allowlist stripping. Test budget adjusted.
Subagent targeting policy conformance
test/agents-manifest-policy-conformance.test.ts
Validates four subagent targeting scenarios: allowed targeting of configured IDs in allowAgents, denial when configured but unlisted, denial for unknown targets even with wildcard, and self-only fallback when allowAgents omitted. Uses temp environment, fake openclaw binary, and full config generation plus messaging/applier pipeline.
Sandbox agents apply command
src/commands/sandbox/agents/apply.ts, src/commands/sandbox/agents.ts
New SandboxAgentsApplyCommand reconciles live sandbox roster against a declarative manifest by parsing sandbox name and supporting -f/--file, --yes, --non-interactive flags. Includes dedicated help printer documenting manifest semantics and rebuild requirements. Parent command updated with apply example and help text.
Agents apply implementation and tests
src/lib/actions/sandbox/agents/apply.ts, src/lib/actions/sandbox/agents/apply.test.ts, src/lib/actions/sandbox/agents/passthrough.ts
runAgentsApply orchestration ensures sandbox liveness, loads manifest, computes add/delete diff while protecting main agent, identifies rebuild-only fields, logs plan and warnings, enforces --yes requirements by interactive mode, and executes deletions then additions. Includes default subprocess-based agent operations (`openclaw agents list
Declarative agents manifest and command documentation
docs/inference/declarative-agents-manifest.mdx, docs/index.yml, docs/reference/commands.mdx, docs/reference/commands-nemohermes.mdx, src/lib/cli/command-registry.test.ts, src/lib/cli/public-display-agents.ts
New guide documents --agents workflow, manifest schema (defaults.subagents.maxSpawnDepth, main tool/subagent overrides, agents[] secondary entries), subagent delegation block fields (allowAgents, delegationMode, model, thinking, requireAgentId), multi-model baking behavior, manager-worker YAML example with expected openclaw.json output, iteration guidance with --recreate-sandbox, and agents apply reconciliation without rebuild. Nav entry added under Inference. CLI references updated with --agents flag description, schema link, and agents apply subcommand documentation; deprecated alias support (setup/setup-spark) extended to include new flags. Command registry test expectations updated; display layout entry added for new command.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Suggested labels

area: docs

Suggested reviewers

  • cv

🐇 A manifest declares agents clear,
With workers, managers, all near.
--agents agents.yaml runs the show,
Defaults and main together flow.
Multi-model sandboxes, strong and true,
Built from YAML, by the crew! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 6.45% 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 PR title 'feat(onboard): add agents.yaml declarative manifest' clearly and concisely summarizes the main change: adding a declarative agents.yaml manifest capability to the onboard workflow.
Linked Issues check ✅ Passed The PR comprehensively implements the core objectives from issue #2853: declarative multi-agent manifest via agents.yaml, onboarding path (nemoclaw onboard --agents), apply path (nemoclaw agents apply -f), manifest validation, workspace management, and OpenClaw config generation.
Out of Scope Changes check ✅ Passed All changes are directly scoped to the declared objectives: agents.yaml manifest loading, onboard flag threading, agents apply command, config generation, comprehensive tests, and documentation. No unrelated modifications detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/agents-manifest

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

@github-actions

Copy link
Copy Markdown
Contributor

@github-code-quality

github-code-quality Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the feat/agents-manifest branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main feat/agents-manifest b920beb +/-
nemoclaw/src/se...cret-scanner.ts 100%
nemoclaw/src/commands/slash.ts 100%
nemoclaw/src/li...bprocess-env.ts 100%
nemoclaw/src/bl...eprint/state.ts 98%
nemoclaw/src/onboard/config.ts 98%
nemoclaw/src/bl...int/snapshot.ts 97%
nemoclaw/src/bl...print/runner.ts 95%
nemoclaw/src/co...ration-state.ts 94%
nemoclaw/src/bl...ate-networks.ts 94%
nemoclaw/src/index.ts 94%

TypeScript / code-coverage/cli

The overall coverage in the feat/agents-manifest branch is 45%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main feat/agents-manifest b920beb +/-
src/lib/state/o...oard-session.ts 90%
src/lib/inference/local.ts 76%
src/lib/sandbox/config.ts 72%
src/lib/onboard/preflight.ts 64%
src/lib/actions...dbox/rebuild.ts 60%
src/lib/state/sandbox.ts 55%
src/lib/actions...licy-channel.ts 52%
src/lib/onboard...er-gpu-patch.ts 50%
src/lib/policy/index.ts 49%
src/lib/onboard.ts 17%

Updated June 15, 2026 21:36 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.

@laitingsheng laitingsheng added integration: openclaw OpenClaw integration behavior feature PR adds or expands user-visible functionality labels Jun 15, 2026
@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, sessions-agents-cli-e2e
Optional E2E: inference-routing-e2e, openclaw-inference-switch-e2e, rebuild-openclaw-e2e

Dispatch hint: cloud-onboard-e2e,sessions-agents-cli-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • cloud-onboard-e2e: Required because the PR changes OpenClaw onboarding and build-time openclaw.json generation. This job performs a real non-interactive OpenClaw onboard with hosted inference and validates that the generated sandbox image boots with the generated configuration.
  • sessions-agents-cli-e2e: Required because the PR changes the live nemoclaw <name> agents command group and adds agents apply. This is the existing live E2E coverage for OpenClaw agents CLI passthrough, add/delete/list lifecycle, public argv routing, and related sandbox execution behavior.

Optional E2E

  • inference-routing-e2e: Optional confidence for the provider/model routing path because manifest-driven secondary agents can append model references to generated OpenClaw provider configuration.
  • openclaw-inference-switch-e2e: Optional confidence that OpenClaw config and registry synchronization still work after a running sandbox changes inference route; adjacent to the generated model/provider configuration changes.
  • rebuild-openclaw-e2e: Optional confidence for rebuild/recreate flows because the new manifest path is documented as requiring onboard --agents ... --recreate-sandbox for fields that must be baked into the image.

New E2E recommendations

  • Manifest-driven OpenClaw multi-agent onboarding (high): Existing E2E covers generic OpenClaw onboard and live agents add/delete/list, but no existing E2E appears to onboard with --agents <agents.yaml> and verify the baked agents.list, agents.defaults.subagents, main-agent overrides, per-agent model expansion, and path isolation in a real sandbox.
    • Suggested test: Add an OpenClaw agents-manifest E2E job that runs nemoclaw onboard --agents <fixture>, then inspects the live sandbox openclaw.json and openclaw agents list --json for the expected main/default entry, secondary agents, provider model entries, and rejected unsafe manifest cases.
  • Live agents apply reconciliation (high): The new nemoclaw <name> agents apply -f <agents.yaml> behavior reconciles a live sandbox roster, prompts/uses --yes, and reports warnings for rebuild-only fields, but current live E2E coverage only exercises add/delete/list passthrough.
    • Suggested test: Extend or add an agents CLI E2E case that applies a manifest to an onboarded OpenClaw sandbox, verifies add/delete reconciliation via openclaw agents list --json, verifies non-interactive confirmation behavior, and asserts rebuild-only manifest fields are reported as warnings.

Dispatch hint

  • Workflow: .github/workflows/nightly-e2e.yaml
  • jobs input: cloud-onboard-e2e,sessions-agents-cli-e2e

@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-openclaw
Optional Vitest E2E scenarios: ubuntu-repo-docker-post-reboot-recovery

Dispatch required Vitest E2E scenarios:

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

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required Vitest E2E scenarios

  • ubuntu-repo-cloud-openclaw: The PR changes OpenClaw onboarding/config generation and agent-manifest plumbing used while building the sandbox image. The canonical live-supported Ubuntu OpenClaw onboarding scenario is the smallest Vitest scenario dispatch that exercises this build/onboard surface.
    • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

  • ubuntu-repo-docker-post-reboot-recovery: Optional adjacent live-supported OpenClaw scenario that also performs the repo-current Docker onboarding/config build before exercising recovery lifecycle invariants.
    • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-docker-post-reboot-recovery

Relevant changed files

  • scripts/generate-openclaw-config.mts
  • src/commands/sandbox/agents.ts
  • src/commands/sandbox/agents/apply.ts
  • src/lib/actions/sandbox/agents/apply.ts
  • src/lib/actions/sandbox/agents/passthrough.ts
  • src/lib/cli/public-display-agents.ts
  • src/lib/onboard/agents-manifest.ts
  • src/lib/onboard/command-support.ts
  • src/lib/onboard/legacy-command.ts

Comment thread test/generate-openclaw-config-agents-manifest.test.ts Fixed
Comment thread src/lib/onboard/agents-manifest.ts Fixed
Comment thread test/generate-openclaw-config-agents-manifest.test.ts Fixed
@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor

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

Review findings

🛠️ Needs attention

  • `agents apply` adds agents whose manifest-declared tools policy is not applied (src/lib/actions/sandbox/agents/apply.ts:365): The live apply path detects `agents[id].tools` as rebuild-only, warns, and then still creates the missing agent with `openclaw agents add`. For a checked-in manifest that defines tools/security policy, the sandbox ends up with the requested agent but without the manifest-required tool boundary, creating a false sense that the live sandbox matches the manifest.
    • Recommendation: Either apply `agents[].tools` through a supported OpenClaw lifecycle before creating the agent, or refuse all roster mutations for any missing agent that declares rebuild-only security/config fields and direct the user to rebuild. Add a negative test proving no add/delete command is invoked when a missing manifest agent declares `tools` that cannot be reconciled live.
    • Evidence: `findRebuildOnlyFields()` reports `agents[${id}].tools`; `runAgentsApply()` logs `Manifest declares tools for "${entry.id}"; the live add cannot bake a tool policy` and then executes `addAgent(options.sandboxName, entry.id, entry.workspace)`. The test `warns before adding a manifest agent that declares a tools policy` asserts add-after-warning behavior.
  • New `agents apply` test file exceeds the current monolith-growth budget (src/lib/actions/sandbox/agents/apply.test.ts:1): The PR adds a new 421-line focused test file, and the repository drift budget flags this as a current monolith growth hotspot. The cases are useful, but the file combines diff computation, manifest validation, CLI mutation orchestration, and confirmation behavior.
    • Recommendation: Split the test into smaller files by responsibility, for example diff/validation helpers vs. `runAgentsApply()` orchestration, or otherwise offset the growth in the test-size budget before merge.
    • Evidence: Drift context reports `src/lib/actions/sandbox/agents/apply.test.ts` with baseLines 0, headLines 421, delta 421, severity `blocker` for current monolith growth.

🔎 Worth checking

  • Source-of-truth review needed: Live `agents apply` manifest parsing and reconciliation: 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: `runAgentsApply()` calls `loadAgentsManifest()`, `validateAgentsManifestForApply()`, and `buildAgentsApplyDiff()`, then adds agents after warning about rebuild-only fields.
  • Source-of-truth review needed: `NEMOCLAW_EXTRA_AGENTS_JSON` process-global invocation state: The advisor marked localized patch analysis as missing.
    • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
    • Evidence: `applyAgentsManifestEnv()` sets `process.env.NEMOCLAW_EXTRA_AGENTS_JSON`; `runOnboardCommand()` awaits `deps.runOnboard(options)` without cleanup.
  • Source-of-truth review needed: Legacy bare-array `NEMOCLAW_EXTRA_AGENTS_JSON_B64` compatibility: 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: `validateExtraAgents()` contains `// Legacy payload shape: bare array of secondary agents.` before accepting `Array.isArray(value)`.
  • Manifest env transport is not scoped to one onboarding invocation (src/lib/onboard/legacy-command.ts:303): `runOnboardCommand()` writes the parsed manifest into process-global `NEMOCLAW_EXTRA_AGENTS_JSON` and awaits `runOnboard()` without restoring the previous value. A later onboarding call in the same Node process that omits `--agents` can still have the stale manifest baked because the Dockerfile patcher reads that global variable. If an accidental sensitive value survives the manifest field-name scan, it can also be persisted into the staged Dockerfile ARG.
    • Recommendation: Restore the previous `NEMOCLAW_EXTRA_AGENTS_JSON` value in a `finally` block, or pass the manifest payload through an explicit build option instead of process-global env. Add tests for two sequential invocations and for the first invocation throwing, proving the second invocation cannot see the first manifest.
    • Evidence: `runOnboardCommand()` calls `applyAgentsManifestEnv(options.agentsManifest)` before `await deps.runOnboard(options)` with no cleanup path. `patchStagedDockerfile()` base64-encodes `process.env.NEMOCLAW_EXTRA_AGENTS_JSON` into `ARG NEMOCLAW_EXTRA_AGENTS_JSON_B64` whenever it is non-empty.
  • `agents apply` deletes existing agents before proving missing agents can be added (src/lib/actions/sandbox/agents/apply.ts:354): The apply loop deletes every orphan first and only then starts adding missing manifest agents. If a later add fails, the sandbox can be left without agents that existed before and without the replacement roster, despite the manifest not being fully applied.
    • Recommendation: Validate all planned operations before any destructive step and prefer add-before-delete, or provide a clear transactional/rollback model. Add a regression test where delete succeeds and a later add fails to lock in the intended rollback or partial-apply behavior.
    • Evidence: `runAgentsApply()` iterates `diff.toDelete` and calls `deleteAgent(...)` before iterating `diff.toAdd` and calling `addAgent(...)`; failures throw without rollback.
  • Live `agents apply` has a divergent source of truth from the build validator (src/lib/actions/sandbox/agents/apply.ts:320): The build-time generator is documented as the structured validation source of truth, but live apply uses a separate subset validator and then mutates the sandbox while merely warning about full-schema fields such as tools, models, subagents, defaults, and main overrides. This duplication can drift and already produces partial application for security-relevant fields.
    • Recommendation: Make the invalid state impossible at the live source boundary: either reuse/export a common manifest validator and refuse mutation when rebuild-only config is present, or clearly split roster-only manifests from build manifests. Add a test proving live apply rejects full-manifest fields it cannot safely apply before any mutation.
    • Evidence: `runAgentsApply()` calls `loadAgentsManifest()`, `validateAgentsManifestForApply()`, and `buildAgentsApplyDiff()` instead of the build-time validator. `validateAgentsManifestForApply()` checks ids/paths/unknown agent keys only; `findRebuildOnlyFields()` reports other fields as warnings.
  • Hermes command reference advertises the OpenClaw-only `--agents` flag (docs/reference/commands-nemohermes.mdx:82): The implementation rejects `--agents` when `--agent hermes` is selected and live `agents apply` rejects non-OpenClaw sandboxes, but the Hermes command reference lists `nemohermes onboard ... [--agents <agents.yaml>]` and compatibility aliases with the same flag. That sends Hermes users toward a path whose semantics are explicitly OpenClaw-only.
    • Recommendation: Remove `--agents` from the Hermes generated reference, or implement and document Hermes-specific manifest semantics. Add or keep a parity test that the Hermes docs and visible command surface do not list OpenClaw-only flags or subcommands.
    • Evidence: `parseOnboardArgs()` rejects `--agents` when `!isOpenclawAgent(agent)`, and `runAgentsApply()` exits for non-OpenClaw sandbox agents. The Hermes docs diff adds `[--agents <agents.yaml>]` to `nemohermes onboard`, `setup`, and `setup-spark`.
  • Security-sensitive delegation coverage mirrors OpenClaw with TypeScript disabled (test/agents-manifest-policy-conformance.test.ts:1): The delegation-policy conformance test locally copies OpenClaw's `resolveSubagentTargetPolicy` behavior instead of exercising the runtime implementation, and starts with `// @ts-nocheck`. The focused config-generator manifest test also uses `// @ts-nocheck`. These tests cover security-sensitive delegation and config shape, so type-shape drift or upstream OpenClaw policy drift can be missed.
    • Recommendation: Remove `@ts-nocheck` and type the helpers narrowly. Add or identify runtime/integration coverage that bakes a manifest and exercises real OpenClaw `sessions_spawn` behavior for allowed targets, omitted targets, unknown targets, and `allowAgents: ["*"]`.
    • Evidence: `test/agents-manifest-policy-conformance.test.ts` starts with `// @ts-nocheck` and states it is a local copy of OpenClaw's `resolveSubagentTargetPolicy`; `test/generate-openclaw-config-agents-manifest.test.ts` also starts with `// @ts-nocheck`.

🌱 Nice ideas

  • Legacy bare-array manifest compatibility lacks a removal or permanence story (scripts/generate-openclaw-config.mts:792): The generator accepts both the new `{agents, defaults?, main?}` object shape and the older bare-array payload. That may be intentional compatibility, but the code only labels it as legacy and does not say whether it is permanent, temporary, or what condition allows removal.
    • Recommendation: Document whether bare-array compatibility is permanent. If it is temporary, add a short removal condition near the compatibility branch and keep a focused regression test for the legacy payload until that condition is met.
    • Evidence: `validateExtraAgents()` contains `// Legacy payload shape: bare array of secondary agents.` before accepting `Array.isArray(value)`.
Consider writing more tests for
  • **Runtime validation** — `agents apply` refuses all roster mutations when any missing manifest agent declares `tools` that cannot be applied live.. This PR crosses host CLI parsing, YAML/env transport, Dockerfile ARG patching, generated OpenClaw config, sandbox startup workspace provisioning, live sandbox mutation, and OpenClaw runtime delegation enforcement. Unit coverage is broad, but the riskiest behavior sits across sandbox/runtime boundaries.
  • **Runtime validation** — `agents apply` preserves the original live roster or rolls back when an add fails after planned deletes.. This PR crosses host CLI parsing, YAML/env transport, Dockerfile ARG patching, generated OpenClaw config, sandbox startup workspace provisioning, live sandbox mutation, and OpenClaw runtime delegation enforcement. Unit coverage is broad, but the riskiest behavior sits across sandbox/runtime boundaries.
  • **Runtime validation** — `runOnboardCommand` restores absent and previous `NEMOCLAW_EXTRA_AGENTS_JSON` after `runOnboard` succeeds and after it throws.. This PR crosses host CLI parsing, YAML/env transport, Dockerfile ARG patching, generated OpenClaw config, sandbox startup workspace provisioning, live sandbox mutation, and OpenClaw runtime delegation enforcement. Unit coverage is broad, but the riskiest behavior sits across sandbox/runtime boundaries.
  • **Runtime validation** — `nemohermes onboard`, `setup`, and `setup-spark` generated docs and visible help do not include `--agents` unless Hermes support exists.. This PR crosses host CLI parsing, YAML/env transport, Dockerfile ARG patching, generated OpenClaw config, sandbox startup workspace provisioning, live sandbox mutation, and OpenClaw runtime delegation enforcement. Unit coverage is broad, but the riskiest behavior sits across sandbox/runtime boundaries.
  • **Runtime validation** — A baked manifest exercises real OpenClaw `sessions_spawn` for configured allowed targets, unlisted targets, unknown targets, wildcard `allowAgents: ["*"]`, and self-only default behavior.. This PR crosses host CLI parsing, YAML/env transport, Dockerfile ARG patching, generated OpenClaw config, sandbox startup workspace provisioning, live sandbox mutation, and OpenClaw runtime delegation enforcement. Unit coverage is broad, but the riskiest behavior sits across sandbox/runtime boundaries.
  • **Security-sensitive delegation coverage mirrors OpenClaw with TypeScript disabled** — Remove `@ts-nocheck` and type the helpers narrowly. Add or identify runtime/integration coverage that bakes a manifest and exercises real OpenClaw `sessions_spawn` behavior for allowed targets, omitted targets, unknown targets, and `allowAgents: ["*"]`.
  • **New `agents apply` test file exceeds the current monolith-growth budget** — Split the test into smaller files by responsibility, for example diff/validation helpers vs. `runAgentsApply()` orchestration, or otherwise offset the growth in the test-size budget before merge.
  • **Acceptance clause:** The setup needs to define agents, workspaces, tools/security policy, default models, and manager/worker relationships in a checked-in file for repeatable IaC/GitOps workflows. — add test evidence or identify existing coverage. The build-time path supports agents, canonical workspaces, tools, model refs, defaults, and subagent relationships. The live `agents apply` path only applies roster add/delete and warns for tools/model/subagents/defaults/main, so it can leave an existing sandbox partially matching the checked-in file.
Since last review details

Current findings:

  • Source-of-truth review needed: Live `agents apply` manifest parsing and reconciliation: 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: `runAgentsApply()` calls `loadAgentsManifest()`, `validateAgentsManifestForApply()`, and `buildAgentsApplyDiff()`, then adds agents after warning about rebuild-only fields.
  • Source-of-truth review needed: `NEMOCLAW_EXTRA_AGENTS_JSON` process-global invocation state: The advisor marked localized patch analysis as missing.
    • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
    • Evidence: `applyAgentsManifestEnv()` sets `process.env.NEMOCLAW_EXTRA_AGENTS_JSON`; `runOnboardCommand()` awaits `deps.runOnboard(options)` without cleanup.
  • Source-of-truth review needed: Legacy bare-array `NEMOCLAW_EXTRA_AGENTS_JSON_B64` compatibility: 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: `validateExtraAgents()` contains `// Legacy payload shape: bare array of secondary agents.` before accepting `Array.isArray(value)`.
  • `agents apply` adds agents whose manifest-declared tools policy is not applied (src/lib/actions/sandbox/agents/apply.ts:365): The live apply path detects `agents[id].tools` as rebuild-only, warns, and then still creates the missing agent with `openclaw agents add`. For a checked-in manifest that defines tools/security policy, the sandbox ends up with the requested agent but without the manifest-required tool boundary, creating a false sense that the live sandbox matches the manifest.
    • Recommendation: Either apply `agents[].tools` through a supported OpenClaw lifecycle before creating the agent, or refuse all roster mutations for any missing agent that declares rebuild-only security/config fields and direct the user to rebuild. Add a negative test proving no add/delete command is invoked when a missing manifest agent declares `tools` that cannot be reconciled live.
    • Evidence: `findRebuildOnlyFields()` reports `agents[${id}].tools`; `runAgentsApply()` logs `Manifest declares tools for "${entry.id}"; the live add cannot bake a tool policy` and then executes `addAgent(options.sandboxName, entry.id, entry.workspace)`. The test `warns before adding a manifest agent that declares a tools policy` asserts add-after-warning behavior.
  • Manifest env transport is not scoped to one onboarding invocation (src/lib/onboard/legacy-command.ts:303): `runOnboardCommand()` writes the parsed manifest into process-global `NEMOCLAW_EXTRA_AGENTS_JSON` and awaits `runOnboard()` without restoring the previous value. A later onboarding call in the same Node process that omits `--agents` can still have the stale manifest baked because the Dockerfile patcher reads that global variable. If an accidental sensitive value survives the manifest field-name scan, it can also be persisted into the staged Dockerfile ARG.
    • Recommendation: Restore the previous `NEMOCLAW_EXTRA_AGENTS_JSON` value in a `finally` block, or pass the manifest payload through an explicit build option instead of process-global env. Add tests for two sequential invocations and for the first invocation throwing, proving the second invocation cannot see the first manifest.
    • Evidence: `runOnboardCommand()` calls `applyAgentsManifestEnv(options.agentsManifest)` before `await deps.runOnboard(options)` with no cleanup path. `patchStagedDockerfile()` base64-encodes `process.env.NEMOCLAW_EXTRA_AGENTS_JSON` into `ARG NEMOCLAW_EXTRA_AGENTS_JSON_B64` whenever it is non-empty.
  • `agents apply` deletes existing agents before proving missing agents can be added (src/lib/actions/sandbox/agents/apply.ts:354): The apply loop deletes every orphan first and only then starts adding missing manifest agents. If a later add fails, the sandbox can be left without agents that existed before and without the replacement roster, despite the manifest not being fully applied.
    • Recommendation: Validate all planned operations before any destructive step and prefer add-before-delete, or provide a clear transactional/rollback model. Add a regression test where delete succeeds and a later add fails to lock in the intended rollback or partial-apply behavior.
    • Evidence: `runAgentsApply()` iterates `diff.toDelete` and calls `deleteAgent(...)` before iterating `diff.toAdd` and calling `addAgent(...)`; failures throw without rollback.
  • Live `agents apply` has a divergent source of truth from the build validator (src/lib/actions/sandbox/agents/apply.ts:320): The build-time generator is documented as the structured validation source of truth, but live apply uses a separate subset validator and then mutates the sandbox while merely warning about full-schema fields such as tools, models, subagents, defaults, and main overrides. This duplication can drift and already produces partial application for security-relevant fields.
    • Recommendation: Make the invalid state impossible at the live source boundary: either reuse/export a common manifest validator and refuse mutation when rebuild-only config is present, or clearly split roster-only manifests from build manifests. Add a test proving live apply rejects full-manifest fields it cannot safely apply before any mutation.
    • Evidence: `runAgentsApply()` calls `loadAgentsManifest()`, `validateAgentsManifestForApply()`, and `buildAgentsApplyDiff()` instead of the build-time validator. `validateAgentsManifestForApply()` checks ids/paths/unknown agent keys only; `findRebuildOnlyFields()` reports other fields as warnings.
  • Hermes command reference advertises the OpenClaw-only `--agents` flag (docs/reference/commands-nemohermes.mdx:82): The implementation rejects `--agents` when `--agent hermes` is selected and live `agents apply` rejects non-OpenClaw sandboxes, but the Hermes command reference lists `nemohermes onboard ... [--agents <agents.yaml>]` and compatibility aliases with the same flag. That sends Hermes users toward a path whose semantics are explicitly OpenClaw-only.
    • Recommendation: Remove `--agents` from the Hermes generated reference, or implement and document Hermes-specific manifest semantics. Add or keep a parity test that the Hermes docs and visible command surface do not list OpenClaw-only flags or subcommands.
    • Evidence: `parseOnboardArgs()` rejects `--agents` when `!isOpenclawAgent(agent)`, and `runAgentsApply()` exits for non-OpenClaw sandbox agents. The Hermes docs diff adds `[--agents <agents.yaml>]` to `nemohermes onboard`, `setup`, and `setup-spark`.
  • Security-sensitive delegation coverage mirrors OpenClaw with TypeScript disabled (test/agents-manifest-policy-conformance.test.ts:1): The delegation-policy conformance test locally copies OpenClaw's `resolveSubagentTargetPolicy` behavior instead of exercising the runtime implementation, and starts with `// @ts-nocheck`. The focused config-generator manifest test also uses `// @ts-nocheck`. These tests cover security-sensitive delegation and config shape, so type-shape drift or upstream OpenClaw policy drift can be missed.
    • Recommendation: Remove `@ts-nocheck` and type the helpers narrowly. Add or identify runtime/integration coverage that bakes a manifest and exercises real OpenClaw `sessions_spawn` behavior for allowed targets, omitted targets, unknown targets, and `allowAgents: ["*"]`.
    • Evidence: `test/agents-manifest-policy-conformance.test.ts` starts with `// @ts-nocheck` and states it is a local copy of OpenClaw's `resolveSubagentTargetPolicy`; `test/generate-openclaw-config-agents-manifest.test.ts` also starts with `// @ts-nocheck`.
  • New `agents apply` test file exceeds the current monolith-growth budget (src/lib/actions/sandbox/agents/apply.test.ts:1): The PR adds a new 421-line focused test file, and the repository drift budget flags this as a current monolith growth hotspot. The cases are useful, but the file combines diff computation, manifest validation, CLI mutation orchestration, and confirmation behavior.
    • Recommendation: Split the test into smaller files by responsibility, for example diff/validation helpers vs. `runAgentsApply()` orchestration, or otherwise offset the growth in the test-size budget before merge.
    • Evidence: Drift context reports `src/lib/actions/sandbox/agents/apply.test.ts` with baseLines 0, headLines 421, delta 421, severity `blocker` for current monolith growth.
  • Legacy bare-array manifest compatibility lacks a removal or permanence story (scripts/generate-openclaw-config.mts:792): The generator accepts both the new `{agents, defaults?, main?}` object shape and the older bare-array payload. That may be intentional compatibility, but the code only labels it as legacy and does not say whether it is permanent, temporary, or what condition allows removal.
    • Recommendation: Document whether bare-array compatibility is permanent. If it is temporary, add a short removal condition near the compatibility branch and keep a focused regression test for the legacy payload until that condition is met.
    • Evidence: `validateExtraAgents()` contains `// Legacy payload shape: bare array of secondary agents.` before accepting `Array.isArray(value)`.

Workflow run details

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/inference/declarative-agents-manifest.mdx (1)

148-155: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a bottom Next Steps section with related page links.

The page currently ends without the required terminal Next Steps section.
As per coding guidelines, “A ‘Next Steps’ section at the bottom links to related pages.”

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/inference/declarative-agents-manifest.mdx` around lines 148 - 155, Add a
"Next Steps" section at the end of the document (after the existing content that
ends at line 155) that links to related pages relevant to declarative agents and
the onboarding/manifest workflow. Follow the existing documentation guidelines
by including a terminal Next Steps section with links to related documentation
pages that would help users continue their workflow after understanding the
agent iteration concepts covered in this page.

Source: Coding guidelines

🧹 Nitpick comments (1)
docs/inference/declarative-agents-manifest.mdx (1)

120-120: ⚡ Quick win

Remove the colon from this section title.

Titles should not contain colons.
As per coding guidelines, “No colons in titles. Flag ‘Inference: Cloud and Local’ — should be ‘Cloud and Local Inference.’”

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/inference/declarative-agents-manifest.mdx` at line 120, The section
title "Example: Manager-Worker" at line 120 contains a colon, which violates the
documentation style guidelines that prohibit colons in titles. Remove the colon
from this section heading and restructure it if needed to maintain clarity, such
as changing it to "Manager-Worker Example" or "Example Manager-Worker".

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/inference/declarative-agents-manifest.mdx`:
- Around line 1-19: The frontmatter metadata in the
declarative-agents-manifest.mdx file is missing required fields that are part of
the documentation standards. Add the missing frontmatter keys `topics`, `tags`,
`difficulty`, `audience`, and `status` to the existing frontmatter section
(which currently contains title, description, keywords, content type, and skill
priority). These fields should be added alongside the existing metadata to
comply with the coding guidelines for documentation pages.

In `@scripts/generate-openclaw-config.mts`:
- Around line 627-642: The validateModelRef function accepts model references
with whitespace-only model portions (after the slash), such as `test-provider/
`, which should be rejected. Add a check to extract the model portion using
`raw.slice(slash + 1)` after validating the slash position, and reject the input
if this model portion is empty or contains only whitespace characters. This
ensures that both the provider and model components are substantive before
accepting the model reference.

In `@test/generate-openclaw-config.test.ts`:
- Around line 1184-1188: The legacy test-size budget for
generate-openclaw-config.test.ts is out of sync with the current file size.
Update the budget entry for generate-openclaw-config.test.ts in the
test-file-size-budget configuration from 1989 to 1984 to reflect the file's
current line count and satisfy the codebase-growth guardrail requirement that
legacy budgets ratchet down when tests shrink.

---

Outside diff comments:
In `@docs/inference/declarative-agents-manifest.mdx`:
- Around line 148-155: Add a "Next Steps" section at the end of the document
(after the existing content that ends at line 155) that links to related pages
relevant to declarative agents and the onboarding/manifest workflow. Follow the
existing documentation guidelines by including a terminal Next Steps section
with links to related documentation pages that would help users continue their
workflow after understanding the agent iteration concepts covered in this page.

---

Nitpick comments:
In `@docs/inference/declarative-agents-manifest.mdx`:
- Line 120: The section title "Example: Manager-Worker" at line 120 contains a
colon, which violates the documentation style guidelines that prohibit colons in
titles. Remove the colon from this section heading and restructure it if needed
to maintain clarity, such as changing it to "Manager-Worker Example" or "Example
Manager-Worker".
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6f58eea9-0e80-424c-816d-6dc5a9ccc48c

📥 Commits

Reviewing files that changed from the base of the PR and between f4f3c58 and 22d8ba0.

📒 Files selected for processing (11)
  • docs/index.yml
  • docs/inference/declarative-agents-manifest.mdx
  • scripts/generate-openclaw-config.mts
  • src/lib/onboard/agents-manifest.test.ts
  • src/lib/onboard/agents-manifest.ts
  • src/lib/onboard/command-support.ts
  • src/lib/onboard/dockerfile-patch-extra-agents.test.ts
  • src/lib/onboard/legacy-command.test.ts
  • src/lib/onboard/legacy-command.ts
  • test/generate-openclaw-config-agents-manifest.test.ts
  • test/generate-openclaw-config.test.ts

Comment thread docs/inference/declarative-agents-manifest.mdx
Comment thread scripts/generate-openclaw-config.mts
Comment thread test/generate-openclaw-config.test.ts
Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (1)
docs/inference/declarative-agents-manifest.mdx (1)

1-19: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the required docs frontmatter metadata fields.

Lines 4-18 still omit required keys for new docs pages: topics, tags, difficulty, audience, and status.

As per coding guidelines, frontmatter must include title, description, keywords, topics, tags, content type, difficulty, audience, and status fields.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/inference/declarative-agents-manifest.mdx` around lines 1 - 19, Add the
five missing required frontmatter fields to the YAML metadata block in
declarative-agents-manifest.mdx: topics, tags, difficulty, audience, and status.
These fields must be added to the frontmatter section (currently lines 1-18)
alongside the existing title, description, keywords, and content type fields to
comply with the documentation guidelines that require all new docs pages to
include these mandatory metadata fields.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@docs/inference/declarative-agents-manifest.mdx`:
- Around line 1-19: Add the five missing required frontmatter fields to the YAML
metadata block in declarative-agents-manifest.mdx: topics, tags, difficulty,
audience, and status. These fields must be added to the frontmatter section
(currently lines 1-18) alongside the existing title, description, keywords, and
content type fields to comply with the documentation guidelines that require all
new docs pages to include these mandatory metadata fields.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: dfff194e-e3ec-46c4-9f62-be45f9bd0a95

📥 Commits

Reviewing files that changed from the base of the PR and between 22d8ba0 and 576e74c.

📒 Files selected for processing (5)
  • ci/test-file-size-budget.json
  • docs/inference/declarative-agents-manifest.mdx
  • scripts/generate-openclaw-config.mts
  • src/lib/onboard/agents-manifest.ts
  • test/generate-openclaw-config-agents-manifest.test.ts
✅ Files skipped from review due to trivial changes (1)
  • ci/test-file-size-budget.json
🚧 Files skipped from review as they are similar to previous changes (2)
  • src/lib/onboard/agents-manifest.ts
  • scripts/generate-openclaw-config.mts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/commands-nemohermes.mdx`:
- Line 1485: Update the documentation to show required arguments for flags in
the command descriptions. Specifically, change `--agents` to `--agents
<agents.yaml>` in the flag lists at both line 1485 and line 1498 where the alias
command flags are documented. For consistency, also update other flags that
require values such as `--from <Dockerfile>` and `--name <sandbox>` to clearly
show their required argument placeholders in both locations.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e2b458c9-665d-4681-9a5c-e45826510285

📥 Commits

Reviewing files that changed from the base of the PR and between 9c4110f and 5017ed7.

📒 Files selected for processing (5)
  • docs/inference/declarative-agents-manifest.mdx
  • docs/reference/commands-nemohermes.mdx
  • src/lib/onboard/agents-manifest.test.ts
  • src/lib/onboard/agents-manifest.ts
  • test/agents-manifest-policy-conformance.test.ts
✅ Files skipped from review due to trivial changes (1)
  • docs/inference/declarative-agents-manifest.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
  • src/lib/onboard/agents-manifest.test.ts
  • src/lib/onboard/agents-manifest.ts

Comment thread docs/reference/commands-nemohermes.mdx Outdated
Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (2)
src/lib/actions/sandbox/agents/apply.test.ts (1)

82-193: ⚡ Quick win

Consider adding test coverage for the interactive-mode exit path.

The test suite covers the nonInteractive: true without --yes case (line 146-169, expects exit 1), but there's no test for the nonInteractive: false (or omitted) without --yes case that exits with code 2 (implementation line 244-246 in apply.ts).

Adding a test case for this path would improve coverage and document the expected exit-code differentiation behavior.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/actions/sandbox/agents/apply.test.ts` around lines 82 - 193, Add a
new test case to the runAgentsApply describe block that covers the
interactive-mode exit path. Create a test similar to the existing "refuses to
apply roster changes without --yes in non-interactive mode" test, but instead
set nonInteractive to false (or omit it entirely) while still not providing the
--yes flag. This test should verify that the exit function is called with code 2
to differentiate from the non-interactive mode behavior which exits with code 1.
This will complete coverage of both exit paths documented in the implementation
at lines 244-246 of apply.ts.
src/lib/actions/sandbox/agents/apply.ts (1)

240-247: ⚡ Quick win

Clarify interactive mode behavior and exit code semantics.

The implementation exits with code 2 when !yes && !nonInteractive, but it doesn't actually prompt the user interactively. The help text in the command file (line 32) says --yes confirms "without an interactive prompt," implying that without --yes there would BE a prompt.

Current behavior:

  • --yes → proceed
  • --yes missing + --non-interactive → exit 1
  • --yes missing + no --non-interactive → exit 2 (but no prompt)

Either implement an interactive prompt for the exit-2 path, or update the help text to clarify that --yes is currently required in all cases (with different exit codes allowing automation to distinguish the contexts).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/actions/sandbox/agents/apply.ts` around lines 240 - 247, The code
exits with different codes based on the nonInteractive flag, but the
`!options.yes && !options.nonInteractive` case does not actually prompt the user
for confirmation as the help text suggests it should. Either implement an
interactive prompt (for example, using a library like inquirer or a built-in
prompt mechanism) in the branch where `!options.yes && !options.nonInteractive`
to ask the user to confirm the roster changes before proceeding, or update the
help text in the command file (line 32) to clarify that the `--yes` flag is
required in all cases with different exit codes distinguishing between
interactive and non-interactive contexts. Choose one approach and ensure the
behavior matches the documented expectations.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/commands.mdx`:
- Line 1257: The rebuild guidance command on line 1257 uses the literal
`nemoclaw onboard` command instead of the shared placeholder `$$nemoclaw`.
Replace the literal `nemoclaw` command name with the `$$nemoclaw` placeholder to
maintain consistency with other CLI command examples on this shared reference
page, so the line reads `$$nemoclaw onboard --agents <file> --recreate-sandbox`.
- Around line 1253-1263: The command heading and examples in the documentation
for the agents apply command show incorrect syntax that does not match the
actual CLI implementation. Update the heading from `$$nemoclaw <name> agents
apply` to `$$nemoclaw sandbox agents apply <name>`, and update all command
examples below it to use the correct syntax order: `$$nemoclaw sandbox agents
apply <name>` followed by the flags, instead of the currently documented
`$$nemoclaw <name> agents apply` pattern. This ensures the documentation
accurately reflects the actual CLI routing and passes parity checks.

---

Nitpick comments:
In `@src/lib/actions/sandbox/agents/apply.test.ts`:
- Around line 82-193: Add a new test case to the runAgentsApply describe block
that covers the interactive-mode exit path. Create a test similar to the
existing "refuses to apply roster changes without --yes in non-interactive mode"
test, but instead set nonInteractive to false (or omit it entirely) while still
not providing the --yes flag. This test should verify that the exit function is
called with code 2 to differentiate from the non-interactive mode behavior which
exits with code 1. This will complete coverage of both exit paths documented in
the implementation at lines 244-246 of apply.ts.

In `@src/lib/actions/sandbox/agents/apply.ts`:
- Around line 240-247: The code exits with different codes based on the
nonInteractive flag, but the `!options.yes && !options.nonInteractive` case does
not actually prompt the user for confirmation as the help text suggests it
should. Either implement an interactive prompt (for example, using a library
like inquirer or a built-in prompt mechanism) in the branch where `!options.yes
&& !options.nonInteractive` to ask the user to confirm the roster changes before
proceeding, or update the help text in the command file (line 32) to clarify
that the `--yes` flag is required in all cases with different exit codes
distinguishing between interactive and non-interactive contexts. Choose one
approach and ensure the behavior matches the documented expectations.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9e59dff5-1866-445b-b8f9-1443006f8bd2

📥 Commits

Reviewing files that changed from the base of the PR and between 9c4110f and 222486f.

📒 Files selected for processing (11)
  • docs/inference/declarative-agents-manifest.mdx
  • docs/reference/commands-nemohermes.mdx
  • docs/reference/commands.mdx
  • src/commands/sandbox/agents.ts
  • src/commands/sandbox/agents/apply.ts
  • src/lib/actions/sandbox/agents/apply.test.ts
  • src/lib/actions/sandbox/agents/apply.ts
  • src/lib/actions/sandbox/agents/passthrough.ts
  • src/lib/onboard/agents-manifest.test.ts
  • src/lib/onboard/agents-manifest.ts
  • test/agents-manifest-policy-conformance.test.ts
✅ Files skipped from review due to trivial changes (2)
  • src/commands/sandbox/agents.ts
  • docs/inference/declarative-agents-manifest.mdx
🚧 Files skipped from review as they are similar to previous changes (3)
  • src/lib/onboard/agents-manifest.test.ts
  • src/lib/onboard/agents-manifest.ts
  • test/agents-manifest-policy-conformance.test.ts

Comment thread docs/reference/commands.mdx
Comment thread docs/reference/commands.mdx Outdated
@cv
cv merged commit 01e5525 into main Jun 17, 2026
42 checks passed
@cv
cv deleted the feat/agents-manifest branch June 17, 2026 07:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature PR adds or expands user-visible functionality integration: openclaw OpenClaw integration behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Declarative multi-agent manifest for NemoClaw-managed sandboxes

4 participants