@openclaw/codex 2026.5.2 → 2026.5.3-beta.2

package/src/commands.ts

@@ -1,32 +0,0 @@
-import type {
-  OpenClawPluginCommandDefinition,
-  PluginCommandContext,
-  PluginCommandResult,
-} from "openclaw/plugin-sdk/plugin-entry";
-import type { CodexCommandDeps } from "./command-handlers.js";
-
-export function createCodexCommand(options: {
-  pluginConfig?: unknown;
-  deps?: Partial<CodexCommandDeps>;
-}): OpenClawPluginCommandDefinition {
-  return {
-    name: "codex",
-    description: "Inspect and control the Codex app-server harness",
-    ownership: "reserved",
-    agentPromptGuidance: [
-      "Native Codex app-server plugin is available (`/codex ...`). For Codex bind/control/thread/resume/steer/stop requests, prefer `/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, and `/codex stop` over ACP.",
-      "Use ACP for Codex only when the user explicitly asks for ACP/acpx or wants to test the ACP path.",
-    ],
-    acceptsArgs: true,
-    requireAuth: true,
-    handler: (ctx) => handleCodexCommand(ctx, options),
-  };
-}
-
-export async function handleCodexCommand(
-  ctx: PluginCommandContext,
-  options: { pluginConfig?: unknown; deps?: Partial<CodexCommandDeps> } = {},
-): Promise<PluginCommandResult> {
-  const { handleCodexSubcommand } = await import("./command-handlers.js");
-  return await handleCodexSubcommand(ctx, options);
-}

package/src/conversation-binding-data.ts

@@ -1,72 +0,0 @@
-import process from "node:process";
-import type { PluginConversationBinding } from "openclaw/plugin-sdk/plugin-entry";
-
-const BINDING_DATA_VERSION = 1;
-
-export type CodexConversationBindingData = {
-  kind: "codex-app-server-session";
-  version: 1;
-  sessionFile: string;
-  workspaceDir: string;
-};
-
-export function createCodexConversationBindingData(params: {
-  sessionFile: string;
-  workspaceDir: string;
-}): CodexConversationBindingData {
-  return {
-    kind: "codex-app-server-session",
-    version: BINDING_DATA_VERSION,
-    sessionFile: params.sessionFile,
-    workspaceDir: params.workspaceDir,
-  };
-}
-
-export function readCodexConversationBindingData(
-  binding: PluginConversationBinding | null | undefined,
-): CodexConversationBindingData | undefined {
-  const data = binding?.data;
-  if (!data || typeof data !== "object" || Array.isArray(data)) {
-    return undefined;
-  }
-  return readCodexConversationBindingDataRecord(data);
-}
-
-export function readCodexConversationBindingDataRecord(
-  data: Record<string, unknown>,
-): CodexConversationBindingData | undefined {
-  if (
-    data.kind !== "codex-app-server-session" ||
-    data.version !== BINDING_DATA_VERSION ||
-    typeof data.sessionFile !== "string" ||
-    !data.sessionFile.trim()
-  ) {
-    return undefined;
-  }
-  return {
-    kind: "codex-app-server-session",
-    version: BINDING_DATA_VERSION,
-    sessionFile: data.sessionFile,
-    workspaceDir:
-      typeof data.workspaceDir === "string" && data.workspaceDir.trim()
-        ? data.workspaceDir
-        : process.cwd(),
-  };
-}
-
-export function resolveCodexDefaultWorkspaceDir(pluginConfig: unknown): string {
-  const appServer = readRecord(readRecord(pluginConfig)?.appServer);
-  const configured = readString(appServer, "defaultWorkspaceDir");
-  return configured ?? process.cwd();
-}
-
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-function readString(record: Record<string, unknown> | undefined, key: string) {
-  const value = record?.[key];
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}

package/src/conversation-binding.test.ts

@@ -1,76 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  handleCodexConversationBindingResolved,
-  handleCodexConversationInboundClaim,
-} from "./conversation-binding.js";
-
-let tempDir: string;
-
-describe("codex conversation binding", () => {
-  beforeEach(async () => {
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-binding-"));
-  });
-
-  afterEach(async () => {
-    await fs.rm(tempDir, { recursive: true, force: true });
-  });
-
-  it("clears the Codex app-server sidecar when a pending bind is denied", async () => {
-    const sessionFile = path.join(tempDir, "session.jsonl");
-    const sidecar = `${sessionFile}.codex-app-server.json`;
-    await fs.writeFile(sidecar, JSON.stringify({ schemaVersion: 1, threadId: "thread-1" }));
-
-    await handleCodexConversationBindingResolved({
-      status: "denied",
-      decision: "deny",
-      request: {
-        data: {
-          kind: "codex-app-server-session",
-          version: 1,
-          sessionFile,
-          workspaceDir: tempDir,
-        },
-        conversation: {
-          channel: "discord",
-          accountId: "default",
-          conversationId: "channel:1",
-        },
-      },
-    });
-
-    await expect(fs.stat(sidecar)).rejects.toMatchObject({ code: "ENOENT" });
-  });
-
-  it("consumes inbound bound messages when command authorization is absent", async () => {
-    const result = await handleCodexConversationInboundClaim(
-      {
-        content: "run this",
-        channel: "discord",
-        isGroup: true,
-      },
-      {
-        channelId: "discord",
-        pluginBinding: {
-          bindingId: "binding-1",
-          pluginId: "codex",
-          pluginRoot: tempDir,
-          channel: "discord",
-          accountId: "default",
-          conversationId: "channel-1",
-          boundAt: Date.now(),
-          data: {
-            kind: "codex-app-server-session",
-            version: 1,
-            sessionFile: path.join(tempDir, "session.jsonl"),
-            workspaceDir: tempDir,
-          },
-        },
-      },
-    );
-
-    expect(result).toEqual({ handled: true });
-  });
-});

package/src/conversation-binding.ts

@@ -1,351 +0,0 @@
-import { formatErrorMessage } from "openclaw/plugin-sdk/agent-harness-runtime";
-import type {
-  PluginConversationBindingResolvedEvent,
-  PluginHookInboundClaimContext,
-  PluginHookInboundClaimEvent,
-} from "openclaw/plugin-sdk/plugin-entry";
-import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
-import { CODEX_CONTROL_METHODS } from "./app-server/capabilities.js";
-import {
-  codexSandboxPolicyForTurn,
-  resolveCodexAppServerRuntimeOptions,
-} from "./app-server/config.js";
-import {
-  type CodexThreadResumeResponse,
-  type CodexThreadStartResponse,
-  type CodexTurnStartResponse,
-  type JsonValue,
-} from "./app-server/protocol.js";
-import {
-  clearCodexAppServerBinding,
-  readCodexAppServerBinding,
-  writeCodexAppServerBinding,
-} from "./app-server/session-binding.js";
-import { getSharedCodexAppServerClient } from "./app-server/shared-client.js";
-import {
-  createCodexConversationBindingData,
-  readCodexConversationBindingData,
-  readCodexConversationBindingDataRecord,
-  resolveCodexDefaultWorkspaceDir,
-  type CodexConversationBindingData,
-} from "./conversation-binding-data.js";
-import { trackCodexConversationActiveTurn } from "./conversation-control.js";
-import { createCodexConversationTurnCollector } from "./conversation-turn-collector.js";
-import { buildCodexConversationTurnInput } from "./conversation-turn-input.js";
-
-const DEFAULT_BOUND_TURN_TIMEOUT_MS = 20 * 60_000;
-
-export {
-  readCodexConversationBindingData,
-  resolveCodexDefaultWorkspaceDir,
-} from "./conversation-binding-data.js";
-
-type CodexConversationRunOptions = {
-  pluginConfig?: unknown;
-  timeoutMs?: number;
-};
-
-type CodexConversationStartParams = {
-  pluginConfig?: unknown;
-  sessionFile: string;
-  workspaceDir?: string;
-  threadId?: string;
-  model?: string;
-  modelProvider?: string;
-};
-
-type BoundTurnResult = {
-  reply: ReplyPayload;
-};
-
-type CodexConversationGlobalState = {
-  queues: Map<string, Promise<void>>;
-};
-
-const CODEX_CONVERSATION_GLOBAL_STATE = Symbol.for("openclaw.codex.conversationBinding");
-
-function getGlobalState(): CodexConversationGlobalState {
-  const globalState = globalThis as typeof globalThis & {
-    [CODEX_CONVERSATION_GLOBAL_STATE]?: CodexConversationGlobalState;
-  };
-  globalState[CODEX_CONVERSATION_GLOBAL_STATE] ??= { queues: new Map() };
-  return globalState[CODEX_CONVERSATION_GLOBAL_STATE];
-}
-
-export async function startCodexConversationThread(
-  params: CodexConversationStartParams,
-): Promise<CodexConversationBindingData> {
-  const workspaceDir =
-    params.workspaceDir?.trim() || resolveCodexDefaultWorkspaceDir(params.pluginConfig);
-  if (params.threadId?.trim()) {
-    await attachExistingThread({
-      pluginConfig: params.pluginConfig,
-      sessionFile: params.sessionFile,
-      threadId: params.threadId.trim(),
-      workspaceDir,
-      model: params.model,
-      modelProvider: params.modelProvider,
-    });
-  } else {
-    await createThread({
-      pluginConfig: params.pluginConfig,
-      sessionFile: params.sessionFile,
-      workspaceDir,
-      model: params.model,
-      modelProvider: params.modelProvider,
-    });
-  }
-  return createCodexConversationBindingData({
-    sessionFile: params.sessionFile,
-    workspaceDir,
-  });
-}
-
-export async function handleCodexConversationInboundClaim(
-  event: PluginHookInboundClaimEvent,
-  ctx: PluginHookInboundClaimContext,
-  options: CodexConversationRunOptions = {},
-): Promise<{ handled: boolean; reply?: ReplyPayload } | undefined> {
-  const data = readCodexConversationBindingData(ctx.pluginBinding);
-  if (!data) {
-    return undefined;
-  }
-  if (event.commandAuthorized !== true) {
-    return { handled: true };
-  }
-  const prompt = (event.bodyForAgent ?? event.content ?? "").trim();
-  if (!prompt) {
-    return { handled: true };
-  }
-  try {
-    const result = await enqueueBoundTurn(data.sessionFile, () =>
-      runBoundTurn({
-        data,
-        prompt,
-        event,
-        pluginConfig: options.pluginConfig,
-        timeoutMs: options.timeoutMs,
-      }),
-    );
-    return { handled: true, reply: result.reply };
-  } catch (error) {
-    return {
-      handled: true,
-      reply: {
-        text: `Codex app-server turn failed: ${formatErrorMessage(error)}`,
-      },
-    };
-  }
-}
-
-export async function handleCodexConversationBindingResolved(
-  event: PluginConversationBindingResolvedEvent,
-): Promise<void> {
-  if (event.status !== "denied") {
-    return;
-  }
-  const data = readCodexConversationBindingDataRecord(event.request.data ?? {});
-  if (!data) {
-    return;
-  }
-  await clearCodexAppServerBinding(data.sessionFile);
-}
-
-async function attachExistingThread(params: {
-  pluginConfig?: unknown;
-  sessionFile: string;
-  threadId: string;
-  workspaceDir: string;
-  model?: string;
-  modelProvider?: string;
-}): Promise<void> {
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-  });
-  const response: CodexThreadResumeResponse = await client.request(
-    CODEX_CONTROL_METHODS.resumeThread,
-    {
-      threadId: params.threadId,
-      ...(params.model ? { model: params.model } : {}),
-      ...(params.modelProvider ? { modelProvider: params.modelProvider } : {}),
-      approvalPolicy: runtime.approvalPolicy,
-      approvalsReviewer: runtime.approvalsReviewer,
-      sandbox: runtime.sandbox,
-      ...(runtime.serviceTier ? { serviceTier: runtime.serviceTier } : {}),
-      persistExtendedHistory: true,
-    },
-    { timeoutMs: runtime.requestTimeoutMs },
-  );
-  const thread = response.thread;
-  await writeCodexAppServerBinding(params.sessionFile, {
-    threadId: thread.id,
-    cwd: thread.cwd ?? params.workspaceDir,
-    model: response.model ?? params.model,
-    modelProvider: response.modelProvider ?? params.modelProvider,
-    approvalPolicy: runtime.approvalPolicy,
-    sandbox: runtime.sandbox,
-    serviceTier: runtime.serviceTier,
-  });
-}
-
-async function createThread(params: {
-  pluginConfig?: unknown;
-  sessionFile: string;
-  workspaceDir: string;
-  model?: string;
-  modelProvider?: string;
-}): Promise<void> {
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-  });
-  const response: CodexThreadStartResponse = await client.request(
-    "thread/start",
-    {
-      cwd: params.workspaceDir,
-      ...(params.model ? { model: params.model } : {}),
-      ...(params.modelProvider ? { modelProvider: params.modelProvider } : {}),
-      approvalPolicy: runtime.approvalPolicy,
-      approvalsReviewer: runtime.approvalsReviewer,
-      sandbox: runtime.sandbox,
-      ...(runtime.serviceTier ? { serviceTier: runtime.serviceTier } : {}),
-      developerInstructions:
-        "This Codex thread is bound to an OpenClaw conversation. Answer normally; OpenClaw will deliver your final response back to the conversation.",
-      experimentalRawEvents: true,
-      persistExtendedHistory: true,
-    },
-    { timeoutMs: runtime.requestTimeoutMs },
-  );
-  await writeCodexAppServerBinding(params.sessionFile, {
-    threadId: response.thread.id,
-    cwd: response.thread.cwd ?? params.workspaceDir,
-    model: response.model ?? params.model,
-    modelProvider: response.modelProvider ?? params.modelProvider,
-    approvalPolicy: runtime.approvalPolicy,
-    sandbox: runtime.sandbox,
-    serviceTier: runtime.serviceTier,
-  });
-}
-
-async function runBoundTurn(params: {
-  data: CodexConversationBindingData;
-  prompt: string;
-  event: PluginHookInboundClaimEvent;
-  pluginConfig?: unknown;
-  timeoutMs?: number;
-}): Promise<BoundTurnResult> {
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const binding = await readCodexAppServerBinding(params.data.sessionFile);
-  const threadId = binding?.threadId;
-  if (!threadId) {
-    throw new Error("bound Codex conversation has no thread binding");
-  }
-
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-    authProfileId: binding.authProfileId,
-  });
-  const collector = createCodexConversationTurnCollector(threadId);
-  const notificationCleanup = client.addNotificationHandler((notification) =>
-    collector.handleNotification(notification),
-  );
-  const requestCleanup = client.addRequestHandler(
-    async (request): Promise<JsonValue | undefined> => {
-      if (request.method === "item/tool/call") {
-        return {
-          contentItems: [
-            {
-              type: "inputText",
-              text: "OpenClaw native Codex conversation binding does not expose dynamic OpenClaw tools yet.",
-            },
-          ],
-          success: false,
-        };
-      }
-      if (
-        request.method === "item/commandExecution/requestApproval" ||
-        request.method === "item/fileChange/requestApproval"
-      ) {
-        return {
-          decision: "decline",
-          reason:
-            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
-        };
-      }
-      if (request.method === "item/permissions/requestApproval") {
-        return { permissions: {}, scope: "turn" };
-      }
-      if (request.method.includes("requestApproval")) {
-        return {
-          decision: "decline",
-          reason:
-            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
-        };
-      }
-      return undefined;
-    },
-  );
-  try {
-    const response: CodexTurnStartResponse = await client.request(
-      "turn/start",
-      {
-        threadId,
-        input: buildCodexConversationTurnInput({ prompt: params.prompt, event: params.event }),
-        cwd: binding.cwd || params.data.workspaceDir,
-        approvalPolicy: binding.approvalPolicy ?? runtime.approvalPolicy,
-        approvalsReviewer: runtime.approvalsReviewer,
-        sandboxPolicy: codexSandboxPolicyForTurn(
-          binding.sandbox ?? runtime.sandbox,
-          binding.cwd || params.data.workspaceDir,
-        ),
-        ...(binding.model ? { model: binding.model } : {}),
-        ...((binding.serviceTier ?? runtime.serviceTier)
-          ? { serviceTier: binding.serviceTier ?? runtime.serviceTier }
-          : {}),
-      },
-      { timeoutMs: runtime.requestTimeoutMs },
-    );
-    const turnId = response.turn.id;
-    const activeCleanup = trackCodexConversationActiveTurn({
-      sessionFile: params.data.sessionFile,
-      threadId,
-      turnId,
-    });
-    collector.setTurnId(turnId);
-    const completion = await collector
-      .wait({
-        timeoutMs: params.timeoutMs ?? DEFAULT_BOUND_TURN_TIMEOUT_MS,
-      })
-      .finally(activeCleanup);
-    const replyText = completion.replyText.trim();
-    return {
-      reply: {
-        text: replyText || "Codex completed without a text reply.",
-      },
-    };
-  } finally {
-    notificationCleanup();
-    requestCleanup();
-  }
-}
-
-function enqueueBoundTurn<T>(key: string, run: () => Promise<T>): Promise<T> {
-  const state = getGlobalState();
-  const previous = state.queues.get(key) ?? Promise.resolve();
-  const next = previous.then(run, run);
-  const queued = next.then(
-    () => undefined,
-    () => undefined,
-  );
-  state.queues.set(key, queued);
-  void next.finally(() => {
-    if (state.queues.get(key) === queued) {
-      state.queues.delete(key);
-    }
-  });
-  return next;
-}

package/src/conversation-control.test.ts

@@ -1,50 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  readCodexAppServerBinding,
-  writeCodexAppServerBinding,
-} from "./app-server/session-binding.js";
-import {
-  setCodexConversationFastMode,
-  setCodexConversationPermissions,
-} from "./conversation-control.js";
-
-let tempDir: string;
-
-describe("codex conversation controls", () => {
-  beforeEach(async () => {
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-control-"));
-  });
-
-  afterEach(async () => {
-    await fs.rm(tempDir, { recursive: true, force: true });
-  });
-
-  it("persists fast mode and permissions for later bound turns", async () => {
-    const sessionFile = path.join(tempDir, "session.jsonl");
-    await writeCodexAppServerBinding(sessionFile, {
-      threadId: "thread-1",
-      cwd: tempDir,
-      model: "gpt-5.4",
-      modelProvider: "openai",
-      approvalPolicy: "never",
-      sandbox: "danger-full-access",
-    });
-
-    await expect(setCodexConversationFastMode({ sessionFile, enabled: true })).resolves.toBe(
-      "Codex fast mode enabled.",
-    );
-    await expect(setCodexConversationPermissions({ sessionFile, mode: "default" })).resolves.toBe(
-      "Codex permissions set to default.",
-    );
-
-    await expect(readCodexAppServerBinding(sessionFile)).resolves.toMatchObject({
-      threadId: "thread-1",
-      serviceTier: "fast",
-      approvalPolicy: "on-request",
-      sandbox: "workspace-write",
-    });
-  });
-});