@opengeni/codex 0.2.13 → 0.2.15

package/dist/mcp-sanitize.d.ts

@@ -1,4 +1,4 @@
-import type { FetchLike } from "./fetch";
+import type { FetchLike } from "./fetch.js";
 /**
  * Maps connector tool names to a Responses-API-legal charset and back. One
  * instance per codex_apps transport (i.e. per turn): tools/list populates it,

package/dist/model-output-truncation.d.ts

@@ -18,7 +18,7 @@
  * runtime request seam and the database history boundary call the same pure
  * function, so replayed conversation truth is identical to live model input.
  */
-export { MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL } from "./oversized-image-card";
+export { MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL } from "./oversized-image-card.js";
 export type ModelHistoryItem = Record<string, unknown>;
 export declare const CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS = 10000;
 export declare const CODEX_TOOL_OUTPUT_SERIALIZATION_ALLOWANCE = 1.2;

package/dist/normalize.d.ts

@@ -1,5 +1,11 @@
 /** Mutates a parsed Responses request body in place and returns it. Pure + synchronous + unit-testable. */
 export declare function normalizeCodexRequestBody(body: Record<string, unknown>, resolveModel: (slug: string) => string): Record<string, unknown>;
+/**
+ * Copy-on-write form for model clients that may retain converted input items.
+ * Only records the mutable normalizer can touch are copied; large content,
+ * tools, and unchanged protocol items remain shared immutable values.
+ */
+export declare function normalizedCodexRequestBody(body: Readonly<Record<string, unknown>>, resolveModel: (slug: string) => string): Record<string, unknown>;
 /**
  * Build a longest-prefix model resolver. Catalog slugs come from GET /models
  * (api-client.ts). One leading `namespace/` segment is stripped first; an

package/dist/realtime.d.ts

@@ -1,7 +1,7 @@
-import { type CodexAuthHeaders } from "./api-client";
-import { CODEX_REALTIME_MODEL, CODEX_REALTIME_VERSION } from "./constants";
-import type { CodexFetch } from "./device-code";
-import { type CodexRealtimeInitialItem } from "./realtime-v3";
+import { type CodexAuthHeaders } from "./api-client.js";
+import { CODEX_REALTIME_MODEL, CODEX_REALTIME_VERSION } from "./constants.js";
+import type { CodexFetch } from "./device-code.js";
+import { type CodexRealtimeInitialItem } from "./realtime-v3.js";
 export declare const CODEX_REALTIME_VOICES: readonly ["juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol", "cove"];
 export type CodexRealtimeVoice = (typeof CODEX_REALTIME_VOICES)[number];
 export type CodexRealtimeCallInput = {

package/dist/refresh.d.ts

@@ -1,4 +1,4 @@
-import type { CodexFetch } from "./device-code";
+import type { CodexFetch } from "./device-code.js";
 /** Permanent — the workspace must reconnect (status => needs_relogin). */
 export declare class CodexReloginRequired extends Error {
     constructor(message: string);

package/dist/response-timeout.d.ts

@@ -1,4 +1,4 @@
-import type { CodexResponseTimeoutClass, CodexResponseTimeoutPolicy } from "./request-context";
+import type { CodexResponseTimeoutClass, CodexResponseTimeoutPolicy } from "./request-context.js";
 export declare const CODEX_RESPONSE_TIMEOUT_ERROR_TYPE = "opengeni_codex_response_timeout";
 export declare const DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY: CodexResponseTimeoutPolicy;
 export declare function resolveCodexResponseTimeoutPolicy(override: Partial<CodexResponseTimeoutPolicy> | undefined): CodexResponseTimeoutPolicy;

package/dist/usage-normalize.d.ts

@@ -1,4 +1,4 @@
-import { type CodexRateLimitResetCreditsSummary } from "./reset-credits";
+import { type CodexRateLimitResetCreditsSummary } from "./reset-credits.js";
 /** The 5-hour (primary) window's `limit_window_seconds`. */
 export declare const CODEX_FIVE_HOUR_WINDOW_SECONDS = 18000;
 /** The weekly (secondary) window's `limit_window_seconds`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codex",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "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": {
@@ -41,6 +41,7 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
+    "@opengeni/network": "^0.2.2",
     "zod": "^4.2.1"
   },
   "engines": {

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;
@@ -357,16 +371,22 @@ async function observedResponse(
           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;
@@ -446,7 +466,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 +476,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 +514,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 +536,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}`,
@@ -590,11 +631,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
@@ -607,7 +647,7 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
         // so the SDK does not burn its retry budget on a limit that won't lift.
         return await bufferCodexErrorResponse(res);
       }
-      return callerWantsStream ? repairCodexStream(res) : await sseToJsonResponse(res);
+      return callerWantsStream ? validateCodexStream(res) : await sseToJsonResponse(res);
     };
 
     try {
@@ -681,29 +721,88 @@ 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.*
@@ -1074,11 +1173,12 @@ 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): Response {
   if (!res.body) {
     const error = codexSseFailureError(
       res,
@@ -1099,7 +1199,6 @@ function repairCodexStream(res: Response): Response {
       headers,
     });
   }
-  const items: unknown[] = [];
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
   let buffer = "";
@@ -1113,9 +1212,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);
+      controller.enqueue(encoder.encode(`${block}${separator}`));
       boundary = findSseBlockBoundary(buffer, final);
     }
   };
@@ -1128,9 +1226,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);
+        controller.enqueue(encoder.encode(buffer));
         buffer = "";
       }
       if (!successfulTerminalSeen) {
@@ -1182,21 +1279,31 @@ 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): 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;
+  }
+  if (!CODEX_TERMINAL_TYPE_HINTS.some((terminalType) => dataStr.includes(terminalType))) {
+    return false;
   }
   let ev: {
     type?: string;
@@ -1210,11 +1317,7 @@ function patchSseBlock(block: string, items: unknown[], source: Response): Patch
   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 };
+    return false;
   }
   if (ev.type === "response.failed") {
     throw codexSseFailureError(
@@ -1268,8 +1371,7 @@ 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.status !== undefined && ev.response.status !== "completed") ||
       (ev.response.error !== null && ev.response.error !== undefined)
     ) {
       throw codexSseFailureError(
@@ -1286,17 +1388,7 @@ function patchSseBlock(block: string, items: unknown[], source: Response): Patch
         },
       );
     }
-    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 };
+    return true;
   }
-  return { block, successfulTerminal: false };
+  return false;
 }

package/src/images.ts

@@ -0,0 +1,209 @@
+import { CODEX_CLIENT_VERSION, CODEX_ORIGINATOR, CODEX_RESPONSES_BASE } from "./constants";
+import type { CodexRequestContext, CodexTokenSnapshot } from "./request-context";
+import type { FetchLike } from "./fetch";
+import { pinnedFetch, readJsonBase64Field, readResponseTextBounded } from "@opengeni/network";
+
+const CODEX_IMAGE_MODEL = "gpt-image-2";
+const CODEX_IMAGE_RESPONSE_MAX_BYTES = 90 * 1024 * 1024;
+const CODEX_IMAGE_ERROR_MAX_BYTES = 64 * 1024;
+const CODEX_IMAGE_MAX_BYTES = 64 * 1024 * 1024;
+const CODEX_IMAGE_REQUEST_TIMEOUT_MS = 5 * 60_000;
+const CODEX_IMAGE_MAX_REFERENCES = 5;
+
+const codexImageFetch: FetchLike = async (input, init) =>
+  await pinnedFetch(
+    input,
+    init,
+    {
+      environment: "production",
+      integrationsAllowPrivateNetworkTargets: false,
+    },
+    {
+      label: "Codex image generation",
+      requireHttpsOutsideLocalTest: true,
+    },
+  );
+
+export type CodexGeneratedImage = {
+  bytes: Uint8Array;
+  declaredMediaType: "image/png";
+};
+
+export type CodexImageReferenceInput = Readonly<{
+  mediaType: "image/png" | "image/jpeg" | "image/webp";
+  bytes: Uint8Array;
+}>;
+
+export class CodexImageApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CodexImageApiError";
+  }
+}
+
+export class CodexImageRequestTimeoutError extends Error {
+  constructor(readonly timeoutMs: number) {
+    super(`Codex image generation timed out after ${Math.ceil(timeoutMs / 1_000)} seconds`);
+    this.name = "CodexImageRequestTimeoutError";
+  }
+}
+
+/**
+ * Execute Codex's standalone, client-side image tool against the same
+ * ChatGPT/Codex account as the owning model turn. Only a definitive 401 is
+ * retried, after refreshing auth; ambiguous transport/5xx outcomes are never
+ * replayed because an image request may already have incurred work or cost.
+ */
+export async function generateCodexSubscriptionImage(input: {
+  prompt: string;
+  references?: readonly CodexImageReferenceInput[];
+  turnId: string;
+  context: Pick<CodexRequestContext, "clientVersion" | "getToken" | "refresh">;
+  abortSignal?: AbortSignal;
+  fetch?: FetchLike;
+  /** Internal test/host override; one absolute budget covers auth retry and body streaming. */
+  requestTimeoutMs?: number;
+}): Promise<CodexGeneratedImage> {
+  const fetchImpl = input.fetch ?? codexImageFetch;
+  const timeoutMs = input.requestTimeoutMs ?? CODEX_IMAGE_REQUEST_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("Codex image request timeout must be a positive safe integer");
+  }
+  const references = input.references ?? [];
+  if (references.length > CODEX_IMAGE_MAX_REFERENCES) {
+    throw new RangeError(
+      `Codex image editing accepts at most ${CODEX_IMAGE_MAX_REFERENCES} images`,
+    );
+  }
+  for (const reference of references) {
+    if (reference.bytes.byteLength === 0) throw new Error("Codex image reference is empty");
+  }
+  const deadline = new AbortController();
+  const timer = setTimeout(
+    () => deadline.abort(new CodexImageRequestTimeoutError(timeoutMs)),
+    timeoutMs,
+  );
+  const signal = input.abortSignal
+    ? AbortSignal.any([input.abortSignal, deadline.signal])
+    : deadline.signal;
+  const request = async (auth: CodexTokenSnapshot): Promise<Response> => {
+    const headers = codexImageHeaders(auth, input.context.clientVersion, input.turnId);
+    return await fetchImpl(
+      `${CODEX_RESPONSES_BASE}/${references.length > 0 ? "images/edits" : "images/generations"}`,
+      {
+        method: "POST",
+        redirect: "error",
+        headers,
+        body: JSON.stringify(
+          references.length > 0
+            ? {
+                images: references.map((reference) => ({
+                  image_url: `data:${reference.mediaType};base64,${Buffer.from(reference.bytes).toString("base64")}`,
+                })),
+                prompt: input.prompt,
+                background: "auto",
+                model: CODEX_IMAGE_MODEL,
+                quality: "auto",
+                size: "auto",
+              }
+            : {
+                prompt: input.prompt,
+                background: "auto",
+                model: CODEX_IMAGE_MODEL,
+                quality: "auto",
+                size: "auto",
+              },
+        ),
+        signal,
+      },
+    );
+  };
+
+  const operation = (async (): Promise<CodexGeneratedImage> => {
+    let response = await request(await input.context.getToken());
+    if (response.status === 401) {
+      await response.body?.cancel().catch(() => undefined);
+      response = await request(await input.context.refresh());
+    }
+    if (!response.ok) {
+      const detail = await readResponseTextBounded(
+        response,
+        CODEX_IMAGE_ERROR_MAX_BYTES,
+        "Codex image error",
+        { signal },
+      ).catch(() => "");
+      throw new CodexImageApiError(
+        response.status,
+        detail
+          ? `Codex image generation failed (${response.status}): ${boundedErrorMessage(detail)}`
+          : `Codex image generation failed (${response.status})`,
+      );
+    }
+
+    const bytes = await readJsonBase64Field(response, {
+      fieldName: "b64_json",
+      shape: "string",
+      maxResponseBytes: CODEX_IMAGE_RESPONSE_MAX_BYTES,
+      maxDecodedBytes: CODEX_IMAGE_MAX_BYTES,
+      label: "Codex image generation",
+      signal,
+    });
+    return { bytes, declaredMediaType: "image/png" };
+  })();
+  let removeAbortListener = (): void => undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+  try {
+    // The race is the backstop for credential resolvers and injected transports
+    // that do not observe AbortSignal. Promise.race attaches a rejection handler
+    // to the losing operation, so it cannot become an unhandled rejection.
+    return await Promise.race([operation, aborted]);
+  } finally {
+    removeAbortListener();
+    clearTimeout(timer);
+  }
+}
+
+function codexImageHeaders(
+  auth: CodexTokenSnapshot,
+  clientVersion: string,
+  turnId: string,
+): Headers {
+  const headers = new Headers({
+    Authorization: `Bearer ${auth.accessToken}`,
+    accept: "application/json",
+    "content-type": "application/json",
+    originator: CODEX_ORIGINATOR,
+    "User-Agent": `${CODEX_ORIGINATOR}/${clientVersion || CODEX_CLIENT_VERSION}`,
+    version: clientVersion || CODEX_CLIENT_VERSION,
+    "x-codex-image-turn-id": turnId,
+  });
+  if (auth.chatgptAccountId) headers.set("ChatGPT-Account-ID", auth.chatgptAccountId);
+  if (auth.isFedramp) headers.set("X-OpenAI-Fedramp", "true");
+  return headers;
+}
+
+function boundedErrorMessage(body: string): string {
+  let message = body;
+  try {
+    const value = JSON.parse(body) as {
+      error?: { message?: unknown };
+      message?: unknown;
+    };
+    const candidate = value.error?.message ?? value.message;
+    if (typeof candidate === "string") message = candidate;
+  } catch {
+    // Preserve a bounded non-JSON provider diagnostic.
+  }
+  return message.replace(/\s+/g, " ").trim().slice(0, 1_000);
+}

package/src/index.ts

@@ -12,5 +12,6 @@ export * from "./fetch";
 export * from "./mcp-sanitize";
 export * from "./model-output-truncation";
 export * from "./opaque-artifact";
+export * from "./images";
 export * from "./realtime";
 export * from "./realtime-v3";