@opengeni/codex 0.2.3 → 0.2.7

package/src/fetch.ts

@@ -10,13 +10,24 @@
 //   - retries once on 401 after a forced token refresh (spec §1.9)
 // Stream parsing is delegated to the SDK (SSE passthrough; spec §0(d)).
 
+import { randomUUID } from "node:crypto";
 import { CODEX_ORIGINATOR } from "./constants";
 import { normalizeCodexRequestBody } from "./normalize";
 import {
   codexRequestStorage,
+  type CodexModelRequestEvent,
+  type CodexRequestContext,
+  type CodexResponseTimeoutPolicy,
   type CodexTokenSnapshot,
   type CodexUsageHeaderSnapshot,
 } from "./request-context";
+import {
+  CODEX_RESPONSE_TIMEOUT_ERROR_TYPE,
+  CodexResponseTimeoutError,
+  classifyCodexResponseTimeoutError,
+  isPreHeadersTimeoutError,
+  resolveCodexResponseTimeoutPolicy,
+} from "./response-timeout";
 
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
@@ -118,6 +129,252 @@ export function parseCodexUsageHeaders(headers: Headers): CodexUsageHeaderSnapsh
   };
 }
 
+type RequestAudit = {
+  ctx: CodexRequestContext;
+  requestId: string;
+  transportAttempt: number;
+  model?: string;
+  logicalStartedAt: number;
+  attemptStartedAt: number;
+  policy: CodexResponseTimeoutPolicy;
+};
+
+async function emitRequestEvent(
+  audit: RequestAudit,
+  event: Omit<
+    CodexModelRequestEvent,
+    "requestId" | "transportAttempt" | "model" | "durationMs" | "timeoutPolicy"
+  >,
+): Promise<void> {
+  await audit.ctx.onModelRequestEvent?.({
+    requestId: audit.requestId,
+    transportAttempt: audit.transportAttempt,
+    ...(audit.model ? { model: audit.model } : {}),
+    durationMs: Math.max(0, Date.now() - audit.attemptStartedAt),
+    timeoutPolicy: audit.policy,
+    ...event,
+  });
+}
+
+function providerRequestId(headers: Headers): string | undefined {
+  return headers.get("x-request-id") ?? headers.get("request-id") ?? undefined;
+}
+
+async function fetchBeforeHeaders(
+  base: FetchLike,
+  input: string,
+  init: RequestInit,
+  audit: RequestAudit,
+): Promise<Response> {
+  const elapsed = Date.now() - audit.logicalStartedAt;
+  const wholeRemainingMs = audit.policy.wholeRequestTimeoutMs - elapsed;
+  const timeoutClass =
+    wholeRemainingMs <= audit.policy.headersTimeoutMs ? "whole_request" : "headers";
+  const deadlineMs = Math.max(1, Math.min(audit.policy.headersTimeoutMs, wholeRemainingMs));
+  if (wholeRemainingMs <= 0) {
+    throw new CodexResponseTimeoutError("whole_request", audit.requestId, false);
+  }
+
+  const externalSignal = init.signal;
+  if (externalSignal?.aborted) throw externalSignal.reason;
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(externalSignal?.reason);
+  externalSignal?.addEventListener("abort", forwardAbort, { once: true });
+  const basePromise = base(input, { ...init, signal: controller.signal });
+  let deadlineError: CodexResponseTimeoutError | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      deadlineError = new CodexResponseTimeoutError(timeoutClass, audit.requestId, false);
+      reject(deadlineError);
+    }, deadlineMs);
+  });
+  try {
+    return await Promise.race([basePromise, deadline]);
+  } catch (error) {
+    if (deadlineError) {
+      controller.abort(deadlineError);
+      void basePromise
+        .then((late) => late.body?.cancel(deadlineError ?? undefined))
+        .catch(() => undefined);
+      throw deadlineError;
+    }
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    externalSignal?.removeEventListener("abort", forwardAbort);
+  }
+}
+
+async function observedResponse(
+  res: Response,
+  audit: RequestAudit,
+  externalSignal: AbortSignal | null | undefined,
+): Promise<Response> {
+  const requestId = providerRequestId(res.headers);
+  if (!res.body) {
+    await emitRequestEvent(audit, {
+      phase: res.ok ? "completed" : "failed",
+      responseObserved: true,
+      status: res.status,
+      ...(requestId ? { providerRequestId: requestId } : {}),
+    });
+    return res;
+  }
+
+  const reader = res.body.getReader();
+  let terminal = false;
+  let firstByte = false;
+  let idleTimer: ReturnType<typeof setTimeout> | undefined;
+  let wholeTimer: ReturnType<typeof setTimeout> | undefined;
+  let armIdle: () => void = () => undefined;
+  let abortFromOutside: (() => void) | undefined;
+
+  const clearTimers = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    if (wholeTimer) clearTimeout(wholeTimer);
+    if (abortFromOutside) externalSignal?.removeEventListener("abort", abortFromOutside);
+  };
+
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const timeOut = (klass: "idle_stream" | "whole_request") => {
+        if (terminal) return;
+        terminal = true;
+        clearTimers();
+        const error = new CodexResponseTimeoutError(klass, audit.requestId, true);
+        void reader.cancel(error).catch(() => undefined);
+        void emitRequestEvent(audit, {
+          phase: "timed_out",
+          responseObserved: true,
+          timeoutClass: klass,
+          status: res.status,
+          ...(requestId ? { providerRequestId: requestId } : {}),
+        }).then(
+          () => controller.error(error),
+          () => controller.error(error),
+        );
+      };
+      armIdle = () => {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => timeOut("idle_stream"), audit.policy.streamIdleTimeoutMs);
+      };
+      armIdle();
+      const wholeRemaining = Math.max(
+        1,
+        audit.policy.wholeRequestTimeoutMs - (Date.now() - audit.logicalStartedAt),
+      );
+      wholeTimer = setTimeout(() => timeOut("whole_request"), wholeRemaining);
+      abortFromOutside = () => {
+        if (terminal) return;
+        terminal = true;
+        clearTimers();
+        const reason = externalSignal?.reason ?? new DOMException("Aborted", "AbortError");
+        void reader.cancel(reason).catch(() => undefined);
+        void emitRequestEvent(audit, {
+          phase: "failed",
+          responseObserved: true,
+          status: res.status,
+          ...(requestId ? { providerRequestId: requestId } : {}),
+        }).then(
+          () => controller.error(reason),
+          () => controller.error(reason),
+        );
+      };
+      if (externalSignal?.aborted) {
+        abortFromOutside();
+      } else {
+        externalSignal?.addEventListener("abort", abortFromOutside, { once: true });
+      }
+    },
+    async pull(controller) {
+      if (terminal) return;
+      try {
+        const chunk = await reader.read();
+        if (terminal) return;
+        if (chunk.done) {
+          terminal = true;
+          clearTimers();
+          await emitRequestEvent(audit, {
+            phase: res.ok ? "completed" : "failed",
+            responseObserved: true,
+            status: res.status,
+            ...(requestId ? { providerRequestId: requestId } : {}),
+          });
+          controller.close();
+          return;
+        }
+        armIdle();
+        if (!firstByte) {
+          firstByte = true;
+          await emitRequestEvent(audit, {
+            phase: "first_byte",
+            responseObserved: true,
+            status: res.status,
+            ...(requestId ? { providerRequestId: requestId } : {}),
+          });
+        }
+        controller.enqueue(chunk.value);
+      } catch (error) {
+        if (terminal) return;
+        terminal = true;
+        clearTimers();
+        await emitRequestEvent(audit, {
+          phase: "failed",
+          responseObserved: true,
+          status: res.status,
+          ...(requestId ? { providerRequestId: requestId } : {}),
+        });
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      if (!terminal) {
+        terminal = true;
+        clearTimers();
+        await emitRequestEvent(audit, {
+          phase: "failed",
+          responseObserved: true,
+          status: res.status,
+          ...(requestId ? { providerRequestId: requestId } : {}),
+        }).catch(() => undefined);
+      }
+      await reader.cancel(reason).catch(() => undefined);
+    },
+  });
+  const headers = new Headers(res.headers);
+  headers.delete("content-length");
+  return new Response(body, { status: res.status, statusText: res.statusText, headers });
+}
+
+function timeoutErrorResponse(info: {
+  timeoutClass: "connect" | "headers" | "idle_stream" | "whole_request";
+  requestId: string;
+  responseObserved: boolean;
+  message: string;
+}): Response {
+  return new Response(
+    JSON.stringify({
+      error: {
+        type: CODEX_RESPONSE_TIMEOUT_ERROR_TYPE,
+        code: CODEX_RESPONSE_TIMEOUT_ERROR_TYPE,
+        message: info.message,
+        timeout_class: info.timeoutClass,
+        response_observed: info.responseObserved,
+        request_id: info.requestId,
+      },
+    }),
+    {
+      status: 504,
+      headers: {
+        "content-type": "application/json",
+        "x-should-retry": "false",
+        [CODEX_TRANSPORT_ERROR_HEADER]: "1",
+      },
+    },
+  );
+}
+
 export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): FetchLike {
   return async (input, init) => {
     const ctx = codexRequestStorage.getStore();
@@ -131,7 +388,15 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
     // URLs whose base already includes /codex (avoids /codex/codex/responses).
     const rewritten = rawUrl.replace(/(?<!\/codex)\/responses(\b|$)/, "/codex/responses$1");
 
-    const attempt = async (auth: CodexTokenSnapshot): Promise<Response> => {
+    const policy = resolveCodexResponseTimeoutPolicy(ctx.responseTimeoutPolicy);
+    const requestId = ctx.nextRequestId?.() ?? randomUUID();
+    const logicalStartedAt = Date.now();
+    let transportAttempt = 0;
+
+    const attempt = async (
+      auth: CodexTokenSnapshot,
+      authenticationAttempt: number,
+    ): Promise<Response> => {
       const headers = new Headers(init?.headers);
       headers.set("Authorization", `Bearer ${auth.accessToken}`);
       if (auth.chatgptAccountId) {
@@ -158,26 +423,90 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
       // the caller's intent so a non-streaming caller (e.g. the compaction
       // summarizer) still gets a single JSON Response back.
       let callerWantsStream = true;
+      let model: string | undefined;
       const nextInit: RequestInit = { ...init, headers };
       if (typeof init?.body === "string") {
         try {
           const parsed = JSON.parse(init.body) as Record<string, unknown>;
           callerWantsStream = parsed.stream === true;
-          nextInit.body = JSON.stringify(normalizeCodexRequestBody(parsed, ctx.resolveModel));
+          const normalized = normalizeCodexRequestBody(parsed, ctx.resolveModel);
+          model = typeof normalized.model === "string" ? normalized.model : undefined;
+          nextInit.body = JSON.stringify(normalized);
         } catch {
           /* leave unparseable bodies untouched (already copied from init) */
         }
       }
+      headers.set(
+        "Idempotency-Key",
+        authenticationAttempt === 0 ? requestId : `${requestId}:auth-${authenticationAttempt}`,
+      );
       if (process.env.CODEX_DEBUG) {
-        const keys =
-          typeof nextInit.body === "string"
-            ? Object.keys(JSON.parse(nextInit.body) as Record<string, unknown>)
-            : [];
+        let keys: string[] = [];
+        if (typeof nextInit.body === "string") {
+          try {
+            keys = Object.keys(JSON.parse(nextInit.body) as Record<string, unknown>);
+          } catch {
+            /* an unparseable body is already passed through unchanged above */
+          }
+        }
         console.error(
           `[codex-debug] POST ${rewritten} stream=${callerWantsStream} bodyKeys=[${keys.join(",")}]`,
         );
       }
-      const res = await base(rewritten, nextInit);
+      let res: Response;
+      transportAttempt += 1;
+      const audit: RequestAudit = {
+        ctx,
+        requestId,
+        transportAttempt,
+        ...(model ? { model } : {}),
+        logicalStartedAt,
+        attemptStartedAt: Date.now(),
+        policy,
+      };
+      await emitRequestEvent(audit, {
+        phase: "started",
+        responseObserved: false,
+      });
+      try {
+        res = await fetchBeforeHeaders(base, rewritten, nextInit, audit);
+        const upstreamRequestId = providerRequestId(res.headers);
+        await emitRequestEvent(audit, {
+          phase: "headers",
+          responseObserved: true,
+          status: res.status,
+          ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+        });
+        const observed = await observedResponse(res, audit, nextInit.signal);
+        res = observed;
+      } catch (error) {
+        if (nextInit.signal?.aborted) {
+          await emitRequestEvent(audit, {
+            phase: "failed",
+            responseObserved: false,
+          }).catch(() => undefined);
+          throw error;
+        }
+        const klass = isPreHeadersTimeoutError(error);
+        if (!klass) {
+          await emitRequestEvent(audit, {
+            phase: "failed",
+            responseObserved: false,
+          });
+          throw error;
+        }
+        // An absent response does not prove that the provider never accepted
+        // this operation. Until a provider-specific receipt can prove
+        // non-acceptance or resume the same operation, never replay it.
+        // Audit persistence must not replace the typed transport timeout.
+        await emitRequestEvent(audit, {
+          phase: "timed_out",
+          responseObserved: false,
+          timeoutClass: klass,
+          willRetry: false,
+        }).catch(() => undefined);
+        throw new CodexResponseTimeoutError(klass, requestId, false);
+      }
       // Multi-account P4 (Part A): scrape the usage headers ONCE, before the
       // OK/!res.ok branch, so the same fire-and-forget read also covers the 429
       // hard-cap path (an exhausted serving account stamps its own fresh
@@ -216,11 +545,22 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
       return callerWantsStream ? repairCodexStream(res) : await sseToJsonResponse(res);
     };
 
-    let res = await attempt(await ctx.getToken());
-    if (res.status === 401) {
-      res = await attempt(await ctx.refresh()); // single refresh-on-401 retry (spec §1.9)
+    try {
+      let res = await attempt(await ctx.getToken(), 0);
+      if (res.status === 401) {
+        res = await attempt(await ctx.refresh(), 1); // single refresh-on-401 retry (spec §1.9)
+      }
+      return res;
+    } catch (error) {
+      const timeout = classifyCodexResponseTimeoutError(error);
+      if (!timeout) throw error;
+      return timeoutErrorResponse({
+        timeoutClass: timeout.timeoutClass,
+        requestId: timeout.requestId ?? requestId,
+        responseObserved: timeout.responseObserved,
+        message: timeout.message,
+      });
     }
-    return res;
   };
 }
 
@@ -292,7 +632,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 +647,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 +658,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 +742,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 +1014,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 === "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.type === "response.incomplete") &&
-    ev.response
-  ) {
+  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 };
 }