Skip to content

Commit 842170b

Browse files
committed
fix(images): close Auto ratio, root image_gen collapse, and default download cap
Addresses the three runtime edge cases raised in review of the #2083 carry. - fulfill forwarded a pre-folded aspect_ratio, so an explicit "auto" looked absent and callXaiImages derived a ratio from `size` instead of suppressing it. Forward the raw literal and let the client own validation. - The parser replaced only the first un-namespaced `image_gen` when a hosted declaration arrived, so two root declarations left a second root behind and the catalog stayed ambiguous. Remove all root collisions, keep namespaced entries, insert exactly one synthetic root. - The default downloader in connectPublicHttps forwarded `maxBytes: undefined` to pinnedHttpGet, whose cap is optional, removing the ceiling rather than inheriting it. Preserve MAX_DOWNLOAD_BYTES and honour tighter explicit limits. Docs now state the implemented precedence: the xAI relay owns /v1/images only when bridgeEnabled is true and images.provider is omitted.
1 parent 97e8f83 commit 842170b

13 files changed

Lines changed: 188 additions & 15 deletions

File tree

‎docs-site/src/content/docs/guides/image-bridge.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ xAI Grok Imagine, so the model you're actually chatting with can still generate
2323
If that grant (or an xAI API key) is missing, `/v1/images` returns an error instead of
2424
falling through to ChatGPT.
2525

26+
The relay only owns the route when no image provider is configured: it runs when
27+
`images.bridgeEnabled` is `true` **and** `images.provider` is omitted. Setting
28+
`images.provider` explicitly hands `/v1/images` to that provider, and its own
29+
validation errors are returned as-is rather than being retried through xAI.
30+
2631
```json
2732
{
2833
"providers": {

‎docs-site/src/content/docs/ja/guides/image-bridge.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ OpenAI 以外のモデル (Claude、Gemini、Grok など) を介して Codex を
1212
- **設定で `images.bridgeEnabled: true` を設定してブリッジを有効にします** (これはオフになっています)
1313
予期しない xAI 請求を避けるためのデフォルト — 以下の [構成](#configuration) を参照してください)。
1414
- **API キー**を持つ `xai` プロバイダー エントリ。ブリッジはフルフィルメントをレジストリ xAI に固定します
15-
画像エンドポイント (`https://api.x.ai/v1`);設定された `baseUrl` オーバーライドは、イメージ呼び出しでは無視されます。 OAuth / `ocx login xai` だけではこのサイドカー・ループは有効になりません。同じ `bridgeEnabled` フラグは、別系統の Codex `/v1/images` リレーを有効にし、組み込みの `image_gen` クライアントが Grok CLI の認可で Imagine を呼べるようにします。認可(または xAI API キー)が無い場合、`/v1/images` は ChatGPT にフォールスルーせずエラーを返します。詳細は [組み込み画像生成](/guides/codex-integration/#built-in-image-generation-image_gen) を参照してください。
15+
画像エンドポイント (`https://api.x.ai/v1`);設定された `baseUrl` オーバーライドは、イメージ呼び出しでは無視されます。 OAuth / `ocx login xai` だけではこのサイドカー・ループは有効になりません。同じ `bridgeEnabled` フラグは、別系統の Codex `/v1/images` リレーを有効にし、組み込みの `image_gen` クライアントが Grok CLI の認可で Imagine を呼べるようにします。認可(または xAI API キー)が無い場合、`/v1/images` は ChatGPT にフォールスルーせずエラーを返します。詳細は [組み込み画像生成](/guides/codex-integration/#built-in-image-generation-image_gen) を参照してください。このリレーが経路を持つのは、`images.bridgeEnabled` が `true` で、かつ `images.provider` が未指定のときだけです。`images.provider` を明示すると `/v1/images` はそのプロバイダーが担当し、そのバリデーションエラーは xAI で再試行されずそのまま返ります。
1616

1717
「`json { "providers": { "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" } } } `」
1818

‎docs-site/src/content/docs/ko/guides/image-bridge.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Codex를 Claude, Gemini, Grok 같은 OpenAI가 아닌 모델로 라우팅하면
1010
## 사전 조건
1111

1212
- 구성에서 `images.bridgeEnabled: true`로 설정해 브리지를 켭니다. 예상치 못한 xAI 요금을 피하려고 기본값은 꺼져 있습니다. 아래 [Configuration](#configuration)을 참고합니다.
13-
- API 키가 있는 `xai` provider 항목이 필요합니다. 브리지는 처리를 레지스트리의 xAI Images endpoint (`https://api.x.ai/v1`)에 고정하며, 이미지 호출에서는 설정된 `baseUrl` override를 무시합니다. OAuth / `ocx login xai`만으로는 이 sidecar 루프가 켜지지 않습니다. 같은 `bridgeEnabled` 플래그는 별도의 Codex `/v1/images` relay를 켜서, 내장 `image_gen` 클라이언트가 Grok CLI grant로 Imagine을 호출할 수 있게 합니다. 그 grant(또는 xAI API key)가 없으면 `/v1/images`는 ChatGPT로 넘어가지 않고 오류를 반환합니다. [Built-in image generation](/guides/codex-integration/#built-in-image-generation-image_gen)을 참고하세요.
13+
- API 키가 있는 `xai` provider 항목이 필요합니다. 브리지는 처리를 레지스트리의 xAI Images endpoint (`https://api.x.ai/v1`)에 고정하며, 이미지 호출에서는 설정된 `baseUrl` override를 무시합니다. OAuth / `ocx login xai`만으로는 이 sidecar 루프가 켜지지 않습니다. 같은 `bridgeEnabled` 플래그는 별도의 Codex `/v1/images` relay를 켜서, 내장 `image_gen` 클라이언트가 Grok CLI grant로 Imagine을 호출할 수 있게 합니다. 그 grant(또는 xAI API key)가 없으면 `/v1/images`는 ChatGPT로 넘어가지 않고 오류를 반환합니다. 이 relay가 경로를 맡는 건 `images.bridgeEnabled`가 `true`이고 `images.provider`를 비워둔 경우뿐입니다. `images.provider`를 지정하면 `/v1/images`는 그 provider가 담당하고, 그쪽 검증 오류는 xAI로 재시도하지 않고 그대로 반환합니다. [Built-in image generation](/guides/codex-integration/#built-in-image-generation-image_gen)을 참고하세요.
1414

1515
```json
1616
{

‎docs-site/src/content/docs/ru/guides/image-bridge.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ Image Bridge обнаруживает такие вызовы и прозрач
2323
Если grant (или API-ключ xAI) отсутствует, `/v1/images` возвращает ошибку и не
2424
переходит на ChatGPT.
2525

26+
Relay владеет маршрутом только тогда, когда `images.bridgeEnabled` равен `true`, а
27+
`images.provider` не задан. Явно указанный `images.provider` передаёт `/v1/images`
28+
этому провайдеру, и его ошибки валидации возвращаются как есть, без повторной
29+
попытки через xAI.
30+
2631
```json
2732
{
2833
"providers": {

‎docs-site/src/content/docs/zh-cn/guides/image-bridge.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ description: 在使用非 OpenAI 提供方时,将 image_generation 托管工
1010
## 前提条件
1111

1212
- **启用桥接**:在配置中设置 `images.bridgeEnabled: true`(默认关闭,以避免意外产生 xAI 费用 - 见下文的 [配置](#configuration))。
13-
- 配置一个带有 **API 密钥** 的 `xai` provider 条目。桥接会将执行固定到注册表中的 xAI Images 端点(`https://api.x.ai/v1`);任何已配置的 `baseUrl` 覆盖都会被图像调用忽略。仅有 OAuth / `ocx login xai` **不会** 启用这条 sidecar 循环。同一项 `bridgeEnabled` 会启用另一条 Codex `/v1/images` 中继,让内置 `image_gen` 客户端用 Grok CLI 授权调用 Imagine — 见 [内置图像生成](/guides/codex-integration/#built-in-image-generation-image_gen)。若该授权(或 xAI API key)缺失,`/v1/images` 会返回错误,而不会落到 ChatGPT。
13+
- 配置一个带有 **API 密钥** 的 `xai` provider 条目。桥接会将执行固定到注册表中的 xAI Images 端点(`https://api.x.ai/v1`);任何已配置的 `baseUrl` 覆盖都会被图像调用忽略。仅有 OAuth / `ocx login xai` **不会** 启用这条 sidecar 循环。同一项 `bridgeEnabled` 会启用另一条 Codex `/v1/images` 中继,让内置 `image_gen` 客户端用 Grok CLI 授权调用 Imagine — 见 [内置图像生成](/guides/codex-integration/#built-in-image-generation-image_gen)。若该授权(或 xAI API key)缺失,`/v1/images` 会返回错误,而不会落到 ChatGPT。只有在 `images.bridgeEnabled` 为 `true` 且未设置 `images.provider` 时,这条中继才拥有该路由;显式设置 `images.provider` 后,`/v1/images` 归该 provider 处理,其校验错误按原样返回,不会改由 xAI 重试。
1414

1515
```json
1616
{

‎src/images/artifacts.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,10 @@ async function connectPublicHttps(
321321
const pinned = pickPinnedAddress(resolved.addresses);
322322
const download = options.pinnedDownload ?? ((resource, peer, signal) =>
323323
pinnedHttpGet(resource, peer, signal, {
324-
maxBytes: options.maxBytes,
324+
// `maxBytes` is optional in pinnedHttpGet, so forwarding undefined removes the
325+
// cap entirely instead of inheriting a default. Keep the 50 MiB ceiling when a
326+
// caller omits a limit, and honour an explicit tighter one.
327+
maxBytes: options.maxBytes ?? MAX_DOWNLOAD_BYTES,
325328
context: `${options.context} download`,
326329
}));
327330
return download(url, pinned, options.signal);

‎src/images/fulfill.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { existsSync } from "node:fs";
22
import { pathToFileURL } from "node:url";
33
import type { ImageBridgePlan, ImageCallResult } from "./types";
4-
import { callXaiImages, resolveXaiAspectRatioLiteral } from "./xai-client";
4+
import { callXaiImages } from "./xai-client";
55
import {
66
materializeInlineImage,
77
downloadImageToArtifact,
@@ -91,7 +91,11 @@ export async function fulfillImageCall(
9191
typeof obj.image_url === "string" ? obj.image_url : typeof obj.image === "string" ? obj.image : undefined;
9292
const size = typeof obj.size === "string" ? obj.size : plan.defaultSize;
9393
const quality = typeof obj.quality === "string" ? obj.quality : plan.defaultQuality;
94-
const aspectRatio = resolveXaiAspectRatioLiteral(obj.aspect_ratio);
94+
// Forward the raw literal and let callXaiImages own validation. Folding "auto"
95+
// to undefined here would make the request look like it carried no ratio at
96+
// all, so the client would derive one from `size` — the opposite of what an
97+
// explicit Auto selection asks for.
98+
const aspectRatio = typeof obj.aspect_ratio === "string" ? obj.aspect_ratio : undefined;
9599

96100
let result;
97101
try {

‎src/images/xai-client.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,12 @@ export function resolveXaiAspectRatioLiteral(value: unknown): string | undefined
4848
}
4949

5050
function resolveAspectRatio(req: XaiImageRequest): string | undefined {
51-
if (req.aspectRatio?.trim()) return resolveXaiAspectRatioLiteral(req.aspectRatio);
51+
// An explicit aspect_ratio owns the decision even when it resolves to nothing:
52+
// "auto" means "let xAI choose", so falling back to a size-derived ratio would
53+
// silently override the caller. Only an absent field consults `size`.
54+
if (req.aspectRatio !== undefined && req.aspectRatio.trim()) {
55+
return resolveXaiAspectRatioLiteral(req.aspectRatio);
56+
}
5257
return mapSizeToAspectRatio(req.size);
5358
}
5459

‎src/responses/parser.ts‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -250,12 +250,20 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
250250
// Identity is the un-namespaced synthetic root (`imageGeneration: true`), not
251251
// the bare name: a namespaced ordinary `image_gen` must not suppress it.
252252
const synthetic = buildImageTool();
253-
const rootIdx = out.findIndex(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace);
254-
if (rootIdx >= 0) {
255-
if (!out[rootIdx]!.imageGeneration) out[rootIdx] = synthetic;
256-
} else {
257-
out.push(synthetic);
253+
// Every un-namespaced `image_gen` collides on one wire name, so removing only
254+
// the first leaves a second root behind and the catalog stays ambiguous.
255+
// Drop all root collisions, keep namespaced entries, then insert exactly one
256+
// synthetic root — at the earliest colliding position so declaration order is
257+
// preserved for models that read the catalog positionally.
258+
let insertAt = -1;
259+
for (let i = out.length - 1; i >= 0; i -= 1) {
260+
const tool = out[i]!;
261+
if (tool.name !== IMAGE_GEN_TOOL_NAME || tool.namespace) continue;
262+
out.splice(i, 1);
263+
insertAt = i;
258264
}
265+
if (insertAt >= 0) out.splice(insertAt, 0, synthetic);
266+
else out.push(synthetic);
259267
}
260268
else if (typeof t.name === "string" && t.type !== "web_search" && t.type !== "image_generation") {
261269
// Any OTHER named tool (e.g. a native/computer-use tool type opencodex doesn't explicitly
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { describe, expect, mock, test } from "bun:test";
2+
3+
// The default downloader inside connectPublicHttps used to forward `maxBytes: undefined`
4+
// to pinnedHttpGet, whose cap is optional — so a caller that omitted a limit removed the
5+
// byte ceiling entirely instead of inheriting MAX_DOWNLOAD_BYTES. Both production callers
6+
// happen to pass an explicit limit today, which is why the existing suites (they all
7+
// inject `pinnedDownload` and bypass the default path) could not see it.
8+
9+
const lookupMock = mock(async (): Promise<{ address: string; family: number }[]> => [
10+
{ address: "93.184.216.34", family: 4 },
11+
]);
12+
mock.module("node:dns/promises", () => ({ lookup: lookupMock }));
13+
14+
const MIN_PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
15+
const seenMaxBytes: Array<number | undefined> = [];
16+
17+
mock.module("../../src/lib/pinned-http", () => ({
18+
pinnedHttpGet: async (
19+
_url: string,
20+
_pinned: unknown,
21+
_signal?: AbortSignal,
22+
options?: { maxBytes?: number },
23+
) => {
24+
seenMaxBytes.push(options?.maxBytes);
25+
return new Response(MIN_PNG, { status: 200 });
26+
},
27+
PinnedHttpError: class extends Error {},
28+
}));
29+
30+
const { fetchPublicHttpsImage, MAX_DOWNLOAD_BYTES } = await import(
31+
`../../src/images/artifacts?cap=${Date.now()}`
32+
);
33+
34+
describe("default image downloader byte cap", () => {
35+
test("an omitted maxBytes inherits MAX_DOWNLOAD_BYTES instead of removing the cap", async () => {
36+
seenMaxBytes.length = 0;
37+
const resp = await fetchPublicHttpsImage("https://public-host/image.png");
38+
expect(resp.status).toBe(200);
39+
expect(seenMaxBytes).toEqual([MAX_DOWNLOAD_BYTES]);
40+
expect(seenMaxBytes[0]).not.toBeUndefined();
41+
});
42+
43+
test("an explicit tighter limit is preserved", async () => {
44+
seenMaxBytes.length = 0;
45+
await fetchPublicHttpsImage("https://public-host/image.png", { maxBytes: 1024 });
46+
expect(seenMaxBytes).toEqual([1024]);
47+
});
48+
});

0 commit comments

Comments
 (0)