refactor(cli): group sandbox actions

[cv]

Summary

Move sandbox-scoped workflow action modules into src/lib/actions/sandbox/** so command adapters and sandbox workflow orchestration have separate, visible layers.

Stack Navigation

• Position: 57 of 60
• Previous PR: #2986 — test(cli): enforce initial layer import boundaries
• Next PR: #2988 — refactor(cli): group global actions

Changes

• Moved sandbox connect/destroy/rebuild/status/logs/doctor/gateway-state/process-recovery/skill/snapshot actions under src/lib/actions/sandbox/.
• Moved sandbox policy/channel action helpers under src/lib/actions/sandbox/policy-channel.ts.
• Updated command adapters, runtime dispatch facade, tests, and remaining callers to the new paths.
• Kept behavior unchanged; this PR is a structural move plus import updates.

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 --stage pre-push passes
• npm run build:cli
• npm run typecheck:cli
• npx tsx scripts/check-layer-import-boundaries.ts
• Sandbox command adapter targeted tests pass
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make 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 [email protected]

Summary by CodeRabbit

• Bug Fixes
  • Enhanced sandbox cleanup during destruction to properly unload Ollama models, terminate proxy processes, and stop host services for complete resource cleanup.

[copy-pr-bot]

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]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR reorganizes sandbox action modules from a flat file structure to a nested directory layout under src/lib/actions/sandbox/, updating all corresponding import paths throughout the codebase and internal module dependencies to reflect the new structure. One new public re-export is added in policy-channel.ts. No functional logic changes.

Changes

Module Reorganization & Import Path Refactoring

Layer / File(s)	Summary
Core Action Module Restructuring src/lib/actions/sandbox/connect.ts, src/lib/actions/sandbox/destroy.ts, src/lib/actions/sandbox/doctor.ts, src/lib/actions/sandbox/gateway-state.ts, src/lib/actions/sandbox/logs.ts, src/lib/actions/sandbox/policy-channel.ts, src/lib/actions/sandbox/process-recovery.ts, src/lib/actions/sandbox/rebuild.ts, src/lib/actions/sandbox/skill-install.ts, src/lib/actions/sandbox/snapshot.ts, src/lib/actions/sandbox/status.ts	All action modules updated to use parent-relative paths (../../... or higher) for internal dependencies instead of local relative paths. Modules now import from centralized locations for branding, infrastructure adapters, session/state management, and utilities. policy-channel.ts additionally adds public re-exports of sandbox-channel utilities (KNOWN_CHANNELS, clearChannelTokens, getChannelDef, getChannelTokenKeys, knownChannelNames, persistChannelTokens).
Sandbox Runtime Facade src/lib/actions/sandbox/runtime.ts	Runtime facade refactored to route sandbox operations (connect/status/logs/destroy/rebuild/skill-install/snapshot) through locally-scoped modules via dynamic require statements; type imports adjusted to reference new module locations.
Command Layer Wiring src/lib/commands/sandbox/connect.ts, src/lib/commands/sandbox/destroy.ts, src/lib/commands/sandbox/logs.ts, src/lib/commands/sandbox/rebuild.ts, src/lib/commands/sandbox/status.ts, src/lib/commands/sandbox/doctor.ts, src/lib/commands/sandbox/skill/common.ts, src/lib/commands/sandbox/snapshot/common.ts, src/lib/commands/sandbox/channels/common.ts, src/lib/commands/sandbox/channels/list.ts, src/lib/commands/sandbox/policy/common.ts, src/lib/commands/sandbox/policy/list.ts	Import paths for sandbox action functions updated from flat names (e.g., sandbox-runtime-actions, policy-channel-actions) to nested structure (e.g., actions/sandbox/runtime, actions/sandbox/policy-channel).
Consumer Updates src/lib/share-command-deps.ts, src/lib/upgrade-sandboxes-action.ts, src/lib/recover-cli-command.ts, src/nemoclaw.ts, test/image-cleanup.test.ts, src/lib/commands/sandbox/oclif-command-adapters.test.ts	Top-level and test files updated to import from new action module paths; test mocks refactored to point to new centralized action modules.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#2984: Performs coordinated refactoring of sandbox domain helpers (logs, log-options, destroy utilities) and updates corresponding sandbox action imports to reference the new domain paths.

Suggested labels

v0.0.35

Suggested reviewers

• prekshivyas

Poem

🐰 Files hop to their tidy new home,
Imports dance through a structured tome,
Paths realign with methodical care—
No logic lost in the move through the air!
With channels exported and facade in place,
This refactor adds order and grace. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.32% 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 'refactor(cli): group sandbox actions' clearly and concisely describes the main structural change: moving and organizing sandbox-related action modules into a grouped directory structure.
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 refactor/layer-sandbox-actions

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/actions/sandbox/process-recovery.ts (1)

11-24: Run the restart-path E2Es before merge.

This module sits directly on the gateway restart/process recovery path, so I'd still validate the refactor with the nightly recovery scenarios; unit and CLI subprocess tests usually won't catch every runtime path-resolution regression in these flows.

As per coding guidelines, "E2E test recommendation: sandbox-survival-e2e — gateway restart recovery; sandbox-operations-e2e — process recovery after gateway kill".

🤖 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/process-recovery.ts` around lines 11 - 24, This
change touches the gateway restart/process-recovery path (module
process-recovery.ts, symbols like agentRuntime, runOpenshell, getOpenshellBinary
and captureOpenshell), so before merging run the recommended E2E suites to
validate runtime path resolution: execute sandbox-survival-e2e (gateway restart
recovery) and sandbox-operations-e2e (process recovery after gateway kill)
against the refactor and confirm the nightly recovery scenarios pass; if
failures appear, trace them to the imports/paths and runtime invocation patterns
in process-recovery.ts (agentRuntime usage, openshell adapter calls) and fix
path/resolution or invocation order until the E2Es pass.

🤖 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.

Nitpick comments:
In `@src/lib/actions/sandbox/process-recovery.ts`:
- Around line 11-24: This change touches the gateway restart/process-recovery
path (module process-recovery.ts, symbols like agentRuntime, runOpenshell,
getOpenshellBinary and captureOpenshell), so before merging run the recommended
E2E suites to validate runtime path resolution: execute sandbox-survival-e2e
(gateway restart recovery) and sandbox-operations-e2e (process recovery after
gateway kill) against the refactor and confirm the nightly recovery scenarios
pass; if failures appear, trace them to the imports/paths and runtime invocation
patterns in process-recovery.ts (agentRuntime usage, openshell adapter calls)
and fix path/resolution or invocation order until the E2Es pass.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 89b2684c-2eed-4da5-8b92-9be423d956f8

📥 Commits

Reviewing files that changed from the base of the PR and between 073225e and f25fcce.

📒 Files selected for processing (29)

• src/lib/actions/sandbox/connect.ts
• src/lib/actions/sandbox/destroy.ts
• src/lib/actions/sandbox/doctor.ts
• src/lib/actions/sandbox/gateway-state.ts
• src/lib/actions/sandbox/logs.ts
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/actions/sandbox/process-recovery.ts
• src/lib/actions/sandbox/rebuild.ts
• src/lib/actions/sandbox/runtime.ts
• src/lib/actions/sandbox/skill-install.ts
• src/lib/actions/sandbox/snapshot.ts
• src/lib/actions/sandbox/status.ts
• src/lib/commands/sandbox/channels/common.ts
• src/lib/commands/sandbox/channels/list.ts
• src/lib/commands/sandbox/connect.ts
• src/lib/commands/sandbox/destroy.ts
• src/lib/commands/sandbox/doctor.ts
• src/lib/commands/sandbox/logs.ts
• src/lib/commands/sandbox/oclif-command-adapters.test.ts
• src/lib/commands/sandbox/policy/common.ts
• src/lib/commands/sandbox/policy/list.ts
• src/lib/commands/sandbox/rebuild.ts
• src/lib/commands/sandbox/skill/common.ts
• src/lib/commands/sandbox/snapshot/common.ts
• src/lib/commands/sandbox/status.ts
• src/lib/share-command-deps.ts
• src/lib/upgrade-sandboxes-action.ts
• src/nemoclaw.ts
• test/image-cleanup.test.ts

[cv]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

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

[cjagwani]

approved