@kodelyth/codex 2026.5.42 → 2026.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodelyth/codex",
-  "version": "2026.5.42",
+  "version": "2026.6.2",
   "description": "Klaw Codex harness and model provider plugin",
   "repository": {
     "type": "git",
@@ -15,7 +15,7 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@kodelyth/plugin-sdk": "1.0.1"
+    "@kodelyth/plugin-sdk": "workspace:*"
   },
   "klaw": {
     "extensions": [
@@ -35,6 +35,21 @@
     "release": {
       "publishToClawHub": true,
       "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist/**",
+    "klaw.plugin.json"
+  ],
+  "peerDependencies": {
+    "klaw": ">=2026.5.39"
+  },
+  "peerDependenciesMeta": {
+    "klaw": {
+      "optional": true
     }
   }
 }

package/doctor-contract-api.test.ts

@@ -1,44 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,230 +0,0 @@
-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

@@ -1,66 +0,0 @@
-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);
-  },
-});