@kodelyth/codex 2026.5.40 → 2026.5.42

package/src/app-server/local-runtime-attribution.ts

@@ -0,0 +1,39 @@
+import type { EmbeddedRunAttemptParams } from "klaw/plugin-sdk/agent-harness-runtime";
+
+const OPENAI_PROVIDER_ID = "openai";
+const OPENAI_RESPONSES_API = "openai-responses";
+const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+const OPENAI_CODEX_RESPONSES_API = "openai-codex-responses";
+
+export type CodexLocalRuntimeAttribution = {
+  provider: string;
+  api?: string;
+};
+
+function normalizeRuntimeId(value: string | undefined): string {
+  return value?.trim().toLowerCase() ?? "";
+}
+
+export function resolveCodexLocalRuntimeAttribution(
+  params: EmbeddedRunAttemptParams,
+): CodexLocalRuntimeAttribution {
+  const authProfileProvider = normalizeRuntimeId(
+    params.runtimePlan?.auth?.authProfileProviderForAuth,
+  );
+  if (
+    normalizeRuntimeId(params.runtimePlan?.observability.harnessId) === "codex" &&
+    authProfileProvider !== OPENAI_PROVIDER_ID &&
+    normalizeRuntimeId(params.model.provider) === OPENAI_PROVIDER_ID &&
+    normalizeRuntimeId(params.model.api) === OPENAI_RESPONSES_API
+  ) {
+    return {
+      provider: OPENAI_CODEX_PROVIDER_ID,
+      api: OPENAI_CODEX_RESPONSES_API,
+    };
+  }
+
+  return {
+    provider: params.provider,
+    api: params.model.api,
+  };
+}

package/src/app-server/managed-binary.test.ts

@@ -0,0 +1,139 @@
+import { mkdir, mkdtemp, realpath, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import type { CodexAppServerStartOptions } from "./config.js";
+import {
+  testing,
+  resolveManagedCodexAppServerPaths,
+  resolveManagedCodexAppServerStartOptions,
+} from "./managed-binary.js";
+
+function startOptions(
+  commandSource: CodexAppServerStartOptions["commandSource"],
+): CodexAppServerStartOptions {
+  return {
+    transport: "stdio",
+    command: "codex",
+    commandSource,
+    args: ["app-server", "--listen", "stdio://"],
+    headers: {},
+  };
+}
+
+function managedCommandPath(root: string, platform: NodeJS.Platform): string {
+  return path.join(root, "node_modules", ".bin", platform === "win32" ? "codex.cmd" : "codex");
+}
+
+describe("managed Codex app-server binary", () => {
+  it("leaves explicit command overrides unchanged", async () => {
+    const explicitOptions = startOptions("config");
+    const pathExists = vi.fn(async () => false);
+
+    await expect(
+      resolveManagedCodexAppServerStartOptions(explicitOptions, {
+        platform: "darwin",
+        pathExists,
+      }),
+    ).resolves.toBe(explicitOptions);
+    expect(pathExists).not.toHaveBeenCalled();
+  });
+
+  it("resolves the plugin-local bundled Codex binary", async () => {
+    const pluginRoot = path.join("/tmp", "klaw", "extensions", "codex");
+    const paths = resolveManagedCodexAppServerPaths({ platform: "darwin", pluginRoot });
+    const pathExists = vi.fn(async (filePath: string) => filePath === paths.commandPath);
+
+    await expect(
+      resolveManagedCodexAppServerStartOptions(startOptions("managed"), {
+        platform: "darwin",
+        pluginRoot,
+        pathExists,
+      }),
+    ).resolves.toEqual({
+      ...startOptions("managed"),
+      command: paths.commandPath,
+      commandSource: "resolved-managed",
+    });
+    expect(paths.commandPath).toBe(managedCommandPath(pluginRoot, "darwin"));
+  });
+
+  it("resolves Windows Codex command shims", () => {
+    const pluginRoot = path.win32.join("C:\\", "Klaw", "dist", "extensions", "codex");
+    const paths = resolveManagedCodexAppServerPaths({ platform: "win32", pluginRoot });
+
+    expect(paths.commandPath.endsWith(path.win32.join("node_modules", ".bin", "codex.cmd"))).toBe(
+      true,
+    );
+  });
+
+  it("uses the package root when the resolver is bundled into a dist chunk", () => {
+    expect(testing.resolveDefaultCodexPluginRoot("/repo/klaw/dist")).toBe("/repo/klaw");
+    expect(testing.resolveDefaultCodexPluginRoot("/repo/klaw/dist-runtime")).toBe("/repo/klaw");
+    expect(
+      testing.resolveDefaultCodexPluginRoot("/repo/klaw/extensions/codex/src/app-server"),
+    ).toBe("/repo/klaw/extensions/codex");
+  });
+
+  it("finds Codex in the package install root used by packaged plugins", async () => {
+    const installRoot = path.join("/tmp", "klaw-plugin-package", "codex");
+    const pluginRoot = path.join(installRoot, "dist", "extensions", "codex");
+    const installedCommand = managedCommandPath(installRoot, "linux");
+    const pathExists = vi.fn(async (filePath: string) => filePath === installedCommand);
+
+    await expect(
+      resolveManagedCodexAppServerStartOptions(startOptions("managed"), {
+        platform: "linux",
+        pluginRoot,
+        pathExists,
+      }),
+    ).resolves.toEqual({
+      ...startOptions("managed"),
+      command: installedCommand,
+      commandSource: "resolved-managed",
+    });
+  });
+
+  it("falls back to the resolved Codex package bin when no command shim exists", async () => {
+    const installRoot = await mkdtemp(path.join(os.tmpdir(), "klaw-codex-package-"));
+    const pluginRoot = path.join(installRoot, "dist", "extensions", "codex");
+    const packageRoot = path.join(installRoot, "node_modules", "@openai", "codex");
+    const packageBin = path.join(packageRoot, "bin", "codex.js");
+    await mkdir(path.dirname(packageBin), { recursive: true });
+    await writeFile(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify({
+        name: "@openai/codex",
+        bin: {
+          codex: "bin/codex.js",
+        },
+      }),
+    );
+    await writeFile(packageBin, "#!/usr/bin/env node\n");
+    const resolvedPackageBin = await realpath(packageBin);
+
+    const pathExists = vi.fn(async (filePath: string) => filePath === resolvedPackageBin);
+
+    await expect(
+      resolveManagedCodexAppServerStartOptions(startOptions("managed"), {
+        platform: "linux",
+        pluginRoot,
+        pathExists,
+      }),
+    ).resolves.toEqual({
+      ...startOptions("managed"),
+      command: resolvedPackageBin,
+      commandSource: "resolved-managed",
+    });
+  });
+
+  it("fails clearly when the managed Codex binary is missing", async () => {
+    await expect(
+      resolveManagedCodexAppServerStartOptions(startOptions("managed"), {
+        platform: "darwin",
+        pluginRoot: path.join("/tmp", "klaw", "extensions", "codex"),
+        pathExists: vi.fn(async () => false),
+      }),
+    ).rejects.toThrow("Managed Codex app-server binary was not found");
+  });
+});

package/src/app-server/managed-binary.ts

@@ -0,0 +1,193 @@
+import { constants as fsConstants, readFileSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CodexAppServerStartOptions } from "./config.js";
+import { MANAGED_CODEX_APP_SERVER_PACKAGE } from "./version.js";
+
+const CODEX_APP_SERVER_MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CODEX_PLUGIN_ROOT = resolveDefaultCodexPluginRoot(CODEX_APP_SERVER_MODULE_DIR);
+
+type ManagedCodexAppServerPaths = {
+  commandPath: string;
+  candidateCommandPaths: string[];
+};
+
+type ResolveManagedCodexAppServerOptions = {
+  platform?: NodeJS.Platform;
+  pluginRoot?: string;
+  pathExists?: (filePath: string, platform: NodeJS.Platform) => Promise<boolean>;
+};
+
+export async function resolveManagedCodexAppServerStartOptions(
+  startOptions: CodexAppServerStartOptions,
+  options: ResolveManagedCodexAppServerOptions = {},
+): Promise<CodexAppServerStartOptions> {
+  if (startOptions.transport !== "stdio" || startOptions.commandSource !== "managed") {
+    return startOptions;
+  }
+
+  const platform = options.platform ?? process.platform;
+  const paths = resolveManagedCodexAppServerPaths({
+    platform,
+    pluginRoot: options.pluginRoot,
+  });
+  const pathExists = options.pathExists ?? commandPathExists;
+  const commandPath = await findManagedCodexAppServerCommandPath({
+    candidateCommandPaths: paths.candidateCommandPaths,
+    pathExists,
+    platform,
+  });
+
+  return {
+    ...startOptions,
+    command: commandPath,
+    commandSource: "resolved-managed",
+  };
+}
+
+export function resolveManagedCodexAppServerPaths(params: {
+  platform?: NodeJS.Platform;
+  pluginRoot?: string;
+}): ManagedCodexAppServerPaths {
+  const platform = params.platform ?? process.platform;
+  const candidateCommandPaths = resolveManagedCodexAppServerCommandCandidates(
+    params.pluginRoot ?? CODEX_PLUGIN_ROOT,
+    platform,
+  );
+  return {
+    commandPath: candidateCommandPaths[0] ?? "",
+    candidateCommandPaths,
+  };
+}
+
+function resolveManagedCodexAppServerCommandCandidates(
+  pluginRoot: string,
+  platform: NodeJS.Platform,
+): string[] {
+  const pathApi = pathForPlatform(platform);
+  const commandName = platform === "win32" ? "codex.cmd" : "codex";
+  const roots = resolveManagedCodexAppServerCandidateRoots(pluginRoot, platform);
+  return [
+    ...new Set([
+      ...roots.map((root) => pathApi.join(root, "node_modules", ".bin", commandName)),
+      ...resolveManagedCodexPackageBinCandidates(roots, platform),
+    ]),
+  ];
+}
+
+function resolveDefaultCodexPluginRoot(moduleDir: string): string {
+  const moduleBaseName = path.basename(moduleDir);
+  if (moduleBaseName === "dist" || moduleBaseName === "dist-runtime") {
+    return path.dirname(moduleDir);
+  }
+  return path.resolve(moduleDir, "..", "..");
+}
+
+function resolveManagedCodexAppServerCandidateRoots(
+  pluginRoot: string,
+  platform: NodeJS.Platform,
+): string[] {
+  const pathApi = pathForPlatform(platform);
+  return [
+    pluginRoot,
+    pathApi.dirname(pluginRoot),
+    pathApi.dirname(pathApi.dirname(pluginRoot)),
+    isDistExtensionRoot(pluginRoot, platform)
+      ? pathApi.dirname(pathApi.dirname(pathApi.dirname(pluginRoot)))
+      : null,
+  ].filter((root): root is string => Boolean(root));
+}
+
+function resolveManagedCodexPackageBinCandidates(
+  roots: readonly string[],
+  platform: NodeJS.Platform,
+): string[] {
+  if (platform === "win32") {
+    return [];
+  }
+
+  const candidates: string[] = [];
+  for (const root of roots) {
+    const candidate = resolveManagedCodexPackageBinCandidate(root);
+    if (candidate) {
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function resolveManagedCodexPackageBinCandidate(root: string): string | null {
+  try {
+    const requireFromRoot = createRequire(path.join(root, "package.json"));
+    const packageJsonPath = requireFromRoot.resolve(
+      `${MANAGED_CODEX_APP_SERVER_PACKAGE}/package.json`,
+    );
+    const packageRoot = path.dirname(packageJsonPath);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      bin?: unknown;
+    };
+    const binPath =
+      typeof packageJson.bin === "string"
+        ? packageJson.bin
+        : isRecord(packageJson.bin) && typeof packageJson.bin.codex === "string"
+          ? packageJson.bin.codex
+          : null;
+    return binPath ? path.resolve(packageRoot, binPath) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export const testing = {
+  resolveDefaultCodexPluginRoot,
+};
+
+function isDistExtensionRoot(pluginRoot: string, platform: NodeJS.Platform): boolean {
+  const pathApi = pathForPlatform(platform);
+  const extensionsDir = pathApi.dirname(pluginRoot);
+  const distDir = pathApi.dirname(extensionsDir);
+  return (
+    pathApi.basename(extensionsDir) === "extensions" &&
+    (pathApi.basename(distDir) === "dist" || pathApi.basename(distDir) === "dist-runtime")
+  );
+}
+
+function pathForPlatform(platform: NodeJS.Platform): typeof path {
+  return platform === "win32" ? path.win32 : path.posix;
+}
+
+async function findManagedCodexAppServerCommandPath(params: {
+  candidateCommandPaths: readonly string[];
+  pathExists: (filePath: string, platform: NodeJS.Platform) => Promise<boolean>;
+  platform: NodeJS.Platform;
+}): Promise<string> {
+  for (const commandPath of params.candidateCommandPaths) {
+    if (await params.pathExists(commandPath, params.platform)) {
+      return commandPath;
+    }
+  }
+
+  throw new Error(
+    [
+      `Managed Codex app-server binary was not found for ${MANAGED_CODEX_APP_SERVER_PACKAGE}.`,
+      "Reinstall or update Klaw, or run pnpm install in a source checkout.",
+      "Set plugins.entries.codex.config.appServer.command or KLAW_CODEX_APP_SERVER_BIN to use a custom Codex binary.",
+    ].join(" "),
+  );
+}
+
+async function commandPathExists(filePath: string, platform: NodeJS.Platform): Promise<boolean> {
+  try {
+    await access(filePath, platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+export { testing as __testing };

package/src/app-server/models.test.ts

@@ -0,0 +1,246 @@
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { CodexAppServerClient } from "./client.js";
+import { createClientHarness } from "./test-support.js";
+
+const mocks = vi.hoisted(() => {
+  const authBridge = {
+    applyAuthProfile: vi.fn(async () => undefined),
+    authProfileId: vi.fn((params?: { authProfileId?: string }) => params?.authProfileId),
+    startOptions: vi.fn(async ({ startOptions }) => startOptions),
+  };
+  const managedBinary = {
+    startOptions: vi.fn(async (startOptions) => startOptions),
+  };
+  const providerAuth = {
+    agentDir: vi.fn(() => "/tmp/klaw-agent"),
+  };
+  return { authBridge, managedBinary, providerAuth };
+});
+
+vi.mock("./auth-bridge.js", () => ({
+  applyCodexAppServerAuthProfile: mocks.authBridge.applyAuthProfile,
+  bridgeCodexAppServerStartOptions: mocks.authBridge.startOptions,
+  resolveCodexAppServerAuthProfileIdForAgent: mocks.authBridge.authProfileId,
+}));
+
+vi.mock("./managed-binary.js", () => ({
+  resolveManagedCodexAppServerStartOptions: mocks.managedBinary.startOptions,
+}));
+
+vi.mock("klaw/plugin-sdk/agent-runtime", () => ({
+  resolveDefaultAgentDir: mocks.providerAuth.agentDir,
+}));
+
+let listCodexAppServerModels: typeof import("./models.js").listCodexAppServerModels;
+let listAllCodexAppServerModels: typeof import("./models.js").listAllCodexAppServerModels;
+let resetSharedCodexAppServerClientForTests: typeof import("./shared-client.js").resetSharedCodexAppServerClientForTests;
+
+describe("listCodexAppServerModels", () => {
+  beforeAll(async () => {
+    ({ listCodexAppServerModels } = await import("./models.js"));
+    ({ listAllCodexAppServerModels } = await import("./models.js"));
+    ({ resetSharedCodexAppServerClientForTests } = await import("./shared-client.js"));
+  });
+
+  afterEach(() => {
+    resetSharedCodexAppServerClientForTests();
+    vi.restoreAllMocks();
+    mocks.authBridge.applyAuthProfile.mockClear();
+    mocks.authBridge.authProfileId.mockClear();
+    mocks.authBridge.authProfileId.mockImplementation(
+      (params?: { authProfileId?: string }) => params?.authProfileId,
+    );
+    mocks.authBridge.startOptions.mockClear();
+    mocks.managedBinary.startOptions.mockClear();
+    mocks.managedBinary.startOptions.mockImplementation(async (startOptions) => startOptions);
+    mocks.providerAuth.agentDir.mockClear();
+  });
+
+  it("lists app-server models through the typed helper", async () => {
+    const harness = createClientHarness();
+    const startSpy = vi.spyOn(CodexAppServerClient, "start").mockReturnValue(harness.client);
+
+    const listPromise = listCodexAppServerModels({ limit: 12, timeoutMs: 1000 });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(1));
+    const initialize = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    harness.send({
+      id: initialize.id,
+      result: { userAgent: "klaw/0.125.0 (macOS; test)" },
+    });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(3));
+    const list = JSON.parse(harness.writes[2] ?? "{}") as { id?: number; method?: string };
+    expect(list.method).toBe("model/list");
+
+    harness.send({
+      id: list.id,
+      result: {
+        data: [
+          {
+            id: "gpt-5.4",
+            model: "gpt-5.4",
+            upgrade: null,
+            upgradeInfo: null,
+            availabilityNux: null,
+            displayName: "gpt-5.4",
+            description: "GPT-5.4",
+            hidden: false,
+            inputModalities: ["text", "image"],
+            supportedReasoningEfforts: [
+              { reasoningEffort: "low", description: "fast" },
+              { reasoningEffort: "xhigh", description: "deep" },
+            ],
+            defaultReasoningEffort: "medium",
+            supportsPersonality: false,
+            additionalSpeedTiers: [],
+            isDefault: true,
+          },
+        ],
+        nextCursor: null,
+      },
+    });
+
+    await expect(listPromise).resolves.toEqual({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          displayName: "gpt-5.4",
+          description: "GPT-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["low", "xhigh"],
+          defaultReasoningEffort: "medium",
+          isDefault: true,
+        },
+      ],
+    });
+    harness.client.close();
+    startSpy.mockRestore();
+  });
+
+  it("lists all app-server model pages through one client", async () => {
+    const harness = createClientHarness();
+    const startSpy = vi.spyOn(CodexAppServerClient, "start").mockReturnValue(harness.client);
+
+    const listPromise = listAllCodexAppServerModels({ limit: 1, timeoutMs: 1000 });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(1));
+    const initialize = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    harness.send({
+      id: initialize.id,
+      result: { userAgent: "klaw/0.125.0 (macOS; test)" },
+    });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(3));
+    const firstList = JSON.parse(harness.writes[2] ?? "{}") as {
+      id?: number;
+      params?: { cursor?: string | null };
+    };
+    expect(firstList.params?.cursor).toBeNull();
+
+    harness.send({
+      id: firstList.id,
+      result: {
+        data: [
+          {
+            id: "gpt-5.4",
+            model: "gpt-5.4",
+            upgrade: null,
+            upgradeInfo: null,
+            availabilityNux: null,
+            displayName: "gpt-5.4",
+            description: "GPT-5.4",
+            hidden: false,
+            inputModalities: ["text"],
+            supportedReasoningEfforts: [],
+            defaultReasoningEffort: "medium",
+            supportsPersonality: false,
+            additionalSpeedTiers: [],
+            isDefault: false,
+          },
+        ],
+        nextCursor: "page-2",
+      },
+    });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(4));
+    const secondList = JSON.parse(harness.writes[3] ?? "{}") as {
+      id?: number;
+      params?: { cursor?: string | null };
+    };
+    expect(secondList.params?.cursor).toBe("page-2");
+
+    harness.send({
+      id: secondList.id,
+      result: {
+        data: [
+          {
+            id: "gpt-5.2",
+            model: "gpt-5.2",
+            upgrade: null,
+            upgradeInfo: null,
+            availabilityNux: null,
+            displayName: "gpt-5.2",
+            description: "GPT-5.2",
+            hidden: false,
+            inputModalities: ["text", "image"],
+            supportedReasoningEfforts: [],
+            defaultReasoningEffort: "medium",
+            supportsPersonality: false,
+            additionalSpeedTiers: [],
+            isDefault: false,
+          },
+        ],
+        nextCursor: null,
+      },
+    });
+
+    const list = await listPromise;
+    expect(list.models.map((model) => model.id)).toEqual(["gpt-5.4", "gpt-5.2"]);
+    harness.client.close();
+    startSpy.mockRestore();
+  });
+
+  it("marks all-model listing truncated after the page cap", async () => {
+    const harness = createClientHarness();
+    const startSpy = vi.spyOn(CodexAppServerClient, "start").mockReturnValue(harness.client);
+
+    const listPromise = listAllCodexAppServerModels({ limit: 1, timeoutMs: 1000, maxPages: 1 });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(1));
+    const initialize = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    harness.send({
+      id: initialize.id,
+      result: { userAgent: "klaw/0.125.0 (macOS; test)" },
+    });
+    await vi.waitFor(() => expect(harness.writes.length).toBeGreaterThanOrEqual(3));
+    const firstList = JSON.parse(harness.writes[2] ?? "{}") as { id?: number };
+    harness.send({
+      id: firstList.id,
+      result: {
+        data: [
+          {
+            id: "gpt-5.4",
+            model: "gpt-5.4",
+            upgrade: null,
+            upgradeInfo: null,
+            availabilityNux: null,
+            displayName: "gpt-5.4",
+            description: "GPT-5.4",
+            hidden: false,
+            inputModalities: ["text"],
+            supportedReasoningEfforts: [],
+            defaultReasoningEffort: "medium",
+            supportsPersonality: false,
+            additionalSpeedTiers: [],
+            isDefault: false,
+          },
+        ],
+        nextCursor: "page-2",
+      },
+    });
+
+    const list = await listPromise;
+    expect(list.models.map((model) => model.id)).toEqual(["gpt-5.4"]);
+    expect(list.nextCursor).toBe("page-2");
+    expect(list.truncated).toBe(true);
+    harness.client.close();
+    startSpy.mockRestore();
+  });
+});