@kodelyth/codex 2026.5.42 → 2026.6.2

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

@@ -1,208 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
-import {
-  acquireSessionWriteLock,
-  appendSessionTranscriptMessage,
-  emitSessionTranscriptUpdate,
-  resolveSessionWriteLockOptions,
-  runAgentHarnessBeforeMessageWriteHook,
-  type AgentMessage,
-  type EmbeddedRunAttemptParams,
-  type SessionWriteLockAcquireTimeoutConfig,
-} from "klaw/plugin-sdk/agent-harness-runtime";
-
-type MirroredAgentMessage = Extract<AgentMessage, { role: "user" | "assistant" | "toolResult" }>;
-
-const MIRROR_IDENTITY_META_KEY = "mirrorIdentity" as const;
-
-function normalizeOptionalString(value: string | null | undefined): string | undefined {
-  const normalized = value?.trim();
-  return normalized ? normalized : undefined;
-}
-
-function buildSenderLabel(params: {
-  senderId?: string;
-  senderName?: string;
-  senderUsername?: string;
-  senderE164?: string;
-}): string | undefined {
-  const label = params.senderName ?? params.senderUsername ?? params.senderE164 ?? params.senderId;
-  if (!label) {
-    return undefined;
-  }
-  if (!params.senderId || label.includes(params.senderId)) {
-    return label;
-  }
-  return `${label} (${params.senderId})`;
-}
-
-export function buildCodexUserPromptMessage(params: EmbeddedRunAttemptParams): AgentMessage {
-  const senderId = normalizeOptionalString(params.senderId);
-  const senderName = normalizeOptionalString(params.senderName);
-  const senderUsername = normalizeOptionalString(params.senderUsername);
-  const senderE164 = normalizeOptionalString(params.senderE164);
-  const senderLabel = buildSenderLabel({ senderId, senderName, senderUsername, senderE164 });
-  const sourceChannel = normalizeOptionalString(
-    params.inputProvenance?.sourceChannel ?? params.messageChannel ?? params.messageProvider,
-  );
-  return {
-    role: "user",
-    content: params.prompt,
-    timestamp: Date.now(),
-    ...(params.inputProvenance ? { provenance: params.inputProvenance } : {}),
-    ...(sourceChannel ? { sourceChannel } : {}),
-    ...(senderId ? { senderId } : {}),
-    ...(senderName ? { senderName } : {}),
-    ...(senderUsername ? { senderUsername } : {}),
-    ...(senderE164 ? { senderE164 } : {}),
-    ...(senderLabel ? { senderLabel } : {}),
-  } as AgentMessage;
-}
-
-/**
- * Tag a message with a stable logical identity for mirror dedupe. Callers
- * should use a value that is invariant for the same logical message across
- * re-emits (e.g. `${turnId}:prompt`, `${turnId}:assistant`) but distinct
- * for genuinely-distinct messages (different turns, different kinds). When
- * present this identity replaces the role/content fingerprint in the
- * idempotency key, so the dedupe survives caller-scope rotation without
- * collapsing distinct same-content turns.
- */
-export function attachCodexMirrorIdentity<T extends AgentMessage>(message: T, identity: string): T {
-  const record = message as unknown as Record<string, unknown>;
-  const existing = record["__klaw"];
-  const baseMeta =
-    existing && typeof existing === "object" && !Array.isArray(existing)
-      ? (existing as Record<string, unknown>)
-      : {};
-  return {
-    ...record,
-    __klaw: { ...baseMeta, [MIRROR_IDENTITY_META_KEY]: identity },
-  } as unknown as T;
-}
-
-function readMirrorIdentity(message: MirroredAgentMessage): string | undefined {
-  const record = message as unknown as { __klaw?: unknown };
-  const meta = record["__klaw"];
-  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
-    return undefined;
-  }
-  const id = (meta as Record<string, unknown>)[MIRROR_IDENTITY_META_KEY];
-  return typeof id === "string" && id.length > 0 ? id : undefined;
-}
-
-// Fallback content fingerprint for callers that did not tag the message
-// with a stable mirror identity. Only role and content participate; volatile
-// metadata (timestamps, usage, etc.) is intentionally excluded so the
-// fingerprint survives snapshot reordering inside a fixed scope. Distinct
-// same-content turns are still distinguished by the caller's idempotency
-// scope when callers route through this fallback.
-function fingerprintMirrorMessageContent(message: MirroredAgentMessage): string {
-  const payload = JSON.stringify({ role: message.role, content: message.content });
-  return createHash("sha256").update(payload).digest("hex").slice(0, 16);
-}
-
-function buildMirrorDedupeIdentity(message: MirroredAgentMessage): string {
-  const explicit = readMirrorIdentity(message);
-  if (explicit) {
-    return explicit;
-  }
-  return `${message.role}:${fingerprintMirrorMessageContent(message)}`;
-}
-
-export async function mirrorCodexAppServerTranscript(params: {
-  sessionFile: string;
-  sessionKey?: string;
-  agentId?: string;
-  messages: AgentMessage[];
-  idempotencyScope?: string;
-  config?: SessionWriteLockAcquireTimeoutConfig;
-}): Promise<void> {
-  const messages = params.messages.filter(
-    (message): message is MirroredAgentMessage =>
-      message.role === "user" || message.role === "assistant" || message.role === "toolResult",
-  );
-  if (messages.length === 0) {
-    return;
-  }
-
-  const lock = await acquireSessionWriteLock({
-    sessionFile: params.sessionFile,
-    ...resolveSessionWriteLockOptions(params.config),
-  });
-  try {
-    const existingIdempotencyKeys = await readTranscriptIdempotencyKeys(params.sessionFile);
-    for (const message of messages) {
-      const dedupeIdentity = buildMirrorDedupeIdentity(message);
-      const idempotencyKey = params.idempotencyScope
-        ? `${params.idempotencyScope}:${dedupeIdentity}`
-        : undefined;
-      if (idempotencyKey && existingIdempotencyKeys.has(idempotencyKey)) {
-        continue;
-      }
-      const transcriptMessage = {
-        ...message,
-        ...(idempotencyKey ? { idempotencyKey } : {}),
-      } as AgentMessage;
-      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 AgentMessage;
-      await appendSessionTranscriptMessage({
-        transcriptPath: params.sessionFile,
-        message: messageToAppend,
-        config: params.config,
-      });
-      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 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

@@ -1,44 +0,0 @@
-import {
-  assistantHistoryMessage,
-  currentPromptHistoryMessage,
-  mediaOnlyHistoryMessage,
-  structuredHistoryMessage,
-} from "klaw/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

@@ -1,171 +0,0 @@
-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(), "klaw-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

@@ -1,107 +0,0 @@
-import { spawn } from "node:child_process";
-import {
-  materializeWindowsSpawnProgram,
-  resolveWindowsSpawnProgram,
-} from "klaw/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

@@ -1,69 +0,0 @@
-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: "klaw/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");
-}

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

@@ -1,90 +0,0 @@
-import { EventEmitter } from "node:events";
-import { PassThrough, Writable } from "node:stream";
-import WebSocket, { type RawData } from "ws";
-import type { CodexAppServerStartOptions } from "./config.js";
-import type { CodexAppServerTransport } from "./transport.js";
-
-export function createWebSocketTransport(
-  options: CodexAppServerStartOptions,
-): CodexAppServerTransport {
-  if (!options.url) {
-    throw new Error(
-      "codex app-server websocket transport requires plugins.entries.codex.config.appServer.url",
-    );
-  }
-  const events = new EventEmitter();
-  const stdout = new PassThrough();
-  const stderr = new PassThrough();
-  const headers = {
-    ...options.headers,
-    ...(options.authToken ? { Authorization: `Bearer ${options.authToken}` } : {}),
-  };
-  const socket = new WebSocket(options.url, { headers });
-  const pendingFrames: string[] = [];
-  let killed = false;
-
-  const sendFrame = (frame: string) => {
-    const trimmed = frame.trim();
-    if (!trimmed) {
-      return;
-    }
-    if (socket.readyState === WebSocket.OPEN) {
-      socket.send(trimmed);
-      return;
-    }
-    pendingFrames.push(trimmed);
-  };
-
-  // `initialize` can be written before the WebSocket open event fires. Buffer
-  // whole JSON-RPC frames so stdio and websocket transports share call timing.
-  socket.once("open", () => {
-    for (const frame of pendingFrames.splice(0)) {
-      socket.send(frame);
-    }
-  });
-  socket.once("error", (error) => events.emit("error", error));
-  socket.once("close", (code, reason) => {
-    killed = true;
-    events.emit("exit", code, reason.toString("utf8"));
-  });
-  socket.on("message", (data) => {
-    const text = websocketFrameToText(data);
-    stdout.write(text.endsWith("\n") ? text : `${text}\n`);
-  });
-
-  const stdin = new Writable({
-    write(chunk, _encoding, callback) {
-      for (const frame of chunk.toString("utf8").split("\n")) {
-        sendFrame(frame);
-      }
-      callback();
-    },
-  });
-
-  return {
-    stdin,
-    stdout,
-    stderr,
-    get killed() {
-      return killed;
-    },
-    kill: () => {
-      killed = true;
-      socket.close();
-    },
-    once: (event, listener) => events.once(event, listener),
-  };
-}
-
-function websocketFrameToText(data: RawData): string {
-  if (typeof data === "string") {
-    return data;
-  }
-  if (Buffer.isBuffer(data)) {
-    return data.toString("utf8");
-  }
-  if (Array.isArray(data)) {
-    return Buffer.concat(data).toString("utf8");
-  }
-  return Buffer.from(data).toString("utf8");
-}