Plugins/CLI: add descriptor-backed lazy root command registration (#57165)

Merged via squash.

Prepared head SHA: ad1dee32eb
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/plugins/cli.ts

@@ -1,5 +1,7 @@
 import type { Command } from "commander";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { removeCommandByName } from "../cli/program/command-tree.js";
+import { registerLazyCommand } from "../cli/program/register-lazy-command.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { loadConfig } from "../config/config.js";
 import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
@@ -10,6 +12,24 @@ import type { PluginLogger } from "./types.js";
 
 const log = createSubsystemLogger("plugins");
 
+type PluginCliRegistrationMode = "eager" | "lazy";
+
+type RegisterPluginCliOptions = {
+  mode?: PluginCliRegistrationMode;
+  primary?: string | null;
+};
+
+function canRegisterPluginCliLazily(entry: {
+  commands: string[];
+  descriptors: OpenClawPluginCliCommandDescriptor[];
+}): boolean {
+  if (entry.descriptors.length === 0) {
+    return false;
+  }
+  const descriptorNames = new Set(entry.descriptors.map((descriptor) => descriptor.name));
+  return entry.commands.every((command) => descriptorNames.has(command));
+}
+
 function loadPluginCliRegistry(
   cfg?: OpenClawConfig,
   env?: NodeJS.ProcessEnv,
@@ -64,17 +84,40 @@ export function getPluginCliCommandDescriptors(
   }
 }
 
-export function registerPluginCliCommands(
+export async function registerPluginCliCommands(
   program: Command,
   cfg?: OpenClawConfig,
   env?: NodeJS.ProcessEnv,
   loaderOptions?: Pick<PluginLoadOptions, "pluginSdkResolution">,
+  options?: RegisterPluginCliOptions,
 ) {
   const { config, workspaceDir, logger, registry } = loadPluginCliRegistry(cfg, env, loaderOptions);
+  const mode = options?.mode ?? "eager";
+  const primary = options?.primary ?? null;
 
   const existingCommands = new Set(program.commands.map((cmd) => cmd.name()));
 
   for (const entry of registry.cliRegistrars) {
+    const registerEntry = async () => {
+      await entry.register({
+        program,
+        config,
+        workspaceDir,
+        logger,
+      });
+    };
+
+    if (primary && entry.commands.includes(primary)) {
+      for (const commandName of new Set(entry.commands)) {
+        removeCommandByName(program, commandName);
+      }
+      await registerEntry();
+      for (const command of entry.commands) {
+        existingCommands.add(command);
+      }
+      continue;
+    }
+
     if (entry.commands.length > 0) {
       const overlaps = entry.commands.filter((command) => existingCommands.has(command));
       if (overlaps.length > 0) {
@@ -86,17 +129,27 @@ export function registerPluginCliCommands(
         continue;
       }
     }
+
     try {
-      const result = entry.register({
-        program,
-        config,
-        workspaceDir,
-        logger,
-      });
-      if (result && typeof result.then === "function") {
-        void result.catch((err) => {
-          log.warn(`plugin CLI register failed (${entry.pluginId}): ${String(err)}`);
-        });
+      if (mode === "lazy" && canRegisterPluginCliLazily(entry)) {
+        for (const descriptor of entry.descriptors) {
+          registerLazyCommand({
+            program,
+            name: descriptor.name,
+            description: descriptor.description,
+            removeNames: entry.commands,
+            register: async () => {
+              await registerEntry();
+            },
+          });
+        }
+      } else {
+        if (mode === "lazy" && entry.descriptors.length > 0) {
+          log.debug(
+            `plugin CLI lazy register fallback to eager (${entry.pluginId}): descriptors do not cover all command roots`,
+          );
+        }
+        await registerEntry();
       }
       for (const command of entry.commands) {
         existingCommands.add(command);