@openclaw/codex 2026.5.1-beta.1

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

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import type { CodexAppServerStartOptions } from "./config.js";
+import {
+  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", "openclaw", "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:\\", "OpenClaw", "dist", "extensions", "codex");
+    const paths = resolveManagedCodexAppServerPaths({ platform: "win32", pluginRoot });
+
+    expect(paths.commandPath.endsWith(path.win32.join("node_modules", ".bin", "codex.cmd"))).toBe(
+      true,
+    );
+  });
+
+  it("finds Codex in the package install root used by packaged plugins", async () => {
+    const installRoot = path.join("/tmp", "openclaw-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("fails clearly when the managed Codex binary is missing", async () => {
+    await expect(
+      resolveManagedCodexAppServerStartOptions(startOptions("managed"), {
+        platform: "darwin",
+        pluginRoot: path.join("/tmp", "openclaw", "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,121 @@
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+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_PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+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 = [
+    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));
+  return [...new Set(roots.map((root) => pathApi.join(root, "node_modules", ".bin", commandName)))];
+}
+
+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 OpenClaw, or run pnpm install in a source checkout.",
+      "Set plugins.entries.codex.config.appServer.command or OPENCLAW_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;
+  }
+}

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

@@ -0,0 +1,242 @@
+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),
+    startOptions: vi.fn(async ({ startOptions }) => startOptions),
+  };
+  const managedBinary = {
+    startOptions: vi.fn(async (startOptions) => startOptions),
+  };
+  const providerAuth = {
+    agentDir: vi.fn(() => "/tmp/openclaw-agent"),
+  };
+  return { authBridge, managedBinary, providerAuth };
+});
+
+vi.mock("./auth-bridge.js", () => ({
+  applyCodexAppServerAuthProfile: mocks.authBridge.applyAuthProfile,
+  bridgeCodexAppServerStartOptions: mocks.authBridge.startOptions,
+}));
+
+vi.mock("./managed-binary.js", () => ({
+  resolveManagedCodexAppServerStartOptions: mocks.managedBinary.startOptions,
+}));
+
+vi.mock("openclaw/plugin-sdk/provider-auth", () => ({
+  resolveOpenClawAgentDir: 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.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: "openclaw/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: "openclaw/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,
+      },
+    });
+
+    await expect(listPromise).resolves.toMatchObject({
+      models: [{ id: "gpt-5.4" }, { id: "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: "openclaw/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",
+      },
+    });
+
+    await expect(listPromise).resolves.toMatchObject({
+      models: [{ id: "gpt-5.4" }],
+      nextCursor: "page-2",
+      truncated: true,
+    });
+    harness.client.close();
+    startSpy.mockRestore();
+  });
+});

package/src/app-server/models.ts

@@ -0,0 +1,168 @@
+import type { CodexAppServerClient } from "./client.js";
+import type { CodexAppServerStartOptions } from "./config.js";
+import type { v2 } from "./protocol-generated/typescript/index.js";
+import { readCodexModelListResponse } from "./protocol-validators.js";
+
+export type CodexAppServerModel = {
+  id: string;
+  model: string;
+  displayName?: string;
+  description?: string;
+  hidden?: boolean;
+  isDefault?: boolean;
+  inputModalities: string[];
+  supportedReasoningEfforts: string[];
+  defaultReasoningEffort?: string;
+};
+
+export type CodexAppServerModelListResult = {
+  models: CodexAppServerModel[];
+  nextCursor?: string;
+  truncated?: boolean;
+};
+
+export type CodexAppServerListModelsOptions = {
+  limit?: number;
+  cursor?: string;
+  includeHidden?: boolean;
+  timeoutMs?: number;
+  startOptions?: CodexAppServerStartOptions;
+  authProfileId?: string;
+  agentDir?: string;
+  sharedClient?: boolean;
+};
+
+export async function listCodexAppServerModels(
+  options: CodexAppServerListModelsOptions = {},
+): Promise<CodexAppServerModelListResult> {
+  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) =>
+    requestModelListPage(client, { ...options, timeoutMs }),
+  );
+}
+
+export async function listAllCodexAppServerModels(
+  options: CodexAppServerListModelsOptions & { maxPages?: number } = {},
+): Promise<CodexAppServerModelListResult> {
+  const maxPages = normalizeMaxPages(options.maxPages);
+  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) => {
+    const models: CodexAppServerModel[] = [];
+    let cursor = options.cursor;
+    let nextCursor: string | undefined;
+    for (let page = 0; page < maxPages; page += 1) {
+      const result = await requestModelListPage(client, {
+        ...options,
+        timeoutMs,
+        cursor,
+      });
+      models.push(...result.models);
+      nextCursor = result.nextCursor;
+      if (!nextCursor) {
+        return { models };
+      }
+      cursor = nextCursor;
+    }
+    return { models, nextCursor, truncated: true };
+  });
+}
+
+async function withCodexAppServerModelClient<T>(
+  options: CodexAppServerListModelsOptions,
+  run: (params: { client: CodexAppServerClient; timeoutMs: number }) => Promise<T>,
+): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? 2500;
+  const useSharedClient = options.sharedClient !== false;
+  const { createIsolatedCodexAppServerClient, getSharedCodexAppServerClient } =
+    await import("./shared-client.js");
+  const client = useSharedClient
+    ? await getSharedCodexAppServerClient({
+        startOptions: options.startOptions,
+        timeoutMs,
+        authProfileId: options.authProfileId,
+        agentDir: options.agentDir,
+      })
+    : await createIsolatedCodexAppServerClient({
+        startOptions: options.startOptions,
+        timeoutMs,
+        authProfileId: options.authProfileId,
+        agentDir: options.agentDir,
+      });
+  try {
+    return await run({ client, timeoutMs });
+  } finally {
+    if (!useSharedClient) {
+      client.close();
+    }
+  }
+}
+
+async function requestModelListPage(
+  client: CodexAppServerClient,
+  options: CodexAppServerListModelsOptions & { timeoutMs: number },
+): Promise<CodexAppServerModelListResult> {
+  const response = await client.request(
+    "model/list",
+    {
+      limit: options.limit ?? null,
+      cursor: options.cursor ?? null,
+      includeHidden: options.includeHidden ?? null,
+    },
+    { timeoutMs: options.timeoutMs },
+  );
+  return readModelListResult(response);
+}
+
+export function readModelListResult(value: unknown): CodexAppServerModelListResult {
+  const response = readCodexModelListResponse(value);
+  if (!response) {
+    return { models: [] };
+  }
+  const models = response.data
+    .map((entry) => readCodexModel(entry))
+    .filter((entry): entry is CodexAppServerModel => entry !== undefined);
+  const nextCursor = response.nextCursor ?? undefined;
+  return { models, ...(nextCursor ? { nextCursor } : {}) };
+}
+
+function readCodexModel(value: v2.Model): CodexAppServerModel | undefined {
+  const id = readNonEmptyString(value.id);
+  const model = readNonEmptyString(value.model) ?? id;
+  if (!id || !model) {
+    return undefined;
+  }
+  return {
+    id,
+    model,
+    ...(readNonEmptyString(value.displayName)
+      ? { displayName: readNonEmptyString(value.displayName) }
+      : {}),
+    ...(readNonEmptyString(value.description)
+      ? { description: readNonEmptyString(value.description) }
+      : {}),
+    hidden: value.hidden,
+    isDefault: value.isDefault,
+    inputModalities: value.inputModalities,
+    supportedReasoningEfforts: readReasoningEfforts(value.supportedReasoningEfforts),
+    ...(readNonEmptyString(value.defaultReasoningEffort)
+      ? { defaultReasoningEffort: readNonEmptyString(value.defaultReasoningEffort) }
+      : {}),
+  };
+}
+
+function readReasoningEfforts(value: v2.ReasoningEffortOption[]): string[] {
+  const efforts = value
+    .map((entry) => readNonEmptyString(entry.reasoningEffort))
+    .filter((entry): entry is string => entry !== undefined);
+  return [...new Set(efforts)];
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function normalizeMaxPages(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 20;
+}