@kodelyth/codex 2026.5.40 → 2026.5.42

package/provider-discovery.ts

@@ -0,0 +1,45 @@
+import type { ProviderCatalogContext } from "klaw/plugin-sdk/provider-catalog-shared";
+import type { ProviderPlugin } from "klaw/plugin-sdk/provider-model-shared";
+import {
+  buildCodexProviderConfig,
+  CODEX_APP_SERVER_AUTH_MARKER,
+  CODEX_PROVIDER_ID,
+  FALLBACK_CODEX_MODELS,
+} from "./provider-catalog.js";
+
+function resolveCodexPluginConfig(ctx: ProviderCatalogContext): unknown {
+  return (ctx.config.plugins?.entries as Record<string, { config?: unknown } | undefined>)?.codex
+    ?.config;
+}
+
+async function runCodexCatalog(ctx: ProviderCatalogContext) {
+  const { buildCodexProviderCatalog } = await import("./provider.js");
+  return await buildCodexProviderCatalog({
+    env: ctx.env,
+    pluginConfig: resolveCodexPluginConfig(ctx),
+  });
+}
+
+export const codexProviderDiscovery: ProviderPlugin = {
+  id: CODEX_PROVIDER_ID,
+  label: "Codex",
+  docsPath: "/providers/models",
+  auth: [],
+  catalog: {
+    order: "late",
+    run: runCodexCatalog,
+  },
+  staticCatalog: {
+    order: "late",
+    run: async () => ({
+      provider: buildCodexProviderConfig(FALLBACK_CODEX_MODELS),
+    }),
+  },
+  resolveSyntheticAuth: () => ({
+    apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+    source: "codex-app-server",
+    mode: "token",
+  }),
+};
+
+export default codexProviderDiscovery;

package/provider.test.ts

@@ -0,0 +1,384 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CODEX_GPT5_BEHAVIOR_CONTRACT } from "./prompt-overlay.js";
+import { codexProviderDiscovery } from "./provider-discovery.js";
+import { buildCodexProvider, buildCodexProviderCatalog } from "./provider.js";
+import { CodexAppServerClient } from "./src/app-server/client.js";
+import {
+  getSharedCodexAppServerClient,
+  resetSharedCodexAppServerClientForTests,
+} from "./src/app-server/shared-client.js";
+
+afterEach(() => {
+  resetSharedCodexAppServerClientForTests();
+  vi.restoreAllMocks();
+});
+
+function expectStaticFallbackCatalog(
+  result: Awaited<ReturnType<typeof buildCodexProviderCatalog>>,
+) {
+  expect(result.provider.models.map((model) => model.id)).toEqual([
+    "gpt-5.5",
+    "gpt-5.4-mini",
+    "gpt-5.2",
+  ]);
+}
+
+function createFakeCodexClient(): CodexAppServerClient {
+  return {
+    initialize: vi.fn(async () => undefined),
+    request: vi.fn(async () => ({ data: [] })),
+    addCloseHandler: vi.fn(() => () => undefined),
+    close: vi.fn(),
+  } as unknown as CodexAppServerClient;
+}
+
+function expectRecordFields(value: unknown, expected: Record<string, unknown>) {
+  if (!value || typeof value !== "object") {
+    throw new Error("Expected record");
+  }
+  const actual = value as Record<string, unknown>;
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    expect(actual[key]).toEqual(expectedValue);
+  }
+  return actual;
+}
+
+function mockCallArg(mockFn: { mock: { calls: unknown[][] } }, callIndex: number): unknown {
+  return mockFn.mock.calls[callIndex]?.[0];
+}
+
+describe("codex provider", () => {
+  it("maps Codex app-server models to a Codex provider catalog", async () => {
+    const listModels = vi.fn(async () => ({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          displayName: "gpt-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+        },
+        {
+          id: "hidden-model",
+          model: "hidden-model",
+          hidden: true,
+          inputModalities: ["text"],
+          supportedReasoningEfforts: [],
+        },
+      ],
+    }));
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      pluginConfig: { discovery: { timeoutMs: 1234 } },
+    });
+
+    expectRecordFields(mockCallArg(listModels, 0), {
+      limit: 100,
+      timeoutMs: 1234,
+      sharedClient: false,
+    });
+    expectRecordFields(result.provider, {
+      auth: "token",
+      api: "openai-codex-responses",
+    });
+    expect(result.provider.models).toHaveLength(1);
+    expectRecordFields(result.provider.models[0], {
+      id: "gpt-5.4",
+      name: "gpt-5.4",
+      reasoning: true,
+      input: ["text", "image"],
+      compat: { supportsReasoningEffort: true, supportsUsageInStreaming: true },
+    });
+  });
+
+  it("keeps a static fallback catalog when discovery is disabled", async () => {
+    const listModels = vi.fn();
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      pluginConfig: { discovery: { enabled: false } },
+    });
+
+    expect(listModels).not.toHaveBeenCalled();
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("uses live plugin config to re-enable discovery after startup disable", async () => {
+    const listModels = vi.fn(async () => ({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          displayName: "gpt-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+        },
+      ],
+    }));
+    const provider = buildCodexProvider({
+      pluginConfig: { discovery: { enabled: false } },
+      listModels,
+    });
+
+    const result = await provider.catalog?.run({
+      config: {
+        plugins: {
+          entries: {
+            codex: {
+              config: {
+                discovery: {
+                  enabled: true,
+                  timeoutMs: 4321,
+                },
+              },
+            },
+          },
+        },
+      },
+      env: {},
+    } as never);
+
+    expectRecordFields(mockCallArg(listModels, 0), {
+      limit: 100,
+      timeoutMs: 4321,
+      sharedClient: false,
+    });
+    const resultProvider = result && "provider" in result ? result.provider : undefined;
+    expect(resultProvider?.models.map((model) => model.id)).toEqual(["gpt-5.4"]);
+  });
+
+  it("pages through live discovery before building the provider catalog", async () => {
+    const listModels = vi
+      .fn()
+      .mockResolvedValueOnce({
+        models: [
+          {
+            id: "gpt-5.4",
+            model: "gpt-5.4",
+            hidden: false,
+            inputModalities: ["text", "image"],
+            supportedReasoningEfforts: ["medium"],
+          },
+        ],
+        nextCursor: "page-2",
+      })
+      .mockResolvedValueOnce({
+        models: [
+          {
+            id: "gpt-5.2",
+            model: "gpt-5.2",
+            hidden: false,
+            inputModalities: ["text"],
+            supportedReasoningEfforts: [],
+          },
+        ],
+      });
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+    });
+
+    expectRecordFields(mockCallArg(listModels, 0), {
+      cursor: undefined,
+      limit: 100,
+      sharedClient: false,
+    });
+    expectRecordFields(mockCallArg(listModels, 1), {
+      cursor: "page-2",
+      limit: 100,
+      sharedClient: false,
+    });
+    expect(result.provider.models.map((model) => model.id)).toEqual(["gpt-5.4", "gpt-5.2"]);
+  });
+
+  it("reports discovery failures before using the fallback catalog", async () => {
+    const error = new Error("app-server down");
+    const onDiscoveryFailure = vi.fn();
+    const listModels = vi.fn(async () => {
+      throw error;
+    });
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      onDiscoveryFailure,
+    });
+
+    expect(onDiscoveryFailure).toHaveBeenCalledWith(error);
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("keeps a static fallback catalog when live discovery is explicitly disabled by env", async () => {
+    const listModels = vi.fn();
+
+    const result = await buildCodexProviderCatalog({
+      env: { KLAW_CODEX_DISCOVERY_LIVE: "0" },
+      listModels,
+    });
+
+    expect(listModels).not.toHaveBeenCalled();
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("closes the transient app-server client after live discovery", async () => {
+    const client = createFakeCodexClient();
+    vi.spyOn(CodexAppServerClient, "start").mockReturnValue(client);
+
+    await buildCodexProviderCatalog({
+      env: { KLAW_CODEX_DISCOVERY_LIVE: "1" },
+    });
+
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not close an active shared app-server client during live discovery", async () => {
+    const activeClient = createFakeCodexClient();
+    const discoveryClient = createFakeCodexClient();
+    vi.spyOn(CodexAppServerClient, "start")
+      .mockReturnValueOnce(activeClient)
+      .mockReturnValueOnce(discoveryClient);
+
+    await getSharedCodexAppServerClient({ timeoutMs: 1000 });
+    await buildCodexProviderCatalog({
+      env: { KLAW_CODEX_DISCOVERY_LIVE: "1" },
+    });
+
+    expect(activeClient.close).not.toHaveBeenCalled();
+    expect(discoveryClient.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves arbitrary Codex app-server model ids as text-only until discovered", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: " custom-model ",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expectRecordFields(model, {
+      id: "custom-model",
+      provider: "codex",
+      api: "openai-codex-responses",
+      baseUrl: "https://chatgpt.com/backend-api",
+      input: ["text"],
+    });
+  });
+
+  it("keeps fallback Codex app-server models image-capable", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: "gpt-5.5",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expectRecordFields(model, {
+      id: "gpt-5.5",
+      input: ["text", "image"],
+    });
+  });
+
+  it("treats o4 ids as reasoning-capable Codex models", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: "o4-mini",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expectRecordFields(model, {
+      id: "o4-mini",
+      reasoning: true,
+      compat: { supportsReasoningEffort: true, supportsUsageInStreaming: true },
+    });
+    expect(
+      provider
+        .resolveThinkingProfile?.({ provider: "codex", modelId: "o4-mini" } as never)
+        ?.levels.some((level) => level.id === "xhigh"),
+    ).toBe(true);
+  });
+
+  it("declares synthetic auth because the harness owns Codex credentials", () => {
+    const provider = buildCodexProvider();
+
+    expect(provider.resolveSyntheticAuth?.({ provider: "codex" })).toEqual({
+      apiKey: "codex-app-server",
+      source: "codex-app-server",
+      mode: "token",
+    });
+  });
+
+  it("exposes a setup auth choice for installing Codex as an external provider", async () => {
+    const provider = buildCodexProvider();
+
+    const authChoice = provider.auth[0];
+    expectRecordFields(authChoice, {
+      id: "app-server",
+      kind: "custom",
+    });
+    expectRecordFields(authChoice?.wizard, {
+      choiceId: "codex",
+      choiceLabel: "Codex app-server",
+      onboardingScopes: ["text-inference"],
+    });
+    const authResult = await authChoice?.run({} as never);
+    expectRecordFields(authResult, {
+      profiles: [],
+      defaultModel: "codex/gpt-5.5",
+    });
+  });
+
+  it("exposes a lightweight provider-discovery entry for model list/status", async () => {
+    expect(codexProviderDiscovery.id).toBe("codex");
+    expect(codexProviderDiscovery.resolveSyntheticAuth?.({ provider: "codex" })).toEqual({
+      apiKey: "codex-app-server",
+      source: "codex-app-server",
+      mode: "token",
+    });
+
+    const result = await codexProviderDiscovery.staticCatalog?.run({
+      config: {},
+      env: {},
+      agentDir: "/tmp/klaw-agent",
+    } as never);
+
+    expect(
+      result && "provider" in result ? result.provider.models.map((model) => model.id) : [],
+    ).toEqual(["gpt-5.5", "gpt-5.4-mini", "gpt-5.2"]);
+  });
+
+  it("adds the GPT-5 prompt overlay to Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    const contribution = provider.resolveSystemPromptContribution?.({
+      provider: "codex",
+      modelId: "gpt-5.4",
+    } as never);
+    expectRecordFields(contribution, {
+      stablePrefix: CODEX_GPT5_BEHAVIOR_CONTRACT,
+    });
+    const interactionStyle = contribution?.sectionOverrides?.interaction_style;
+    expect(interactionStyle).toContain("Live chat tone: short, natural, human.");
+    expect(interactionStyle).not.toContain("Use heartbeats to create useful proactive progress");
+  });
+
+  it("does not add the GPT-5 prompt overlay to non-GPT-5 Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    expect(
+      provider.resolveSystemPromptContribution?.({
+        provider: "codex",
+        modelId: "o4-mini",
+      } as never),
+    ).toBeUndefined();
+  });
+});

package/provider.ts

@@ -0,0 +1,243 @@
+import { createSubsystemLogger } from "klaw/plugin-sdk/core";
+import { resolvePluginConfigObject } from "klaw/plugin-sdk/plugin-config-runtime";
+import type { ProviderRuntimeModel } from "klaw/plugin-sdk/plugin-entry";
+import {
+  normalizeModelCompat,
+  type ModelProviderConfig,
+  type ProviderPlugin,
+} from "klaw/plugin-sdk/provider-model-shared";
+import { resolveCodexSystemPromptContribution } from "./prompt-overlay.js";
+import {
+  buildCodexModelDefinition,
+  buildCodexProviderConfig,
+  CODEX_APP_SERVER_AUTH_MARKER,
+  CODEX_BASE_URL,
+  CODEX_PROVIDER_ID,
+  FALLBACK_CODEX_MODELS,
+} from "./provider-catalog.js";
+import {
+  type CodexAppServerStartOptions,
+  readCodexPluginConfig,
+  resolveCodexAppServerRuntimeOptions,
+} from "./src/app-server/config.js";
+import type {
+  CodexAppServerModel,
+  CodexAppServerModelListResult,
+} from "./src/app-server/models.js";
+
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 2500;
+const LIVE_DISCOVERY_ENV = "KLAW_CODEX_DISCOVERY_LIVE";
+const MODEL_DISCOVERY_PAGE_LIMIT = 100;
+const CODEX_APP_SERVER_SETUP_METHOD_ID = "app-server";
+const CODEX_DEFAULT_MODEL_REF = `${CODEX_PROVIDER_ID}/${FALLBACK_CODEX_MODELS[0].id}`;
+const codexCatalogLog = createSubsystemLogger("codex/catalog");
+
+type CodexModelLister = (options: {
+  timeoutMs: number;
+  limit?: number;
+  cursor?: string;
+  startOptions?: CodexAppServerStartOptions;
+  sharedClient?: boolean;
+}) => Promise<CodexAppServerModelListResult>;
+
+type BuildCodexProviderOptions = {
+  pluginConfig?: unknown;
+  listModels?: CodexModelLister;
+};
+
+type BuildCatalogOptions = {
+  env?: NodeJS.ProcessEnv;
+  pluginConfig?: unknown;
+  listModels?: CodexModelLister;
+  onDiscoveryFailure?: (error: unknown) => void;
+};
+
+export function buildCodexProvider(options: BuildCodexProviderOptions = {}): ProviderPlugin {
+  return {
+    id: CODEX_PROVIDER_ID,
+    label: "Codex",
+    docsPath: "/providers/models",
+    auth: [
+      {
+        id: CODEX_APP_SERVER_SETUP_METHOD_ID,
+        label: "Codex app-server",
+        hint: "Use the Codex app-server runtime and managed model catalog.",
+        kind: "custom",
+        wizard: {
+          choiceId: CODEX_PROVIDER_ID,
+          choiceLabel: "Codex app-server",
+          choiceHint: "Use the Codex app-server runtime and managed model catalog.",
+          assistantPriority: -40,
+          groupId: CODEX_PROVIDER_ID,
+          groupLabel: "Codex",
+          groupHint: "Codex app-server model provider",
+          onboardingScopes: ["text-inference"],
+        },
+        run: async () => ({ profiles: [], defaultModel: CODEX_DEFAULT_MODEL_REF }),
+      },
+    ],
+    catalog: {
+      order: "late",
+      run: async (ctx) => {
+        const runtimePluginConfig = resolvePluginConfigObject(ctx.config, CODEX_PROVIDER_ID);
+        const pluginConfig = runtimePluginConfig ?? (ctx.config ? undefined : options.pluginConfig);
+        return await buildCodexProviderCatalog({
+          env: ctx.env,
+          pluginConfig,
+          listModels: options.listModels,
+        });
+      },
+    },
+    staticCatalog: {
+      order: "late",
+      run: async () => ({
+        provider: buildCodexProviderConfig(FALLBACK_CODEX_MODELS),
+      }),
+    },
+    resolveDynamicModel: (ctx) => resolveCodexDynamicModel(ctx.modelId),
+    resolveSyntheticAuth: () => ({
+      apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+      source: "codex-app-server",
+      mode: "token",
+    }),
+    resolveThinkingProfile: ({ modelId }) => ({
+      levels: [
+        { id: "off" },
+        { id: "minimal" },
+        { id: "low" },
+        { id: "medium" },
+        { id: "high" },
+        ...(isKnownXHighCodexModel(modelId) ? [{ id: "xhigh" as const }] : []),
+      ],
+    }),
+    resolveSystemPromptContribution: ({ config, modelId }) =>
+      resolveCodexSystemPromptContribution({ config, modelId }),
+    isModernModelRef: ({ modelId }) => isModernCodexModel(modelId),
+  };
+}
+
+export async function buildCodexProviderCatalog(
+  options: BuildCatalogOptions = {},
+): Promise<{ provider: ModelProviderConfig }> {
+  const config = readCodexPluginConfig(options.pluginConfig);
+  const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig: options.pluginConfig });
+  const timeoutMs = normalizeTimeoutMs(config.discovery?.timeoutMs);
+  let discovered: CodexAppServerModel[] = [];
+  if (config.discovery?.enabled !== false && !shouldSkipLiveDiscovery(options.env)) {
+    discovered = await listModelsBestEffort({
+      listModels: options.listModels ?? listCodexAppServerModelsLazy,
+      timeoutMs,
+      startOptions: appServer.start,
+      onDiscoveryFailure: options.onDiscoveryFailure,
+    });
+  }
+  return {
+    provider: buildCodexProviderConfig(discovered.length > 0 ? discovered : FALLBACK_CODEX_MODELS),
+  };
+}
+
+function resolveCodexDynamicModel(modelId: string) {
+  const id = modelId.trim();
+  if (!id) {
+    return undefined;
+  }
+  const fallbackModel = FALLBACK_CODEX_MODELS.find((model) => model.id === id);
+  return normalizeModelCompat({
+    ...buildCodexModelDefinition({
+      id,
+      model: id,
+      inputModalities: fallbackModel?.inputModalities ?? ["text"],
+      supportedReasoningEfforts:
+        fallbackModel?.supportedReasoningEfforts ??
+        (shouldDefaultToReasoningModel(id) ? ["medium"] : []),
+    }),
+    provider: CODEX_PROVIDER_ID,
+    baseUrl: CODEX_BASE_URL,
+  } as ProviderRuntimeModel);
+}
+
+async function listModelsBestEffort(params: {
+  listModels: CodexModelLister;
+  timeoutMs: number;
+  startOptions: CodexAppServerStartOptions;
+  onDiscoveryFailure?: (error: unknown) => void;
+}): Promise<CodexAppServerModel[]> {
+  try {
+    const models: CodexAppServerModel[] = [];
+    let cursor: string | undefined;
+    do {
+      const result = await params.listModels({
+        timeoutMs: params.timeoutMs,
+        limit: MODEL_DISCOVERY_PAGE_LIMIT,
+        cursor,
+        startOptions: params.startOptions,
+        sharedClient: false,
+      });
+      models.push(...result.models.filter((model) => !model.hidden));
+      cursor = result.nextCursor;
+    } while (cursor);
+    return models;
+  } catch (error) {
+    params.onDiscoveryFailure?.(error);
+    codexCatalogLog.debug("codex model discovery failed; using fallback catalog", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+async function listCodexAppServerModelsLazy(options: {
+  timeoutMs: number;
+  limit?: number;
+  cursor?: string;
+  startOptions?: CodexAppServerStartOptions;
+  sharedClient?: boolean;
+}): Promise<CodexAppServerModelListResult> {
+  const { listCodexAppServerModels } = await import("./src/app-server/models.js");
+  return listCodexAppServerModels(options);
+}
+
+function normalizeTimeoutMs(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : DEFAULT_DISCOVERY_TIMEOUT_MS;
+}
+
+function shouldSkipLiveDiscovery(env: NodeJS.ProcessEnv = process.env): boolean {
+  const override = env[LIVE_DISCOVERY_ENV]?.trim().toLowerCase();
+  if (override === "0" || override === "false") {
+    return true;
+  }
+  return Boolean(env.VITEST) && override !== "1";
+}
+
+function shouldDefaultToReasoningModel(modelId: string): boolean {
+  const lower = modelId.toLowerCase();
+  return (
+    lower.startsWith("gpt-5") ||
+    lower.startsWith("o1") ||
+    lower.startsWith("o3") ||
+    lower.startsWith("o4")
+  );
+}
+
+function isKnownXHighCodexModel(modelId: string): boolean {
+  const lower = modelId.trim().toLowerCase();
+  return (
+    lower.startsWith("gpt-5") ||
+    lower.startsWith("o3") ||
+    lower.startsWith("o4") ||
+    lower.includes("codex")
+  );
+}
+
+// Exported so adapter request paths (thread-lifecycle.resolveReasoningEffort)
+// can branch on model-family enum support: modern Codex models use the
+// none/low/medium/high/xhigh effort enum and reject "minimal", which is the
+// CLI default. (#71946)
+export function isModernCodexModel(modelId: string): boolean {
+  const lower = modelId.trim().toLowerCase();
+  return (
+    lower === "gpt-5.5" || lower === "gpt-5.4" || lower === "gpt-5.4-mini" || lower === "gpt-5.2"
+  );
+}