@openclaw/codex 2026.5.1-beta.1

package/src/app-server/transcript-mirror.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { CURRENT_SESSION_VERSION, type SessionManager } from "@mariozechner/pi-coding-agent";
+import {
+  acquireSessionWriteLock,
+  emitSessionTranscriptUpdate,
+  runAgentHarnessBeforeMessageWriteHook,
+  type AgentMessage,
+} from "openclaw/plugin-sdk/agent-harness-runtime";
+
+const TRANSCRIPT_APPEND_SCAN_CHUNK_BYTES = 64 * 1024;
+const SESSION_MANAGER_APPEND_MAX_BYTES = 8 * 1024 * 1024;
+
+type TranscriptLeafInfo = {
+  leafId?: string;
+  hasParentLinkedEntries: boolean;
+  nonSessionEntryCount: number;
+};
+
+export async function mirrorCodexAppServerTranscript(params: {
+  sessionFile: string;
+  sessionKey?: string;
+  agentId?: string;
+  messages: AgentMessage[];
+  idempotencyScope?: string;
+}): Promise<void> {
+  const messages = params.messages.filter(
+    (message) => message.role === "user" || message.role === "assistant",
+  );
+  if (messages.length === 0) {
+    return;
+  }
+
+  await fs.mkdir(path.dirname(params.sessionFile), { recursive: true });
+  const lock = await acquireSessionWriteLock({
+    sessionFile: params.sessionFile,
+    timeoutMs: 10_000,
+  });
+  try {
+    const existingIdempotencyKeys = await readTranscriptIdempotencyKeys(params.sessionFile);
+    for (const [index, message] of messages.entries()) {
+      const idempotencyKey = params.idempotencyScope
+        ? `${params.idempotencyScope}:${message.role}:${index}`
+        : undefined;
+      if (idempotencyKey && existingIdempotencyKeys.has(idempotencyKey)) {
+        continue;
+      }
+      const transcriptMessage = {
+        ...message,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+      } as Parameters<SessionManager["appendMessage"]>[0];
+      const nextMessage = runAgentHarnessBeforeMessageWriteHook({
+        message: transcriptMessage,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+      });
+      if (!nextMessage) {
+        continue;
+      }
+      const messageToAppend = (idempotencyKey
+        ? {
+            ...(nextMessage as unknown as Record<string, unknown>),
+            idempotencyKey,
+          }
+        : nextMessage) as unknown as Parameters<SessionManager["appendMessage"]>[0];
+      await appendCodexAppServerTranscriptMessage({
+        transcriptPath: params.sessionFile,
+        message: messageToAppend,
+      });
+      if (idempotencyKey) {
+        existingIdempotencyKeys.add(idempotencyKey);
+      }
+    }
+  } finally {
+    await lock.release();
+  }
+
+  if (params.sessionKey) {
+    emitSessionTranscriptUpdate({ sessionFile: params.sessionFile, sessionKey: params.sessionKey });
+  } else {
+    emitSessionTranscriptUpdate(params.sessionFile);
+  }
+}
+
+async function appendCodexAppServerTranscriptMessage(params: {
+  transcriptPath: string;
+  message: unknown;
+}): Promise<void> {
+  await ensureTranscriptHeader(params.transcriptPath);
+  const stat = await fs.stat(params.transcriptPath).catch(() => null);
+  let leafInfo: TranscriptLeafInfo = await readTranscriptLeafInfo(params.transcriptPath).catch(
+    () => ({
+      hasParentLinkedEntries: false,
+      nonSessionEntryCount: 0,
+    }),
+  );
+  const hasLinearEntries = !leafInfo.hasParentLinkedEntries && leafInfo.nonSessionEntryCount > 0;
+  const shouldRawAppend = hasLinearEntries && (stat?.size ?? 0) > SESSION_MANAGER_APPEND_MAX_BYTES;
+  if (hasLinearEntries && !shouldRawAppend) {
+    const migrated = await migrateLinearTranscriptToParentLinked(params.transcriptPath);
+    leafInfo = {
+      ...(migrated.leafId ? { leafId: migrated.leafId } : {}),
+      hasParentLinkedEntries: Boolean(migrated.leafId),
+      nonSessionEntryCount: leafInfo.nonSessionEntryCount,
+    };
+  }
+  const entry = {
+    type: "message",
+    id: randomUUID(),
+    ...(shouldRawAppend ? {} : { parentId: leafInfo.leafId ?? null }),
+    timestamp: new Date().toISOString(),
+    message: params.message,
+  };
+  await fs.appendFile(params.transcriptPath, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+async function ensureTranscriptHeader(transcriptPath: string): Promise<void> {
+  const stat = await fs.stat(transcriptPath).catch(() => null);
+  if (stat?.isFile() && stat.size > 0) {
+    return;
+  }
+  await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+  const header = {
+    type: "session",
+    version: CURRENT_SESSION_VERSION,
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    cwd: process.cwd(),
+  };
+  await fs.writeFile(transcriptPath, `${JSON.stringify(header)}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+    flag: stat?.isFile() ? "w" : "wx",
+  });
+}
+
+async function readTranscriptLeafInfo(transcriptPath: string): Promise<TranscriptLeafInfo> {
+  const handle = await fs.open(transcriptPath, "r");
+  try {
+    const decoder = new StringDecoder("utf8");
+    const buffer = Buffer.allocUnsafe(TRANSCRIPT_APPEND_SCAN_CHUNK_BYTES);
+    let carry = "";
+    let leafId: string | undefined;
+    let hasParentLinkedEntries = false;
+    let nonSessionEntryCount = 0;
+    while (true) {
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+      if (bytesRead <= 0) {
+        break;
+      }
+      const text = carry + decoder.write(buffer.subarray(0, bytesRead));
+      const lines = text.split(/\r?\n/);
+      carry = lines.pop() ?? "";
+      for (const line of lines) {
+        if (lineHasNonSessionEntry(line)) {
+          nonSessionEntryCount += 1;
+        }
+        const id = lineParentLinkedEntryId(line);
+        if (id) {
+          leafId = id;
+          hasParentLinkedEntries = true;
+        }
+      }
+      await yieldTranscriptAppendScan();
+    }
+    const tail = carry + decoder.end();
+    if (lineHasNonSessionEntry(tail)) {
+      nonSessionEntryCount += 1;
+    }
+    const id = lineParentLinkedEntryId(tail);
+    if (id) {
+      leafId = id;
+      hasParentLinkedEntries = true;
+    }
+    return {
+      ...(leafId ? { leafId } : {}),
+      hasParentLinkedEntries,
+      nonSessionEntryCount,
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
+async function migrateLinearTranscriptToParentLinked(transcriptPath: string): Promise<{
+  leafId?: string;
+}> {
+  const raw = await fs.readFile(transcriptPath, "utf-8");
+  const existingIds = new Set<string>();
+  const output: string[] = [];
+  let previousId: string | null = null;
+  let leafId: string | undefined;
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      output.push(line);
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      output.push(line);
+      continue;
+    }
+    const record = parsed as Record<string, unknown>;
+    if (record.type === "session") {
+      output.push(JSON.stringify({ ...record, version: CURRENT_SESSION_VERSION }));
+      continue;
+    }
+    const id = normalizeEntryId(record.id) ?? generateEntryId(existingIds);
+    existingIds.add(id);
+    record.id = id;
+    if (!Object.hasOwn(record, "parentId")) {
+      record.parentId = previousId;
+    }
+    previousId = id;
+    leafId = id;
+    output.push(JSON.stringify(record));
+  }
+  await fs.writeFile(transcriptPath, `${output.join("\n")}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  const result: { leafId?: string } = {};
+  if (leafId) {
+    result.leafId = leafId;
+  }
+  return result;
+}
+
+function normalizeEntryId(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function generateEntryId(existingIds: Set<string>): string {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const id = randomUUID().slice(0, 8);
+    if (!existingIds.has(id)) {
+      existingIds.add(id);
+      return id;
+    }
+  }
+  const id = randomUUID();
+  existingIds.add(id);
+  return id;
+}
+
+function lineHasNonSessionEntry(line: string): boolean {
+  if (!line.trim()) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(line) as { type?: unknown };
+    return parsed.type !== "session";
+  } catch {
+    return false;
+  }
+}
+
+function lineParentLinkedEntryId(line: string): string | undefined {
+  if (!line.trim()) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(line) as { type?: unknown; id?: unknown; parentId?: unknown };
+    return parsed.type !== "session" && typeof parsed.id === "string" && "parentId" in parsed
+      ? parsed.id
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function yieldTranscriptAppendScan(): Promise<void> {
+  await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+async function readTranscriptIdempotencyKeys(sessionFile: string): Promise<Set<string>> {
+  const keys = new Set<string>();
+  let raw: string;
+  try {
+    raw = await fs.readFile(sessionFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+    return keys;
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line) as { message?: { idempotencyKey?: unknown } };
+      if (typeof parsed.message?.idempotencyKey === "string") {
+        keys.add(parsed.message.idempotencyKey);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return keys;
+}

package/src/app-server/transcript-repair-runtime-contract.test.ts

@@ -0,0 +1,44 @@
+import {
+  assistantHistoryMessage,
+  currentPromptHistoryMessage,
+  mediaOnlyHistoryMessage,
+  structuredHistoryMessage,
+} from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { describe, expect, it } from "vitest";
+import { projectContextEngineAssemblyForCodex } from "./context-engine-projection.js";
+
+describe("Codex transcript projection runtime contract", () => {
+  it("drops only the duplicate trailing current prompt while preserving prior structured context", () => {
+    const prompt = "newest inbound message";
+
+    const result = projectContextEngineAssemblyForCodex({
+      prompt,
+      originalHistoryMessages: [structuredHistoryMessage()],
+      assembledMessages: [
+        structuredHistoryMessage(),
+        assistantHistoryMessage(),
+        currentPromptHistoryMessage(prompt),
+      ],
+    });
+
+    expect(result.promptText).toContain("Current user request:\nnewest inbound message");
+    expect(result.promptText).toContain("[user]\nolder structured context\n[image omitted]");
+    expect(result.promptText).toContain("[assistant]\nack");
+    expect(result.promptText).not.toContain("[user]\nnewest inbound message");
+  });
+
+  it("keeps media-only user history visible as omitted media instead of dropping the turn", () => {
+    const result = projectContextEngineAssemblyForCodex({
+      prompt: "newest inbound message",
+      originalHistoryMessages: [mediaOnlyHistoryMessage()],
+      assembledMessages: [
+        mediaOnlyHistoryMessage(),
+        currentPromptHistoryMessage("newest inbound message"),
+      ],
+    });
+
+    expect(result.promptText).toContain("[user]\n[image omitted]");
+    expect(result.promptText).not.toContain("data:image/png");
+    expect(result.promptText).not.toContain("bbbb");
+  });
+});

package/src/app-server/transport-stdio.test.ts

@@ -0,0 +1,171 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { CodexAppServerStartOptions } from "./config.js";
+import {
+  resolveCodexAppServerSpawnEnv,
+  resolveCodexAppServerSpawnInvocation,
+} from "./transport-stdio.js";
+
+const tempDirs: string[] = [];
+
+async function createTempDir(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-codex-spawn-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+function startOptions(command: string): CodexAppServerStartOptions {
+  return {
+    transport: "stdio",
+    command,
+    args: ["app-server", "--listen", "stdio://"],
+    headers: {},
+  };
+}
+
+describe("resolveCodexAppServerSpawnInvocation", () => {
+  it("keeps non-Windows Codex app-server invocation unchanged", () => {
+    const resolved = resolveCodexAppServerSpawnInvocation(startOptions("codex"), {
+      platform: "darwin",
+      env: {},
+      execPath: "/usr/local/bin/node",
+    });
+
+    expect(resolved).toEqual({
+      command: "codex",
+      args: ["app-server", "--listen", "stdio://"],
+      shell: undefined,
+      windowsHide: undefined,
+    });
+  });
+
+  it("requires managed Codex commands to be resolved before spawn", () => {
+    expect(() =>
+      resolveCodexAppServerSpawnInvocation(
+        {
+          ...startOptions("codex"),
+          commandSource: "managed",
+        },
+        {
+          platform: "darwin",
+          env: {},
+          execPath: "/usr/local/bin/node",
+        },
+      ),
+    ).toThrow("must be resolved before spawn");
+  });
+
+  it("resolves Windows npm .cmd Codex shims through Node instead of raw spawn", async () => {
+    const binDir = await createTempDir();
+    const entryPath = path.join(binDir, "node_modules", "@openai", "codex", "bin", "codex.js");
+    const shimPath = path.join(binDir, "codex.cmd");
+    await mkdir(path.dirname(entryPath), { recursive: true });
+    await writeFile(entryPath, "console.log('codex')\n", "utf8");
+    await writeFile(
+      shimPath,
+      '@ECHO off\r\n"%~dp0\\node_modules\\@openai\\codex\\bin\\codex.js" %*\r\n',
+      "utf8",
+    );
+
+    const resolved = resolveCodexAppServerSpawnInvocation(startOptions("codex"), {
+      platform: "win32",
+      env: { PATH: binDir, PATHEXT: ".CMD;.EXE;.BAT" },
+      execPath: "C:\\node\\node.exe",
+    });
+
+    expect(resolved).toEqual({
+      command: "C:\\node\\node.exe",
+      args: [entryPath, "app-server", "--listen", "stdio://"],
+      shell: undefined,
+      windowsHide: true,
+    });
+  });
+});
+
+describe("resolveCodexAppServerSpawnEnv", () => {
+  it("applies configured env overrides before clearing denied env vars", () => {
+    expect({
+      ...resolveCodexAppServerSpawnEnv(
+        {
+          env: {
+            OPENAI_API_KEY: "configured-openai-key",
+            KEEP: "override",
+          },
+          clearEnv: ["OPENAI_API_KEY", "CODEX_API_KEY", "MISSING"],
+        },
+        {
+          OPENAI_API_KEY: "parent-openai-key",
+          CODEX_API_KEY: "parent-codex-key",
+          KEEP: "parent",
+        },
+      ),
+    }).toEqual({
+      KEEP: "override",
+    });
+  });
+
+  it("clears denied env vars case-insensitively on Windows", () => {
+    expect({
+      ...resolveCodexAppServerSpawnEnv(
+        {
+          env: {
+            OpenAI_Api_Key: "configured-openai-key",
+            Other: "configured",
+          },
+          clearEnv: ["OPENAI_API_KEY", " CODEX_API_KEY ", ""],
+        },
+        {
+          Codex_Api_Key: "parent-codex-key",
+          KEEP: "parent",
+        },
+        "win32",
+      ),
+    }).toEqual({
+      KEEP: "parent",
+      Other: "configured",
+    });
+  });
+
+  it("uses a null-prototype env map and ignores prototype-polluting keys", () => {
+    const overrides = Object.create(null) as Record<string, string | undefined>;
+    Object.defineProperty(overrides, "__proto__", {
+      value: "polluted",
+      enumerable: true,
+    });
+    Object.defineProperty(overrides, "constructor", {
+      value: "polluted",
+      enumerable: true,
+    });
+    Object.defineProperty(overrides, "prototype", {
+      value: "polluted",
+      enumerable: true,
+    });
+    overrides.SAFE = "1";
+
+    const env = resolveCodexAppServerSpawnEnv(
+      {
+        env: overrides as Record<string, string>,
+      },
+      {
+        BASE: "1",
+      },
+    );
+
+    expect(Object.getPrototypeOf(env)).toBeNull();
+    expect({ ...env }).toEqual({
+      BASE: "1",
+      SAFE: "1",
+    });
+    expect(Object.hasOwn(env, "__proto__")).toBe(false);
+    expect(Object.hasOwn(env, "constructor")).toBe(false);
+    expect(Object.hasOwn(env, "prototype")).toBe(false);
+  });
+});

package/src/app-server/transport-stdio.ts

@@ -0,0 +1,107 @@
+import { spawn } from "node:child_process";
+import {
+  materializeWindowsSpawnProgram,
+  resolveWindowsSpawnProgram,
+} from "openclaw/plugin-sdk/windows-spawn";
+import type { CodexAppServerStartOptions } from "./config.js";
+import type { CodexAppServerTransport } from "./transport.js";
+
+const UNSAFE_ENVIRONMENT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+type CodexAppServerSpawnRuntime = {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  execPath: string;
+};
+
+const DEFAULT_SPAWN_RUNTIME: CodexAppServerSpawnRuntime = {
+  platform: process.platform,
+  env: process.env,
+  execPath: process.execPath,
+};
+
+export function resolveCodexAppServerSpawnInvocation(
+  options: CodexAppServerStartOptions,
+  runtime: CodexAppServerSpawnRuntime = DEFAULT_SPAWN_RUNTIME,
+): { command: string; args: string[]; shell?: boolean; windowsHide?: boolean } {
+  if (options.commandSource === "managed") {
+    throw new Error("Managed Codex app-server start options must be resolved before spawn.");
+  }
+  const program = resolveWindowsSpawnProgram({
+    command: options.command,
+    platform: runtime.platform,
+    env: runtime.env,
+    execPath: runtime.execPath,
+    packageName: "@openai/codex",
+  });
+  const resolved = materializeWindowsSpawnProgram(program, options.args);
+  return {
+    command: resolved.command,
+    args: resolved.argv,
+    shell: resolved.shell,
+    windowsHide: resolved.windowsHide,
+  };
+}
+
+export function resolveCodexAppServerSpawnEnv(
+  options: Pick<CodexAppServerStartOptions, "env" | "clearEnv">,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): NodeJS.ProcessEnv {
+  const env = Object.create(null) as NodeJS.ProcessEnv;
+  copySafeEnvironmentEntries(env, baseEnv);
+  copySafeEnvironmentEntries(env, options.env ?? {});
+  const keysToClear = normalizedEnvironmentKeys(options.clearEnv ?? []);
+  if (platform === "win32") {
+    const lowerCaseKeysToClear = new Set(keysToClear.map((key) => key.toLowerCase()));
+    for (const candidate of Object.keys(env)) {
+      if (lowerCaseKeysToClear.has(candidate.toLowerCase())) {
+        delete env[candidate];
+      }
+    }
+  } else {
+    for (const key of keysToClear) {
+      delete env[key];
+    }
+  }
+  return env;
+}
+
+function normalizedEnvironmentKeys(rawKeys: readonly string[]): string[] {
+  const keys: string[] = [];
+  for (const rawKey of rawKeys) {
+    const key = rawKey.trim();
+    if (key.length > 0) {
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+
+function copySafeEnvironmentEntries(
+  target: NodeJS.ProcessEnv,
+  source: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (UNSAFE_ENVIRONMENT_KEYS.has(key)) {
+      continue;
+    }
+    target[key] = value;
+  }
+}
+
+export function createStdioTransport(options: CodexAppServerStartOptions): CodexAppServerTransport {
+  const env = resolveCodexAppServerSpawnEnv(options);
+  const invocation = resolveCodexAppServerSpawnInvocation(options, {
+    platform: process.platform,
+    env,
+    execPath: process.execPath,
+  });
+  return spawn(invocation.command, invocation.args, {
+    env,
+    detached: process.platform !== "win32",
+    shell: invocation.shell,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: invocation.windowsHide,
+  });
+}

package/src/app-server/transport-websocket.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { WebSocketServer, type RawData } from "ws";
+import { CodexAppServerClient } from "./client.js";
+
+describe("Codex app-server websocket transport", () => {
+  const clients: CodexAppServerClient[] = [];
+  const servers: WebSocketServer[] = [];
+
+  afterEach(async () => {
+    for (const client of clients) {
+      client.close();
+    }
+    clients.length = 0;
+    await Promise.all(
+      servers
+        .splice(0)
+        .map(
+          (server) =>
+            new Promise<void>((resolve, reject) =>
+              server.close((error) => (error ? reject(error) : resolve())),
+            ),
+        ),
+    );
+  });
+
+  it("can speak JSON-RPC over websocket transport", async () => {
+    const server = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+    servers.push(server);
+    const authHeaders: Array<string | undefined> = [];
+    server.on("connection", (socket, request) => {
+      authHeaders.push(request.headers.authorization);
+      socket.on("message", (data) => {
+        const message = JSON.parse(rawDataToText(data)) as { id?: number; method?: string };
+        if (message.method === "initialize") {
+          socket.send(
+            JSON.stringify({ id: message.id, result: { userAgent: "openclaw/0.125.0" } }),
+          );
+          return;
+        }
+        if (message.method === "model/list") {
+          socket.send(JSON.stringify({ id: message.id, result: { data: [] } }));
+        }
+      });
+    });
+    await new Promise<void>((resolve) => server.once("listening", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("expected websocket test server port");
+    }
+    const client = CodexAppServerClient.start({
+      transport: "websocket",
+      url: `ws://127.0.0.1:${address.port}`,
+      authToken: "secret",
+    });
+    clients.push(client);
+
+    await expect(client.initialize()).resolves.toBeUndefined();
+    await expect(client.request("model/list", {})).resolves.toEqual({ data: [] });
+    expect(authHeaders).toEqual(["Bearer secret"]);
+  });
+});
+
+function rawDataToText(data: RawData): string {
+  if (Array.isArray(data)) {
+    return Buffer.concat(data).toString("utf8");
+  }
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(new Uint8Array(data)).toString("utf8");
+  }
+  return Buffer.from(data).toString("utf8");
+}