@kodelyth/codex 2026.5.40 → 2026.5.42

package/doctor-contract-api.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { legacyConfigRules, normalizeCompatibilityConfig } from "./doctor-contract-api.js";
+
+describe("codex doctor contract", () => {
+  it("reports the retired dynamic tools profile config key", () => {
+    expect(
+      legacyConfigRules[0]?.match({
+        codexDynamicToolsProfile: "klaw-compat",
+        codexDynamicToolsLoading: "direct",
+      }),
+    ).toBe(true);
+    expect(legacyConfigRules[0]?.match({ codexDynamicToolsLoading: "direct" })).toBe(false);
+  });
+
+  it("removes the retired dynamic tools profile without dropping other Codex config", () => {
+    const original = {
+      plugins: {
+        entries: {
+          codex: {
+            enabled: true,
+            config: {
+              codexDynamicToolsProfile: "klaw-compat",
+              codexDynamicToolsLoading: "direct",
+              codexDynamicToolsExclude: ["custom_tool"],
+              appServer: { mode: "guardian" },
+            },
+          },
+        },
+      },
+    };
+
+    const result = normalizeCompatibilityConfig({ cfg: original });
+
+    expect(result.changes).toEqual([
+      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
+    ]);
+    expect(result.config.plugins?.entries?.codex?.config).toEqual({
+      codexDynamicToolsLoading: "direct",
+      codexDynamicToolsExclude: ["custom_tool"],
+      appServer: { mode: "guardian" },
+    });
+    expect(original.plugins.entries.codex.config).toHaveProperty("codexDynamicToolsProfile");
+  });
+});

package/doctor-contract-api.ts

@@ -0,0 +1,68 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { DoctorSessionRouteStateOwner } from "klaw/plugin-sdk/runtime-doctor";
+
+type LegacyConfigRule = {
+  path: string[];
+  message: string;
+  match: (value: unknown) => boolean;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function hasRetiredDynamicToolsProfile(value: unknown): boolean {
+  return Object.prototype.hasOwnProperty.call(asRecord(value) ?? {}, "codexDynamicToolsProfile");
+}
+
+export const legacyConfigRules: LegacyConfigRule[] = [
+  {
+    path: ["plugins", "entries", "codex", "config"],
+    message:
+      'plugins.entries.codex.config.codexDynamicToolsProfile is retired; Codex app-server always keeps Codex-native workspace tools native. Run "klaw doctor --fix".',
+    match: hasRetiredDynamicToolsProfile,
+  },
+];
+
+export function normalizeCompatibilityConfig({ cfg }: { cfg: KlawConfig }): {
+  config: KlawConfig;
+  changes: string[];
+} {
+  const rawEntry = asRecord(cfg.plugins?.entries?.codex);
+  const rawPluginConfig = asRecord(rawEntry?.config);
+  if (!rawPluginConfig || !hasRetiredDynamicToolsProfile(rawPluginConfig)) {
+    return { config: cfg, changes: [] };
+  }
+
+  const nextConfig = structuredClone(cfg) as KlawConfig & {
+    plugins?: Record<string, unknown>;
+  };
+  const nextPlugins = asRecord(nextConfig.plugins);
+  const nextEntries = asRecord(nextPlugins?.entries);
+  const nextEntry = asRecord(nextEntries?.codex);
+  const nextPluginConfig = asRecord(nextEntry?.config);
+  if (!nextPluginConfig) {
+    return { config: cfg, changes: [] };
+  }
+
+  delete nextPluginConfig.codexDynamicToolsProfile;
+  return {
+    config: nextConfig,
+    changes: [
+      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
+    ],
+  };
+}
+
+export const sessionRouteStateOwners: DoctorSessionRouteStateOwner[] = [
+  {
+    id: "codex",
+    label: "Codex",
+    providerIds: ["codex", "codex-cli", "openai-codex"],
+    runtimeIds: ["codex", "codex-cli"],
+    cliSessionKeys: ["codex-cli"],
+    authProfilePrefixes: ["codex:", "codex-cli:", "openai-codex:"],
+  },
+];

package/harness.ts

@@ -0,0 +1,72 @@
+import type { AgentHarness } from "klaw/plugin-sdk/agent-harness-runtime";
+import type {
+  CodexAppServerListModelsOptions,
+  CodexAppServerModel,
+  CodexAppServerModelListResult,
+} from "./src/app-server/models.js";
+
+const DEFAULT_CODEX_HARNESS_PROVIDER_IDS = new Set(["codex"]);
+
+export type { CodexAppServerListModelsOptions, CodexAppServerModel, CodexAppServerModelListResult };
+
+export function createCodexAppServerAgentHarness(options?: {
+  id?: string;
+  label?: string;
+  providerIds?: Iterable<string>;
+  pluginConfig?: unknown;
+  resolvePluginConfig?: () => unknown;
+}): AgentHarness {
+  const providerIds = new Set(
+    [...(options?.providerIds ?? DEFAULT_CODEX_HARNESS_PROVIDER_IDS)].map((id) =>
+      id.trim().toLowerCase(),
+    ),
+  );
+  return {
+    id: options?.id ?? "codex",
+    label: options?.label ?? "Codex agent harness",
+    deliveryDefaults: {
+      sourceVisibleReplies: "message_tool",
+    },
+    supports: (ctx) => {
+      const provider = ctx.provider.trim().toLowerCase();
+      if (providerIds.has(provider)) {
+        return { supported: true, priority: 100 };
+      }
+      return {
+        supported: false,
+        reason: `provider is not one of: ${[...providerIds].toSorted().join(", ")}`,
+      };
+    },
+    runAttempt: async (params) => {
+      const { runCodexAppServerAttempt } = await import("./src/app-server/run-attempt.js");
+      return runCodexAppServerAttempt(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+        nativeHookRelay: { enabled: true },
+      });
+    },
+    runSideQuestion: async (params) => {
+      const { runCodexAppServerSideQuestion } = await import("./src/app-server/side-question.js");
+      return runCodexAppServerSideQuestion(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+        nativeHookRelay: { enabled: true },
+      });
+    },
+    compact: async (params) => {
+      const { maybeCompactCodexAppServerSession } = await import("./src/app-server/compact.js");
+      return maybeCompactCodexAppServerSession(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+      });
+    },
+    reset: async (params) => {
+      if (params.sessionFile) {
+        const { clearCodexAppServerBinding } = await import("./src/app-server/session-binding.js");
+        await clearCodexAppServerBinding(params.sessionFile);
+      }
+    },
+    dispose: async () => {
+      const { clearSharedCodexAppServerClientAndWait } =
+        await import("./src/app-server/shared-client.js");
+      await clearSharedCodexAppServerClientAndWait();
+    },
+  };
+}

package/index.test.ts

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import { createTestPluginApi } from "klaw/plugin-sdk/plugin-test-api";
+import { describe, expect, it, vi } from "vitest";
+import { createCodexAppServerAgentHarness } from "./harness.js";
+import plugin from "./index.js";
+
+const runCodexAppServerAttemptMock = vi.hoisted(() => vi.fn());
+const runCodexAppServerSideQuestionMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./src/app-server/run-attempt.js", () => ({
+  runCodexAppServerAttempt: runCodexAppServerAttemptMock,
+}));
+vi.mock("./src/app-server/side-question.js", () => ({
+  runCodexAppServerSideQuestion: runCodexAppServerSideQuestionMock,
+}));
+
+function mockCall(mock: { mock: { calls: unknown[][] } }, index = 0) {
+  return mock.mock.calls.at(index);
+}
+
+function mockCallArg(mock: { mock: { calls: unknown[][] } }, index = 0, argIndex = 0) {
+  return mockCall(mock, index)?.at(argIndex);
+}
+
+describe("codex plugin", () => {
+  it("is opt-in by default", () => {
+    const manifest = JSON.parse(
+      fs.readFileSync(new URL("./klaw.plugin.json", import.meta.url), "utf8"),
+    ) as { enabledByDefault?: unknown };
+
+    expect(manifest.enabledByDefault).toBeUndefined();
+  });
+
+  it("registers the codex provider and agent harness", () => {
+    const registerAgentHarness = vi.fn();
+    const registerCommand = vi.fn();
+    const registerMediaUnderstandingProvider = vi.fn();
+    const registerMigrationProvider = vi.fn();
+    const registerProvider = vi.fn();
+    const on = vi.fn();
+    const onConversationBindingResolved = vi.fn();
+
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: {},
+        runtime: {} as never,
+        registerAgentHarness,
+        registerCommand,
+        registerMediaUnderstandingProvider,
+        registerMigrationProvider,
+        registerProvider,
+        on,
+        onConversationBindingResolved,
+      }),
+    );
+
+    const providerRegistration = mockCallArg(registerProvider) as Record<string, unknown>;
+    const agentHarnessRegistration = mockCallArg(registerAgentHarness) as Record<string, unknown>;
+    const mediaProviderRegistration = mockCallArg(registerMediaUnderstandingProvider) as
+      | Record<string, unknown>
+      | undefined;
+    const inboundClaimRegistration = mockCall(on) as [unknown, unknown] | undefined;
+    const bindingResolvedRegistration = mockCall(onConversationBindingResolved) as
+      | [unknown]
+      | undefined;
+
+    expect(providerRegistration.id).toBe("codex");
+    expect(providerRegistration.label).toBe("Codex");
+    expect(agentHarnessRegistration.id).toBe("codex");
+    expect(agentHarnessRegistration.label).toBe("Codex agent harness");
+    expect(agentHarnessRegistration.deliveryDefaults).toEqual({
+      sourceVisibleReplies: "message_tool",
+    });
+    expect(typeof agentHarnessRegistration.dispose).toBe("function");
+    expect(mediaProviderRegistration?.id).toBe("codex");
+    expect(mediaProviderRegistration?.capabilities).toEqual(["image"]);
+    expect(mediaProviderRegistration?.defaultModels).toEqual({ image: "gpt-5.5" });
+    expect(typeof mediaProviderRegistration?.describeImage).toBe("function");
+    expect(typeof mediaProviderRegistration?.describeImages).toBe("function");
+    const commandRegistration = mockCallArg(registerCommand) as Record<string, unknown> | undefined;
+    expect(commandRegistration?.name).toBe("codex");
+    expect(commandRegistration?.description).toBe(
+      "Inspect and control the Codex app-server harness",
+    );
+    const migrationRegistration = mockCallArg(registerMigrationProvider) as
+      | Record<string, unknown>
+      | undefined;
+    expect(migrationRegistration?.id).toBe("codex");
+    expect(migrationRegistration?.label).toBe("Codex");
+    expect(inboundClaimRegistration?.[0]).toBe("inbound_claim");
+    expect(typeof inboundClaimRegistration?.[1]).toBe("function");
+    expect(typeof bindingResolvedRegistration?.[0]).toBe("function");
+  });
+
+  it("registers with capture APIs that do not expose conversation binding hooks yet", () => {
+    const registerProvider = vi.fn();
+    const api = createTestPluginApi({
+      id: "codex",
+      name: "Codex",
+      source: "test",
+      config: {},
+      pluginConfig: {},
+      runtime: {} as never,
+      registerAgentHarness: vi.fn(),
+      registerCommand: vi.fn(),
+      registerMediaUnderstandingProvider: vi.fn(),
+      registerProvider,
+      on: vi.fn(),
+    });
+    delete (api as { onConversationBindingResolved?: unknown }).onConversationBindingResolved;
+
+    plugin.register(api);
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+    expect((mockCallArg(registerProvider) as { id?: string } | undefined)?.id).toBe("codex");
+  });
+
+  it("only claims the codex provider by default", () => {
+    const harness = createCodexAppServerAgentHarness();
+
+    expect(harness.deliveryDefaults?.sourceVisibleReplies).toBe("message_tool");
+    expect(
+      harness.supports({ provider: "codex", modelId: "gpt-5.4", requestedRuntime: "auto" })
+        .supported,
+    ).toBe(true);
+    const unsupported = harness.supports({
+      provider: "openai-codex",
+      modelId: "gpt-5.4",
+      requestedRuntime: "auto",
+    });
+    expect(unsupported.supported).toBe(false);
+  });
+
+  it("enables the native hook relay for public Codex app-server attempts", async () => {
+    const harness = createCodexAppServerAgentHarness({ pluginConfig: { appServer: {} } });
+    const result = { success: true };
+    runCodexAppServerAttemptMock.mockResolvedValueOnce(result);
+
+    await expect(harness.runAttempt({ prompt: "hello" } as never)).resolves.toBe(result);
+
+    expect(runCodexAppServerAttemptMock).toHaveBeenCalledWith(
+      { prompt: "hello" },
+      {
+        pluginConfig: { appServer: {} },
+        nativeHookRelay: { enabled: true },
+      },
+    );
+  });
+
+  it("passes live Codex plugin config into public Codex app-server attempts", async () => {
+    const registerAgentHarness = vi.fn();
+    const liveConfig = {
+      plugins: {
+        entries: {
+          codex: {
+            config: {
+              codexPlugins: {
+                enabled: true,
+                plugins: {
+                  "google-calendar": {
+                    marketplaceName: "openai-curated",
+                    pluginName: "google-calendar",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: { codexPlugins: { enabled: false } },
+        runtime: {
+          config: {
+            current: () => liveConfig,
+          },
+        } as never,
+        registerAgentHarness,
+        registerCommand: vi.fn(),
+        registerMediaUnderstandingProvider: vi.fn(),
+        registerMigrationProvider: vi.fn(),
+        registerProvider: vi.fn(),
+        on: vi.fn(),
+      }),
+    );
+    const harness = mockCallArg(registerAgentHarness) as ReturnType<
+      typeof createCodexAppServerAgentHarness
+    >;
+    const result = { success: true };
+    runCodexAppServerAttemptMock.mockResolvedValueOnce(result);
+
+    await expect(harness.runAttempt({ prompt: "calendar" } as never)).resolves.toBe(result);
+
+    expect(runCodexAppServerAttemptMock).toHaveBeenCalledWith(
+      { prompt: "calendar" },
+      {
+        pluginConfig: liveConfig.plugins.entries.codex.config,
+        nativeHookRelay: { enabled: true },
+      },
+    );
+  });
+
+  it("enables the native hook relay for public Codex side questions", async () => {
+    const harness = createCodexAppServerAgentHarness({ pluginConfig: { appServer: {} } });
+    const runSideQuestion = harness.runSideQuestion;
+    const result = { text: "ok" };
+    runCodexAppServerSideQuestionMock.mockResolvedValueOnce(result);
+
+    if (!runSideQuestion) {
+      throw new Error("Expected Codex harness to expose side questions");
+    }
+    await expect(runSideQuestion({ question: "btw" } as never)).resolves.toBe(result);
+
+    expect(runCodexAppServerSideQuestionMock).toHaveBeenCalledWith(
+      { question: "btw" },
+      {
+        pluginConfig: { appServer: {} },
+        nativeHookRelay: { enabled: true },
+      },
+    );
+  });
+});

package/index.ts

@@ -0,0 +1,66 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { resolveLivePluginConfigObject } from "klaw/plugin-sdk/plugin-config-runtime";
+import { definePluginEntry } from "klaw/plugin-sdk/plugin-entry";
+import { createCodexAppServerAgentHarness } from "./harness.js";
+import { buildCodexMediaUnderstandingProvider } from "./media-understanding-provider.js";
+import { buildCodexProvider } from "./provider.js";
+import { createCodexCommand } from "./src/commands.js";
+import {
+  handleCodexConversationBindingResolved,
+  handleCodexConversationInboundClaim,
+} from "./src/conversation-binding.js";
+import { buildCodexMigrationProvider } from "./src/migration/provider.js";
+import {
+  createCodexCliSessionNodeHostCommands,
+  createCodexCliSessionNodeInvokePolicies,
+  listCodexCliSessionsOnNode,
+  resumeCodexCliSessionOnNode,
+  resolveCodexCliSessionForBindingOnNode,
+} from "./src/node-cli-sessions.js";
+
+export default definePluginEntry({
+  id: "codex",
+  name: "Codex",
+  description: "Codex app-server harness and Codex-managed GPT model catalog.",
+  register(api) {
+    const resolveCurrentPluginConfig = () =>
+      resolveLivePluginConfigObject(
+        api.runtime.config?.current ? () => api.runtime.config.current() as KlawConfig : undefined,
+        "codex",
+        api.pluginConfig as Record<string, unknown>,
+      ) ?? api.pluginConfig;
+    api.registerAgentHarness(
+      createCodexAppServerAgentHarness({ resolvePluginConfig: resolveCurrentPluginConfig }),
+    );
+    api.registerProvider(buildCodexProvider({ pluginConfig: api.pluginConfig }));
+    api.registerMediaUnderstandingProvider(
+      buildCodexMediaUnderstandingProvider({ pluginConfig: api.pluginConfig }),
+    );
+    api.registerMigrationProvider(buildCodexMigrationProvider({ runtime: api.runtime }));
+    for (const command of createCodexCliSessionNodeHostCommands()) {
+      api.registerNodeHostCommand(command);
+    }
+    for (const policy of createCodexCliSessionNodeInvokePolicies()) {
+      api.registerNodeInvokePolicy(policy);
+    }
+    api.registerCommand(
+      createCodexCommand({
+        pluginConfig: api.pluginConfig,
+        deps: {
+          listCodexCliSessionsOnNode: (params) =>
+            listCodexCliSessionsOnNode({ runtime: api.runtime, ...params }),
+          resolveCodexCliSessionForBindingOnNode: (params) =>
+            resolveCodexCliSessionForBindingOnNode({ runtime: api.runtime, ...params }),
+        },
+      }),
+    );
+    api.on("inbound_claim", (event, ctx) =>
+      handleCodexConversationInboundClaim(event, ctx, {
+        pluginConfig: resolveCurrentPluginConfig(),
+        resumeCodexCliSessionOnNode: (params) =>
+          resumeCodexCliSessionOnNode({ runtime: api.runtime, ...params }),
+      }),
+    );
+    api.onConversationBindingResolved?.(handleCodexConversationBindingResolved);
+  },
+});

package/klaw.plugin.json

@@ -2,39 +2,25 @@
   "id": "codex",
   "name": "Codex",
   "description": "Codex app-server harness and Codex-managed GPT model catalog.",
-  "providers": [
-    "codex"
-  ],
+  "providers": ["codex"],
   "contracts": {
-    "mediaUnderstandingProviders": [
-      "codex"
-    ],
-    "migrationProviders": [
-      "codex"
-    ]
+    "mediaUnderstandingProviders": ["codex"],
+    "migrationProviders": ["codex"]
   },
   "mediaUnderstandingProviderMetadata": {
     "codex": {
-      "capabilities": [
-        "image"
-      ],
+      "capabilities": ["image"],
       "defaultModels": {
         "image": "gpt-5.5"
       }
     }
   },
   "providerCatalogEntry": "./provider-discovery.ts",
-  "syntheticAuthRefs": [
-    "codex"
-  ],
-  "nonSecretAuthMarkers": [
-    "codex-app-server"
-  ],
+  "syntheticAuthRefs": ["codex"],
+  "nonSecretAuthMarkers": ["codex-app-server"],
   "activation": {
     "onStartup": false,
-    "onAgentHarnesses": [
-      "codex"
-    ]
+    "onAgentHarnesses": ["codex"]
   },
   "commandAliases": [
     {
@@ -49,26 +35,19 @@
     "properties": {
       "codexDynamicToolsLoading": {
         "type": "string",
-        "enum": [
-          "searchable",
-          "direct"
-        ],
+        "enum": ["searchable", "direct"],
         "default": "searchable"
       },
       "codexDynamicToolsExclude": {
         "type": "array",
-        "items": {
-          "type": "string"
-        },
+        "items": { "type": "string" },
         "default": []
       },
       "discovery": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "enabled": {
-            "type": "boolean"
-          },
+          "enabled": { "type": "boolean" },
           "timeoutMs": {
             "type": "number",
             "minimum": 1,
@@ -135,9 +114,7 @@
                 },
                 "marketplaceName": {
                   "type": "string",
-                  "enum": [
-                    "openai-curated"
-                  ]
+                  "enum": ["openai-curated"]
                 },
                 "pluginName": {
                   "type": "string"
@@ -156,53 +133,33 @@
         "properties": {
           "mode": {
             "type": "string",
-            "enum": [
-              "yolo",
-              "guardian"
-            ],
+            "enum": ["yolo", "guardian"],
             "default": "yolo"
           },
           "transport": {
             "type": "string",
-            "enum": [
-              "stdio",
-              "websocket"
-            ],
+            "enum": ["stdio", "websocket"],
             "default": "stdio"
           },
-          "command": {
-            "type": "string"
-          },
+          "command": { "type": "string" },
           "args": {
             "oneOf": [
               {
                 "type": "array",
-                "items": {
-                  "type": "string"
-                }
+                "items": { "type": "string" }
               },
-              {
-                "type": "string"
-              }
+              { "type": "string" }
             ]
           },
-          "url": {
-            "type": "string"
-          },
-          "authToken": {
-            "type": "string"
-          },
+          "url": { "type": "string" },
+          "authToken": { "type": "string" },
           "headers": {
             "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            }
+            "additionalProperties": { "type": "string" }
           },
           "clearEnv": {
             "type": "array",
-            "items": {
-              "type": "string"
-            }
+            "items": { "type": "string" }
           },
           "codeModeOnly": {
             "type": "boolean",
@@ -220,35 +177,17 @@
           },
           "approvalPolicy": {
             "type": "string",
-            "enum": [
-              "never",
-              "on-request",
-              "on-failure",
-              "untrusted"
-            ]
+            "enum": ["never", "on-request", "on-failure", "untrusted"]
           },
           "sandbox": {
             "type": "string",
-            "enum": [
-              "read-only",
-              "workspace-write",
-              "danger-full-access"
-            ]
+            "enum": ["read-only", "workspace-write", "danger-full-access"]
           },
           "approvalsReviewer": {
             "type": "string",
-            "enum": [
-              "user",
-              "auto_review",
-              "guardian_subagent"
-            ]
-          },
-          "serviceTier": {
-            "type": [
-              "string",
-              "null"
-            ]
+            "enum": ["user", "auto_review", "guardian_subagent"]
           },
+          "serviceTier": { "type": ["string", "null"] },
           "defaultWorkspaceDir": {
             "type": "string"
           }