@openclaw/codex 2026.5.1-beta.1

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

@@ -0,0 +1,90 @@
+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");
+}

package/src/app-server/transport.ts

@@ -0,0 +1,117 @@
+export type CodexAppServerTransport = {
+  stdin: {
+    write: (data: string, callback?: (error?: Error | null) => void) => unknown;
+    end?: () => unknown;
+    destroy?: () => unknown;
+    unref?: () => unknown;
+    on?: (event: "error", listener: (error: Error) => void) => unknown;
+  };
+  stdout: NodeJS.ReadableStream & {
+    destroy?: () => unknown;
+    unref?: () => unknown;
+  };
+  stderr: NodeJS.ReadableStream & {
+    destroy?: () => unknown;
+    unref?: () => unknown;
+  };
+  pid?: number;
+  exitCode?: number | null;
+  signalCode?: string | null;
+  killed?: boolean;
+  kill?: (signal?: NodeJS.Signals) => unknown;
+  unref?: () => unknown;
+  once: (event: string, listener: (...args: unknown[]) => void) => unknown;
+  off?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+};
+
+export function closeCodexAppServerTransport(
+  child: CodexAppServerTransport,
+  options: { forceKillDelayMs?: number } = {},
+): void {
+  child.stdout.destroy?.();
+  child.stderr.destroy?.();
+  child.stdin.end?.();
+  child.stdin.destroy?.();
+  signalCodexAppServerTransport(child, "SIGTERM");
+  const forceKillDelayMs = options.forceKillDelayMs ?? 1_000;
+  const forceKill = setTimeout(
+    () => {
+      if (hasCodexAppServerTransportExited(child)) {
+        return;
+      }
+      signalCodexAppServerTransport(child, "SIGKILL");
+    },
+    Math.max(1, forceKillDelayMs),
+  );
+  forceKill.unref?.();
+  child.once("exit", () => clearTimeout(forceKill));
+  child.unref?.();
+  child.stdout.unref?.();
+  child.stderr.unref?.();
+  child.stdin.unref?.();
+}
+
+export async function closeCodexAppServerTransportAndWait(
+  child: CodexAppServerTransport,
+  options: { exitTimeoutMs?: number; forceKillDelayMs?: number } = {},
+): Promise<boolean> {
+  if (!hasCodexAppServerTransportExited(child)) {
+    closeCodexAppServerTransport(child, options);
+  }
+  return await waitForCodexAppServerTransportExit(child, options.exitTimeoutMs ?? 2_000);
+}
+
+function hasCodexAppServerTransportExited(child: CodexAppServerTransport): boolean {
+  return child.exitCode !== null && child.exitCode !== undefined
+    ? true
+    : child.signalCode !== null && child.signalCode !== undefined;
+}
+
+async function waitForCodexAppServerTransportExit(
+  child: CodexAppServerTransport,
+  timeoutMs: number,
+): Promise<boolean> {
+  if (hasCodexAppServerTransportExited(child)) {
+    return true;
+  }
+  return await new Promise<boolean>((resolve) => {
+    let settled = false;
+    const onExit = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve(true);
+    };
+    const timeout = setTimeout(
+      () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        child.off?.("exit", onExit);
+        resolve(false);
+      },
+      Math.max(1, timeoutMs),
+    );
+    timeout.unref?.();
+    child.once("exit", onExit);
+  });
+}
+
+function signalCodexAppServerTransport(
+  child: CodexAppServerTransport,
+  signal: NodeJS.Signals,
+): void {
+  if (child.pid && process.platform !== "win32") {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+      // Fall back to the child handle. The process may already be gone or not
+      // be a process-group leader on older call sites.
+    }
+  }
+  child.kill?.(signal);
+}

package/src/app-server/user-input-bridge.test.ts

@@ -0,0 +1,137 @@
+import type { EmbeddedRunAttemptParams } from "openclaw/plugin-sdk/agent-harness-runtime";
+import { describe, expect, it, vi } from "vitest";
+import { createCodexUserInputBridge } from "./user-input-bridge.js";
+
+function createParams(): EmbeddedRunAttemptParams {
+  return {
+    sessionId: "session-1",
+    sessionKey: "agent:main:session-1",
+    onBlockReply: vi.fn(),
+  } as unknown as EmbeddedRunAttemptParams;
+}
+
+describe("Codex app-server user input bridge", () => {
+  it("prompts the originating chat and resolves request_user_input from the next queued message", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    const response = bridge.handleRequest({
+      id: "input-1",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "tool-1",
+        questions: [
+          {
+            id: "choice",
+            header: "Mode",
+            question: "Pick a mode",
+            isOther: false,
+            isSecret: false,
+            options: [
+              { label: "Fast", description: "Use less reasoning" },
+              { label: "Deep", description: "Use more reasoning" },
+            ],
+          },
+        ],
+      },
+    });
+
+    await vi.waitFor(() => expect(params.onBlockReply).toHaveBeenCalledTimes(1));
+    expect(params.onBlockReply).toHaveBeenCalledWith({
+      text: expect.stringContaining("Pick a mode"),
+    });
+    expect(bridge.handleQueuedMessage("2")).toBe(true);
+
+    await expect(response).resolves.toEqual({
+      answers: { choice: { answers: ["Deep"] } },
+    });
+  });
+
+  it("maps keyed multi-question replies to Codex answer ids", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    const response = bridge.handleRequest({
+      id: "input-2",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "tool-1",
+        questions: [
+          {
+            id: "repo",
+            header: "Repository",
+            question: "Which repo?",
+            isOther: true,
+            isSecret: false,
+            options: null,
+          },
+          {
+            id: "scope",
+            header: "Scope",
+            question: "Which scope?",
+            isOther: false,
+            isSecret: false,
+            options: [{ label: "Tests", description: "Only tests" }],
+          },
+        ],
+      },
+    });
+
+    await vi.waitFor(() => expect(params.onBlockReply).toHaveBeenCalledTimes(1));
+    expect(bridge.handleQueuedMessage("repo: openclaw\nscope: Tests")).toBe(true);
+
+    await expect(response).resolves.toEqual({
+      answers: {
+        repo: { answers: ["openclaw"] },
+        scope: { answers: ["Tests"] },
+      },
+    });
+  });
+
+  it("clears pending prompts when Codex resolves the server request itself", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    const response = bridge.handleRequest({
+      id: "input-3",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "tool-1",
+        questions: [
+          {
+            id: "answer",
+            header: "Answer",
+            question: "Continue?",
+            isOther: true,
+            isSecret: false,
+            options: null,
+          },
+        ],
+      },
+    });
+
+    await vi.waitFor(() => expect(params.onBlockReply).toHaveBeenCalledTimes(1));
+    bridge.handleNotification({
+      method: "serverRequest/resolved",
+      params: { threadId: "thread-1", requestId: "input-3" },
+    });
+
+    await expect(response).resolves.toEqual({ answers: {} });
+    expect(bridge.handleQueuedMessage("too late")).toBe(false);
+  });
+});

package/src/app-server/user-input-bridge.ts

@@ -0,0 +1,294 @@
+import {
+  embeddedAgentLog,
+  type EmbeddedRunAttemptParams,
+} from "openclaw/plugin-sdk/agent-harness-runtime";
+import {
+  isJsonObject,
+  type CodexServerNotification,
+  type JsonObject,
+  type JsonValue,
+} from "./protocol.js";
+
+type PendingUserInput = {
+  requestId: number | string;
+  threadId: string;
+  turnId: string;
+  itemId: string;
+  questions: UserInputQuestion[];
+  resolve: (value: JsonValue) => void;
+  cleanup: () => void;
+};
+
+type UserInputQuestion = {
+  id: string;
+  header: string;
+  question: string;
+  isOther: boolean;
+  isSecret: boolean;
+  options: UserInputOption[] | null;
+};
+
+type UserInputOption = {
+  label: string;
+  description: string;
+};
+
+type CodexUserInputBridge = {
+  handleRequest: (request: {
+    id: number | string;
+    params?: JsonValue;
+  }) => Promise<JsonValue | undefined>;
+  handleQueuedMessage: (text: string) => boolean;
+  handleNotification: (notification: CodexServerNotification) => void;
+  cancelPending: () => void;
+};
+
+export function createCodexUserInputBridge(params: {
+  paramsForRun: EmbeddedRunAttemptParams;
+  threadId: string;
+  turnId: string;
+  signal?: AbortSignal;
+}): CodexUserInputBridge {
+  let pending: PendingUserInput | undefined;
+
+  const resolvePending = (value: JsonValue) => {
+    const current = pending;
+    if (!current) {
+      return;
+    }
+    pending = undefined;
+    current.cleanup();
+    current.resolve(value);
+  };
+
+  return {
+    async handleRequest(request) {
+      const requestParams = readUserInputParams(request.params);
+      if (!requestParams) {
+        return undefined;
+      }
+      if (requestParams.threadId !== params.threadId || requestParams.turnId !== params.turnId) {
+        return undefined;
+      }
+
+      resolvePending(emptyUserInputResponse());
+
+      return new Promise<JsonValue>((resolve) => {
+        const abortListener = () => resolvePending(emptyUserInputResponse());
+        const cleanup = () => params.signal?.removeEventListener("abort", abortListener);
+        pending = {
+          requestId: request.id,
+          threadId: requestParams.threadId,
+          turnId: requestParams.turnId,
+          itemId: requestParams.itemId,
+          questions: requestParams.questions,
+          resolve,
+          cleanup,
+        };
+        params.signal?.addEventListener("abort", abortListener, { once: true });
+        if (params.signal?.aborted) {
+          resolvePending(emptyUserInputResponse());
+          return;
+        }
+        void deliverUserInputPrompt(params.paramsForRun, requestParams.questions).catch((error) => {
+          embeddedAgentLog.warn("failed to deliver codex user input prompt", { error });
+        });
+      });
+    },
+    handleQueuedMessage(text) {
+      const current = pending;
+      if (!current) {
+        return false;
+      }
+      resolvePending(buildUserInputResponse(current.questions, text));
+      return true;
+    },
+    handleNotification(notification) {
+      if (notification.method !== "serverRequest/resolved" || !pending) {
+        return;
+      }
+      const notificationParams = isJsonObject(notification.params)
+        ? notification.params
+        : undefined;
+      const requestId = notificationParams ? readRequestId(notificationParams) : undefined;
+      if (
+        notificationParams &&
+        readString(notificationParams, "threadId") === pending.threadId &&
+        requestId !== undefined &&
+        String(requestId) === String(pending.requestId)
+      ) {
+        resolvePending(emptyUserInputResponse());
+      }
+    },
+    cancelPending() {
+      resolvePending(emptyUserInputResponse());
+    },
+  };
+}
+
+function readUserInputParams(value: JsonValue | undefined):
+  | {
+      threadId: string;
+      turnId: string;
+      itemId: string;
+      questions: UserInputQuestion[];
+    }
+  | undefined {
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  const threadId = readString(value, "threadId");
+  const turnId = readString(value, "turnId");
+  const itemId = readString(value, "itemId");
+  const questionsRaw = value.questions;
+  if (!threadId || !turnId || !itemId || !Array.isArray(questionsRaw)) {
+    return undefined;
+  }
+  const questions = questionsRaw
+    .map(readQuestion)
+    .filter((question): question is UserInputQuestion => Boolean(question));
+  return { threadId, turnId, itemId, questions };
+}
+
+function readQuestion(value: JsonValue): UserInputQuestion | undefined {
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  const id = readString(value, "id");
+  const header = readString(value, "header");
+  const question = readString(value, "question");
+  if (!id || !header || !question) {
+    return undefined;
+  }
+  return {
+    id,
+    header,
+    question,
+    isOther: value.isOther === true,
+    isSecret: value.isSecret === true,
+    options: readOptions(value.options),
+  };
+}
+
+function readOptions(value: JsonValue | undefined): UserInputOption[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const options = value
+    .map(readOption)
+    .filter((option): option is UserInputOption => Boolean(option));
+  return options.length > 0 ? options : null;
+}
+
+function readOption(value: JsonValue): UserInputOption | undefined {
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  const label = readString(value, "label");
+  const description = readString(value, "description") ?? "";
+  return label ? { label, description } : undefined;
+}
+
+async function deliverUserInputPrompt(
+  params: EmbeddedRunAttemptParams,
+  questions: UserInputQuestion[],
+): Promise<void> {
+  const text = formatUserInputPrompt(questions);
+  if (params.onBlockReply) {
+    await params.onBlockReply({ text });
+    return;
+  }
+  await params.onPartialReply?.({ text });
+}
+
+function formatUserInputPrompt(questions: UserInputQuestion[]): string {
+  const lines = ["Codex needs input:"];
+  questions.forEach((question, index) => {
+    if (questions.length > 1) {
+      lines.push("", `${index + 1}. ${question.header}`, question.question);
+    } else {
+      lines.push("", question.header, question.question);
+    }
+    if (question.isSecret) {
+      lines.push("This channel may show your reply to other participants.");
+    }
+    question.options?.forEach((option, optionIndex) => {
+      lines.push(
+        `${optionIndex + 1}. ${option.label}${option.description ? ` - ${option.description}` : ""}`,
+      );
+    });
+    if (question.isOther) {
+      lines.push("Other: reply with your own answer.");
+    }
+  });
+  return lines.join("\n");
+}
+
+function buildUserInputResponse(questions: UserInputQuestion[], inputText: string): JsonObject {
+  const answers: JsonObject = {};
+  if (questions.length === 1) {
+    const question = questions[0];
+    if (question) {
+      answers[question.id] = { answers: [normalizeAnswer(inputText, question)] };
+    }
+    return { answers };
+  }
+
+  const keyed = parseKeyedAnswers(inputText);
+  const fallbackLines = inputText
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  questions.forEach((question, index) => {
+    const key =
+      keyed.get(question.id.toLowerCase()) ??
+      keyed.get(question.header.toLowerCase()) ??
+      keyed.get(question.question.toLowerCase()) ??
+      keyed.get(String(index + 1));
+    const answer = key ?? fallbackLines[index] ?? "";
+    answers[question.id] = { answers: answer ? [normalizeAnswer(answer, question)] : [] };
+  });
+  return { answers };
+}
+
+function normalizeAnswer(answer: string, question: UserInputQuestion): string {
+  const trimmed = answer.trim();
+  const options = question.options ?? [];
+  const optionIndex = /^\d+$/.test(trimmed) ? Number(trimmed) - 1 : -1;
+  const indexed = optionIndex >= 0 ? options[optionIndex] : undefined;
+  if (indexed) {
+    return indexed.label;
+  }
+  const exact = options.find((option) => option.label.toLowerCase() === trimmed.toLowerCase());
+  return exact?.label ?? trimmed;
+}
+
+function parseKeyedAnswers(inputText: string): Map<string, string> {
+  const answers = new Map<string, string>();
+  for (const line of inputText.split(/\r?\n/)) {
+    const match = line.match(/^\s*([^:=-]+?)\s*[:=-]\s*(.+?)\s*$/);
+    if (!match) {
+      continue;
+    }
+    const key = match[1]?.trim().toLowerCase();
+    const value = match[2]?.trim();
+    if (key && value) {
+      answers.set(key, value);
+    }
+  }
+  return answers;
+}
+
+function emptyUserInputResponse(): JsonObject {
+  return { answers: {} };
+}
+
+function readString(record: JsonObject, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readRequestId(record: JsonObject): string | number | undefined {
+  const value = record.requestId;
+  return typeof value === "string" || typeof value === "number" ? value : undefined;
+}

package/src/app-server/version.ts

@@ -0,0 +1,3 @@
+export const MIN_CODEX_APP_SERVER_VERSION = "0.125.0";
+export const MANAGED_CODEX_APP_SERVER_PACKAGE = "@openai/codex";
+export const MANAGED_CODEX_APP_SERVER_PACKAGE_VERSION = "0.128.0";

package/src/app-server/vision-tools.ts

@@ -0,0 +1,12 @@
+export function filterToolsForVisionInputs<T extends { name?: string }>(
+  tools: T[],
+  params: {
+    modelHasVision: boolean;
+    hasInboundImages: boolean;
+  },
+): T[] {
+  if (!params.modelHasVision || !params.hasInboundImages) {
+    return tools;
+  }
+  return tools.filter((tool) => tool.name !== "image");
+}