@openclaw/codex 2026.5.1-beta.1

package/src/app-server/run-attempt.vision-tools.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { filterToolsForVisionInputs } from "./vision-tools.js";
+
+describe("Codex dynamic tool filtering", () => {
+  it("drops the image tool when the model already has inbound vision input", () => {
+    const toolNames = filterToolsForVisionInputs(
+      [{ name: "image" }, { name: "read" }, { name: "write" }],
+      {
+        modelHasVision: true,
+        hasInboundImages: true,
+      },
+    ).map((tool) => tool.name);
+
+    expect(toolNames).toContain("read");
+    expect(toolNames).toContain("write");
+    expect(toolNames).not.toContain("image");
+  });
+
+  it("keeps the image tool unless both model vision and inbound images are present", () => {
+    const tools = [{ name: "image" }, { name: "read" }];
+
+    expect(
+      filterToolsForVisionInputs(tools, {
+        modelHasVision: false,
+        hasInboundImages: true,
+      }),
+    ).toBe(tools);
+    expect(
+      filterToolsForVisionInputs(tools, {
+        modelHasVision: true,
+        hasInboundImages: false,
+      }),
+    ).toBe(tools);
+  });
+});

package/src/app-server/schema-normalization-runtime-contract.test.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { EmbeddedRunAttemptParams } from "openclaw/plugin-sdk/agent-harness";
+import {
+  createParameterFreeTool,
+  createPermissiveTool,
+  normalizedParameterFreeSchema,
+} from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createCodexTestModel } from "./test-support.js";
+import { startOrResumeThread } from "./thread-lifecycle.js";
+
+let tempDir: string;
+
+function createParams(sessionFile: string, workspaceDir: string): EmbeddedRunAttemptParams {
+  return {
+    prompt: "hello",
+    sessionId: "session-1",
+    sessionKey: "agent:main:session-1",
+    sessionFile,
+    workspaceDir,
+    runId: "run-1",
+    provider: "codex",
+    modelId: "gpt-5.4",
+    model: createCodexTestModel("codex"),
+    thinkLevel: "medium",
+    disableTools: true,
+    timeoutMs: 5_000,
+    authStorage: {} as never,
+    modelRegistry: {} as never,
+  } as EmbeddedRunAttemptParams;
+}
+
+function createAppServerOptions(): Parameters<typeof startOrResumeThread>[0]["appServer"] {
+  return {
+    start: {
+      transport: "stdio",
+      command: "codex",
+      args: ["app-server"],
+      headers: {},
+    },
+    requestTimeoutMs: 60_000,
+    approvalPolicy: "never",
+    approvalsReviewer: "user",
+    sandbox: "workspace-write",
+  };
+}
+
+function threadStartResult(threadId = "thread-1") {
+  return {
+    thread: {
+      id: threadId,
+      forkedFromId: null,
+      preview: "",
+      ephemeral: false,
+      modelProvider: "openai",
+      createdAt: 1,
+      updatedAt: 1,
+      status: { type: "idle" },
+      path: null,
+      cwd: tempDir,
+      cliVersion: "0.125.0",
+      source: "unknown",
+      agentNickname: null,
+      agentRole: null,
+      gitInfo: null,
+      name: null,
+      turns: [],
+    },
+    model: "gpt-5.4",
+    modelProvider: "openai",
+    serviceTier: null,
+    cwd: tempDir,
+    instructionSources: [],
+    approvalPolicy: "never",
+    approvalsReviewer: "user",
+    sandbox: { type: "dangerFullAccess" },
+    permissionProfile: null,
+    reasoningEffort: null,
+  };
+}
+
+describe("Codex app-server dynamic tool schema boundary contract", () => {
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-schema-contract-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("passes prepared executable dynamic tool schemas through thread start unchanged", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const workspaceDir = path.join(tempDir, "workspace");
+    const parameterFreeTool = createParameterFreeTool("message");
+    const dynamicTool = {
+      name: parameterFreeTool.name,
+      description: parameterFreeTool.description,
+      inputSchema: normalizedParameterFreeSchema(),
+    };
+    const request = vi.fn(async (method: string) => {
+      if (method === "thread/start") {
+        return threadStartResult();
+      }
+      throw new Error(`unexpected method: ${method}`);
+    });
+
+    await startOrResumeThread({
+      client: { request } as never,
+      params: createParams(sessionFile, workspaceDir),
+      cwd: workspaceDir,
+      dynamicTools: [dynamicTool],
+      appServer: createAppServerOptions(),
+    });
+
+    expect(request).toHaveBeenCalledWith(
+      "thread/start",
+      expect.objectContaining({
+        dynamicTools: [dynamicTool],
+      }),
+    );
+  });
+
+  it("treats dynamic tool schema changes as thread-fingerprint changes", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const workspaceDir = path.join(tempDir, "workspace");
+    const appServer = createAppServerOptions();
+    let nextThreadId = 1;
+    const request = vi.fn(async (method: string) => {
+      if (method === "thread/start") {
+        return threadStartResult(`thread-${nextThreadId++}`);
+      }
+      throw new Error(`unexpected method: ${method}`);
+    });
+
+    await startOrResumeThread({
+      client: { request } as never,
+      params: createParams(sessionFile, workspaceDir),
+      cwd: workspaceDir,
+      dynamicTools: [
+        {
+          name: "message",
+          description: "Permissive test tool",
+          inputSchema: { type: "object" },
+        },
+      ],
+      appServer,
+    });
+    const permissiveTool = createPermissiveTool("message");
+    await startOrResumeThread({
+      client: { request } as never,
+      params: createParams(sessionFile, workspaceDir),
+      cwd: workspaceDir,
+      dynamicTools: [
+        {
+          name: permissiveTool.name,
+          description: permissiveTool.description,
+          inputSchema: permissiveTool.parameters,
+        },
+      ],
+      appServer,
+    });
+
+    expect(request.mock.calls.map(([method]) => method)).toEqual(["thread/start", "thread/start"]);
+  });
+});

package/src/app-server/session-binding.test.ts

@@ -0,0 +1,52 @@
+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 {
+  clearCodexAppServerBinding,
+  readCodexAppServerBinding,
+  resolveCodexAppServerBindingPath,
+  writeCodexAppServerBinding,
+} from "./session-binding.js";
+
+let tempDir: string;
+
+describe("codex app-server session 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("round-trips the thread binding beside the PI session file", async () => {
+    const sessionFile = path.join(tempDir, "session.json");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-123",
+      cwd: tempDir,
+      model: "gpt-5.4-codex",
+      modelProvider: "openai",
+      dynamicToolsFingerprint: "tools-v1",
+    });
+
+    const binding = await readCodexAppServerBinding(sessionFile);
+
+    expect(binding).toMatchObject({
+      schemaVersion: 1,
+      threadId: "thread-123",
+      sessionFile,
+      cwd: tempDir,
+      model: "gpt-5.4-codex",
+      modelProvider: "openai",
+      dynamicToolsFingerprint: "tools-v1",
+    });
+    await expect(fs.stat(resolveCodexAppServerBindingPath(sessionFile))).resolves.toBeTruthy();
+  });
+
+  it("clears missing bindings without throwing", async () => {
+    const sessionFile = path.join(tempDir, "missing.json");
+    await clearCodexAppServerBinding(sessionFile);
+    await expect(readCodexAppServerBinding(sessionFile)).resolves.toBeUndefined();
+  });
+});

package/src/app-server/session-binding.ts

@@ -0,0 +1,131 @@
+import fs from "node:fs/promises";
+import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { CodexAppServerApprovalPolicy, CodexAppServerSandboxMode } from "./config.js";
+import type { CodexServiceTier } from "./protocol.js";
+
+export type CodexAppServerThreadBinding = {
+  schemaVersion: 1;
+  threadId: string;
+  sessionFile: string;
+  cwd: string;
+  authProfileId?: string;
+  model?: string;
+  modelProvider?: string;
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+  serviceTier?: CodexServiceTier;
+  dynamicToolsFingerprint?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export function resolveCodexAppServerBindingPath(sessionFile: string): string {
+  return `${sessionFile}.codex-app-server.json`;
+}
+
+export async function readCodexAppServerBinding(
+  sessionFile: string,
+): Promise<CodexAppServerThreadBinding | undefined> {
+  const path = resolveCodexAppServerBindingPath(sessionFile);
+  let raw: string;
+  try {
+    raw = await fs.readFile(path, "utf8");
+  } catch (error) {
+    if (isNotFound(error)) {
+      return undefined;
+    }
+    embeddedAgentLog.warn("failed to read codex app-server binding", { path, error });
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<CodexAppServerThreadBinding>;
+    if (parsed.schemaVersion !== 1 || typeof parsed.threadId !== "string") {
+      return undefined;
+    }
+    return {
+      schemaVersion: 1,
+      threadId: parsed.threadId,
+      sessionFile,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : "",
+      authProfileId: typeof parsed.authProfileId === "string" ? parsed.authProfileId : undefined,
+      model: typeof parsed.model === "string" ? parsed.model : undefined,
+      modelProvider: typeof parsed.modelProvider === "string" ? parsed.modelProvider : undefined,
+      approvalPolicy: readApprovalPolicy(parsed.approvalPolicy),
+      sandbox: readSandboxMode(parsed.sandbox),
+      serviceTier: readServiceTier(parsed.serviceTier),
+      dynamicToolsFingerprint:
+        typeof parsed.dynamicToolsFingerprint === "string"
+          ? parsed.dynamicToolsFingerprint
+          : undefined,
+      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : new Date().toISOString(),
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date().toISOString(),
+    };
+  } catch (error) {
+    embeddedAgentLog.warn("failed to parse codex app-server binding", { path, error });
+    return undefined;
+  }
+}
+
+export async function writeCodexAppServerBinding(
+  sessionFile: string,
+  binding: Omit<
+    CodexAppServerThreadBinding,
+    "schemaVersion" | "sessionFile" | "createdAt" | "updatedAt"
+  > & {
+    createdAt?: string;
+  },
+): Promise<void> {
+  const now = new Date().toISOString();
+  const payload: CodexAppServerThreadBinding = {
+    schemaVersion: 1,
+    sessionFile,
+    threadId: binding.threadId,
+    cwd: binding.cwd,
+    authProfileId: binding.authProfileId,
+    model: binding.model,
+    modelProvider: binding.modelProvider,
+    approvalPolicy: binding.approvalPolicy,
+    sandbox: binding.sandbox,
+    serviceTier: binding.serviceTier,
+    dynamicToolsFingerprint: binding.dynamicToolsFingerprint,
+    createdAt: binding.createdAt ?? now,
+    updatedAt: now,
+  };
+  await fs.writeFile(
+    resolveCodexAppServerBindingPath(sessionFile),
+    `${JSON.stringify(payload, null, 2)}\n`,
+  );
+}
+
+export async function clearCodexAppServerBinding(sessionFile: string): Promise<void> {
+  try {
+    await fs.unlink(resolveCodexAppServerBindingPath(sessionFile));
+  } catch (error) {
+    if (!isNotFound(error)) {
+      embeddedAgentLog.warn("failed to clear codex app-server binding", { sessionFile, error });
+    }
+  }
+}
+
+function isNotFound(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function readApprovalPolicy(value: unknown): CodexAppServerApprovalPolicy | undefined {
+  return value === "never" ||
+    value === "on-request" ||
+    value === "on-failure" ||
+    value === "untrusted"
+    ? value
+    : undefined;
+}
+
+function readSandboxMode(value: unknown): CodexAppServerSandboxMode | undefined {
+  return value === "read-only" || value === "workspace-write" || value === "danger-full-access"
+    ? value
+    : undefined;
+}
+
+function readServiceTier(value: unknown): CodexServiceTier | undefined {
+  return value === "fast" || value === "flex" ? value : undefined;
+}

package/src/app-server/session-history.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs/promises";
+import type { SessionEntry, SessionManager } from "@mariozechner/pi-coding-agent";
+import {
+  buildSessionContext,
+  migrateSessionEntries,
+  parseSessionEntries,
+} from "@mariozechner/pi-coding-agent";
+import type { AgentMessage } from "openclaw/plugin-sdk/agent-harness-runtime";
+
+function isMissingFileError(error: unknown): boolean {
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT",
+  );
+}
+
+export async function readCodexMirroredSessionHistoryMessages(
+  sessionFile: string,
+  sessionManager?: Pick<SessionManager, "buildSessionContext">,
+): Promise<AgentMessage[] | undefined> {
+  try {
+    if (sessionManager) {
+      return sessionManager.buildSessionContext().messages;
+    }
+    const raw = await fs.readFile(sessionFile, "utf-8");
+    const entries = parseSessionEntries(raw);
+    const firstEntry = entries[0] as { type?: unknown; id?: unknown } | undefined;
+    if (firstEntry?.type !== "session" || typeof firstEntry.id !== "string") {
+      return undefined;
+    }
+    migrateSessionEntries(entries);
+    const sessionEntries = entries.filter(
+      (entry): entry is SessionEntry => entry.type !== "session",
+    );
+    return buildSessionContext(sessionEntries).messages;
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return [];
+    }
+    return undefined;
+  }
+}