@opengeni/codex 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codex",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "ChatGPT/Codex subscription auth + transport: device-code login, token refresh, and the Responses-backend fetch. Pure HTTP + transforms; no database dependency.",
   "license": "Apache-2.0",
   "repository": {

package/src/api-client.ts

@@ -3,6 +3,13 @@
 
 import { CODEX_ORIGINATOR, CODEX_RESPONSES_BASE, CODEX_WHAM_BASE } from "./constants";
 import type { CodexFetch } from "./device-code";
+import {
+  parseCodexRateLimitResetConsumeResponse,
+  parseCodexRateLimitResetCreditsDetails,
+  type CodexRateLimitResetConsumeResponse,
+  type CodexRateLimitResetCreditsDetails,
+} from "./reset-credits";
+import { runBoundedCodexOperation } from "./bounded-operation";
 
 export type CodexAuthHeaders = {
   accessToken: string;
@@ -11,6 +18,16 @@ export type CodexAuthHeaders = {
   clientVersion: string;
 };
 
+const CODEX_READ_TIMEOUT_MS = 5_000;
+const RESET_CREDIT_DETAILS_TIMEOUT_MS = 5_000;
+const RESET_CREDIT_CONSUME_TIMEOUT_MS = 10_000;
+
+export type ResetCreditFetchFailureReason =
+  | "http_error"
+  | "invalid_response"
+  | "network_error"
+  | "timeout";
+
 function subscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
   return {
     Authorization: `Bearer ${a.accessToken}`,
@@ -26,34 +43,126 @@ function subscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
 export async function fetchCodexModels(
   a: CodexAuthHeaders,
   fetchImpl: CodexFetch = fetch,
+  timeoutMs = CODEX_READ_TIMEOUT_MS,
 ): Promise<{ ok: boolean; status: number; slugs: string[] }> {
-  const res = await fetchImpl(
-    `${CODEX_RESPONSES_BASE}/models?client_version=${encodeURIComponent(a.clientVersion)}`,
-    {
-      method: "GET",
-      headers: subscriptionHeaders(a),
-    },
-  );
-  if (!res.ok) {
-    return { ok: false, status: res.status, slugs: [] };
-  }
-  const body = (await res.json()) as { models?: Array<{ slug?: string }> };
-  const slugs = (body.models ?? [])
-    .map((m) => m.slug)
-    .filter((s): s is string => typeof s === "string");
-  return { ok: true, status: res.status, slugs };
+  const fetched = await runBoundedCodexOperation(async (signal) => {
+    const res = await fetchImpl(
+      `${CODEX_RESPONSES_BASE}/models?client_version=${encodeURIComponent(a.clientVersion)}`,
+      { method: "GET", headers: subscriptionHeaders(a), signal },
+    );
+    if (!res.ok) {
+      await res.arrayBuffer().catch(() => undefined);
+      return { ok: false, status: res.status, slugs: [] as string[] };
+    }
+    const body = (await res.json()) as { models?: Array<{ slug?: string }> };
+    const slugs = (body.models ?? [])
+      .map((model) => model.slug)
+      .filter((slug): slug is string => typeof slug === "string");
+    return { ok: true, status: res.status, slugs };
+  }, timeoutMs);
+  return fetched.ok ? fetched.value : { ok: false, status: 0, slugs: [] };
 }
 
 /** GET /wham/usage — authoritative limits. NB the WHAM base is /backend-api, NOT /codex (spec §1.8a). */
 export async function fetchCodexUsage(
   a: CodexAuthHeaders,
   fetchImpl: CodexFetch = fetch,
+  timeoutMs = CODEX_READ_TIMEOUT_MS,
 ): Promise<{ status: number; payload: unknown }> {
-  const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/usage`, {
-    method: "GET",
-    headers: subscriptionHeaders(a),
-  });
-  // A 404 may carry a usage-limit body; the route layer normalizes it to a limits state (spec §1.8c).
-  const payload = res.ok || res.status === 404 ? await res.json().catch(() => null) : null;
-  return { status: res.status, payload };
+  const fetched = await runBoundedCodexOperation(async (signal) => {
+    const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/usage`, {
+      method: "GET",
+      headers: subscriptionHeaders(a),
+      signal,
+    });
+    // A 404 may carry a usage-limit body; the route layer normalizes it to a limits state (spec §1.8c).
+    const payload = res.ok || res.status === 404 ? await res.json().catch(() => null) : null;
+    if (!res.ok && res.status !== 404) await res.arrayBuffer().catch(() => undefined);
+    return { status: res.status, payload };
+  }, timeoutMs);
+  if (!fetched.ok) throw new Error(`Codex usage request ${fetched.reason}`);
+  return fetched.value;
+}
+
+/**
+ * GET /wham/rate-limit-reset-credits — detailed earned reset credits.
+ *
+ * A non-2xx or malformed body returns an explicit non-ok result. The caller may
+ * fall back to the count-only summary embedded in /wham/usage, but must never
+ * invent actionable rows from that count.
+ */
+export async function fetchCodexRateLimitResetCredits(
+  a: CodexAuthHeaders,
+  fetchImpl: CodexFetch = fetch,
+  timeoutMs = RESET_CREDIT_DETAILS_TIMEOUT_MS,
+): Promise<
+  | { ok: true; status: number; details: CodexRateLimitResetCreditsDetails }
+  | { ok: false; status: number; reason: ResetCreditFetchFailureReason }
+> {
+  const fetched = await runBoundedCodexOperation(async (signal) => {
+    const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits`, {
+      method: "GET",
+      headers: subscriptionHeaders(a),
+      signal,
+    });
+    if (!res.ok) {
+      // Drain the body without retaining/logging it. Provider error bodies may
+      // contain account-specific details and are not part of this contract.
+      await res.arrayBuffer().catch(() => undefined);
+      return { ok: false as const, status: res.status, reason: "http_error" as const };
+    }
+    const details = parseCodexRateLimitResetCreditsDetails(await res.json().catch(() => null));
+    return details
+      ? { ok: true as const, status: res.status, details }
+      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+  }, timeoutMs);
+  return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
+}
+
+/**
+ * POST /wham/rate-limit-reset-credits/consume with the exact v0.144.6 body.
+ * `idempotencyKey` identifies one logical human redemption and MUST be reused
+ * by the server on retries. Supplying `creditId` is preferred; omission leaves
+ * provider selection in control and is therefore not used by OpenGeni's
+ * human-only flow.
+ */
+export async function consumeCodexRateLimitResetCredit(
+  a: CodexAuthHeaders,
+  input: { idempotencyKey: string; creditId?: string | undefined },
+  fetchImpl: CodexFetch = fetch,
+  timeoutMs = RESET_CREDIT_CONSUME_TIMEOUT_MS,
+): Promise<
+  | { ok: true; status: number; result: CodexRateLimitResetConsumeResponse }
+  | {
+      ok: false;
+      status: number;
+      reason: ResetCreditFetchFailureReason | "invalid_request";
+    }
+> {
+  if (input.idempotencyKey.length === 0 || input.creditId === "") {
+    return { ok: false, status: 0, reason: "invalid_request" };
+  }
+  const fetched = await runBoundedCodexOperation(async (signal) => {
+    const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits/consume`, {
+      method: "POST",
+      headers: {
+        ...subscriptionHeaders(a),
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        redeem_request_id: input.idempotencyKey,
+        ...(input.creditId ? { credit_id: input.creditId } : {}),
+      }),
+      signal,
+    });
+    if (!res.ok) {
+      await res.arrayBuffer().catch(() => undefined);
+      return { ok: false as const, status: res.status, reason: "http_error" as const };
+    }
+    const result = parseCodexRateLimitResetConsumeResponse(await res.json().catch(() => null));
+    return result
+      ? { ok: true as const, status: res.status, result }
+      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+  }, timeoutMs);
+  return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
 }

package/src/bounded-operation.ts

@@ -0,0 +1,43 @@
+export type CodexOperationFailureReason = "network_error" | "timeout";
+
+/**
+ * Bound the complete provider operation, including response-body consumption.
+ *
+ * AbortController makes native fetch release its socket, while Promise.race is
+ * the backstop for injected/custom fetch implementations that ignore `signal`.
+ * The losing operation is rejection-handled and can never become an unhandled
+ * promise after the caller has received the timeout result.
+ */
+export async function runBoundedCodexOperation<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+): Promise<{ ok: true; value: T } | { ok: false; reason: CodexOperationFailureReason }> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("Codex operation timeout must be positive");
+  }
+
+  const controller = new AbortController();
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const work = operation(controller.signal).then(
+    (value) => ({ ok: true as const, value }),
+    () => ({
+      ok: false as const,
+      reason:
+        timedOut || controller.signal.aborted ? ("timeout" as const) : ("network_error" as const),
+    }),
+  );
+  const deadline = new Promise<{ ok: false; reason: "timeout" }>((resolve) => {
+    timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+      resolve({ ok: false, reason: "timeout" });
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([work, deadline]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}

package/src/constants.ts

@@ -57,6 +57,24 @@ 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
 
+// Codex Responses transport deadlines. The OpenAI SDK's own timeout only covers
+// the wait for response headers and erases the underlying timeout class into the
+// bare `Request timed out.` error. Keep the provider-specific budgets here so
+// the transport can enforce and durably report them without enabling the SDK's
+// blind request replay.
+export const CODEX_RESPONSE_HEADERS_TIMEOUT_MS = 4 * 60_000;
+export const CODEX_RESPONSE_STREAM_IDLE_TIMEOUT_MS = 5 * 60_000;
+export const CODEX_RESPONSE_WHOLE_TIMEOUT_MS = 30 * 60_000;
+// Kept as a compatibility-shaped policy field, but automatic replay is disabled
+// until a provider-specific operation receipt can prove non-acceptance or resume
+// the same operation identity. An absent response does not prove that the
+// provider never accepted the request.
+export const CODEX_RESPONSE_NO_BYTE_RETRIES = 0;
+export const CODEX_RESPONSE_RETRY_BACKOFF_MS = 1_000;
+// Must exceed the transport-owned whole-response deadline. This SDK guard is a
+// last-resort envelope; the inner transport emits the typed/durable failure.
+export const CODEX_RESPONSE_SDK_OUTER_TIMEOUT_MS = 35 * 60_000;
+
 // ── Apps / connectors MCP (spec §1.10, §E) ───────────────────────────────────
 // One server-side MCP exposes ALL the user's ChatGPT/Codex connectors
 // (gmail/github/linear/slack/sentry/drive/calendar/…). Streamable HTTP, always.

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;
   };
 }
 

package/src/index.ts

@@ -4,8 +4,10 @@ export * from "./device-code";
 export * from "./refresh";
 export * from "./normalize";
 export * from "./usage-normalize";
+export * from "./reset-credits";
 export * from "./api-client";
 export * from "./request-context";
+export * from "./response-timeout";
 export * from "./fetch";
 export * from "./mcp-sanitize";
 export * from "./model-output-truncation";