fix(codex-supervisor): ship CLI metadata entry (#102803)

steipete-oai · steipete · web-flow · commit 745b8c315eaa · 2026-07-09T10:31:47.000-07:00
* fix(codex-supervisor): ship CLI metadata entry

* chore: keep release notes in PR body

---------

Co-authored-by: Peter Steinberger &lt;peter@steipete.me&gt;
diff --git a/extensions/codex-supervisor/cli-metadata.test.ts b/extensions/codex-supervisor/cli-metadata.test.ts
@@ -0,0 +1,53 @@
+// Codex Supervisor tests cover lightweight CLI discovery and lazy registration.
+import { Command } from "commander";
+import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
+import { describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  registerCodexSupervisorCli: vi.fn(),
+}));
+
+vi.mock("./src/cli.js", () => ({
+  registerCodexSupervisorCli: mocks.registerCodexSupervisorCli,
+}));
+
+import entry from "./cli-metadata.js";
+
+describe("codex-supervisor CLI metadata entry", () => {
+  it("advertises codex and loads its registrar only when invoked", async () => {
+    const registerCli = vi.fn();
+    const api = createTestPluginApi({
+      id: "codex-supervisor",
+      name: "Codex Supervisor",
+      registerCli,
+    });
+
+    entry.register(api);
+
+    expect(registerCli).toHaveBeenCalledWith(expect.any(Function), {
+      descriptors: [
+        {
+          name: "codex",
+          description: "Inspect Codex sessions across the Gateway and paired nodes",
+          hasSubcommands: true,
+        },
+      ],
+    });
+    expect(mocks.registerCodexSupervisorCli).not.toHaveBeenCalled();
+
+    const registrar = registerCli.mock.calls[0]?.[0];
+    if (typeof registrar !== "function") {
+      throw new Error("expected codex-supervisor CLI registrar");
+    }
+    const program = new Command();
+    await registrar({
+      program,
+      parentPath: [],
+      config: {},
+      workspaceDir: undefined,
+      logger: api.logger,
+    });
+
+    expect(mocks.registerCodexSupervisorCli).toHaveBeenCalledWith(program);
+  });
+});
diff --git a/extensions/codex-supervisor/cli-metadata.ts b/extensions/codex-supervisor/cli-metadata.ts
@@ -0,0 +1,27 @@
+// Codex Supervisor CLI metadata stays lightweight until the command runs.
+import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+
+export function registerCodexSupervisorCliMetadata(api: OpenClawPluginApi): void {
+  api.registerCli(
+    async ({ program }) => {
+      const { registerCodexSupervisorCli } = await import("./src/cli.js");
+      registerCodexSupervisorCli(program);
+    },
+    {
+      descriptors: [
+        {
+          name: "codex",
+          description: "Inspect Codex sessions across the Gateway and paired nodes",
+          hasSubcommands: true,
+        },
+      ],
+    },
+  );
+}
+
+export default definePluginEntry({
+  id: "codex-supervisor",
+  name: "Codex Supervisor",
+  description: "Supervise Codex app-server sessions from OpenClaw.",
+  register: registerCodexSupervisorCliMetadata,
+});
diff --git a/extensions/codex-supervisor/index.ts b/extensions/codex-supervisor/index.ts
@@ -3,7 +3,7 @@
  * OpenClaw agents.
  */
 import { buildJsonPluginConfigSchema, definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { registerCodexSupervisorCli } from "./src/cli.js";
+import { registerCodexSupervisorCliMetadata } from "./cli-metadata.js";
 import {
   CodexSupervisorPluginConfigSchema,
   resolveCodexSupervisorPluginConfig,
@@ -46,15 +46,7 @@ export default definePluginEntry({
       api.registerNodeInvokePolicy(policy);
     }
     registerCodexSessionCatalogGateway({ api, supervisor: catalogSupervisor });
-    api.registerCli(({ program }) => registerCodexSupervisorCli(program), {
-      descriptors: [
-        {
-          name: "codex",
-          description: "Inspect Codex sessions across the Gateway and paired nodes",
-          hasSubcommands: true,
-        },
-      ],
-    });
+    registerCodexSupervisorCliMetadata(api);
     for (const tool of createCodexSupervisorTools({
       supervisor,
       policy: {
diff --git a/extensions/codex-supervisor/openclaw.plugin.json b/extensions/codex-supervisor/openclaw.plugin.json
@@ -2,7 +2,8 @@
   "id": "codex-supervisor",
   "enabledByDefault": false,
   "activation": {
-    "onStartup": true
+    "onStartup": true,
+    "onCommands": ["codex"]
   },
   "name": "Codex Supervisor",
   "description": "Supervise Codex app-server sessions from OpenClaw.",
diff --git a/src/plugins/bundled-plugin-metadata.test.ts b/src/plugins/bundled-plugin-metadata.test.ts
@@ -579,6 +579,14 @@ describe("bundled plugin metadata", () => {
     expect(entry?.manifest.activation?.onCommands).toStrictEqual(["voicecall"]);
   });
 
+  it("scopes Codex Supervisor CLI activation to the codex command", () => {
+    const entry = listRepoBundledPluginManifests().find(
+      ({ manifest }) => manifest.id === "codex-supervisor",
+    );
+
+    expect(entry?.manifest.activation?.onCommands).toStrictEqual(["codex"]);
+  });
+
   it("keeps empty-config Gateway startup narrower than declared startup sidecars", () => {
     const manifestRegistry = createRepoBundledManifestRegistry();
     const index = createInstalledPluginIndexForManifests(manifestRegistry);
diff --git a/test/scripts/bundled-plugin-build-entries.test.ts b/test/scripts/bundled-plugin-build-entries.test.ts
@@ -68,6 +68,16 @@ describe("bundled plugin build entries", () => {
     expect(pickEntries(entries, Object.keys(expectedEntries))).toStrictEqual(expectedEntries);
   });
 
+  it("keeps Codex Supervisor CLI metadata in bundled build and pack entries", () => {
+    const entries = listBundledPluginBuildEntries();
+    const artifacts = listBundledPluginPackArtifacts();
+
+    expect(entries["extensions/codex-supervisor/cli-metadata"]).toBe(
+      "extensions/codex-supervisor/cli-metadata.ts",
+    );
+    expect(artifacts).toContain("dist/extensions/codex-supervisor/cli-metadata.js");
+  });
+
   it("filters bundled plugin build entries for bounded script lanes", () => {
     const entries = listBundledPluginBuildEntries({
       env: {
