@kodelyth/codex 2026.5.40 → 2026.5.42

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.stdin.end?.();
+  child.stdin.destroy?.();
+  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.stdout.destroy?.();
+    child.stderr.destroy?.();
+  });
+  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),
+    );
+    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,249 @@
+import type { EmbeddedRunAttemptParams } from "klaw/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;
+}
+
+function expectFirstBlockReplyText(params: EmbeddedRunAttemptParams): string {
+  const onBlockReply = params.onBlockReply;
+  if (onBlockReply === undefined) {
+    throw new Error("Expected onBlockReply callback");
+  }
+  const payload = vi.mocked(onBlockReply).mock.calls[0]?.[0];
+  if (typeof payload?.text !== "string") {
+    throw new Error("Expected first block reply text");
+  }
+  return payload.text;
+}
+
+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(expectFirstBlockReplyText(params)).toContain("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: klaw\nscope: Tests")).toBe(true);
+
+    await expect(response).resolves.toEqual({
+      answers: {
+        repo: { answers: ["klaw"] },
+        scope: { answers: ["Tests"] },
+      },
+    });
+  });
+
+  it("rejects free-form option replies when Other is disabled", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    const response = bridge.handleRequest({
+      id: "input-options",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "tool-1",
+        questions: [
+          {
+            id: "mode",
+            header: "Mode",
+            question: "Pick a mode",
+            isOther: false,
+            isSecret: false,
+            options: [{ label: "Fast", description: "Use less reasoning" }],
+          },
+        ],
+      },
+    });
+
+    await vi.waitFor(() => expect(params.onBlockReply).toHaveBeenCalledTimes(1));
+    expect(bridge.handleQueuedMessage("banana")).toBe(true);
+
+    await expect(response).resolves.toEqual({
+      answers: { mode: { answers: [] } },
+    });
+  });
+
+  it("escapes prompt question and option text before chat display", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    const response = bridge.handleRequest({
+      id: "input-escaped",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "tool-1",
+        questions: [
+          {
+            id: "mode",
+            header: "Mode <@U123>",
+            question: "Pick [trusted](https://evil) @here",
+            isOther: false,
+            isSecret: false,
+            options: [{ label: "Fast <@U123>", description: "Use [less](https://evil)" }],
+          },
+        ],
+      },
+    });
+
+    await vi.waitFor(() => expect(params.onBlockReply).toHaveBeenCalledTimes(1));
+    const text = expectFirstBlockReplyText(params);
+    expect(text).toContain("Mode &lt;\uff20U123&gt;");
+    expect(text).toContain("Pick \uff3btrusted\uff3d\uff08https://evil\uff09 \uff20here");
+    expect(text).toContain(
+      "Fast &lt;\uff20U123&gt; - Use \uff3bless\uff3d\uff08https://evil\uff09",
+    );
+    expect(text).not.toContain("<@U123>");
+    expect(text).not.toContain("[trusted](https://evil)");
+    expect(text).not.toContain("@here");
+
+    expect(bridge.handleQueuedMessage("1")).toBe(true);
+    await expect(response).resolves.toEqual({
+      answers: { mode: { answers: ["Fast <@U123>"] } },
+    });
+  });
+
+  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);
+  });
+
+  it("resolves malformed empty question prompts without waiting for chat input", async () => {
+    const params = createParams();
+    const bridge = createCodexUserInputBridge({
+      paramsForRun: params,
+      threadId: "thread-1",
+      turnId: "turn-1",
+    });
+
+    await expect(
+      bridge.handleRequest({
+        id: "input-empty",
+        params: {
+          threadId: "thread-1",
+          turnId: "turn-1",
+          itemId: "tool-1",
+          questions: [],
+        },
+      }),
+    ).resolves.toEqual({ answers: {} });
+    expect(params.onBlockReply).not.toHaveBeenCalled();
+    expect(bridge.handleQueuedMessage("late answer")).toBe(false);
+  });
+});

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

@@ -0,0 +1,316 @@
+import {
+  embeddedAgentLog,
+  type EmbeddedRunAttemptParams,
+} from "klaw/plugin-sdk/agent-harness-runtime";
+import { formatCodexDisplayText } from "../command-formatters.js";
+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;
+      }
+      if (requestParams.questions.length === 0) {
+        return emptyUserInputResponse();
+      }
+
+      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}. ${formatCodexDisplayText(question.header)}`,
+        formatCodexDisplayText(question.question),
+      );
+    } else {
+      lines.push(
+        "",
+        formatCodexDisplayText(question.header),
+        formatCodexDisplayText(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}. ${formatCodexDisplayText(option.label)}${
+          option.description ? ` - ${formatCodexDisplayText(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) {
+      const answer = normalizeAnswer(inputText, question);
+      answers[question.id] = { answers: answer ? [answer] : [] };
+    }
+    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] ?? "";
+    const normalized = answer ? normalizeAnswer(answer, question) : undefined;
+    answers[question.id] = { answers: normalized ? [normalized] : [] };
+  });
+  return { answers };
+}
+
+function normalizeAnswer(answer: string, question: UserInputQuestion): string | undefined {
+  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());
+  if (exact) {
+    return exact.label;
+  }
+  if (options.length > 0 && !question.isOther) {
+    return undefined;
+  }
+  return trimmed || undefined;
+}
+
+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,4 @@
+export const MIN_CODEX_APP_SERVER_VERSION = "0.125.0";
+export const MANAGED_CODEX_APP_SERVER_PACKAGE = "@openai/codex";
+// Keep this in sync with the Codex CLI live-test package pin.
+export const MANAGED_CODEX_APP_SERVER_PACKAGE_VERSION = "0.130.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");
+}