@opengeni/codex 0.2.2 → 0.2.5

package/src/constants.ts

@@ -31,7 +31,7 @@ export const CODEX_MODEL_ID_PREFIX = "codex/";
 export const CODEX_FALLBACK_MODEL_SLUGS = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"] as const;
 
 // Live Codex model-catalog values for every exposed gpt-5.6 subscription slug.
-// Verified 2026-07-14 against Codex CLI 0.144.4's freshly fetched
+// Verified 2026-07-18 against Codex CLI 0.144.6's freshly fetched
 // ~/.codex/models_cache.json and the matching openai/codex core derivations:
 //   raw context window                = 272,000
 //   effective input window (95%)      = 258,400
@@ -52,7 +52,7 @@ export const CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT = Math.floor(
 // 2026-07-09: 0.142.4 filtered every GPT-5.6 slug out of GET /models, while the
 // official Codex 0.144.0+ releases return all three exact slugs above. Keep
 // this pinned to the latest stable Codex release we have verified end-to-end.
-export const CODEX_CLIENT_VERSION = "0.144.4";
+export const CODEX_CLIENT_VERSION = "0.144.6";
 
 export const CODEX_REFRESH_WINDOW_MS = 5 * 60 * 1000; // proactive refresh when within 5 min of exp (spec §1.1)
 export const CODEX_REFRESH_FALLBACK_MS = 8 * 24 * 60 * 60 * 1000; // 8 days when exp is unparseable

package/src/fetch.ts

@@ -292,7 +292,11 @@ async function bufferCodexErrorResponse(res: Response): Promise<Response> {
   if (errorType === CODEX_USAGE_LIMIT_ERROR_TYPE) {
     headers.set("x-should-retry", "false");
   }
-  return new Response(bodyText, { status: res.status, statusText: res.statusText, headers });
+  return new Response(bodyText, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
 }
 
 /**
@@ -303,14 +307,10 @@ async function bufferCodexErrorResponse(res: Response): Promise<Response> {
 async function sseToJsonResponse(res: Response): Promise<Response> {
   const text = await res.text();
   let final: Record<string, unknown> | null = null;
+  let terminalError: Response | null = null;
   const items: unknown[] = []; // assembled from output_item.done (the codex backend
   // leaves response.completed.response.output empty and emits the items separately).
-  for (const block of text.split("\n\n")) {
-    const data = block
-      .split("\n")
-      .filter((l) => l.startsWith("data:"))
-      .map((l) => l.slice(5).trim())
-      .join("\n");
+  for (const data of sseDataPayloads(text)) {
     if (!data || data === "[DONE]") {
       continue;
     }
@@ -318,21 +318,79 @@ async function sseToJsonResponse(res: Response): Promise<Response> {
       const ev = JSON.parse(data) as {
         type?: string;
         response?: Record<string, unknown>;
+        error?: unknown;
+        code?: unknown;
+        message?: unknown;
+        param?: unknown;
         item?: unknown;
       };
       if (ev.type === "response.output_item.done" && ev.item !== undefined) {
         items.push(ev.item);
-      } else if (
-        ev.type === "response.completed" ||
-        ev.type === "response.done" ||
-        ev.type === "response.incomplete"
-      ) {
+      } else if (ev.type === "response.failed") {
+        terminalError = codexSseFailureResponse(
+          res,
+          ev.response?.error,
+          "response_failed",
+          "The Codex response failed",
+          {
+            eventType: ev.type,
+            responseId: ev.response?.id,
+            responseStatus: ev.response?.status,
+          },
+        );
+      } else if (ev.type === "error" || ev.type === "response.error") {
+        terminalError = codexSseFailureResponse(
+          res,
+          ev.error ?? ev.response?.error ?? ev,
+          "response_error",
+          "The Codex response stream reported an error",
+          {
+            eventType: ev.type,
+            responseId: ev.response?.id,
+            responseStatus: ev.response?.status,
+          },
+        );
+      } else if (ev.type === "response.incomplete") {
+        const details = ev.response?.incomplete_details;
+        const reason =
+          details && typeof details === "object"
+            ? (details as Record<string, unknown>).reason
+            : undefined;
+        terminalError = codexSseFailureResponse(
+          res,
+          {
+            code: "response_incomplete",
+            message:
+              typeof reason === "string" && reason.length > 0
+                ? `The Codex response was incomplete (${reason})`
+                : "The Codex response was incomplete",
+          },
+          "response_incomplete",
+          "The Codex response was incomplete",
+          {
+            eventType: ev.type,
+            responseId: ev.response?.id,
+            responseStatus: ev.response?.status,
+          },
+        );
+      } else if (ev.type === "response.completed" || ev.type === "response.done") {
         final = ev.response ?? null;
       }
     } catch {
       /* ignore non-JSON keepalive lines */
     }
   }
+  if (terminalError) {
+    return terminalError;
+  }
+  if (!final) {
+    return codexSseFailureResponse(
+      res,
+      null,
+      "invalid_sse_terminal",
+      "The Codex response stream ended without a terminal response",
+    );
+  }
   if (final && items.length > 0) {
     final = { ...final, output: items }; // prefer the assembled items over an empty output array
   }
@@ -344,7 +402,269 @@ async function sseToJsonResponse(res: Response): Promise<Response> {
   const headers = new Headers(res.headers);
   headers.set("content-type", "application/json");
   headers.delete("content-length");
-  return new Response(JSON.stringify(final ?? {}), { status: 200, headers });
+  return new Response(JSON.stringify(final), { status: 200, headers });
+}
+
+const NON_RETRYABLE_SSE_ERROR_CODES = new Set([
+  "bio_policy",
+  "context_length_exceeded",
+  "cyber_policy",
+  "insufficient_quota",
+  "invalid_prompt",
+  "usage_limit_reached",
+]);
+
+/**
+ * Project the data payloads from a complete SSE body. EventSource accepts LF,
+ * CRLF, and bare CR line endings; splitting only on `\n\n` can therefore merge
+ * a standards-valid terminal failure into the preceding event and silently
+ * turn it into `{}`. Preserve the SSE rule that multiple data lines are joined
+ * with `\n`, and tolerate a final event without a trailing blank line as the
+ * previous transport parser did.
+ */
+function sseDataPayloads(text: string): string[] {
+  const payloads: string[] = [];
+  let dataLines: string[] = [];
+  const dispatch = () => {
+    if (dataLines.length > 0) payloads.push(dataLines.join("\n"));
+    dataLines = [];
+  };
+
+  for (const line of text.split(/\r\n|\r|\n/)) {
+    if (line === "") {
+      dispatch();
+      continue;
+    }
+    if (line === "data") {
+      dataLines.push("");
+      continue;
+    }
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    dataLines.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  dispatch();
+  return payloads;
+}
+
+const CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES = 256;
+const CODEX_TERMINAL_ERROR_MESSAGE_MAX_BYTES = 4 * 1024;
+const CODEX_TERMINAL_ERROR_TRUNCATION_MARKER = "… [truncated]";
+
+function boundedTerminalErrorField(
+  value: unknown,
+  maxBytes: number,
+): { value?: string; truncated: boolean } {
+  if (typeof value !== "string") return { truncated: false };
+  const encoder = new TextEncoder();
+  const encoded = encoder.encode(value);
+  if (encoded.byteLength <= maxBytes) return { value, truncated: false };
+
+  const markerBytes = encoder.encode(CODEX_TERMINAL_ERROR_TRUNCATION_MARKER).byteLength;
+  let prefixEnd = Math.max(0, maxBytes - markerBytes);
+  while (prefixEnd > 0 && (encoded[prefixEnd]! & 0xc0) === 0x80) {
+    prefixEnd -= 1;
+  }
+  return {
+    value: `${new TextDecoder().decode(encoded.subarray(0, prefixEnd))}${CODEX_TERMINAL_ERROR_TRUNCATION_MARKER}`,
+    truncated: true,
+  };
+}
+
+/**
+ * Convert a terminal error carried inside an HTTP-200 SSE stream into the
+ * ordinary non-2xx JSON error contract expected by the OpenAI SDK. Codex CLI
+ * treats the same events as provider failures; returning a successful `{}`
+ * loses the actual cause and makes compaction look semantically empty.
+ */
+function codexSseFailureResponse(
+  source: Response,
+  rawError: unknown,
+  fallbackCode: string,
+  fallbackMessage: string,
+  metadata: {
+    eventType?: unknown;
+    responseId?: unknown;
+    responseStatus?: unknown;
+  } = {},
+): Response {
+  const projection = codexSseFailureProjection(
+    source,
+    rawError,
+    fallbackCode,
+    fallbackMessage,
+    metadata,
+  );
+  return new Response(JSON.stringify({ error: projection.error }), {
+    status: projection.status,
+    headers: projection.headers,
+  });
+}
+
+export type CodexSseFailureProjection = {
+  status: number;
+  error: {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+    event_type?: string;
+    response_id?: string;
+    response_status?: string;
+    diagnostic_truncated?: true;
+  };
+  headers: Headers;
+};
+
+function codexSseFailureProjection(
+  source: Response,
+  rawError: unknown,
+  fallbackCode: string,
+  fallbackMessage: string,
+  metadata: {
+    eventType?: unknown;
+    responseId?: unknown;
+    responseStatus?: unknown;
+  } = {},
+): CodexSseFailureProjection {
+  const record =
+    rawError && typeof rawError === "object" && !Array.isArray(rawError)
+      ? (rawError as Record<string, unknown>)
+      : {};
+  const typeField = boundedTerminalErrorField(record.type, CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES);
+  const codeField = boundedTerminalErrorField(record.code, CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES);
+  const messageField = boundedTerminalErrorField(
+    record.message ?? (typeof rawError === "string" ? rawError : undefined),
+    CODEX_TERMINAL_ERROR_MESSAGE_MAX_BYTES,
+  );
+  const paramField = boundedTerminalErrorField(record.param, CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES);
+  const eventTypeField = boundedTerminalErrorField(
+    metadata.eventType,
+    CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES,
+  );
+  const responseIdField = boundedTerminalErrorField(
+    metadata.responseId,
+    CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES,
+  );
+  const responseStatusField = boundedTerminalErrorField(
+    metadata.responseStatus,
+    CODEX_TERMINAL_ERROR_FIELD_MAX_BYTES,
+  );
+  const providerType =
+    typeField.value === "error" ||
+    typeField.value === "response.error" ||
+    typeField.value === "response.failed"
+      ? undefined
+      : typeField.value;
+  const code =
+    (codeField.value?.length ? codeField.value : undefined) ??
+    (providerType?.length ? providerType : undefined) ??
+    fallbackCode;
+  const diagnosticTruncated =
+    typeField.truncated ||
+    codeField.truncated ||
+    messageField.truncated ||
+    paramField.truncated ||
+    eventTypeField.truncated ||
+    responseIdField.truncated ||
+    responseStatusField.truncated ||
+    Object.keys(record).some((key) => !["type", "code", "message", "param"].includes(key)) ||
+    (rawError !== null &&
+      rawError !== undefined &&
+      typeof rawError !== "string" &&
+      (typeof rawError !== "object" || Array.isArray(rawError)));
+  const error: CodexSseFailureProjection["error"] = {
+    type: providerType?.length ? providerType : code,
+    code,
+    message: messageField.value?.length ? messageField.value : fallbackMessage,
+    ...(paramField.value?.length ? { param: paramField.value } : {}),
+    ...(eventTypeField.value?.length ? { event_type: eventTypeField.value } : {}),
+    ...(responseIdField.value?.length ? { response_id: responseIdField.value } : {}),
+    ...(responseStatusField.value?.length ? { response_status: responseStatusField.value } : {}),
+    ...(diagnosticTruncated ? { diagnostic_truncated: true } : {}),
+  };
+  const status =
+    code === "rate_limit_exceeded" ||
+    code === "usage_limit_reached" ||
+    code === "insufficient_quota"
+      ? 429
+      : NON_RETRYABLE_SSE_ERROR_CODES.has(code)
+        ? 400
+        : 502;
+  const headers = new Headers(source.headers);
+  headers.set("content-type", "application/json");
+  headers.set(CODEX_TRANSPORT_ERROR_HEADER, "1");
+  // A terminal event means the provider already accepted and completed this
+  // request. Never let the OpenAI SDK replay it merely because we synthesized
+  // a non-2xx response to preserve the terminal failure.
+  headers.set("x-should-retry", "false");
+  headers.delete("content-length");
+  headers.delete("content-encoding");
+  return { status, error, headers };
+}
+
+/**
+ * A provider terminal carried inside an accepted HTTP-200 stream. The OpenAI
+ * SDK cannot turn that late terminal into a non-2xx APIError because headers
+ * have already been accepted, so the body transform throws this equivalent
+ * bounded shape. Provider-supplied message/param text is intentionally absent:
+ * the worker may persist Error.message, while identifiers/classifications are
+ * sufficient for retry, compaction, and incident diagnostics.
+ */
+export class CodexStreamingTerminalError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly type: string;
+  readonly eventType?: string;
+  readonly responseId?: string;
+  readonly responseStatus?: string;
+  readonly headers: Headers;
+  readonly error: Record<string, unknown>;
+
+  constructor(projection: CodexSseFailureProjection, publicMessage: string) {
+    super(publicMessage);
+    this.name = "CodexStreamingTerminalError";
+    this.status = projection.status;
+    this.code = projection.error.code;
+    this.type = projection.error.type;
+    if (projection.error.event_type !== undefined) {
+      this.eventType = projection.error.event_type;
+    }
+    if (projection.error.response_id !== undefined) {
+      this.responseId = projection.error.response_id;
+    }
+    if (projection.error.response_status !== undefined) {
+      this.responseStatus = projection.error.response_status;
+    }
+    this.headers = projection.headers;
+    this.error = {
+      type: projection.error.type,
+      code: projection.error.code,
+      ...(projection.error.event_type ? { event_type: projection.error.event_type } : {}),
+      ...(projection.error.response_id ? { response_id: projection.error.response_id } : {}),
+      ...(projection.error.response_status
+        ? { response_status: projection.error.response_status }
+        : {}),
+      ...(projection.error.diagnostic_truncated ? { diagnostic_truncated: true } : {}),
+    };
+  }
+}
+
+function codexSseFailureError(
+  source: Response,
+  rawError: unknown,
+  fallbackCode: string,
+  publicMessage: string,
+  metadata: {
+    eventType?: unknown;
+    responseId?: unknown;
+    responseStatus?: unknown;
+  } = {},
+): CodexStreamingTerminalError {
+  return new CodexStreamingTerminalError(
+    codexSseFailureProjection(source, rawError, fallbackCode, publicMessage, metadata),
+    publicMessage,
+  );
 }
 
 /**
@@ -354,66 +674,223 @@ async function sseToJsonResponse(res: Response): Promise<Response> {
  */
 function repairCodexStream(res: Response): Response {
   if (!res.body) {
-    return res;
+    const error = codexSseFailureError(
+      res,
+      null,
+      "invalid_sse_terminal",
+      "The Codex response stream ended without a terminal response",
+    );
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.error(error);
+      },
+    });
+    const headers = new Headers(res.headers);
+    headers.delete("content-length");
+    return new Response(body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    });
   }
   const items: unknown[] = [];
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
   let buffer = "";
+  let successfulTerminalSeen = false;
+  const emitCompleteBlocks = (
+    controller: TransformStreamDefaultController<Uint8Array>,
+    final: boolean,
+  ) => {
+    let boundary = findSseBlockBoundary(buffer, final);
+    while (boundary) {
+      const block = buffer.slice(0, boundary.start);
+      const separator = buffer.slice(boundary.start, boundary.end);
+      buffer = buffer.slice(boundary.end);
+      const patched = patchSseBlock(block, items, res);
+      successfulTerminalSeen ||= patched.successfulTerminal;
+      controller.enqueue(encoder.encode(`${patched.block}${separator}`));
+      boundary = findSseBlockBoundary(buffer, final);
+    }
+  };
   const transform = new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
       buffer += decoder.decode(chunk, { stream: true });
-      let idx = buffer.indexOf("\n\n");
-      while (idx !== -1) {
-        const block = buffer.slice(0, idx);
-        buffer = buffer.slice(idx + 2);
-        controller.enqueue(encoder.encode(`${patchSseBlock(block, items)}\n\n`));
-        idx = buffer.indexOf("\n\n");
-      }
+      emitCompleteBlocks(controller, false);
     },
     flush(controller) {
+      buffer += decoder.decode();
+      emitCompleteBlocks(controller, true);
       if (buffer.length > 0) {
-        controller.enqueue(encoder.encode(patchSseBlock(buffer, items)));
+        const patched = patchSseBlock(buffer, items, res);
+        successfulTerminalSeen ||= patched.successfulTerminal;
+        controller.enqueue(encoder.encode(patched.block));
+        buffer = "";
+      }
+      if (!successfulTerminalSeen) {
+        throw codexSseFailureError(
+          res,
+          null,
+          "invalid_sse_terminal",
+          "The Codex response stream ended without a terminal response",
+        );
       }
     },
   });
   const headers = new Headers(res.headers);
   headers.delete("content-length");
-  return new Response(res.body.pipeThrough(transform), { status: res.status, headers });
+  return new Response(res.body.pipeThrough(transform), {
+    status: res.status,
+    headers,
+  });
+}
+
+type SseBlockBoundary = { start: number; end: number };
+
+/**
+ * Find two consecutive SSE line endings without misreading one CRLF as a bare
+ * CR followed by a bare LF. A trailing CR is intentionally held until the next
+ * chunk (or final flush), because only then can it be distinguished from the
+ * first byte of CRLF.
+ */
+function findSseBlockBoundary(value: string, final: boolean): SseBlockBoundary | null {
+  for (let index = 0; index < value.length; index += 1) {
+    const firstEnd = sseLineEndingEnd(value, index, final);
+    if (firstEnd === null) continue;
+    const secondEnd = sseLineEndingEnd(value, firstEnd, final);
+    if (secondEnd !== null) {
+      return { start: index, end: secondEnd };
+    }
+    index = firstEnd - 1;
+  }
+  return null;
 }
 
-/** Collect output_item.done items (mutating `items`); rewrite the terminal event's empty output. */
-function patchSseBlock(block: string, items: unknown[]): string {
-  const lines = block.split("\n");
+function sseLineEndingEnd(value: string, index: number, final: boolean): number | null {
+  const current = value[index];
+  if (current === "\n") return index + 1;
+  if (current !== "\r") return null;
+  if (index + 1 < value.length) {
+    return value[index + 1] === "\n" ? index + 2 : index + 1;
+  }
+  return final ? index + 1 : null;
+}
+
+type PatchedSseBlock = { block: string; successfulTerminal: boolean };
+
+/**
+ * Collect output_item.done items and rewrite only a successful terminal event.
+ * Failed/error/incomplete terminals throw before their provider message can be
+ * exposed to Agents as an ordinary response_done event.
+ */
+function patchSseBlock(block: string, items: unknown[], source: Response): PatchedSseBlock {
+  const lines = block.split(/\r\n|\r|\n/);
   const dataStr = lines
     .filter((l) => l.startsWith("data:"))
     .map((l) => l.slice(5).trim())
     .join("\n");
   if (!dataStr || dataStr === "[DONE]") {
-    return block;
+    return { block, successfulTerminal: false };
   }
-  let ev: { type?: string; item?: unknown; response?: Record<string, unknown> };
+  let ev: {
+    type?: string;
+    item?: unknown;
+    response?: Record<string, unknown>;
+    error?: unknown;
+    code?: unknown;
+    message?: unknown;
+    param?: unknown;
+  };
   try {
     ev = JSON.parse(dataStr);
   } catch {
-    return block;
+    return { block, successfulTerminal: false };
   }
   if (ev.type === "response.output_item.done" && ev.item !== undefined) {
     items.push(ev.item);
-    return block;
+    return { block, successfulTerminal: false };
+  }
+  if (ev.type === "response.failed") {
+    throw codexSseFailureError(
+      source,
+      ev.response?.error,
+      "response_failed",
+      "The Codex response failed",
+      {
+        eventType: ev.type,
+        responseId: ev.response?.id,
+        responseStatus: ev.response?.status,
+      },
+    );
   }
-  if (
-    (ev.type === "response.completed" ||
-      ev.type === "response.done" ||
-      ev.type === "response.incomplete") &&
-    ev.response
-  ) {
+  if (ev.type === "error" || ev.type === "response.error") {
+    throw codexSseFailureError(
+      source,
+      ev.error ?? ev.response?.error ?? ev,
+      "response_error",
+      "The Codex response stream reported an error",
+      {
+        eventType: ev.type,
+        responseId: ev.response?.id,
+        responseStatus: ev.response?.status,
+      },
+    );
+  }
+  if (ev.type === "response.incomplete") {
+    const details = ev.response?.incomplete_details;
+    const reason =
+      details && typeof details === "object"
+        ? (details as Record<string, unknown>).reason
+        : undefined;
+    throw codexSseFailureError(
+      source,
+      {
+        code: "response_incomplete",
+        message:
+          typeof reason === "string" && reason.length > 0
+            ? `The Codex response was incomplete (${reason})`
+            : "The Codex response was incomplete",
+      },
+      "response_incomplete",
+      "The Codex response was incomplete",
+      {
+        eventType: ev.type,
+        responseId: ev.response?.id,
+        responseStatus: ev.response?.status,
+      },
+    );
+  }
+  if ((ev.type === "response.completed" || ev.type === "response.done") && ev.response) {
+    if (
+      ev.response.status === "failed" ||
+      ev.response.status === "incomplete" ||
+      (ev.response.error !== null && ev.response.error !== undefined)
+    ) {
+      throw codexSseFailureError(
+        source,
+        ev.response.error,
+        ev.response.status === "incomplete" ? "response_incomplete" : "response_failed",
+        ev.response.status === "incomplete"
+          ? "The Codex response was incomplete"
+          : "The Codex response failed",
+        {
+          eventType: ev.type,
+          responseId: ev.response.id,
+          responseStatus: ev.response.status,
+        },
+      );
+    }
     const out = ev.response.output;
     if ((!Array.isArray(out) || out.length === 0) && items.length > 0) {
       ev.response = { ...ev.response, output: items };
       const nonData = lines.filter((l) => !l.startsWith("data:"));
-      return [...nonData, `data: ${JSON.stringify(ev)}`].join("\n");
+      const lineEnding = block.match(/\r\n|\r|\n/)?.[0] ?? "\n";
+      return {
+        block: [...nonData, `data: ${JSON.stringify(ev)}`].join(lineEnding),
+        successfulTerminal: true,
+      };
     }
+    return { block, successfulTerminal: true };
   }
-  return block;
+  return { block, successfulTerminal: false };
 }

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./api-client";
 export * from "./request-context";
 export * from "./fetch";
 export * from "./mcp-sanitize";
+export * from "./model-output-truncation";