@opengeni/codex 0.2.11 → 0.2.15

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

package/src/mcp-sanitize.ts

@@ -169,8 +169,10 @@ function sanitizeToolsInRpcMessage(
  * leaving the original content untouched.
  *
  * No-op when there is no `structuredContent` — so a tools/list response (or any
- * result without it) passes through unchanged. Runs alongside (after) the empty
- * outputSchema drop, which is what stops the MCP SDK -32602ing this same result.
+ * result without it) passes through unchanged. Valid object payloads stay intact
+ * for protocol-aware consumers. Invalid optional values (such as null) are removed
+ * after any useful value is copied into `content`, because the MCP client validates
+ * this field as an object before the tool can return. Runs after the outputSchema drop.
  */
 function inlineStructuredContentInRpcMessage(message: unknown): void {
   if (!message || typeof message !== "object") {
@@ -185,13 +187,15 @@ function inlineStructuredContentInRpcMessage(message: unknown): void {
     return;
   }
   const structured = record.structuredContent;
-  if (structured === undefined || structured === null) {
-    return;
+  if (structured !== undefined && structured !== null) {
+    const text = typeof structured === "string" ? structured : JSON.stringify(structured);
+    const content = Array.isArray(record.content) ? [...record.content] : [];
+    content.push({ type: "text", text });
+    record.content = content;
+  }
+  if (typeof structured !== "object" || structured === null || Array.isArray(structured)) {
+    delete record.structuredContent;
   }
-  const text = typeof structured === "string" ? structured : JSON.stringify(structured);
-  const content = Array.isArray(record.content) ? [...record.content] : [];
-  content.push({ type: "text", text });
-  record.content = content;
 }
 
 /** Sanitize a single JSON body (application/json MCP response). */

package/src/model-output-truncation.ts

@@ -167,7 +167,13 @@ export function boundModelToolOutputItems<T extends ModelHistoryItem>(
   items: readonly T[],
   policyTokens = DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
 ): T[] {
-  return items.map((item) => boundModelToolOutputItem(item, policyTokens));
+  let bounded: T[] | null = null;
+  for (const [index, item] of items.entries()) {
+    const next = boundModelToolOutputItem(item, policyTokens);
+    if (next !== item && bounded === null) bounded = items.slice(0, index);
+    bounded?.push(next);
+  }
+  return bounded ?? (items as T[]);
 }
 
 function boundToolOutputValue(output: unknown, budgetTokens: number): unknown {

package/src/normalize.ts

@@ -115,6 +115,32 @@ export function normalizeCodexRequestBody(
   return body;
 }
 
+/**
+ * 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 function normalizedCodexRequestBody(
+  body: Readonly<Record<string, unknown>>,
+  resolveModel: (slug: string) => string,
+): Record<string, unknown> {
+  const projected: Record<string, unknown> = { ...body };
+  if (body.reasoning && typeof body.reasoning === "object" && !Array.isArray(body.reasoning)) {
+    projected.reasoning = { ...(body.reasoning as Record<string, unknown>) };
+  }
+  if (Array.isArray(body.input)) {
+    projected.input = body.input.map((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+      const record = item as Record<string, unknown>;
+      return "id" in record ||
+        (record.type === "tool_search_call" && typeof record.arguments === "string")
+        ? { ...record }
+        : item;
+    });
+  }
+  return normalizeCodexRequestBody(projected, resolveModel);
+}
+
 /**
  * Build a longest-prefix model resolver. Catalog slugs come from GET /models
  * (api-client.ts). One leading `namespace/` segment is stripped first; an