@opengeni/codex 0.2.13 → 0.2.16

package/src/fetch.ts

@@ -39,6 +39,20 @@ export type FetchLike = (input: string | URL | Request, init?: RequestInit) => P
  * error that happened during the same Codex turn.
  */
 export const CODEX_TRANSPORT_ERROR_HEADER = "x-opengeni-codex-transport-error";
+/** Internal transport handoff; always removed before network I/O. */
+export const CODEX_REQUEST_BODY_NORMALIZED_HEADER = "x-opengeni-request-body-normalized";
+const REPLAYABLE_REQUEST_BODY_FACTORY = Symbol.for("opengeni.replayable-request-body-factory");
+
+type ReplayableRequestInit = RequestInit & {
+  [REPLAYABLE_REQUEST_BODY_FACTORY]?: () => ReadableStream<Uint8Array>;
+};
+/** Internal resolved-model handoff; always removed before network I/O. */
+export const CODEX_REQUEST_MODEL_HEADER = "x-opengeni-request-model";
+/** Internal durable request-identity handoff; always removed before network I/O. */
+export const CODEX_REQUEST_ID_HEADER = "x-opengeni-request-id";
+/** Internal original response-mode handoff; always removed before network I/O. */
+export const CODEX_REQUEST_CALLER_STREAM_HEADER = "x-opengeni-request-caller-stream";
+const MAX_CODEX_ERROR_BODY_BYTES = 64 * 1024;
 
 function headersCarryCodexTransportMarker(headers: unknown): boolean {
   if (!headers || typeof headers !== "object") return false;
@@ -186,25 +200,157 @@ type RequestAudit = {
   transportAttempt: number;
   model?: string;
   logicalStartedAt: number;
-  attemptStartedAt: number;
+  attemptStartedAtMonotonic: number;
   policy: CodexResponseTimeoutPolicy;
+  terminalOutcome: RequestTerminalOutcome | null;
 };
 
-async function emitRequestEvent(
+type RequestTerminalOutcome = "completed" | "failed" | "timed_out";
+
+type SemanticTerminalState = {
+  phase: "completed" | "failed" | null;
+  /** Non-streaming callers must parse the complete SSE body before settling. */
+  deferTransportTerminal: boolean;
+};
+
+type CodexSseEvent = {
+  type?: string;
+  response?: Record<string, unknown>;
+  error?: unknown;
+  code?: unknown;
+  message?: unknown;
+  param?: unknown;
+  item?: unknown;
+};
+
+type CodexSseTerminalClassification =
+  | { phase: "completed" }
+  | {
+      phase: "failed";
+      rawError: unknown;
+      fallbackCode: string;
+      fallbackMessage: string;
+    }
+  | null;
+
+function classifyCodexSseTerminal(ev: CodexSseEvent): CodexSseTerminalClassification {
+  if (ev.type === "response.failed") {
+    return {
+      phase: "failed",
+      rawError: ev.response?.error,
+      fallbackCode: "response_failed",
+      fallbackMessage: "The Codex response failed",
+    };
+  }
+  if (ev.type === "error" || ev.type === "response.error") {
+    return {
+      phase: "failed",
+      rawError: ev.error ?? ev.response?.error ?? ev,
+      fallbackCode: "response_error",
+      fallbackMessage: "The Codex response stream reported an error",
+    };
+  }
+  if (ev.type === "response.incomplete") {
+    const details = ev.response?.incomplete_details;
+    const reason =
+      details && typeof details === "object"
+        ? (details as Record<string, unknown>).reason
+        : undefined;
+    return {
+      phase: "failed",
+      rawError: {
+        code: "response_incomplete",
+        message:
+          typeof reason === "string" && reason.length > 0
+            ? `The Codex response was incomplete (${reason})`
+            : "The Codex response was incomplete",
+      },
+      fallbackCode: "response_incomplete",
+      fallbackMessage: "The Codex response was incomplete",
+    };
+  }
+  if (ev.type !== "response.completed" && ev.type !== "response.done") {
+    return null;
+  }
+  if (!ev.response) {
+    return null;
+  }
+
+  const responseStatus = ev.response.status;
+  if (
+    (responseStatus !== undefined && responseStatus !== "completed") ||
+    (ev.response.error !== null && ev.response.error !== undefined)
+  ) {
+    const incomplete = responseStatus === "incomplete";
+    return {
+      phase: "failed",
+      rawError: ev.response.error,
+      fallbackCode: incomplete ? "response_incomplete" : "response_failed",
+      fallbackMessage: incomplete
+        ? "The Codex response was incomplete"
+        : "The Codex response failed",
+    };
+  }
+  return { phase: "completed" };
+}
+
+function markSemanticTerminal(state: SemanticTerminalState, phase: "completed" | "failed"): void {
+  if (state.phase === null) {
+    state.phase = phase;
+  }
+}
+
+function terminalOutcomeForPhase(
+  phase: CodexModelRequestEvent["phase"],
+): RequestTerminalOutcome | null {
+  if (phase === "completed" || phase === "failed" || phase === "timed_out") {
+    return phase;
+  }
+  return null;
+}
+
+function requestEventFor(
   audit: RequestAudit,
   event: Omit<
     CodexModelRequestEvent,
     "requestId" | "transportAttempt" | "model" | "durationMs" | "timeoutPolicy"
   >,
-): Promise<void> {
-  await audit.ctx.onModelRequestEvent?.({
+): CodexModelRequestEvent {
+  return {
     requestId: audit.requestId,
     transportAttempt: audit.transportAttempt,
     ...(audit.model ? { model: audit.model } : {}),
-    durationMs: Math.max(0, Date.now() - audit.attemptStartedAt),
+    durationMs: Math.max(0, performance.now() - audit.attemptStartedAtMonotonic),
     timeoutPolicy: audit.policy,
     ...event,
-  });
+  };
+}
+
+async function emitRequestEvent(
+  audit: RequestAudit,
+  event: Omit<
+    CodexModelRequestEvent,
+    "requestId" | "transportAttempt" | "model" | "durationMs" | "timeoutPolicy"
+  >,
+): Promise<boolean> {
+  const terminalOutcome = terminalOutcomeForPhase(event.phase);
+  if (terminalOutcome !== null) {
+    if (audit.terminalOutcome !== null) {
+      return false;
+    }
+    // Fence before invoking either observer. The durable observer may reject,
+    // but a later transport callback must never turn that one terminal into a
+    // contradictory second terminal.
+    audit.terminalOutcome = terminalOutcome;
+  }
+  const observed = requestEventFor(audit, event);
+  try {
+    audit.ctx.onModelRequestDiagnostic?.(observed);
+  } catch {
+    // Diagnostic observers are strictly non-blocking and cannot affect transport.
+  }
+  await audit.ctx.onModelRequestEvent?.(observed);
+  return true;
 }
 
 function providerRequestId(headers: Headers): string | undefined {
@@ -261,11 +407,13 @@ async function observedResponse(
   res: Response,
   audit: RequestAudit,
   externalSignal: AbortSignal | null | undefined,
+  semanticTerminal?: SemanticTerminalState,
 ): Promise<Response> {
   const requestId = providerRequestId(res.headers);
   if (!res.body) {
+    if (semanticTerminal) markSemanticTerminal(semanticTerminal, "failed");
     await emitRequestEvent(audit, {
-      phase: res.ok ? "completed" : "failed",
+      phase: semanticTerminal?.phase ?? (res.ok ? "completed" : "failed"),
       responseObserved: true,
       status: res.status,
       ...(requestId ? { providerRequestId: requestId } : {}),
@@ -293,17 +441,19 @@ async function observedResponse(
         if (terminal) return;
         terminal = true;
         clearTimers();
+        const semanticPhase = semanticTerminal?.phase;
+        const phase = semanticPhase ?? "timed_out";
         const error = new CodexResponseTimeoutError(klass, audit.requestId, true);
         void reader.cancel(error).catch(() => undefined);
         void emitRequestEvent(audit, {
-          phase: "timed_out",
+          phase,
           responseObserved: true,
-          timeoutClass: klass,
+          ...(phase === "timed_out" ? { timeoutClass: klass } : {}),
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
         }).then(
-          () => controller.error(error),
-          () => controller.error(error),
+          () => (phase === "completed" ? controller.close() : controller.error(error)),
+          () => (phase === "completed" ? controller.close() : controller.error(error)),
         );
       };
       armIdle = () => {
@@ -323,13 +473,15 @@ async function observedResponse(
         const reason = externalSignal?.reason ?? new DOMException("Aborted", "AbortError");
         void reader.cancel(reason).catch(() => undefined);
         void emitRequestEvent(audit, {
-          phase: "failed",
+          phase: semanticTerminal?.phase ?? "failed",
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
         }).then(
-          () => controller.error(reason),
-          () => controller.error(reason),
+          () =>
+            semanticTerminal?.phase === "completed" ? controller.close() : controller.error(reason),
+          () =>
+            semanticTerminal?.phase === "completed" ? controller.close() : controller.error(reason),
         );
       };
       if (externalSignal?.aborted) {
@@ -348,45 +500,69 @@ async function observedResponse(
         if (chunk.done) {
           terminal = true;
           clearTimers();
-          await emitRequestEvent(audit, {
-            phase: res.ok ? "completed" : "failed",
-            responseObserved: true,
-            status: res.status,
-            ...(requestId ? { providerRequestId: requestId } : {}),
-          });
+          if (semanticTerminal && semanticTerminal.phase === null) {
+            if (!semanticTerminal.deferTransportTerminal) {
+              markSemanticTerminal(semanticTerminal, "failed");
+            }
+          }
+          if (!semanticTerminal?.deferTransportTerminal || semanticTerminal.phase !== null) {
+            await emitRequestEvent(audit, {
+              phase: semanticTerminal?.phase ?? (res.ok ? "completed" : "failed"),
+              responseObserved: true,
+              status: res.status,
+              ...(requestId ? { providerRequestId: requestId } : {}),
+            });
+          }
           controller.close();
           return;
         }
-        armIdle();
         if (!firstByte) {
           firstByte = true;
+          // Deliver the provider byte before durable audit I/O. Audit latency
+          // is not provider silence and must not manufacture an idle timeout.
+          if (idleTimer) clearTimeout(idleTimer);
+          controller.enqueue(chunk.value);
           await emitRequestEvent(audit, {
             phase: "first_byte",
             responseObserved: true,
             status: res.status,
             ...(requestId ? { providerRequestId: requestId } : {}),
           });
+          if (!terminal) armIdle();
+          return;
         }
+        armIdle();
         controller.enqueue(chunk.value);
       } catch (error) {
         if (terminal) return;
         terminal = true;
         clearTimers();
+        const semanticPhase = semanticTerminal?.phase;
+        if (semanticTerminal && semanticPhase === null) {
+          markSemanticTerminal(semanticTerminal, "failed");
+        }
         await emitRequestEvent(audit, {
-          phase: "failed",
+          phase: semanticPhase ?? "failed",
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
         });
-        controller.error(error);
+        if (semanticPhase === "completed") {
+          controller.close();
+        } else {
+          controller.error(error);
+        }
       }
     },
     async cancel(reason) {
       if (!terminal) {
         terminal = true;
         clearTimers();
+        if (semanticTerminal && semanticTerminal.phase === null) {
+          markSemanticTerminal(semanticTerminal, "failed");
+        }
         await emitRequestEvent(audit, {
-          phase: "failed",
+          phase: semanticTerminal?.phase ?? "failed",
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
@@ -446,7 +622,8 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
     const rewritten = rawUrl.replace(/(?<!\/codex)\/responses(\b|$)/, "/codex/responses$1");
 
     const policy = resolveCodexResponseTimeoutPolicy(ctx.responseTimeoutPolicy);
-    const requestId = ctx.nextRequestId?.() ?? randomUUID();
+    const handedRequestId = new Headers(init?.headers).get(CODEX_REQUEST_ID_HEADER);
+    const requestId = handedRequestId ?? ctx.nextRequestId?.() ?? randomUUID();
     const logicalStartedAt = Date.now();
     let transportAttempt = 0;
 
@@ -455,6 +632,13 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
       authenticationAttempt: number,
     ): Promise<Response> => {
       const headers = new Headers(init?.headers);
+      const bodyAlreadyNormalized = headers.get(CODEX_REQUEST_BODY_NORMALIZED_HEADER) === "1";
+      const normalizedModel = headers.get(CODEX_REQUEST_MODEL_HEADER) ?? undefined;
+      const normalizedCallerStream = headers.get(CODEX_REQUEST_CALLER_STREAM_HEADER);
+      headers.delete(CODEX_REQUEST_BODY_NORMALIZED_HEADER);
+      headers.delete(CODEX_REQUEST_MODEL_HEADER);
+      headers.delete(CODEX_REQUEST_ID_HEADER);
+      headers.delete(CODEX_REQUEST_CALLER_STREAM_HEADER);
       headers.set("Authorization", `Bearer ${auth.accessToken}`);
       if (auth.chatgptAccountId) {
         headers.set("ChatGPT-Account-ID", auth.chatgptAccountId);
@@ -486,13 +670,20 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
       }
 
       // The backend is streaming-only; force stream=true on the wire but remember
-      // 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;
+      // the caller's intent for legacy/unowned non-streaming consumers. The owned
+      // compaction path consumes the same streaming model boundary as normal turns.
+      let callerWantsStream = bodyAlreadyNormalized ? normalizedCallerStream !== "0" : true;
+      let model: string | undefined = normalizedModel;
       let requestOpaqueArtifacts: string[] = [];
-      const nextInit: RequestInit = { ...init, headers };
-      if (typeof init?.body === "string") {
+      const replayableBodyFactory = (init as ReplayableRequestInit | undefined)?.[
+        REPLAYABLE_REQUEST_BODY_FACTORY
+      ];
+      const nextInit: RequestInit = {
+        ...init,
+        headers,
+        ...(replayableBodyFactory ? { body: replayableBodyFactory() } : {}),
+      };
+      if (!bodyAlreadyNormalized && typeof init?.body === "string") {
         try {
           const parsed = JSON.parse(init.body) as Record<string, unknown>;
           callerWantsStream = parsed.stream === true;
@@ -501,10 +692,16 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
           nextInit.body = JSON.stringify(normalized);
           requestOpaqueArtifacts = opaqueProviderArtifactFingerprints(normalized.input);
         } catch {
-          /* leave unparseable bodies untouched (already copied from init) */
+          // This is the final request-policy boundary for the strict Responses
+          // endpoint. Never let malformed bytes bypass the reviewed policy.
+          throw new Error("Model request could not be prepared");
         }
+      } else if (!bodyAlreadyNormalized) {
+        throw new Error("Model request could not be prepared");
+      }
+      if (!bodyAlreadyNormalized) {
+        ctx.onRequestOpaqueArtifacts?.({ requestId, fingerprints: requestOpaqueArtifacts });
       }
-      ctx.onRequestOpaqueArtifacts?.({ requestId, fingerprints: requestOpaqueArtifacts });
       headers.set(
         "Idempotency-Key",
         authenticationAttempt === 0 ? requestId : `${requestId}:auth-${authenticationAttempt}`,
@@ -525,13 +722,18 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
         transportAttempt,
         ...(model ? { model } : {}),
         logicalStartedAt,
-        attemptStartedAt: Date.now(),
+        attemptStartedAtMonotonic: performance.now(),
         policy,
+        terminalOutcome: null,
       };
       await emitRequestEvent(audit, {
         phase: "started",
         responseObserved: false,
       });
+      const semanticTerminal: SemanticTerminalState = {
+        phase: null,
+        deferTransportTerminal: !callerWantsStream,
+      };
       try {
         res = await fetchBeforeHeaders(base, rewritten, nextInit, audit);
         const upstreamRequestId = providerRequestId(res.headers);
@@ -541,8 +743,7 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
           status: res.status,
           ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
         });
-        const observed = await observedResponse(res, audit, nextInit.signal);
-        res = observed;
+        res = await observedResponse(res, audit, nextInit.signal, semanticTerminal);
       } catch (error) {
         if (nextInit.signal?.aborted) {
           await emitRequestEvent(audit, {
@@ -590,11 +791,10 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
           status: res.status,
         });
       }
-      // The codex backend leaves the terminal event's response.output empty and
-      // delivers the assistant items via output_item.done events instead. The
-      // @openai/agents parser (streaming AND non-streaming) reads response.output,
-      // so we must reconstruct it: collapse to one JSON Response for a non-streaming
-      // caller, or repair the live stream's terminal event for a streaming caller.
+      // The backend leaves terminal response.output empty and delivers assistant
+      // items through output_item.done. The typed model reducer reconstructs normal
+      // streaming calls; only the legacy non-streaming transport fallback collapses
+      // SSE into one JSON response here.
       if (!res.ok) {
         // Buffer the error body once and re-emit it as a concrete JSON Response.
         // A streaming responses request whose error body is left as the raw
@@ -605,9 +805,25 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
         // Response lets the SDK reconstruct error.error for EVERY codex error
         // (401/400/5xx too). For a hard usage cap we also pin x-should-retry:false
         // so the SDK does not burn its retry budget on a limit that won't lift.
-        return await bufferCodexErrorResponse(res);
+        const buffered = await bufferCodexErrorResponse(res);
+        const upstreamRequestId = providerRequestId(res.headers);
+        markSemanticTerminal(semanticTerminal, "failed");
+        await emitRequestEvent(audit, {
+          phase: "failed",
+          responseObserved: true,
+          status: res.status,
+          ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+        }).catch(() => undefined);
+        return buffered;
       }
-      return callerWantsStream ? repairCodexStream(res) : await sseToJsonResponse(res);
+      if (callerWantsStream) {
+        res = validateCodexStream(res, (phase) => {
+          markSemanticTerminal(semanticTerminal, phase);
+        });
+      } else {
+        res = await sseToJsonResponse(res, audit, semanticTerminal);
+      }
+      return res;
     };
 
     try {
@@ -681,35 +897,99 @@ export function classifyCodexUsageLimitError(error: unknown): CodexUsageLimitInf
  * Reading the body here also drains the socket of a discarded 401 (no leak).
  */
 async function bufferCodexErrorResponse(res: Response): Promise<Response> {
-  const bodyText = await res.text().catch(() => "");
+  const { text: bodyText, truncated } = await readBoundedResponseText(
+    res,
+    MAX_CODEX_ERROR_BODY_BYTES,
+  );
   const headers = new Headers(res.headers);
   headers.set("content-type", "application/json");
   headers.set(CODEX_TRANSPORT_ERROR_HEADER, "1");
   headers.delete("content-length"); // body re-serialized
   headers.delete("content-encoding"); // text() already decoded any gzip
   let errorType: string | undefined;
+  let responseBody = bodyText;
   try {
     const parsed = JSON.parse(bodyText) as { error?: { type?: unknown } };
     errorType = typeof parsed.error?.type === "string" ? parsed.error.type : undefined;
   } catch {
     /* non-JSON error body — leave as-is, no retry-header override */
   }
+  if (truncated) {
+    responseBody = JSON.stringify({
+      error: {
+        type: "provider_error_body_too_large",
+        code: "provider_error_body_too_large",
+        message: `The provider returned an error body larger than ${MAX_CODEX_ERROR_BODY_BYTES} bytes`,
+      },
+    });
+    headers.set("x-opengeni-provider-error-truncated", "1");
+  }
   if (errorType === CODEX_USAGE_LIMIT_ERROR_TYPE) {
     headers.set("x-should-retry", "false");
   }
-  return new Response(bodyText, {
+  return new Response(responseBody, {
     status: res.status,
     statusText: res.statusText,
     headers,
   });
 }
 
+async function readBoundedResponseText(
+  response: Response,
+  maxBytes: number,
+): Promise<{ text: string; truncated: boolean }> {
+  if (!response.body) return { text: "", truncated: false };
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parts: string[] = [];
+  let bytes = 0;
+  let truncated = false;
+  try {
+    while (bytes < maxBytes) {
+      const next = await reader.read();
+      if (next.done) {
+        parts.push(decoder.decode());
+        return { text: parts.join(""), truncated };
+      }
+      const remaining = maxBytes - bytes;
+      const accepted =
+        next.value.byteLength > remaining ? next.value.subarray(0, remaining) : next.value;
+      bytes += accepted.byteLength;
+      parts.push(decoder.decode(accepted, { stream: true }));
+      if (accepted.byteLength !== next.value.byteLength) {
+        truncated = true;
+        break;
+      }
+      if (bytes >= maxBytes) {
+        // Reaching the hard cap is sufficient to classify the body as
+        // oversized. Probing for one more chunk can wait forever when an
+        // upstream producer stops emitting without closing its stream.
+        truncated = true;
+        break;
+      }
+    }
+  } catch {
+    truncated = true;
+  } finally {
+    // Cancellation is advisory cleanup. Some Fetch/Streams implementations do
+    // not settle cancel() until the producer exits; never let an oversized
+    // provider error hold the request open behind that implementation detail.
+    if (truncated) void reader.cancel().catch(() => undefined);
+  }
+  return { text: parts.join(""), truncated };
+}
+
 /**
  * Collapse a Responses SSE stream into the single JSON Response object a
  * non-streaming `responses.create` caller expects: the terminal response.*
  * event carries the full `response` payload.
  */
-async function sseToJsonResponse(res: Response): Promise<Response> {
+async function sseToJsonResponse(
+  res: Response,
+  audit: RequestAudit,
+  semanticTerminal: SemanticTerminalState,
+): Promise<Response> {
+  const upstreamRequestId = providerRequestId(res.headers);
   const text = await res.text();
   let final: Record<string, unknown> | null = null;
   let terminalError: Response | null = null;
@@ -720,75 +1000,49 @@ async function sseToJsonResponse(res: Response): Promise<Response> {
       continue;
     }
     try {
-      const ev = JSON.parse(data) as {
-        type?: string;
-        response?: Record<string, unknown>;
-        error?: unknown;
-        code?: unknown;
-        message?: unknown;
-        param?: unknown;
-        item?: unknown;
-      };
+      const ev = JSON.parse(data) as CodexSseEvent;
       if (ev.type === "response.output_item.done" && ev.item !== undefined) {
         items.push(ev.item);
-      } 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;
+      } else {
+        const terminal = classifyCodexSseTerminal(ev);
+        if (terminal?.phase === "failed") {
+          terminalError = codexSseFailureResponse(
+            res,
+            terminal.rawError,
+            terminal.fallbackCode,
+            terminal.fallbackMessage,
+            {
+              eventType: ev.type,
+              responseId: ev.response?.id,
+              responseStatus: ev.response?.status,
+            },
+          );
+        } else if (terminal?.phase === "completed") {
+          final = ev.response ?? null;
+        }
       }
     } catch {
       /* ignore non-JSON keepalive lines */
     }
   }
   if (terminalError) {
+    markSemanticTerminal(semanticTerminal, "failed");
+    await emitRequestEvent(audit, {
+      phase: "failed",
+      responseObserved: true,
+      status: res.status,
+      ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+    });
     return terminalError;
   }
   if (!final) {
+    markSemanticTerminal(semanticTerminal, "failed");
+    await emitRequestEvent(audit, {
+      phase: "failed",
+      responseObserved: true,
+      status: res.status,
+      ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+    });
     return codexSseFailureResponse(
       res,
       null,
@@ -804,6 +1058,13 @@ async function sseToJsonResponse(res: Response): Promise<Response> {
       `[codex-debug] sse->json items=${items.length} outputLen=${Array.isArray(final?.output) ? (final.output as unknown[]).length : "?"}`,
     );
   }
+  markSemanticTerminal(semanticTerminal, "completed");
+  await emitRequestEvent(audit, {
+    phase: "completed",
+    responseObserved: true,
+    status: res.status,
+    ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+  });
   const headers = new Headers(res.headers);
   headers.set("content-type", "application/json");
   headers.delete("content-length");
@@ -1074,12 +1335,17 @@ function codexSseFailureError(
 }
 
 /**
- * Repair a live Responses SSE stream for the @openai/agents streaming parser: pass
- * every event through unchanged, collect the output_item.done items, and inject
- * them into the terminal event's empty `output` so the parser sees the message.
+ * Preserve a live Responses SSE stream byte-for-byte while translating only
+ * provider-specific terminal failures into typed transport errors. Successful
+ * output reconstruction belongs to the model reducer, so this layer retains no
+ * duplicate output-item graph.
  */
-function repairCodexStream(res: Response): Response {
+function validateCodexStream(
+  res: Response,
+  onSemanticTerminal?: (phase: "completed" | "failed") => void,
+): Response {
   if (!res.body) {
+    onSemanticTerminal?.("failed");
     const error = codexSseFailureError(
       res,
       null,
@@ -1099,7 +1365,6 @@ function repairCodexStream(res: Response): Response {
       headers,
     });
   }
-  const items: unknown[] = [];
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
   let buffer = "";
@@ -1113,9 +1378,8 @@ function repairCodexStream(res: Response): Response {
       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}`));
+      successfulTerminalSeen ||= inspectCodexSseBlock(block, res, onSemanticTerminal);
+      controller.enqueue(encoder.encode(`${block}${separator}`));
       boundary = findSseBlockBoundary(buffer, final);
     }
   };
@@ -1128,9 +1392,8 @@ function repairCodexStream(res: Response): Response {
       buffer += decoder.decode();
       emitCompleteBlocks(controller, true);
       if (buffer.length > 0) {
-        const patched = patchSseBlock(buffer, items, res);
-        successfulTerminalSeen ||= patched.successfulTerminal;
-        controller.enqueue(encoder.encode(patched.block));
+        successfulTerminalSeen ||= inspectCodexSseBlock(buffer, res, onSemanticTerminal);
+        controller.enqueue(encoder.encode(buffer));
         buffer = "";
       }
       if (!successfulTerminalSeen) {
@@ -1182,83 +1445,50 @@ function sseLineEndingEnd(value: string, index: number, final: boolean): number
   return final ? index + 1 : null;
 }
 
-type PatchedSseBlock = { block: string; successfulTerminal: boolean };
+const CODEX_TERMINAL_TYPE_HINTS = [
+  '"response.completed"',
+  '"response.done"',
+  '"response.failed"',
+  '"response.incomplete"',
+  '"response.error"',
+  '"error"',
+] as const;
 
 /**
- * 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.
+ * Parse only blocks that can be terminal. Ordinary deltas and output items pass
+ * without object allocation; failed/error/incomplete terminals throw before the
+ * model can mistake them for an ordinary response_done event.
  */
-function patchSseBlock(block: string, items: unknown[], source: Response): PatchedSseBlock {
+function inspectCodexSseBlock(
+  block: string,
+  source: Response,
+  onSemanticTerminal?: (phase: "completed" | "failed") => void,
+): boolean {
   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, successfulTerminal: false };
+    return false;
   }
-  let ev: {
-    type?: string;
-    item?: unknown;
-    response?: Record<string, unknown>;
-    error?: unknown;
-    code?: unknown;
-    message?: unknown;
-    param?: unknown;
-  };
+  if (!CODEX_TERMINAL_TYPE_HINTS.some((terminalType) => dataStr.includes(terminalType))) {
+    return false;
+  }
+  let ev: CodexSseEvent;
   try {
     ev = JSON.parse(dataStr);
   } catch {
-    return { block, successfulTerminal: false };
-  }
-  if (ev.type === "response.output_item.done" && ev.item !== undefined) {
-    items.push(ev.item);
-    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,
-      },
-    );
+    return false;
   }
-  if (ev.type === "response.incomplete") {
-    const details = ev.response?.incomplete_details;
-    const reason =
-      details && typeof details === "object"
-        ? (details as Record<string, unknown>).reason
-        : undefined;
+  const terminal = classifyCodexSseTerminal(ev);
+  if (terminal?.phase === "failed") {
+    onSemanticTerminal?.("failed");
     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",
+      terminal.rawError,
+      terminal.fallbackCode,
+      terminal.fallbackMessage,
       {
         eventType: ev.type,
         responseId: ev.response?.id,
@@ -1266,37 +1496,9 @@ function patchSseBlock(block: string, items: unknown[], source: Response): Patch
       },
     );
   }
-  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:"));
-      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 };
+  if (terminal?.phase === "completed") {
+    onSemanticTerminal?.("completed");
+    return true;
   }
-  return { block, successfulTerminal: false };
+  return false;
 }