@cartanova/qgrid-cli 2.9.2 → 2.9.5

package/bundle/src/utils/providers/openai/openai-direct-client.ts

@@ -12,6 +12,10 @@ import {
   type OpenAIResponsesOptions,
   type OpenAIResponsesRequest,
 } from "./openai-backend-protocol";
+import {
+  buildStandaloneImageRequest,
+  readStandaloneImageResponse,
+} from "./openai-image-generation";
 import { normalizeOpenAISSE, type OpenAIEventStream } from "./openai-sse";
 
 export interface OpenAIDirectCredentials {
@@ -446,8 +450,10 @@ export interface OpenAIDirectClientOptions extends OpenAIHttpsTransportOptions {
 
 export class OpenAIDirectClient {
   private readonly transport: OpenAIResponsesTransport;
+  private imageCredentials: OpenAIDirectCredentials;
 
-  constructor(options: OpenAIDirectClientOptions) {
+  constructor(private readonly options: OpenAIDirectClientOptions) {
+    this.imageCredentials = options.credentials;
     this.transport =
       options.transport ??
       (options.transportKind === "websocket"
@@ -456,6 +462,12 @@ export class OpenAIDirectClient {
   }
 
   responses(options: OpenAIResponsesOptions, signal?: AbortSignal): OpenAIEventStream {
+    if (
+      typeof options.imageGeneration === "object" &&
+      options.imageGeneration.background === "transparent"
+    ) {
+      return this.standaloneImages(options, signal);
+    }
     const clientRequestId = crypto.randomUUID();
     const affinityId = options.promptCacheKey
       ? cacheAffinityUuid(options.promptCacheKey)
@@ -472,6 +484,41 @@ export class OpenAIDirectClient {
     });
   }
 
+  private async *standaloneImages(
+    options: OpenAIResponsesOptions,
+    signal?: AbortSignal,
+  ): OpenAIEventStream {
+    const request = buildStandaloneImageRequest(options);
+    const requestId = crypto.randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+      signal?.throwIfAborted();
+      const response = await (this.options.fetch ?? fetch)(request.url, {
+        method: "POST",
+        headers: {
+          ...buildCodexIdentityHeaders(
+            this.imageCredentials.accessToken,
+            this.imageCredentials.accountId,
+          ),
+          Accept: "application/json",
+          "x-codex-image-turn-id": requestId,
+        },
+        body: JSON.stringify(request.body),
+        signal,
+      });
+      if (response.status === 401 && attempt === 0 && this.options.refreshCredentials) {
+        await response.body?.cancel();
+        this.imageCredentials = await this.options.refreshCredentials();
+        continue;
+      }
+      if (!response.ok) throw await responseError(response);
+      const images = await readStandaloneImageResponse(response);
+      signal?.throwIfAborted();
+      yield* images;
+      yield { type: "completed", responseId: requestId, model: "gpt-image-2" };
+      return;
+    }
+  }
+
   close(): void {
     this.transport.close?.();
   }

package/bundle/src/utils/providers/openai/openai-dispatcher.test.ts

@@ -1,8 +1,12 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
+const { refreshMock } = vi.hoisted(() => ({ refreshMock: vi.fn() }));
+vi.mock("./openai-refresh", () => ({ handleChatgptAuthTokensRefresh: refreshMock }));
+
+import { QueryInput, QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
 import { type GenerateRequest } from "../common/provider-dispatcher";
 import {
+  buildOpenAIResponsesRequest,
   type OpenAINormalizedEvent,
   type OpenAIResponsesOptions,
 } from "./openai-backend-protocol";
@@ -47,6 +51,136 @@ async function tickTimer(): Promise<void> {
 }
 
 describe("OpenAIDispatcher direct runtime", () => {
+  beforeEach(() => { refreshMock.mockReset(); });
+
+  it("refreshes a quota 401 once, shares the recovery, and uses the new credentials", async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response("", { status: 401 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({
+        rate_limits: { primary_window: { used_percent: 20 } },
+      })));
+    refreshMock.mockResolvedValue({ accessToken: "new-access", chatgptAccountId: "acct" });
+    const factory = vi.fn(() => ({ responses: () => events({ type: "completed", responseId: "r" }) }));
+    const d = new OpenAIDispatcher(config(), { fetch: fetchMock, clientFactory: factory });
+    await d.onTokenAdded(1, "one", credentials);
+    const [first, second] = await Promise.all([
+      d.getRateLimitsByTokenId(1), d.getRateLimitsByTokenId(1),
+    ]);
+    expect(first).toEqual(second);
+    expect(first.data.rateLimits.primary?.usedPercent).toBe(20);
+    expect(refreshMock).toHaveBeenCalledExactlyOnceWith(1);
+    expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe("Bearer new-access");
+    await d.generate(request());
+    expect(factory).toHaveBeenCalledWith(expect.objectContaining({
+      credentials: { accessToken: "new-access", accountId: "acct" },
+    }), 1);
+  });
+
+  it("does not loop when quota still returns 401 after refresh", async () => {
+    const fetchMock = vi.fn().mockImplementation(() => Promise.resolve(new Response("", { status: 401 })));
+    refreshMock.mockResolvedValue({ accessToken: "new-access", chatgptAccountId: "acct" });
+    const d = new OpenAIDispatcher(config(), { fetch: fetchMock });
+    await d.onTokenAdded(1, "one", credentials);
+    await expect(d.getRateLimitsByTokenId(1)).rejects.toThrow("HTTP 401");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(refreshMock).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([403, 429, 500, 503])("does not refresh credentials for quota HTTP %s", async (status) => {
+    const d = new OpenAIDispatcher(config(), {
+      fetch: vi.fn().mockResolvedValue(new Response("", { status })),
+    });
+    await d.onTokenAdded(1, "one", credentials);
+    await expect(d.getRateLimitsByTokenId(1)).rejects.toThrow(`HTTP ${status}`);
+    expect(refreshMock).not.toHaveBeenCalled();
+    expect(d.tokenCount).toBe(1);
+  });
+
+  it("propagates refresh failure instead of retrying rejected credentials", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 401 }));
+    refreshMock.mockRejectedValue(new Error("OpenAI refresh failed: 401 refresh_token_reused"));
+    const d = new OpenAIDispatcher(config(), { fetch: fetchMock });
+    await d.onTokenAdded(1, "one", credentials);
+    await expect(d.getRateLimitsByTokenId(1)).rejects.toThrow("refresh_token_reused");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses a newer subscriber credential and never caches an old generation's lookup", async () => {
+    let finishRefresh!: (value: { accessToken: string; chatgptAccountId: string }) => void;
+    refreshMock.mockImplementation(() => new Promise((resolve) => { finishRefresh = resolve; }));
+    const quota = (percent: number) => new Response(JSON.stringify({
+      rate_limits: { primary_window: { used_percent: percent } },
+    }));
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response("", { status: 401 }))
+      .mockResolvedValueOnce(quota(20))
+      .mockResolvedValueOnce(quota(30));
+    const d = new OpenAIDispatcher(config(), { fetch: fetchMock });
+    await d.onTokenAdded(1, "one", credentials);
+    const pending = d.getRateLimitsByTokenId(1);
+    await vi.waitFor(() => expect(refreshMock).toHaveBeenCalledTimes(1));
+    await d.onTokenUpdated(1, "one", { ...credentials, accessToken: "subscriber-access" });
+    finishRefresh({ accessToken: "older-refresh-access", chatgptAccountId: "acct" });
+    await pending;
+    expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe("Bearer subscriber-access");
+    expect((await d.getRateLimitsByTokenId(1)).data.rateLimits.primary?.usedPercent).toBe(30);
+  });
+
+  it("does not share pending quota requests across subscriber generations", async () => {
+    let finishOld!: (value: Response) => void;
+    const quota = (percent: number) => new Response(JSON.stringify({
+      rate_limits: { primary_window: { used_percent: percent } },
+    }));
+    const fetchMock = vi.fn()
+      .mockImplementationOnce(() => new Promise((resolve) => { finishOld = resolve; }))
+      .mockResolvedValueOnce(quota(10));
+    const d = new OpenAIDispatcher(config(), { fetch: fetchMock });
+    await d.onTokenAdded(1, "one", credentials);
+    const old = d.getRateLimitsByTokenId(1);
+    await d.onTokenUpdated(1, "one", { ...credentials, accessToken: "new" });
+    const current = d.getRateLimitsByTokenId(1);
+    finishOld(quota(90));
+    await old;
+    expect((await current).data.rateLimits.primary?.usedPercent).toBe(10);
+    expect((await d.getRateLimitsByTokenId(1)).data.rateLimits.primary?.usedPercent).toBe(10);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it.each(["transparent", "opaque", "auto"] as const)(
+    "preserves %s background through validation and Responses serialization",
+    async (background) => {
+      const args = QueryInput.parse({
+        model: "openai/gpt-test",
+        prompt: "an isolated red circle",
+        imageGeneration: true,
+        imageGenerationOptions: { background, quality: "high", size: "1024x1024" },
+      });
+      let body: ReturnType<typeof buildOpenAIResponsesRequest> | undefined;
+      const d = dispatcher((options) => {
+        body = buildOpenAIResponsesRequest(options);
+        return events(
+          { type: "image", id: "i", base64: "png", mimeType: "image/png" },
+          { type: "completed", responseId: "r" },
+        );
+      });
+      await d.onTokenAdded(1, "one", credentials);
+      await d.generate(request({
+        imageGeneration: args.imageGeneration,
+        imageGenerationOptions: args.imageGenerationOptions,
+      }));
+      expect(body?.tools).toEqual([{
+        type: "image_generation", background, quality: "high", size: "1024x1024",
+      }]);
+    },
+  );
+
+  it("rejects unsupported image backgrounds", () => {
+    expect(QueryInput.safeParse({
+      prompt: "a circle", imageGeneration: true,
+      imageGenerationOptions: { background: "green" },
+    }).success).toBe(false);
+  });
+
   it("passes the resolved transport to the injectable client factory", async () => {
     const factory = vi.fn(
       (_options: import("./openai-direct-client").OpenAIDirectClientOptions) => ({
@@ -430,6 +564,7 @@ describe("effort 어휘 해석 (Codex 카탈로그 기준)", () => {
   }
 
   it("모델이 지원하는 값은 그대로 보내고, 상한 초과·공개 API 어휘는 reasoning 에서 빼 백엔드 기본값을 쓴다", async () => {
+    await expect(mappedEffortFor("gpt-6-astra", "ultra")).resolves.toBe("ultra");
     await expect(mappedEffortFor("gpt-5.6-terra", "ultra")).resolves.toBe("ultra");
     await expect(mappedEffortFor("gpt-5.5", "xhigh")).resolves.toBe("xhigh");
     await expect(mappedEffortFor("gpt-5.5", "max")).resolves.toBeUndefined();

package/bundle/src/utils/providers/openai/openai-dispatcher.ts

@@ -143,7 +143,7 @@ export class OpenAIDispatcher implements ProviderDispatcher {
   readonly rateLimitsCache = new Map<number, OpenAIRateLimitsWithMeta & { generation: number }>();
   private readonly pendingRateLimits = new Map<
     number,
-    Promise<OpenAIRateLimitsWithMeta & { generation: number }>
+    { token: TokenMetadata; generation: number; promise: Promise<OpenAIRateLimitsWithMeta> }
   >();
   private readonly clients = new Map<number, ClientEntry>();
   private readonly retiredClients = new Set<ClientEntry>();
@@ -318,7 +318,11 @@ export class OpenAIDispatcher implements ProviderDispatcher {
           onDelta?.(event.text);
         } else if (event.type === "image") {
           imageAttempted = true;
-          images.push({ data: event.base64, revisedPrompt: event.revisedPrompt ?? null });
+          images.push({
+            data: event.base64,
+            revisedPrompt: event.revisedPrompt ?? null,
+            ...(event.generation ? { generation: event.generation } : {}),
+          });
         } else if (event.type === "output-item" && event.item.type === "image_generation_call") {
           imageAttempted = true;
         } else if (event.type === "completed" && event.usage) {
@@ -356,6 +360,7 @@ export class OpenAIDispatcher implements ProviderDispatcher {
       durationMs: Date.now() - startedAt,
       ttftMs: firstDeltaAt === undefined ? null : firstDeltaAt - startedAt,
       model: servingModel,
+      ...(servingModel !== req.model ? { requestedModel: req.model } : {}),
       threadCoord: { workerId: selection.tokenId, threadId: req.promptCacheKey ?? "", epoch: -1 },
       ...(images.length ? { images } : {}),
     };
@@ -378,17 +383,7 @@ export class OpenAIDispatcher implements ProviderDispatcher {
           },
           transportKind: this.transportKind,
           fetch: this.fetchImpl,
-          refreshCredentials: async () => {
-            const refreshed = await handleChatgptAuthTokensRefresh(selection.tokenId);
-            const current = this.tokenMetadata.get(selection.tokenId);
-            if (current)
-              current.credentials = {
-                ...current.credentials,
-                accessToken: refreshed.accessToken,
-                accountId: refreshed.chatgptAccountId,
-              };
-            return { accessToken: refreshed.accessToken, accountId: refreshed.chatgptAccountId };
-          },
+          refreshCredentials: () => this.refreshCredentials(selection.tokenId),
         },
         selection.tokenId,
       );
@@ -519,6 +514,7 @@ export class OpenAIDispatcher implements ProviderDispatcher {
   ): Promise<OpenAIRateLimitsWithMeta> {
     const token = this.tokenMetadata.get(tokenId);
     if (!token) throw new Error(`openai token ${tokenId} not found`);
+    const generation = token.generation;
     const cached = this.rateLimitsCache.get(tokenId);
     if (
       cached &&
@@ -531,23 +527,53 @@ export class OpenAIDispatcher implements ProviderDispatcher {
     // 조회가 몰릴 수 있다 — 진행 중인 fetch 를 공유한다. 최초 호출자의 abort 로
     // 공유 조회가 실패해도 소비처(isQuotaEligible)가 fail-open 으로 처리한다.
     const pending = this.pendingRateLimits.get(tokenId);
-    if (pending) return pending;
+    if (pending?.token === token && pending.generation === generation) return pending.promise;
     const fetchPromise = (async () => {
       const result = await readOpenAIQuotaUsage({
         credentials: token.credentials,
+        refreshCredentials: () => this.refreshCredentials(tokenId),
         fetch: this.fetchImpl,
         ...(signal ? { signal } : {}),
       });
       if (result.kind === "lookup_failed") throw new Error(result.reason);
       if (!result.raw) throw new Error("OpenAI quota response missing raw rate limits");
-      const entry = { data: result.raw, cachedAt: Date.now(), generation: token.generation };
-      if (this.tokenMetadata.get(tokenId) === token) this.rateLimitsCache.set(tokenId, entry);
+      const entry = { data: result.raw, cachedAt: Date.now(), generation };
+      if (this.tokenMetadata.get(tokenId) === token && token.generation === generation) {
+        this.rateLimitsCache.set(tokenId, entry);
+      }
       return entry;
-    })().finally(() => this.pendingRateLimits.delete(tokenId));
-    this.pendingRateLimits.set(tokenId, fetchPromise);
+    })().finally(() => {
+      if (this.pendingRateLimits.get(tokenId)?.promise === fetchPromise) {
+        this.pendingRateLimits.delete(tokenId);
+      }
+    });
+    this.pendingRateLimits.set(tokenId, { token, generation, promise: fetchPromise });
     return fetchPromise;
   }
 
+  private async refreshCredentials(tokenId: number) {
+    const previous = this.tokenMetadata.get(tokenId);
+    const generation = previous?.generation;
+    const refreshed = await handleChatgptAuthTokensRefresh(tokenId);
+    const credentials = {
+      accessToken: refreshed.accessToken,
+      accountId: refreshed.chatgptAccountId,
+    };
+    const current = this.tokenMetadata.get(tokenId);
+    if (!current?.active) throw new Error(`openai token ${tokenId} is no longer active`);
+    // A subscriber update may already contain newer credentials. Never overwrite it
+    // with the result of a refresh that started against an older generation.
+    if (current === previous && current.generation === generation) {
+      current.credentials = { ...current.credentials, ...credentials };
+      this.retireClient(tokenId);
+      this.invalidateRateLimitsCache(tokenId);
+    }
+    return {
+      accessToken: current.credentials.accessToken,
+      accountId: current.credentials.accountId,
+    };
+  }
+
   private async isQuotaEligible(
     id: number,
     token: TokenMetadata,

package/bundle/src/utils/providers/openai/openai-image-generation.test.ts

@@ -0,0 +1,135 @@
+import { PNG } from "pngjs";
+import { describe, expect, it, vi } from "vitest";
+
+import { OpenAIDirectClient } from "./openai-direct-client";
+
+function png(alpha: number[] = [0, 255]): string {
+  const image = new PNG({ width: 2, height: 1 });
+  for (let i = 0; i < 2; i++) image.data.set([255, 0, 0, alpha[i]!], i * 4);
+  return PNG.sync.write(image).toString("base64");
+}
+
+function result(data = png()) {
+  return {
+    created: 123, background: "transparent", quality: "medium", size: "2x1",
+    data: [{ b64_json: data }],
+    usage: { input_tokens: 28, output_tokens: 2, total_tokens: 30 },
+  };
+}
+
+const options = {
+  model: "gpt-5.5", instructions: "Keep the red color.",
+  history: [{ type: "message", role: "user", content: [{ type: "input_text", text: "Draw a circle." }] }],
+  imageGeneration: { background: "transparent", size: "1024x1024", quality: "high" },
+};
+
+async function run(fetchImpl: typeof fetch, overrides = {}) {
+  const client = new OpenAIDirectClient({
+    credentials: { accessToken: "test", accountId: "account" }, fetch: fetchImpl,
+  });
+  return Array.fromAsync(client.responses({ ...options, ...overrides }));
+}
+
+describe("standalone transparent images", () => {
+  it("uses the Images endpoint and preserves actual metadata without charging a driver", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => Response.json(result()));
+    const events = await run(fetchMock);
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe("https://chatgpt.com/backend-api/codex/images/generations");
+    expect(init?.headers).toMatchObject({ Accept: "application/json" });
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      model: "gpt-image-2", background: "transparent", quality: "high", size: "1024x1024",
+      prompt: expect.stringContaining("Keep the red color."),
+    });
+    expect(events[0]).toMatchObject({
+      type: "image", generation: {
+        route: "codex-images", model: "gpt-image-2", size: "2x1", quality: "medium",
+        usage: { input_tokens: 28, output_tokens: 2 },
+      },
+    });
+    expect(events[1]).toMatchObject({ type: "completed", model: "gpt-image-2" });
+    expect(events[1]).not.toHaveProperty("usage");
+  });
+
+  it("edits with reference images from both history and the latest input", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => Response.json(result()));
+    await run(fetchMock, { history: [
+      { type: "message", role: "user", content: [
+        { type: "input_text", text: "Keep this character." },
+        { type: "input_image", image_url: "data:image/png;base64,first" },
+      ] },
+      { type: "message", role: "user", content: [
+        { type: "input_text", text: "Use this pose on transparent background." },
+        { type: "input_image", image_url: "https://example.com/pose.png" },
+      ] },
+    ] });
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe("https://chatgpt.com/backend-api/codex/images/edits");
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      images: [{ image_url: "data:image/png;base64,first" }, { image_url: "https://example.com/pose.png" }],
+      prompt: expect.stringContaining("Use this pose"),
+    });
+  });
+
+  it.each([[255, 255], [0, 0], [254, 255]])("rejects images without a transparent background and visible content (%s)", async (...alpha) => {
+    const fetchMock = vi.fn<typeof fetch>(async () => Response.json(result(png(alpha))));
+    await expect(run(fetchMock)).rejects.toThrow(/transparent|visible/);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects malformed images without falling back", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => Response.json(result("bm90IHBuZw==")));
+    await expect(run(fetchMock)).rejects.toThrow(/PNG/);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not silently ignore structured output on the image-only route", async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    await expect(run(fetchMock, { outputSchema: { schema: { type: "object" } } })).rejects.toThrow(/structured/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("never replays a rejected generation", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async () => Response.json({ error: { message: "denied" } }, { status: 429 }));
+    await expect(run(fetchMock)).rejects.toThrow("denied");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("refreshes credentials once after a rejected 401", async () => {
+    const fetchMock = vi.fn<typeof fetch>()
+      .mockResolvedValueOnce(new Response("expired", { status: 401 }))
+      .mockResolvedValueOnce(Response.json(result()));
+    const refresh = vi.fn(async () => ({ accessToken: "new", accountId: "new-account" }));
+    const client = new OpenAIDirectClient({
+      credentials: { accessToken: "old", accountId: "old-account" }, fetch: fetchMock,
+      refreshCredentials: refresh,
+    });
+    await Array.fromAsync(client.responses(options));
+    expect(refresh).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[1]?.[1]?.headers).toMatchObject({ Authorization: "Bearer new" });
+  });
+
+  it("forwards cancellation and never retries it", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async (_url, init) => {
+      expect(init?.signal).toBe(controller.signal);
+      await new Promise((_resolve, reject) => init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true }));
+      return Response.json(result());
+    });
+    const controller = new AbortController();
+    const client = new OpenAIDirectClient({ credentials: { accessToken: "a", accountId: "b" }, fetch: fetchMock });
+    const pending = Array.fromAsync(client.responses(options, controller.signal));
+    const assertion = expect(pending).rejects.toThrow("cancelled");
+    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+    controller.abort(new Error("cancelled"));
+    await assertion;
+    expect(fetchMock).toHaveBeenCalledOnce();
+  });
+
+  it("rejects too many references before network I/O", async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    await expect(run(fetchMock, { history: [{ type: "message", role: "user", content:
+      Array.from({ length: 6 }, () => ({ type: "input_image", image_url: "https://example.com/a.png" })),
+    }] })).rejects.toThrow("at most 5");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/bundle/src/utils/providers/openai/openai-image-generation.ts

@@ -0,0 +1,177 @@
+import { PNG } from "pngjs";
+import { z } from "zod";
+
+import { ImageGenerationMetadata } from "../../../application/qgrid/qgrid.types";
+import {
+  CHATGPT_CODEX_RESPONSES_URL,
+  OpenAIProtocolError,
+  type OpenAINormalizedEvent,
+  type OpenAIResponsesOptions,
+} from "./openai-backend-protocol";
+
+const MAX_PNG_BYTES = 32 * 1024 * 1024;
+const MAX_IMAGE_PIXELS = 4096 * 4096;
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+export function buildStandaloneImageRequest(options: OpenAIResponsesOptions) {
+  if (options.outputSchema || options.tools?.length) {
+    throw new OpenAIProtocolError(
+      "Transparent image generation does not support tools or structured output",
+    );
+  }
+  const controls = options.imageGeneration;
+  if (!controls || controls === true || controls.background !== "transparent") {
+    throw new OpenAIProtocolError(
+      "Standalone images require an explicit transparent background request",
+    );
+  }
+  const text: string[] = [];
+  const images: Array<{ image_url: string }> = [];
+  if (options.instructions) text.push(`System instructions:\n${options.instructions}`);
+  for (const item of options.history) {
+    if (item.type === "reasoning") continue;
+    if (item.type === "image_generation_call" && typeof item.result === "string") {
+      images.push({ image_url: `data:image/png;base64,${item.result}` });
+      continue;
+    }
+    if (item.type !== "message" && typeof item.role !== "string") {
+      throw new OpenAIProtocolError(
+        "Unsupported conversation item for transparent image generation",
+      );
+    }
+    if (typeof item.content === "string") {
+      text.push(`${item.role ?? "user"}:\n${item.content}`);
+      continue;
+    }
+    if (!Array.isArray(item.content)) {
+      throw new OpenAIProtocolError("Unsupported message content for transparent image generation");
+    }
+    for (const part of item.content) {
+      if (!part || typeof part !== "object") {
+        throw new OpenAIProtocolError("Unsupported message part for transparent image generation");
+      }
+      if (
+        ["input_text", "output_text", "text"].includes(part.type) &&
+        typeof part.text === "string"
+      ) {
+        text.push(`${item.role ?? "user"}:\n${part.text}`);
+      } else if (part.type === "input_image" || part.type === "image_url") {
+        const url = typeof part.image_url === "string" ? part.image_url : part.image_url?.url;
+        if (typeof url !== "string" || !/^(https:\/\/|data:image\/)/i.test(url)) {
+          throw new OpenAIProtocolError("Image references must be HTTPS URLs or image data URLs");
+        }
+        images.push({ image_url: url });
+      } else {
+        throw new OpenAIProtocolError("Unsupported message part for transparent image generation");
+      }
+    }
+  }
+  if (images.length > 5)
+    throw new OpenAIProtocolError("Transparent image editing supports at most 5 reference images");
+  if (!text.some((part) => part.trim())) throw new OpenAIProtocolError("Image prompt is empty");
+  return {
+    url: CHATGPT_CODEX_RESPONSES_URL.replace(
+      /\/responses$/,
+      `/images/${images.length ? "edits" : "generations"}`,
+    ),
+    body: {
+      model: "gpt-image-2",
+      prompt: text.join("\n\n"),
+      background: "transparent",
+      ...(controls.quality ? { quality: controls.quality } : {}),
+      ...(controls.size ? { size: controls.size } : {}),
+      ...(images.length ? { images } : {}),
+    },
+  };
+}
+
+// Decode before accepting the result: an alpha channel alone can still be fully opaque.
+export function inspectTransparentPng(base64: string): { width: number; height: number } {
+  if (base64.length > Math.ceil(MAX_PNG_BYTES / 3) * 4 || !/^[A-Za-z0-9+/]+={0,2}$/.test(base64)) {
+    throw new OpenAIProtocolError("Invalid or oversized generated PNG");
+  }
+  const bytes = Buffer.from(base64, "base64");
+  if (
+    bytes.length < 33 ||
+    !bytes.subarray(0, 8).equals(PNG_SIGNATURE) ||
+    bytes.toString("ascii", 12, 16) !== "IHDR"
+  ) {
+    throw new OpenAIProtocolError("Image generation did not return a PNG");
+  }
+  const width = bytes.readUInt32BE(16);
+  const height = bytes.readUInt32BE(20);
+  if (!width || !height || width * height > MAX_IMAGE_PIXELS) {
+    throw new OpenAIProtocolError("Generated PNG dimensions exceed the decoding limit");
+  }
+  let image: PNG;
+  try {
+    image = PNG.sync.read(bytes);
+  } catch {
+    throw new OpenAIProtocolError("Image generation returned an invalid PNG");
+  }
+  let transparent = false;
+  let visible = false;
+  for (let i = 3; i < image.data.length; i += 4) {
+    transparent ||= image.data[i] === 0;
+    visible ||= image.data[i]! > 0;
+    if (transparent && visible) return { width: image.width, height: image.height };
+  }
+  throw new OpenAIProtocolError(
+    "Image generation did not return visible content on a transparent background",
+  );
+}
+
+export async function readStandaloneImageResponse(
+  response: Response,
+): Promise<OpenAINormalizedEvent[]> {
+  if (!response.body) throw new OpenAIProtocolError("Image response had no body");
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel();
+        throw new OpenAIProtocolError("Image response exceeded the size limit");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const schema = z.object({
+    data: z
+      .array(z.object({ b64_json: z.string().min(1), revised_prompt: z.string().nullish() }))
+      .min(1)
+      .max(16),
+    quality: z.string().optional(),
+    usage: ImageGenerationMetadata.shape.usage,
+  });
+  let parsed: z.infer<typeof schema>;
+  try {
+    parsed = schema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+  } catch {
+    throw new OpenAIProtocolError("Invalid standalone image response");
+  }
+  return parsed.data.map((item, index) => {
+    const dimensions = inspectTransparentPng(item.b64_json);
+    return {
+      type: "image",
+      base64: item.b64_json,
+      mimeType: "image/png",
+      ...(item.revised_prompt ? { revisedPrompt: item.revised_prompt } : {}),
+      generation: {
+        route: "codex-images",
+        model: "gpt-image-2",
+        background: "transparent",
+        size: `${dimensions.width}x${dimensions.height}`,
+        ...(parsed.quality ? { quality: parsed.quality } : {}),
+        ...(index === 0 && parsed.usage ? { usage: parsed.usage } : {}),
+      },
+    };
+  });
+}