refactor(cli): group inference helpers

.coderabbit.yaml

@@ -251,7 +251,7 @@ reviews:
         gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=snapshot-commands-e2e,rebuild-openclaw-e2e
         ```
 
-    - path: "src/lib/shields*.ts"
+    - path: "src/lib/shields/**"
       instructions: |
         These files control shields down/up, config mutability, audit
         trail, and auto-restore timer.

bin/lib/agent-defs.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-defs.ts,
-// compiled to dist/lib/agent-defs.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/defs.ts,
+// compiled to dist/lib/agent/defs.js.
 
-module.exports = require("../../dist/lib/agent-defs");
+module.exports = require("../../dist/lib/agent/defs");

bin/lib/agent-onboard.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-onboard.ts,
-// compiled to dist/lib/agent-onboard.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/onboard.ts,
+// compiled to dist/lib/agent/onboard.js.
 
-module.exports = require("../../dist/lib/agent-onboard");
+module.exports = require("../../dist/lib/agent/onboard");

bin/lib/agent-runtime.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/agent-runtime.ts,
-// compiled to dist/lib/agent-runtime.js.
+// Thin re-export shim — the implementation lives in src/lib/agent/runtime.ts,
+// compiled to dist/lib/agent/runtime.js.
 
-module.exports = require("../../dist/lib/agent-runtime");
+module.exports = require("../../dist/lib/agent/runtime");

bin/lib/credentials.js

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 //
-// Thin re-export shim — the implementation lives in src/lib/credentials.ts,
-// compiled to dist/lib/credentials.js.
+// Thin re-export shim — the implementation lives in src/lib/credentials/store.ts,
+// compiled to dist/lib/credentials/store.js.
 
-const mod = require("../../dist/lib/credentials");
+const mod = require("../../dist/lib/credentials/store");
 
 const exports_ = { ...mod };
 

bin/lib/ports.js

@@ -5,4 +5,4 @@
 // Override any port via environment variables.
 // Based on the approach from jnun (PR #683).
 
-module.exports = require("../../dist/lib/ports");
+module.exports = require("../../dist/lib/core/ports");

scripts/check-legacy-migrated-paths.ts

@@ -26,10 +26,10 @@ const RUNTIME_MOVES: Record<string, string> = moveMap.runtimeMoves;
 const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/chat-filter.js": "src/lib/chat-filter.ts",
   "bin/lib/config-io.js": "src/lib/state/config-io.ts",
-  "bin/lib/debug.js": "src/lib/debug.ts",
-  "bin/lib/inference-config.js": "src/lib/inference-config.ts",
-  "bin/lib/local-inference.js": "src/lib/local-inference.ts",
-  "bin/lib/nim.js": "src/lib/nim.ts",
+  "bin/lib/debug.js": "src/lib/diagnostics/debug.ts",
+  "bin/lib/inference-config.js": "src/lib/inference/config.ts",
+  "bin/lib/local-inference.js": "src/lib/inference/local.ts",
+  "bin/lib/nim.js": "src/lib/inference/nim.ts",
   "bin/lib/onboard-session.js": "src/lib/onboard-session.ts",
   "bin/lib/platform.js": "src/lib/platform.ts",
   "bin/lib/preflight.js": "src/lib/preflight.ts",
@@ -38,7 +38,7 @@ const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/runtime-recovery.js": "src/lib/runtime-recovery.ts",
   "bin/lib/sandbox-build-context.js": "src/lib/sandbox-build-context.ts",
   "bin/lib/services.js": "src/lib/services.ts",
-  "bin/lib/version.js": "src/lib/version.ts",
+  "bin/lib/version.js": "src/lib/core/version.ts",
   "bin/lib/onboard.js": "src/lib/onboard.ts",
   "bin/lib/policies.js": "src/lib/policies.ts",
   "bin/lib/runner.js": "src/lib/runner.ts",

scripts/dev-tier-selector.js

@@ -18,7 +18,7 @@
 const readline = require("readline");
 
 // ── Stubs ──────────────────────────────────────────────────────────────────
-const creds = require("../dist/lib/credentials.js");
+const creds = require("../dist/lib/credentials/store.js");
 const runner = require("../dist/lib/runner.js");
 const registry = require("../dist/lib/state/registry.js");
 

scripts/generate-openclaw-config.py

@@ -69,7 +69,7 @@ def _coerce_positive_int(env: dict, name: str, default: int) -> int:
 def is_loopback(hostname: str) -> bool:
     """Check if a hostname is a loopback address.
 
-    Mirrors isLoopbackHostname() from src/lib/url-utils.ts.
+    Mirrors isLoopbackHostname() from src/lib/core/url-utils.ts.
     Returns True for localhost, ::1, and 127.x.x.x addresses.
     """
     normalized = (hostname or "").strip().lower().strip("[]")

scripts/ts-migration-assist.ts

@@ -22,13 +22,13 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
   "bin/lib/onboard.js": [
     ['require("./runner")', 'require("../../bin/lib/runner")'],
     ['require("./sandbox-build-context")', 'require("../../bin/lib/sandbox-build-context")'],
-    ['require("./local-inference")', 'require("../../bin/lib/local-inference")'],
-    ['require("./inference-config")', 'require("../../bin/lib/inference-config")'],
+    ['require("./inference/local")', 'require("../../bin/lib/local-inference")'],
+    ['require("./inference/config")', 'require("../../bin/lib/inference-config")'],
     ['require("./platform")', 'require("../../bin/lib/platform")'],
     ['require("./resolve-openshell")', 'require("../../bin/lib/resolve-openshell")'],
-    ['require("./credentials")', 'require("../../bin/lib/credentials")'],
+    ['require("./credentials/store")', 'require("../../bin/lib/credentials")'],
     ['require("./state/registry")', 'require("../../bin/lib/registry")'],
-    ['require("./nim")', 'require("../../bin/lib/nim")'],
+    ['require("./inference/nim")', 'require("../../bin/lib/nim")'],
     ['require("./onboard-session")', 'require("../../bin/lib/onboard-session")'],
     ['require("./policies")', 'require("../../bin/lib/policies")'],
     ['require("./usage-notice")', 'require("../../bin/lib/usage-notice")'],
@@ -42,15 +42,15 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
     ['require("./lib/registry")', 'require("../bin/lib/registry")'],
     ['require("./lib/nim")', 'require("../bin/lib/nim")'],
     ['require("./lib/policies")', 'require("../bin/lib/policies")'],
-    ['require("./lib/inference-config")', 'require("../bin/lib/inference-config")'],
+    ['require("./lib/inference/config")', 'require("../bin/lib/inference-config")'],
     ['require("./lib/version")', 'require("../bin/lib/version")'],
     ['require("./lib/onboard-session")', 'require("../bin/lib/onboard-session")'],
     ['require("./lib/runtime-recovery")', 'require("../bin/lib/runtime-recovery")'],
     ['require("./lib/usage-notice")', 'require("../bin/lib/usage-notice")'],
     ['require("./lib/services")', 'require("../bin/lib/services")'],
-    ['require("./lib/debug")', 'require("../bin/lib/debug")'],
-    ['require("./lib/debug-command")', 'require("./lib/debug-command")'],
-    ['require("../dist/lib/debug-command")', 'require("./lib/debug-command")'],
+    ['require("./lib/debug")', 'require("./lib/diagnostics/debug")'],
+    ['require("./lib/debug-command")', 'require("./lib/diagnostics/debug-command")'],
+    ['require("../dist/lib/debug-command")', 'require("./lib/diagnostics/debug-command")'],
     ['require("../dist/lib/openshell")', 'require("./lib/openshell")'],
     ['require("../dist/lib/inventory-commands")', 'require("./lib/inventory-commands")'],
     ['require("../dist/lib/deploy")', 'require("./lib/deploy")'],

src/lib/README.md

@@ -0,0 +1,57 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# `src/lib` layout
+
+`src/lib` is organized by architectural role first, then by product area. Use this map when adding new code or when moving legacy flat modules into clearer homes.
+
+## Primary layers
+
+```text
+src/lib/commands/**  oclif adapter classes and parser glue
+src/lib/actions/**   workflow orchestration and user-facing command behavior
+src/lib/domain/**    pure decisions, policy, classification, and planning
+src/lib/adapters/**  host boundaries: process, fs, Docker, OpenShell, HTTP
+src/lib/state/**     persisted local state and state-file I/O
+src/lib/cli/**       CLI framework, metadata, routing, and help infrastructure
+src/lib/core/**      tiny cross-cutting primitives with minimal dependencies
+```
+
+Layering rules:
+
+- Command classes should parse argv and call actions; they should not own product logic.
+- Actions may compose domain helpers, adapters, state modules, and output.
+- Domain helpers should stay pure and avoid direct process, filesystem, Docker, OpenShell, or network calls.
+- Adapters isolate host-boundary calls so actions and tests can inject fakes.
+- State modules own persisted local files and registry/session I/O.
+
+## Transitional feature folders
+
+Some older modules are still too large or coupled to split directly into actions/domain/adapters. Use these feature folders as intermediate homes while preserving behavior:
+
+```text
+src/lib/agent/**        agent definition, agent-specific onboarding, runtime helpers
+src/lib/credentials/**  credential storage and credential command support
+src/lib/dashboard/**    dashboard contract, health, and recovery helpers
+src/lib/deploy/**       deploy/build-image support that is not yet action-shaped
+src/lib/diagnostics/**  debug collection and diagnostic report helpers
+src/lib/inference/**    inference config, health probes, local runtime helpers
+src/lib/messaging/**    channel/messaging policy and message filtering helpers
+src/lib/onboard/**      onboarding support modules around the large legacy flow
+src/lib/policy/**       policy preset loading and application support
+src/lib/runtime/**      sandbox/runtime recovery helpers
+src/lib/sandbox/**      sandbox config, build, stream, and version support
+src/lib/security/**     redaction, secret patterns, and credential filtering
+src/lib/shields/**      shields orchestration, timers, and audit helpers
+src/lib/tunnel/**       local service/tunnel command support
+```
+
+Prefer small mechanical PRs that move one cluster at a time. High-import legacy files such as `onboard.ts`, `runner.ts`, `policies.ts`, `nim.ts`, and `services.ts` should either move late or keep temporary compatibility re-export files at their old paths.
+
+## Suggested migration sequence
+
+1. Document the target map and conventions before moving more code.
+2. Move low-risk feature clusters such as `agent`, `dashboard`, `diagnostics`, and `shields`.
+3. Move security/credentials/core helpers.
+4. Move inference/model/local-runtime helpers.
+5. Move onboarding support files before considering the large `onboard.ts` flow.

src/lib/actions/deploy.ts

@@ -3,7 +3,7 @@
 
 import { execFileSync, spawnSync } from "node:child_process";
 
-import { getCredential } from "../credentials";
+import { getCredential } from "../credentials/store";
 import { executeDeploy } from "../deploy";
 import { ROOT, run, runInteractive, shellQuote, validateName } from "../runner";
 

src/lib/actions/maintenance.ts

@@ -3,7 +3,7 @@
 
 /* v8 ignore start -- exercised through CLI subprocess maintenance tests. */
 
-import { prompt as askPrompt } from "../credentials";
+import { prompt as askPrompt } from "../credentials/store";
 import {
   type GarbageCollectImagesOptions,
   normalizeGarbageCollectImagesOptions,

src/lib/actions/onboard.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { listAgents } from "../agent-defs";
+import { listAgents } from "../agent/defs";
 import { runDeprecatedOnboardAliasCommand, runOnboardCommand } from "../onboard-command";
 import { NOTICE_ACCEPT_ENV, NOTICE_ACCEPT_FLAG } from "../usage-notice";
 

src/lib/actions/root-help.ts

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { AGENT_PRODUCT_NAME, CLI_DISPLAY_NAME, CLI_NAME } from "../branding";
-import { commandsByGroup, visibleCommands, type CommandDef } from "../command-registry";
+import { AGENT_PRODUCT_NAME, CLI_DISPLAY_NAME, CLI_NAME } from "../cli/branding";
+import { commandsByGroup, visibleCommands, type CommandDef } from "../cli/command-registry";
 import { getRegisteredOclifCommandSummary } from "../cli/oclif-metadata";
-import { getVersion } from "../version";
+import { getVersion } from "../core/version";
 
 const useColor = !process.env.NO_COLOR && !!process.stdout.isTTY;
 const trueColor =

src/lib/actions/sandbox/connect.ts

@@ -6,9 +6,9 @@
 import { spawnSync } from "node:child_process";
 import os from "node:os";
 
-import { CLI_NAME } from "../../branding";
-import { parseGatewayInference } from "../../inference-config";
-import { ensureOllamaAuthProxy } from "../../onboard-ollama-proxy";
+import { CLI_NAME } from "../../cli/branding";
+import { parseGatewayInference } from "../../inference/config";
+import { ensureOllamaAuthProxy } from "../../inference/ollama/proxy";
 import {
   captureOpenshell,
   getOpenshellBinary,
@@ -24,7 +24,7 @@ import {
 } from "../../state/sandbox-session";
 import { checkAndRecoverSandboxProcesses } from "./process-recovery";
 import * as sandboxVersion from "../../sandbox-version";
-import { D, G, R, YW } from "../../terminal-style";
+import { D, G, R, YW } from "../../cli/terminal-style";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 
 const agentRuntime = require("../../../../bin/lib/agent-runtime");

src/lib/actions/sandbox/destroy.ts

@@ -5,16 +5,16 @@
 
 import fs from "node:fs";
 
-import { CLI_NAME } from "../../branding";
-import { prompt as askPrompt } from "../../credentials";
+import { CLI_NAME } from "../../cli/branding";
+import { prompt as askPrompt } from "../../credentials/store";
 import {
   type DestroySandboxOptions,
   normalizeDestroySandboxOptions,
 } from "../../domain/lifecycle/options";
 import * as onboardSession from "../../onboard-session";
 import type { Session } from "../../onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import { DASHBOARD_PORT } from "../../ports";
+import { DASHBOARD_PORT } from "../../core/ports";
 import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
@@ -27,7 +27,7 @@ import {
   shouldCleanupGatewayAfterDestroy,
   shouldStopHostServicesAfterDestroy,
 } from "../../domain/sandbox/destroy";
-import { G, R, YW } from "../../terminal-style";
+import { G, R, YW } from "../../cli/terminal-style";
 
 type DockerRmi = (tag: string, opts?: { ignoreError?: boolean }) => { status: number | null };
 
@@ -90,7 +90,7 @@ function cleanupSandboxServices(
 
   const sb = registry.getSandbox(sandboxName);
   if (sb?.provider?.includes("ollama")) {
-    const { unloadOllamaModels } = require("../../onboard-ollama-proxy");
+    const { unloadOllamaModels } = require("../../inference/ollama/proxy");
     unloadOllamaModels();
   }
 
@@ -187,7 +187,7 @@ export async function destroySandbox(
     }
   }
 
-  const nim = require("../../nim") as {
+  const nim = require("../../inference/nim") as {
     stopNimContainer: (sandboxName: string, opts?: { silent?: boolean }) => void;
     stopNimContainerByName: (name: string) => void;
   };
@@ -203,7 +203,7 @@ export async function destroySandbox(
   }
 
   if (sb?.provider?.includes("ollama")) {
-    const { unloadOllamaModels, killStaleProxy } = require("../../onboard-ollama-proxy");
+    const { unloadOllamaModels, killStaleProxy } = require("../../inference/ollama/proxy");
     unloadOllamaModels();
     killStaleProxy();
   }

src/lib/actions/sandbox/doctor.ts

@@ -7,15 +7,15 @@ import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { isErrnoException } from "../../errno";
+import { CLI_DISPLAY_NAME, CLI_NAME } from "../../cli/branding";
+import { isErrnoException } from "../../core/errno";
 import { recoverNamedGatewayRuntime } from "../../gateway-runtime-action";
-import { probeProviderHealth } from "../../inference-health";
-import { parseGatewayInference } from "../../inference-config";
+import { probeProviderHealth } from "../../inference/health";
+import { parseGatewayInference } from "../../inference/config";
 import { stripAnsi } from "../../adapters/openshell/client";
 import { captureOpenshell } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import { GATEWAY_PORT, OLLAMA_PORT } from "../../ports";
+import { GATEWAY_PORT, OLLAMA_PORT } from "../../core/ports";
 import * as registry from "../../state/registry";
 import type { SandboxEntry } from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
@@ -24,7 +24,7 @@ import { parseLiveSandboxNames } from "../../runtime-recovery";
 import * as sandboxVersion from "../../sandbox-version";
 import * as shields from "../../shields";
 import { buildStatusCommandDeps } from "../../status-command-deps";
-import { B, D, G, R, RD, YW } from "../../terminal-style";
+import { B, D, G, R, RD, YW } from "../../cli/terminal-style";
 
 const agentRuntime = require("../../../../bin/lib/agent-runtime");
 

src/lib/actions/sandbox/gateway-state.ts

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
+import { CLI_DISPLAY_NAME, CLI_NAME } from "../../cli/branding";
 import { parseSandboxPhase } from "../../state/gateway";
 import {
   getNamedGatewayLifecycleState,

src/lib/actions/sandbox/policy-channel.ts

@@ -6,9 +6,9 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { hashCredential } from "../../credential-hash";
-import { getCredential, prompt as askPrompt } from "../../credentials";
+import { CLI_DISPLAY_NAME, CLI_NAME } from "../../cli/branding";
+import { hashCredential } from "../../security/credential-hash";
+import { getCredential, prompt as askPrompt } from "../../credentials/store";
 import { recoverNamedGatewayRuntime } from "../../gateway-runtime-action";
 const { isNonInteractive } = require("../../onboard") as { isNonInteractive: () => boolean };
 const onboardProviders = require("../../onboard-providers");

src/lib/actions/sandbox/process-recovery.ts

@@ -8,7 +8,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { DASHBOARD_PORT } from "../../ports";
+import { DASHBOARD_PORT } from "../../core/ports";
 import { ROOT, shellQuote } from "../../runner";
 import {
   captureOpenshell,
@@ -19,8 +19,8 @@ import {
 } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
 import { parseForwardList } from "../../state/sandbox-session";
-import { G, R } from "../../terminal-style";
-import { sleepSeconds } from "../../wait";
+import { G, R } from "../../cli/terminal-style";
+import { sleepSeconds } from "../../core/wait";
 
 const agentRuntime = require("../../../../bin/lib/agent-runtime");