@kodelyth/codex 2026.5.40 → 2026.5.42

package/src/conversation-control.ts

@@ -0,0 +1,303 @@
+import { CODEX_CONTROL_METHODS } from "./app-server/capabilities.js";
+import {
+  isCodexFastServiceTier,
+  resolveCodexAppServerRuntimeOptions,
+  type CodexAppServerApprovalPolicy,
+  type CodexAppServerSandboxMode,
+} from "./app-server/config.js";
+import type { CodexServiceTier, CodexThreadResumeResponse } from "./app-server/protocol.js";
+import {
+  readCodexAppServerBinding,
+  writeCodexAppServerBinding,
+} from "./app-server/session-binding.js";
+import { getSharedCodexAppServerClient } from "./app-server/shared-client.js";
+import { formatCodexDisplayText } from "./command-formatters.js";
+
+type ActiveTurn = {
+  sessionFile: string;
+  threadId: string;
+  turnId: string;
+};
+
+type CodexAppServerBindingLookup = NonNullable<Parameters<typeof readCodexAppServerBinding>[1]>;
+
+type PermissionsMode = "default" | "yolo";
+
+const CODEX_CONVERSATION_CONTROL_STATE = Symbol.for("klaw.codex.conversationControl");
+
+function getActiveTurns(): Map<string, ActiveTurn> {
+  const globalState = globalThis as typeof globalThis & {
+    [CODEX_CONVERSATION_CONTROL_STATE]?: Map<string, ActiveTurn>;
+  };
+  globalState[CODEX_CONVERSATION_CONTROL_STATE] ??= new Map();
+  return globalState[CODEX_CONVERSATION_CONTROL_STATE];
+}
+
+export function trackCodexConversationActiveTurn(active: ActiveTurn): () => void {
+  const activeTurns = getActiveTurns();
+  activeTurns.set(active.sessionFile, active);
+  return () => {
+    const current = activeTurns.get(active.sessionFile);
+    if (current?.turnId === active.turnId) {
+      activeTurns.delete(active.sessionFile);
+    }
+  };
+}
+
+export function readCodexConversationActiveTurn(sessionFile: string): ActiveTurn | undefined {
+  return getActiveTurns().get(sessionFile);
+}
+
+export async function stopCodexConversationTurn(params: {
+  sessionFile: string;
+  pluginConfig?: unknown;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): Promise<{ stopped: boolean; message: string }> {
+  const active = readCodexConversationActiveTurn(params.sessionFile);
+  if (!active) {
+    return { stopped: false, message: "No active Codex run to stop." };
+  }
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const lookup = buildBindingLookup(params);
+  const binding = await readCodexAppServerBinding(params.sessionFile, lookup);
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: binding?.authProfileId,
+    ...lookup,
+  });
+  await client.request(
+    "turn/interrupt",
+    {
+      threadId: active.threadId,
+      turnId: active.turnId,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  return { stopped: true, message: "Codex stop requested." };
+}
+
+export async function steerCodexConversationTurn(params: {
+  sessionFile: string;
+  message: string;
+  pluginConfig?: unknown;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): Promise<{ steered: boolean; message: string }> {
+  const active = readCodexConversationActiveTurn(params.sessionFile);
+  const text = params.message.trim();
+  if (!text) {
+    return { steered: false, message: "Usage: /codex steer <message>" };
+  }
+  if (!active) {
+    return { steered: false, message: "No active Codex run to steer." };
+  }
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const lookup = buildBindingLookup(params);
+  const binding = await readCodexAppServerBinding(params.sessionFile, lookup);
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: binding?.authProfileId,
+    ...lookup,
+  });
+  await client.request(
+    "turn/steer",
+    {
+      threadId: active.threadId,
+      expectedTurnId: active.turnId,
+      input: [{ type: "text", text, text_elements: [] }],
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  return { steered: true, message: "Sent steer message to Codex." };
+}
+
+export async function setCodexConversationModel(params: {
+  sessionFile: string;
+  model: string;
+  pluginConfig?: unknown;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): Promise<string> {
+  const model = params.model.trim();
+  if (!model) {
+    return "Usage: /codex model <model>";
+  }
+  const lookup = buildBindingLookup(params);
+  const binding = await requireThreadBinding(params.sessionFile, lookup);
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const response = await resumeThreadWithOverrides({
+    pluginConfig: params.pluginConfig,
+    threadId: binding.threadId,
+    authProfileId: binding.authProfileId,
+    ...lookup,
+    model,
+  });
+  await writeCodexAppServerBinding(
+    params.sessionFile,
+    {
+      ...binding,
+      cwd: response.thread.cwd ?? binding.cwd,
+      model: response.model ?? model,
+      modelProvider: response.modelProvider ?? binding.modelProvider,
+      approvalPolicy: binding.approvalPolicy,
+      sandbox: binding.sandbox,
+      serviceTier: binding.serviceTier ?? runtime.serviceTier,
+    },
+    lookup,
+  );
+  return `Codex model set to ${formatCodexDisplayText(response.model ?? model)}.`;
+}
+
+export async function setCodexConversationFastMode(params: {
+  sessionFile: string;
+  enabled?: boolean;
+  pluginConfig?: unknown;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): Promise<string> {
+  const lookup = buildBindingLookup(params);
+  const binding = await requireThreadBinding(params.sessionFile, lookup);
+  if (params.enabled == null) {
+    return `Codex fast mode: ${isCodexFastServiceTier(binding.serviceTier) ? "on" : "off"}.`;
+  }
+  const serviceTier: CodexServiceTier = params.enabled ? "priority" : "flex";
+  // Fast mode is sent on each later turn; do not require Codex to accept an
+  // immediate thread/resume control request just to persist the preference.
+  await writeCodexAppServerBinding(
+    params.sessionFile,
+    {
+      ...binding,
+      serviceTier,
+    },
+    lookup,
+  );
+  return `Codex fast mode ${params.enabled ? "enabled" : "disabled"}.`;
+}
+
+export async function setCodexConversationPermissions(params: {
+  sessionFile: string;
+  mode?: PermissionsMode;
+  pluginConfig?: unknown;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): Promise<string> {
+  const lookup = buildBindingLookup(params);
+  const binding = await requireThreadBinding(params.sessionFile, lookup);
+  if (!params.mode) {
+    return `Codex permissions: ${formatPermissionsMode(binding)}.`;
+  }
+  const policy = permissionsForMode(params.mode);
+  // Native bound turns pass these settings at turn/start time, so this command
+  // can update the local binding even when app-server resume overrides fail.
+  await writeCodexAppServerBinding(
+    params.sessionFile,
+    {
+      ...binding,
+      approvalPolicy: policy.approvalPolicy,
+      sandbox: policy.sandbox,
+    },
+    lookup,
+  );
+  return `Codex permissions set to ${params.mode === "yolo" ? "full access" : "default"}.`;
+}
+
+export function parseCodexFastModeArg(arg: string | undefined): boolean | undefined {
+  const normalized = arg?.trim().toLowerCase();
+  if (!normalized || normalized === "status") {
+    return undefined;
+  }
+  if (normalized === "on" || normalized === "true" || normalized === "fast") {
+    return true;
+  }
+  if (normalized === "off" || normalized === "false" || normalized === "flex") {
+    return false;
+  }
+  return undefined;
+}
+
+export function parseCodexPermissionsModeArg(arg: string | undefined): PermissionsMode | undefined {
+  const normalized = arg?.trim().toLowerCase();
+  if (!normalized || normalized === "status") {
+    return undefined;
+  }
+  if (normalized === "yolo" || normalized === "full" || normalized === "full-access") {
+    return "yolo";
+  }
+  if (normalized === "default" || normalized === "guardian") {
+    return "default";
+  }
+  return undefined;
+}
+
+export function formatPermissionsMode(binding: {
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+}): string {
+  return binding.approvalPolicy === "never" && binding.sandbox === "danger-full-access"
+    ? "full access"
+    : "default";
+}
+
+async function requireThreadBinding(sessionFile: string, lookup: CodexAppServerBindingLookup = {}) {
+  const binding = await readCodexAppServerBinding(sessionFile, lookup);
+  if (!binding?.threadId) {
+    throw new Error("No Codex thread is attached to this Klaw session yet.");
+  }
+  return binding;
+}
+
+async function resumeThreadWithOverrides(params: {
+  pluginConfig?: unknown;
+  threadId: string;
+  authProfileId?: string;
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+  model?: string;
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+  serviceTier?: CodexServiceTier;
+}): Promise<CodexThreadResumeResponse> {
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: params.authProfileId,
+    ...buildBindingLookup(params),
+  });
+  return await client.request(
+    CODEX_CONTROL_METHODS.resumeThread,
+    {
+      threadId: params.threadId,
+      ...(params.model ? { model: params.model } : {}),
+      approvalPolicy: params.approvalPolicy ?? runtime.approvalPolicy,
+      sandbox: params.sandbox ?? runtime.sandbox,
+      approvalsReviewer: runtime.approvalsReviewer,
+      ...(params.serviceTier ? { serviceTier: params.serviceTier } : {}),
+      persistExtendedHistory: true,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+}
+
+function buildBindingLookup(params: {
+  agentDir?: string;
+  config?: CodexAppServerBindingLookup["config"];
+}): CodexAppServerBindingLookup {
+  const agentDir = params.agentDir?.trim();
+  return {
+    ...(agentDir ? { agentDir } : {}),
+    ...(params.config ? { config: params.config } : {}),
+  };
+}
+
+function permissionsForMode(mode: PermissionsMode): {
+  approvalPolicy: CodexAppServerApprovalPolicy;
+  sandbox: CodexAppServerSandboxMode;
+} {
+  return mode === "yolo"
+    ? { approvalPolicy: "never", sandbox: "danger-full-access" }
+    : { approvalPolicy: "on-request", sandbox: "workspace-write" };
+}

package/src/conversation-turn-collector.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from "vitest";
+import { createCodexConversationTurnCollector } from "./conversation-turn-collector.js";
+
+describe("codex conversation turn collector", () => {
+  it("collects streamed assistant deltas for the active turn", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", turnId: "turn-1", itemId: "item-1", delta: "hello " },
+    });
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", turnId: "turn-1", itemId: "item-1", delta: "world" },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
+    });
+
+    await expect(completion).resolves.toEqual({ replyText: "hello world" });
+  });
+
+  it("buffers pre-start notifications and replays only the selected turn", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: {
+          id: "turn-stale",
+          status: "completed",
+          items: [{ type: "agentMessage", id: "wrong", text: "stale answer" }],
+        },
+      },
+    });
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", turnId: "turn-1", itemId: "right", delta: "fresh " },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: {
+          id: "turn-1",
+          status: "completed",
+          items: [{ type: "agentMessage", id: "right", text: "fresh answer" }],
+        },
+      },
+    });
+
+    collector.setTurnId("turn-1");
+
+    await expect(collector.wait({ timeoutMs: 1_000 })).resolves.toEqual({
+      replyText: "fresh answer",
+    });
+  });
+
+  it("uses completed agent message items when deltas are absent", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "item/completed",
+      params: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        item: { type: "agentMessage", id: "item-1", text: "final answer" },
+      },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
+    });
+
+    await expect(completion).resolves.toEqual({ replyText: "final answer" });
+  });
+
+  it("ignores notifications for other threads or turns", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-2", turnId: "turn-1", itemId: "wrong", delta: "wrong" },
+    });
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", turnId: "turn-2", itemId: "wrong", delta: "wrong" },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: {
+          id: "turn-1",
+          status: "completed",
+          items: [{ type: "agentMessage", id: "item-1", text: "right" }],
+        },
+      },
+    });
+
+    await expect(completion).resolves.toEqual({ replyText: "right" });
+  });
+
+  it("ignores unscoped deltas once the active turn is known", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", itemId: "wrong", delta: "wrong" },
+    });
+    collector.handleNotification({
+      method: "item/agentMessage/delta",
+      params: { threadId: "thread-1", turnId: "turn-1", itemId: "right", delta: "right" },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
+    });
+
+    await expect(completion).resolves.toEqual({ replyText: "right" });
+  });
+
+  it("does not complete from unscoped turn completion once the active turn is known", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: {
+          status: "completed",
+          items: [{ type: "agentMessage", id: "wrong", text: "wrong" }],
+        },
+      },
+    });
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: {
+          id: "turn-1",
+          status: "completed",
+          items: [{ type: "agentMessage", id: "right", text: "right" }],
+        },
+      },
+    });
+
+    await expect(completion).resolves.toEqual({ replyText: "right" });
+  });
+
+  it("rejects failed turns with the app-server error message", async () => {
+    const collector = createCodexConversationTurnCollector("thread-1");
+    collector.setTurnId("turn-1");
+    const completion = collector.wait({ timeoutMs: 1_000 });
+
+    collector.handleNotification({
+      method: "turn/completed",
+      params: {
+        threadId: "thread-1",
+        turn: { id: "turn-1", status: "failed", error: { message: "model exploded" }, items: [] },
+      },
+    });
+
+    await expect(completion).rejects.toThrow("model exploded");
+  });
+
+  it("times out when the app-server never completes the turn", async () => {
+    vi.useFakeTimers();
+    try {
+      const collector = createCodexConversationTurnCollector("thread-1");
+      const completion = collector.wait({ timeoutMs: 100 });
+      const assertion = expect(completion).rejects.toThrow("codex app-server bound turn timed out");
+      await vi.advanceTimersByTimeAsync(100);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/conversation-turn-collector.ts

@@ -0,0 +1,186 @@
+import {
+  isJsonObject,
+  type CodexServerNotification,
+  type JsonObject,
+} from "./app-server/protocol.js";
+
+const MAX_PENDING_NOTIFICATIONS_PER_TURN = 100;
+
+export function createCodexConversationTurnCollector(threadId: string) {
+  let turnId: string | undefined;
+  let completed = false;
+  let failedError: string | undefined;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const assistantTextByItem = new Map<string, string>();
+  const assistantOrder: string[] = [];
+  const pendingNotificationsByTurnId = new Map<string, CodexServerNotification[]>();
+  let resolveCompletion: ((value: { replyText: string }) => void) | undefined;
+  let rejectCompletion: ((error: Error) => void) | undefined;
+
+  const rememberItem = (itemId: string) => {
+    if (!assistantOrder.includes(itemId)) {
+      assistantOrder.push(itemId);
+    }
+  };
+  const collectReplyText = (): string => {
+    const texts = assistantOrder
+      .map((itemId) => assistantTextByItem.get(itemId)?.trim())
+      .filter((text): text is string => Boolean(text));
+    return texts.at(-1) ?? "";
+  };
+  const clearWaitState = () => {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = undefined;
+    }
+    resolveCompletion = undefined;
+    rejectCompletion = undefined;
+  };
+  const finish = () => {
+    if (completed) {
+      return;
+    }
+    completed = true;
+    if (failedError) {
+      rejectCompletion?.(new Error(failedError));
+    } else {
+      resolveCompletion?.({ replyText: collectReplyText() });
+    }
+    clearWaitState();
+  };
+
+  const handleNotification = (notification: CodexServerNotification) => {
+    const params = isJsonObject(notification.params) ? notification.params : undefined;
+    if (!params || readString(params, "threadId") !== threadId) {
+      return;
+    }
+    if (!turnId) {
+      const pendingTurnId = readNotificationTurnId(params);
+      if (pendingTurnId) {
+        const pending = pendingNotificationsByTurnId.get(pendingTurnId) ?? [];
+        if (pending.length < MAX_PENDING_NOTIFICATIONS_PER_TURN) {
+          pending.push(notification);
+          pendingNotificationsByTurnId.set(pendingTurnId, pending);
+        }
+      }
+      return;
+    }
+    if (!isNotificationForTurn(params, threadId, turnId)) {
+      return;
+    }
+    if (notification.method === "item/agentMessage/delta") {
+      const itemId = readString(params, "itemId") ?? readString(params, "id") ?? "assistant";
+      const delta = readTextString(params, "delta");
+      if (!delta) {
+        return;
+      }
+      rememberItem(itemId);
+      assistantTextByItem.set(itemId, `${assistantTextByItem.get(itemId) ?? ""}${delta}`);
+      return;
+    }
+    if (notification.method === "item/completed") {
+      const item = isJsonObject(params.item) ? params.item : undefined;
+      if (item?.type === "agentMessage") {
+        const itemId = readString(item, "id") ?? readString(params, "itemId") ?? "assistant";
+        const text = readTextString(item, "text");
+        if (text) {
+          rememberItem(itemId);
+          assistantTextByItem.set(itemId, text);
+        }
+      }
+      return;
+    }
+    if (notification.method === "turn/completed") {
+      const turn = isJsonObject(params.turn) ? params.turn : undefined;
+      const status = readString(turn, "status");
+      if (status === "failed") {
+        failedError =
+          readString(readRecord(turn?.error), "message") ?? "codex app-server turn failed";
+      }
+      const items = Array.isArray(turn?.items) ? turn.items : [];
+      for (const item of items) {
+        if (!isJsonObject(item) || item.type !== "agentMessage") {
+          continue;
+        }
+        const itemId = readString(item, "id") ?? `assistant-${assistantOrder.length + 1}`;
+        const text = readTextString(item, "text");
+        if (text) {
+          rememberItem(itemId);
+          assistantTextByItem.set(itemId, text);
+        }
+      }
+      finish();
+    }
+  };
+
+  return {
+    setTurnId(nextTurnId: string) {
+      turnId = nextTurnId;
+      const pending = pendingNotificationsByTurnId.get(nextTurnId) ?? [];
+      pendingNotificationsByTurnId.clear();
+      for (const notification of pending) {
+        handleNotification(notification);
+      }
+    },
+    handleNotification,
+    wait(params: { timeoutMs: number }): Promise<{ replyText: string }> {
+      if (completed) {
+        return failedError
+          ? Promise.reject(new Error(failedError))
+          : Promise.resolve({ replyText: collectReplyText() });
+      }
+      return new Promise<{ replyText: string }>((resolve, reject) => {
+        resolveCompletion = resolve;
+        rejectCompletion = reject;
+        timeout = setTimeout(
+          () => {
+            completed = true;
+            reject(new Error("codex app-server bound turn timed out"));
+            clearWaitState();
+          },
+          Math.max(100, params.timeoutMs),
+        );
+        timeout.unref?.();
+      });
+    },
+  };
+}
+
+function isNotificationForTurn(
+  params: JsonObject,
+  threadId: string,
+  turnId: string | undefined,
+): boolean {
+  if (readString(params, "threadId") !== threadId) {
+    return false;
+  }
+  if (!turnId) {
+    return true;
+  }
+  const directTurnId = readString(params, "turnId");
+  if (directTurnId) {
+    return directTurnId === turnId;
+  }
+  const turn = isJsonObject(params.turn) ? params.turn : undefined;
+  return readString(turn, "id") === turnId;
+}
+
+function readNotificationTurnId(params: JsonObject): string | undefined {
+  return readString(params, "turnId") ?? readString(readRecord(params.turn), "id");
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readString(record: Record<string, unknown> | JsonObject | undefined, key: string) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readTextString(record: Record<string, unknown> | JsonObject | undefined, key: string) {
+  const value = record?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}