@openclaw/codex 2026.5.1-beta.1

package/harness.ts

@@ -0,0 +1,59 @@
+import type { AgentHarness } from "openclaw/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;
+}): 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?.pluginConfig });
+    },
+    compact: async (params) => {
+      const { maybeCompactCodexAppServerSession } = await import("./src/app-server/compact.js");
+      return maybeCompactCodexAppServerSession(params, { pluginConfig: 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,106 @@
+import fs from "node:fs";
+import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
+import { describe, expect, it, vi } from "vitest";
+import { createCodexAppServerAgentHarness } from "./harness.js";
+import plugin from "./index.js";
+
+describe("codex plugin", () => {
+  it("is opt-in by default", () => {
+    const manifest = JSON.parse(
+      fs.readFileSync(new URL("./openclaw.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,
+      }),
+    );
+
+    expect(registerProvider.mock.calls[0]?.[0]).toMatchObject({ id: "codex", label: "Codex" });
+    expect(registerAgentHarness.mock.calls[0]?.[0]).toMatchObject({
+      id: "codex",
+      label: "Codex agent harness",
+      deliveryDefaults: { sourceVisibleReplies: "message_tool" },
+      dispose: expect.any(Function),
+    });
+    expect(registerMediaUnderstandingProvider.mock.calls[0]?.[0]).toMatchObject({
+      id: "codex",
+      capabilities: ["image"],
+      defaultModels: { image: "gpt-5.5" },
+      describeImage: expect.any(Function),
+      describeImages: expect.any(Function),
+    });
+    expect(registerCommand.mock.calls[0]?.[0]).toMatchObject({
+      name: "codex",
+      description: "Inspect and control the Codex app-server harness",
+    });
+    expect(registerMigrationProvider.mock.calls[0]?.[0]).toMatchObject({
+      id: "codex",
+      label: "Codex",
+    });
+    expect(on).toHaveBeenCalledWith("inbound_claim", expect.any(Function));
+    expect(onConversationBindingResolved).toHaveBeenCalledWith(expect.any(Function));
+  });
+
+  it("registers with capture APIs that do not expose conversation binding hooks yet", () => {
+    const api = createTestPluginApi({
+      id: "codex",
+      name: "Codex",
+      source: "test",
+      config: {},
+      pluginConfig: {},
+      runtime: {} as never,
+      registerAgentHarness: vi.fn(),
+      registerCommand: vi.fn(),
+      registerMediaUnderstandingProvider: vi.fn(),
+      registerProvider: vi.fn(),
+      on: vi.fn(),
+    }) as ReturnType<typeof createTestPluginApi> & {
+      onConversationBindingResolved?: ReturnType<typeof vi.fn>;
+    };
+    delete (api as { onConversationBindingResolved?: unknown }).onConversationBindingResolved;
+
+    expect(() => plugin.register(api)).not.toThrow();
+  });
+
+  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);
+    expect(
+      harness.supports({
+        provider: "openai-codex",
+        modelId: "gpt-5.4",
+        requestedRuntime: "auto",
+      }),
+    ).toMatchObject({ supported: false });
+  });
+});

package/index.ts

@@ -0,0 +1,41 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveLivePluginConfigObject } from "openclaw/plugin-sdk/plugin-config-runtime";
+import { definePluginEntry } from "openclaw/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";
+
+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 OpenClawConfig
+          : undefined,
+        "codex",
+        api.pluginConfig as Record<string, unknown>,
+      ) ?? api.pluginConfig;
+    api.registerAgentHarness(createCodexAppServerAgentHarness({ pluginConfig: api.pluginConfig }));
+    api.registerProvider(buildCodexProvider({ pluginConfig: api.pluginConfig }));
+    api.registerMediaUnderstandingProvider(
+      buildCodexMediaUnderstandingProvider({ pluginConfig: api.pluginConfig }),
+    );
+    api.registerMigrationProvider(buildCodexMigrationProvider());
+    api.registerCommand(createCodexCommand({ pluginConfig: api.pluginConfig }));
+    api.on("inbound_claim", (event, ctx) =>
+      handleCodexConversationInboundClaim(event, ctx, {
+        pluginConfig: resolveCurrentPluginConfig(),
+      }),
+    );
+    api.onConversationBindingResolved?.(handleCodexConversationBindingResolved);
+  },
+});

package/media-understanding-provider.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildCodexMediaUnderstandingProvider } from "./media-understanding-provider.js";
+import type { CodexAppServerClient } from "./src/app-server/client.js";
+import type { CodexServerNotification, JsonValue } from "./src/app-server/protocol.js";
+
+function codexModel(inputModalities: string[] = ["text", "image"]) {
+  return {
+    id: "gpt-5.4",
+    model: "gpt-5.4",
+    upgrade: null,
+    upgradeInfo: null,
+    availabilityNux: null,
+    displayName: "gpt-5.4",
+    description: "GPT-5.4",
+    hidden: false,
+    supportedReasoningEfforts: [{ reasoningEffort: "low", description: "fast" }],
+    defaultReasoningEffort: "low",
+    inputModalities,
+    supportsPersonality: false,
+    additionalSpeedTiers: [],
+    isDefault: true,
+  };
+}
+
+function threadStartResult() {
+  return {
+    thread: {
+      id: "thread-1",
+      forkedFromId: null,
+      preview: "",
+      ephemeral: true,
+      modelProvider: "openai",
+      createdAt: 1,
+      updatedAt: 1,
+      status: { type: "idle" },
+      path: null,
+      cwd: "/tmp/openclaw-agent",
+      cliVersion: "0.125.0",
+      source: "unknown",
+      agentNickname: null,
+      agentRole: null,
+      gitInfo: null,
+      name: null,
+      turns: [],
+    },
+    model: "gpt-5.4",
+    modelProvider: "openai",
+    serviceTier: null,
+    cwd: "/tmp/openclaw-agent",
+    instructionSources: [],
+    approvalPolicy: "on-request",
+    approvalsReviewer: "user",
+    sandbox: { type: "dangerFullAccess" },
+    permissionProfile: null,
+    reasoningEffort: null,
+  };
+}
+
+function turnStartResult(status = "inProgress", items: JsonValue[] = []) {
+  return {
+    turn: {
+      id: "turn-1",
+      status,
+      items,
+      error: null,
+      startedAt: null,
+      completedAt: null,
+      durationMs: null,
+    },
+  };
+}
+
+function createFakeClient(options?: {
+  inputModalities?: string[];
+  completeWithItems?: boolean;
+  notifyError?: string;
+  approvalRequestMethod?: string;
+}) {
+  const notifications = new Set<(notification: CodexServerNotification) => void>();
+  const requestHandlers = new Set<(request: { method: string }) => JsonValue | undefined>();
+  const requests: Array<{ method: string; params?: JsonValue }> = [];
+  const approvalResponses: JsonValue[] = [];
+  const request = vi.fn(async (method: string, params?: JsonValue) => {
+    requests.push({ method, params });
+    if (method === "model/list") {
+      return {
+        data: [codexModel(options?.inputModalities)],
+        nextCursor: null,
+      };
+    }
+    if (method === "thread/start") {
+      return threadStartResult();
+    }
+    if (method === "turn/start") {
+      if (options?.approvalRequestMethod) {
+        for (const handler of requestHandlers) {
+          const response = handler({ method: options.approvalRequestMethod });
+          if (response !== undefined) {
+            approvalResponses.push(response);
+          }
+        }
+      }
+      if (options?.notifyError) {
+        for (const notify of notifications) {
+          notify({
+            method: "error",
+            params: {
+              threadId: "thread-1",
+              turnId: "turn-1",
+              error: {
+                message: options.notifyError,
+                codexErrorInfo: null,
+                additionalDetails: null,
+              },
+              willRetry: false,
+            },
+          });
+        }
+      } else if (!options?.completeWithItems) {
+        for (const notify of notifications) {
+          notify({
+            method: "item/agentMessage/delta",
+            params: {
+              threadId: "thread-1",
+              turnId: "turn-1",
+              itemId: "msg-1",
+              delta: "A red square.",
+            },
+          });
+          notify({
+            method: "turn/completed",
+            params: {
+              threadId: "thread-1",
+              turnId: "turn-1",
+              turn: turnStartResult("completed").turn,
+            },
+          });
+        }
+      }
+      return turnStartResult(
+        options?.completeWithItems ? "completed" : "inProgress",
+        options?.completeWithItems
+          ? [
+              {
+                id: "msg-1",
+                type: "agentMessage",
+                text: "A blue circle.",
+                phase: null,
+                memoryCitation: null,
+              },
+            ]
+          : [],
+      );
+    }
+    return {};
+  });
+
+  const client = {
+    request,
+    addNotificationHandler(handler: (notification: CodexServerNotification) => void) {
+      notifications.add(handler);
+      return () => notifications.delete(handler);
+    },
+    addRequestHandler(handler: (request: { method: string }) => JsonValue | undefined) {
+      requestHandlers.add(handler);
+      return () => requestHandlers.delete(handler);
+    },
+  } as unknown as CodexAppServerClient;
+
+  return { client, requests, approvalResponses };
+}
+
+describe("codex media understanding provider", () => {
+  it("runs image understanding through a bounded Codex app-server turn", async () => {
+    const { client, requests } = createFakeClient();
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientFactory: async () => client,
+    });
+
+    const result = await provider.describeImage?.({
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      prompt: "Describe briefly.",
+      timeoutMs: 30_000,
+      cfg: {},
+      agentDir: "/tmp/openclaw-agent",
+    });
+
+    expect(result).toEqual({ text: "A red square.", model: "gpt-5.4" });
+    expect(requests.map((entry) => entry.method)).toEqual([
+      "model/list",
+      "thread/start",
+      "turn/start",
+    ]);
+    expect(requests[1]?.params).toMatchObject({
+      model: "gpt-5.4",
+      modelProvider: "openai",
+      approvalPolicy: "on-request",
+      sandbox: "read-only",
+      dynamicTools: [],
+      ephemeral: true,
+      persistExtendedHistory: false,
+    });
+    expect(requests[2]?.params).toMatchObject({
+      threadId: "thread-1",
+      approvalPolicy: "on-request",
+      model: "gpt-5.4",
+      input: [
+        { type: "text", text: "Describe briefly.", text_elements: [] },
+        { type: "image", url: "data:image/png;base64,aW1hZ2UtYnl0ZXM=" },
+      ],
+    });
+  });
+
+  it("declines approval requests during image understanding", async () => {
+    const { client, approvalResponses } = createFakeClient({
+      approvalRequestMethod: "item/permissions/requestApproval",
+    });
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientFactory: async () => client,
+    });
+
+    await provider.describeImage?.({
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      prompt: "Describe briefly.",
+      timeoutMs: 30_000,
+      cfg: {},
+      agentDir: "/tmp/openclaw-agent",
+    });
+
+    expect(approvalResponses).toEqual([{ permissions: {}, scope: "turn" }]);
+  });
+
+  it("extracts text from terminal turn items", async () => {
+    const { client } = createFakeClient({ completeWithItems: true });
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientFactory: async () => client,
+    });
+
+    const result = await provider.describeImages?.({
+      images: [{ buffer: Buffer.from("image-bytes"), fileName: "image.png", mime: "image/png" }],
+      provider: "codex",
+      model: "gpt-5.4",
+      prompt: "Describe briefly.",
+      timeoutMs: 30_000,
+      cfg: {},
+      agentDir: "/tmp/openclaw-agent",
+    });
+
+    expect(result).toEqual({ text: "A blue circle.", model: "gpt-5.4" });
+  });
+
+  it("rejects text-only Codex app-server models before starting a turn", async () => {
+    const { client, requests } = createFakeClient({ inputModalities: ["text"] });
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientFactory: async () => client,
+    });
+
+    await expect(
+      provider.describeImage?.({
+        buffer: Buffer.from("image-bytes"),
+        fileName: "image.png",
+        mime: "image/png",
+        provider: "codex",
+        model: "gpt-5.4",
+        timeoutMs: 30_000,
+        cfg: {},
+        agentDir: "/tmp/openclaw-agent",
+      }),
+    ).rejects.toThrow("Codex app-server model does not support images: gpt-5.4");
+    expect(requests.map((entry) => entry.method)).toEqual(["model/list"]);
+  });
+
+  it("surfaces Codex app-server turn errors", async () => {
+    const { client } = createFakeClient({ notifyError: "vision unavailable" });
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientFactory: async () => client,
+    });
+
+    await expect(
+      provider.describeImage?.({
+        buffer: Buffer.from("image-bytes"),
+        fileName: "image.png",
+        mime: "image/png",
+        provider: "codex",
+        model: "gpt-5.4",
+        timeoutMs: 30_000,
+        cfg: {},
+        agentDir: "/tmp/openclaw-agent",
+      }),
+    ).rejects.toThrow("vision unavailable");
+  });
+});