feat: tuple schema (prefixItems) support for structured outputs (#77)

* feat: tuple schema support — prefixItems auto-conversion for structured outputs

Upstream Codex API doesn't support JSON Schema prefixItems (tuple),
so we convert tuple schemas to equivalent object schemas on the request
side and reconvert the response back to arrays. All three endpoints
(OpenAI, Gemini, Responses passthrough) are covered.

- New module: src/translation/tuple-schema.ts (convert/reconvert/detect)
- prepareSchema() composes tuple conversion + additionalProperties injection
- Streaming: buffer text deltas when tupleSchema present, flush reconverted on completion
- 23 unit tests for core conversion logic

* fix: responses endpoint tuple reconversion + cleanup

- Add tuple schema reconversion to /v1/responses (stream + collect),
making all three endpoints consistent
- Remove unrelated web/src/hooks/use-status.ts from this branch
- Add console.warn to silent catch blocks for easier debugging
- Add streaming buffer tradeoff comment

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -15,6 +15,7 @@
 - Structured Outputs 支持：`/v1/chat/completions` 支持 `response_format`（`json_object` / `json_schema`），Gemini 端点支持 `responseMimeType` + `responseSchema`，自动翻译为 Codex Responses API 的 `text.format`；`/v1/responses` 直通 `text` 字段
 
 - 模型列表自动同步：后端动态 fetch 成功后自动回写 `config/models.yaml`，静态配置不再滞后；前端每 60s 轮询模型列表，新模型无需刷新页面即可选择
+- Tuple Schema 支持：`prefixItems`（JSON Schema 2020-12 tuple）自动转换为等价 object schema 发给上游，响应侧还原为数组；OpenAI / Gemini / Responses 三端点统一支持
 
 ### Changed
 

src/routes/chat.ts

@@ -44,10 +44,10 @@ function makeOpenAIFormat(wantReasoning: boolean): FormatAdapter {
         code: "codex_api_error",
       },
     }),
-    streamTranslator: (api, response, model, onUsage, onResponseId) =>
-      streamCodexToOpenAI(api, response, model, onUsage, onResponseId, wantReasoning),
-    collectTranslator: (api, response, model) =>
-      collectCodexResponse(api, response, model, wantReasoning),
+    streamTranslator: (api, response, model, onUsage, onResponseId, tupleSchema) =>
+      streamCodexToOpenAI(api, response, model, onUsage, onResponseId, wantReasoning, tupleSchema),
+    collectTranslator: (api, response, model, tupleSchema) =>
+      collectCodexResponse(api, response, model, wantReasoning, tupleSchema),
   };
 }
 
@@ -122,7 +122,7 @@ export function createChatRoutes(
     }
     const req = parsed.data;
 
-    const codexRequest = translateToCodexRequest(req);
+    const { codexRequest, tupleSchema } = translateToCodexRequest(req);
     const displayModel = buildDisplayModelName(parseModelName(req.model));
     const wantReasoning = !!req.reasoning_effort;
 
@@ -134,6 +134,7 @@ export function createChatRoutes(
         codexRequest,
         model: displayModel,
         isStreaming: req.stream,
+        tupleSchema,
       },
       makeOpenAIFormat(wantReasoning),
       proxyPool,

src/routes/gemini.ts

@@ -67,8 +67,10 @@ const GEMINI_FORMAT: FormatAdapter = {
     ),
   format429: (msg) => makeError(429, msg, "RESOURCE_EXHAUSTED"),
   formatError: (status, msg) => makeError(status, msg),
-  streamTranslator: streamCodexToGemini,
-  collectTranslator: collectCodexToGeminiResponse,
+  streamTranslator: (api, response, model, onUsage, onResponseId, tupleSchema) =>
+    streamCodexToGemini(api, response, model, onUsage, onResponseId, tupleSchema),
+  collectTranslator: (api, response, model, tupleSchema) =>
+    collectCodexToGeminiResponse(api, response, model, tupleSchema),
 };
 
 export function createGeminiRoutes(
@@ -142,7 +144,7 @@ export function createGeminiRoutes(
     }
     const req = validationResult.data;
 
-    const codexRequest = translateGeminiToCodexRequest(
+    const { codexRequest, tupleSchema } = translateGeminiToCodexRequest(
       req,
       geminiModel,
     );
@@ -159,6 +161,7 @@ export function createGeminiRoutes(
         codexRequest,
         model: geminiModel,
         isStreaming,
+        tupleSchema,
       },
       GEMINI_FORMAT,
       proxyPool,

src/routes/messages.ts

@@ -40,9 +40,9 @@ function makeAnthropicFormat(wantThinking: boolean): FormatAdapter {
       ),
     format429: (msg) => makeError("rate_limit_error", msg),
     formatError: (_status, msg) => makeError("api_error", msg),
-    streamTranslator: (api, response, model, onUsage, onResponseId) =>
+    streamTranslator: (api, response, model, onUsage, onResponseId, _tupleSchema) =>
       streamCodexToAnthropic(api, response, model, onUsage, onResponseId, wantThinking),
-    collectTranslator: (api, response, model) =>
+    collectTranslator: (api, response, model, _tupleSchema) =>
       collectCodexToAnthropicResponse(api, response, model, wantThinking),
   };
 }

src/routes/responses.ts

@@ -12,7 +12,8 @@ import type { CookieJar } from "../proxy/cookie-jar.js";
 import type { ProxyPool } from "../proxy/proxy-pool.js";
 import type { CodexResponsesRequest, CodexInputItem, CodexApi } from "../proxy/codex-api.js";
 import { getConfig } from "../config.js";
-import { injectAdditionalProperties } from "../translation/shared-utils.js";
+import { prepareSchema } from "../translation/shared-utils.js";
+import { reconvertTupleValues } from "../translation/tuple-schema.js";
 import { parseModelName, resolveModelId, getModelInfo, buildDisplayModelName } from "../models/model-store.js";
 import { EmptyResponseError } from "../translation/codex-event-extractor.js";
 import {
@@ -34,8 +35,57 @@ async function* streamPassthrough(
   _model: string,
   onUsage: (u: { input_tokens: number; output_tokens: number }) => void,
   onResponseId: (id: string) => void,
+  tupleSchema?: Record<string, unknown> | null,
 ): AsyncGenerator<string> {
+  // When tupleSchema is present, buffer text deltas and reconvert on completion.
+  // This means the client receives zero incremental text — all text arrives at once
+  // after response.completed. This is a known tradeoff for tuple reconversion correctness.
+  let tupleTextBuffer = tupleSchema ? "" : null;
+
   for await (const raw of api.parseStream(response)) {
+    // Buffer text deltas when tuple reconversion is active
+    if (tupleTextBuffer !== null && raw.event === "response.output_text.delta") {
+      const data = raw.data;
+      if (isRecord(data) && typeof data.delta === "string") {
+        tupleTextBuffer += data.delta;
+        continue; // suppress this event — will flush reconverted text on completion
+      }
+    }
+
+    // On completion, flush reconverted text before emitting the completed event
+    if (tupleTextBuffer !== null && tupleSchema && raw.event === "response.completed") {
+      if (tupleTextBuffer) {
+        let reconvertedText = tupleTextBuffer;
+        try {
+          const parsed = JSON.parse(tupleTextBuffer) as unknown;
+          reconvertedText = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+        } catch (e) {
+          console.warn("[tuple-reconvert] streaming JSON parse failed, emitting raw text:", e);
+        }
+        // Emit a single text delta with reconverted content
+        yield `event: response.output_text.delta\ndata: ${JSON.stringify({ type: "response.output_text.delta", delta: reconvertedText })}\n\n`;
+      }
+      // Patch the completed event's output text if present
+      const data = raw.data;
+      if (isRecord(data) && isRecord(data.response) && tupleTextBuffer) {
+        const resp = data.response;
+        if (Array.isArray(resp.output)) {
+          for (const item of resp.output as unknown[]) {
+            if (isRecord(item) && Array.isArray(item.content)) {
+              for (const part of item.content as unknown[]) {
+                if (isRecord(part) && part.type === "output_text" && typeof part.text === "string") {
+                  try {
+                    const parsed = JSON.parse(part.text) as unknown;
+                    part.text = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+                  } catch { /* leave as-is */ }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
     // Re-emit raw SSE event
     yield `event: ${raw.event}\ndata: ${JSON.stringify(raw.data)}\n\n`;
 
@@ -66,6 +116,7 @@ async function collectPassthrough(
   api: CodexApi,
   response: Response,
   _model: string,
+  tupleSchema?: Record<string, unknown> | null,
 ): Promise<{
   response: unknown;
   usage: { input_tokens: number; output_tokens: number };
@@ -107,6 +158,27 @@ async function collectPassthrough(
     throw new EmptyResponseError(responseId, usage);
   }
 
+  // Reconvert tuple objects back to arrays in output text
+  if (tupleSchema && isRecord(finalResponse)) {
+    const resp = finalResponse;
+    if (Array.isArray(resp.output)) {
+      for (const item of resp.output as unknown[]) {
+        if (isRecord(item) && Array.isArray(item.content)) {
+          for (const part of item.content as unknown[]) {
+            if (isRecord(part) && part.type === "output_text" && typeof part.text === "string") {
+              try {
+                const parsed = JSON.parse(part.text) as unknown;
+                part.text = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+              } catch (e) {
+                console.warn("[tuple-reconvert] collect JSON parse failed, passing through:", e);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
   return { response: finalResponse, usage, responseId };
 }
 
@@ -139,8 +211,10 @@ const PASSTHROUGH_FORMAT: FormatAdapter = {
       message: msg,
     },
   }),
-  streamTranslator: streamPassthrough,
-  collectTranslator: collectPassthrough,
+  streamTranslator: (api, response, model, onUsage, onResponseId, tupleSchema) =>
+    streamPassthrough(api, response, model, onUsage, onResponseId, tupleSchema),
+  collectTranslator: (api, response, model, tupleSchema) =>
+    collectPassthrough(api, response, model, tupleSchema),
 };
 
 // ── Route ──────────────────────────────────────────────────────────
@@ -263,20 +337,25 @@ export function createResponsesRoutes(
     }
 
     // Pass through text format (JSON mode / structured outputs) as-is
+    let tupleSchema: Record<string, unknown> | null = null;
     if (
       isRecord(body.text) &&
       isRecord(body.text.format) &&
       typeof body.text.format.type === "string"
     ) {
+      let formatSchema: Record<string, unknown> | undefined;
+      if (isRecord(body.text.format.schema)) {
+        const prepared = prepareSchema(body.text.format.schema as Record<string, unknown>);
+        formatSchema = prepared.schema;
+        tupleSchema = prepared.originalSchema;
+      }
       codexRequest.text = {
         format: {
           type: body.text.format.type as "text" | "json_object" | "json_schema",
           ...(typeof body.text.format.name === "string"
             ? { name: body.text.format.name }
             : {}),
-          ...(isRecord(body.text.format.schema)
-            ? { schema: injectAdditionalProperties(body.text.format.schema as Record<string, unknown>) }
-            : {}),
+          ...(formatSchema ? { schema: formatSchema } : {}),
           ...(typeof body.text.format.strict === "boolean"
             ? { strict: body.text.format.strict }
             : {}),
@@ -295,6 +374,7 @@ export function createResponsesRoutes(
         codexRequest,
         model: displayModel,
         isStreaming: clientWantsStream,
+        tupleSchema,
       },
       PASSTHROUGH_FORMAT,
       proxyPool,

src/routes/shared/proxy-handler.ts

@@ -22,6 +22,8 @@ export interface ProxyRequest {
   codexRequest: CodexResponsesRequest;
   model: string;
   isStreaming: boolean;
+  /** Original schema before tuple→object conversion (for response reconversion). */
+  tupleSchema?: Record<string, unknown> | null;
 }
 
 /** Format-specific adapter provided by each route. */
@@ -37,11 +39,13 @@ export interface FormatAdapter {
     model: string,
     onUsage: (u: { input_tokens: number; output_tokens: number; cached_tokens?: number; reasoning_tokens?: number }) => void,
     onResponseId: (id: string) => void,
+    tupleSchema?: Record<string, unknown> | null,
   ) => AsyncGenerator<string>;
   collectTranslator: (
     api: CodexApi,
     response: Response,
     model: string,
+    tupleSchema?: Record<string, unknown> | null,
   ) => Promise<{
     response: unknown;
     usage: { input_tokens: number; output_tokens: number; cached_tokens?: number; reasoning_tokens?: number };
@@ -147,6 +151,7 @@ export async function handleProxyRequest(
                 usageInfo = u;
               },
               () => {},
+              req.tupleSchema,
             )) {
               await s.write(chunk);
             }
@@ -176,6 +181,7 @@ export async function handleProxyRequest(
               currentCodexApi,
               currentRawResponse,
               req.model,
+              req.tupleSchema,
             );
             accountPool.release(currentEntryId, result.usage);
             return c.json(result.response);

src/translation/__tests__/tuple-schema.test.ts

@@ -0,0 +1,378 @@
+import { describe, it, expect } from "vitest";
+import {
+  convertTupleSchemas,
+  reconvertTupleValues,
+  hasTupleSchemas,
+} from "../tuple-schema.js";
+
+describe("hasTupleSchemas", () => {
+  it("returns false when no prefixItems", () => {
+    expect(hasTupleSchemas({ type: "object", properties: { a: { type: "string" } } })).toBe(false);
+  });
+
+  it("returns true when prefixItems at top level", () => {
+    expect(hasTupleSchemas({ type: "array", prefixItems: [{ type: "number" }] })).toBe(true);
+  });
+
+  it("returns true when prefixItems nested in properties", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        point: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "string" }],
+        },
+      },
+    };
+    expect(hasTupleSchemas(schema)).toBe(true);
+  });
+
+  it("returns true when prefixItems inside items", () => {
+    const schema = {
+      type: "array",
+      items: {
+        type: "array",
+        prefixItems: [{ type: "number" }],
+      },
+    };
+    expect(hasTupleSchemas(schema)).toBe(true);
+  });
+
+  it("returns true when prefixItems inside oneOf", () => {
+    const schema = {
+      oneOf: [
+        { type: "string" },
+        { type: "array", prefixItems: [{ type: "number" }] },
+      ],
+    };
+    expect(hasTupleSchemas(schema)).toBe(true);
+  });
+});
+
+describe("convertTupleSchemas", () => {
+  it("does not mutate input", () => {
+    const original = {
+      type: "object",
+      properties: {
+        point: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "string" }],
+          items: false,
+        },
+      },
+    };
+    const frozen = JSON.parse(JSON.stringify(original));
+    convertTupleSchemas(structuredClone(original));
+    expect(original).toEqual(frozen);
+  });
+
+  it("converts simple tuple to object", () => {
+    const schema = {
+      type: "array",
+      prefixItems: [
+        { type: "number" },
+        { type: "number" },
+        { type: "string" },
+      ],
+      items: false,
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result).toEqual({
+      type: "object",
+      properties: {
+        "0": { type: "number" },
+        "1": { type: "number" },
+        "2": { type: "string" },
+      },
+      required: ["0", "1", "2"],
+      additionalProperties: false,
+    });
+  });
+
+  it("converts tuple nested in object property", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        point: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "string" }],
+          items: false,
+        },
+        name: { type: "string" },
+      },
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result.type).toBe("object");
+    expect(result.properties).toEqual({
+      point: {
+        type: "object",
+        properties: {
+          "0": { type: "number" },
+          "1": { type: "string" },
+        },
+        required: ["0", "1"],
+        additionalProperties: false,
+      },
+      name: { type: "string" },
+    });
+  });
+
+  it("converts nested tuple (tuple inside tuple element)", () => {
+    const schema = {
+      type: "array",
+      prefixItems: [
+        {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "number" }],
+          items: false,
+        },
+        { type: "string" },
+      ],
+      items: false,
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result).toEqual({
+      type: "object",
+      properties: {
+        "0": {
+          type: "object",
+          properties: {
+            "0": { type: "number" },
+            "1": { type: "number" },
+          },
+          required: ["0", "1"],
+          additionalProperties: false,
+        },
+        "1": { type: "string" },
+      },
+      required: ["0", "1"],
+      additionalProperties: false,
+    });
+  });
+
+  it("converts tuple inside array items", () => {
+    const schema = {
+      type: "array",
+      items: {
+        type: "array",
+        prefixItems: [{ type: "number" }, { type: "string" }],
+        items: false,
+      },
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result).toEqual({
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          "0": { type: "number" },
+          "1": { type: "string" },
+        },
+        required: ["0", "1"],
+        additionalProperties: false,
+      },
+    });
+  });
+
+  it("converts tuple inside oneOf", () => {
+    const schema = {
+      oneOf: [
+        { type: "string" },
+        {
+          type: "array",
+          prefixItems: [{ type: "number" }],
+          items: false,
+        },
+      ],
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect((result.oneOf as Record<string, unknown>[])[1]).toEqual({
+      type: "object",
+      properties: { "0": { type: "number" } },
+      required: ["0"],
+      additionalProperties: false,
+    });
+  });
+
+  it("converts tuple inside $defs", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        coord: { $ref: "#/$defs/Coordinate" },
+      },
+      $defs: {
+        Coordinate: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "number" }],
+          items: false,
+        },
+      },
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect((result.$defs as Record<string, unknown>).Coordinate).toEqual({
+      type: "object",
+      properties: {
+        "0": { type: "number" },
+        "1": { type: "number" },
+      },
+      required: ["0", "1"],
+      additionalProperties: false,
+    });
+  });
+
+  it("leaves non-tuple schemas unchanged", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        names: { type: "array", items: { type: "string" } },
+        age: { type: "number" },
+      },
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result).toEqual(schema);
+  });
+
+  it("handles empty prefixItems", () => {
+    const schema = { type: "array", prefixItems: [], items: false };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result).toEqual({
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    });
+  });
+
+  it("converts tuple without items: false (open tuple)", () => {
+    // prefixItems without items: false means additional items are allowed
+    // We still convert to object but note this loses the "additional items" semantics
+    const schema = {
+      type: "array",
+      prefixItems: [{ type: "number" }, { type: "string" }],
+    };
+    const result = convertTupleSchemas(structuredClone(schema));
+    expect(result.type).toBe("object");
+    expect(result.properties).toEqual({
+      "0": { type: "number" },
+      "1": { type: "string" },
+    });
+    expect(result.required).toEqual(["0", "1"]);
+    expect(result.additionalProperties).toBe(false);
+  });
+});
+
+describe("reconvertTupleValues", () => {
+  it("converts object with numeric keys back to array", () => {
+    const originalSchema = {
+      type: "array",
+      prefixItems: [{ type: "number" }, { type: "number" }, { type: "string" }],
+      items: false,
+    };
+    const data = { "0": 40.7, "1": -74.0, "2": "NYC" };
+    const result = reconvertTupleValues(data, originalSchema);
+    expect(result).toEqual([40.7, -74.0, "NYC"]);
+  });
+
+  it("reconverts tuple nested in object", () => {
+    const originalSchema = {
+      type: "object",
+      properties: {
+        point: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "string" }],
+          items: false,
+        },
+        name: { type: "string" },
+      },
+    };
+    const data = { point: { "0": 42, "1": "hello" }, name: "test" };
+    const result = reconvertTupleValues(data, originalSchema) as Record<string, unknown>;
+    expect(result.point).toEqual([42, "hello"]);
+    expect(result.name).toBe("test");
+  });
+
+  it("reconverts nested tuples", () => {
+    const originalSchema = {
+      type: "array",
+      prefixItems: [
+        {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "number" }],
+          items: false,
+        },
+        { type: "string" },
+      ],
+      items: false,
+    };
+    const data = { "0": { "0": 1, "1": 2 }, "1": "label" };
+    const result = reconvertTupleValues(data, originalSchema);
+    expect(result).toEqual([[1, 2], "label"]);
+  });
+
+  it("reconverts array of tuples", () => {
+    const originalSchema = {
+      type: "array",
+      items: {
+        type: "array",
+        prefixItems: [{ type: "number" }, { type: "string" }],
+        items: false,
+      },
+    };
+    const data = [
+      { "0": 1, "1": "a" },
+      { "0": 2, "1": "b" },
+    ];
+    const result = reconvertTupleValues(data, originalSchema);
+    expect(result).toEqual([
+      [1, "a"],
+      [2, "b"],
+    ]);
+  });
+
+  it("handles null values in tuple positions", () => {
+    const originalSchema = {
+      type: "array",
+      prefixItems: [{ type: "number" }, { type: "string" }],
+      items: false,
+    };
+    const data = { "0": null, "1": "hello" };
+    const result = reconvertTupleValues(data, originalSchema);
+    expect(result).toEqual([null, "hello"]);
+  });
+
+  it("returns data unchanged when schema has no tuples", () => {
+    const originalSchema = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    const data = { name: "test" };
+    const result = reconvertTupleValues(data, originalSchema);
+    expect(result).toEqual({ name: "test" });
+  });
+
+  it("returns primitive data unchanged", () => {
+    const originalSchema = { type: "string" };
+    expect(reconvertTupleValues("hello", originalSchema)).toBe("hello");
+    expect(reconvertTupleValues(42, originalSchema)).toBe(42);
+    expect(reconvertTupleValues(null, originalSchema)).toBe(null);
+  });
+
+  it("reconverts tuple inside $defs via $ref", () => {
+    const originalSchema = {
+      type: "object",
+      properties: {
+        coord: { $ref: "#/$defs/Coordinate" },
+      },
+      $defs: {
+        Coordinate: {
+          type: "array",
+          prefixItems: [{ type: "number" }, { type: "number" }],
+          items: false,
+        },
+      },
+    };
+    const data = { coord: { "0": 40.7, "1": -74.0 } };
+    const result = reconvertTupleValues(data, originalSchema) as Record<string, unknown>;
+    expect(result.coord).toEqual([40.7, -74.0]);
+  });
+});

src/translation/codex-to-gemini.ts

@@ -16,6 +16,7 @@ import type {
   GeminiPart,
 } from "../types/gemini.js";
 import { iterateCodexEvents, EmptyResponseError } from "./codex-event-extractor.js";
+import { reconvertTupleValues } from "./tuple-schema.js";
 
 export interface GeminiUsageInfo {
   input_tokens: number;
@@ -34,11 +35,13 @@ export async function* streamCodexToGemini(
   model: string,
   onUsage?: (usage: GeminiUsageInfo) => void,
   onResponseId?: (id: string) => void,
+  tupleSchema?: Record<string, unknown> | null,
 ): AsyncGenerator<string> {
   let inputTokens = 0;
   let outputTokens = 0;
   let cachedTokens: number | undefined;
   let hasContent = false;
+  let tupleTextBuffer = tupleSchema ? "" : null;
 
   for await (const evt of iterateCodexEvents(codexApi, rawResponse)) {
     if (evt.responseId) onResponseId?.(evt.responseId);
@@ -94,11 +97,40 @@ export async function* streamCodexToGemini(
       case "response.output_text.delta": {
         if (evt.textDelta) {
           hasContent = true;
-          const chunk: GeminiGenerateContentResponse = {
+          if (tupleTextBuffer !== null) {
+            tupleTextBuffer += evt.textDelta;
+          } else {
+            const chunk: GeminiGenerateContentResponse = {
+              candidates: [
+                {
+                  content: {
+                    parts: [{ text: evt.textDelta }],
+                    role: "model",
+                  },
+                  index: 0,
+                },
+              ],
+              modelVersion: model,
+            };
+            yield `data: ${JSON.stringify(chunk)}\n\n`;
+          }
+        }
+        break;
+      }
+
+      case "response.completed": {
+        // Flush buffered tuple text as reconverted JSON
+        if (tupleTextBuffer !== null && tupleSchema && tupleTextBuffer) {
+          let text = tupleTextBuffer;
+          try {
+            const parsed = JSON.parse(tupleTextBuffer) as unknown;
+            text = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+          } catch (e) { console.warn("[tuple-reconvert] streaming JSON parse failed, emitting raw text:", e); }
+          const tupleChunk: GeminiGenerateContentResponse = {
             candidates: [
               {
                 content: {
-                  parts: [{ text: evt.textDelta }],
+                  parts: [{ text }],
                   role: "model",
                 },
                 index: 0,
@@ -106,12 +138,8 @@ export async function* streamCodexToGemini(
             ],
             modelVersion: model,
           };
-          yield `data: ${JSON.stringify(chunk)}\n\n`;
+          yield `data: ${JSON.stringify(tupleChunk)}\n\n`;
         }
-        break;
-      }
-
-      case "response.completed": {
         if (evt.usage) {
           inputTokens = evt.usage.input_tokens;
           outputTokens = evt.usage.output_tokens;
@@ -171,6 +199,7 @@ export async function collectCodexToGeminiResponse(
   codexApi: CodexApi,
   rawResponse: Response,
   model: string,
+  tupleSchema?: Record<string, unknown> | null,
 ): Promise<{
   response: GeminiGenerateContentResponse;
   usage: GeminiUsageInfo;
@@ -223,6 +252,14 @@ export async function collectCodexToGeminiResponse(
     throw new EmptyResponseError(responseId, { input_tokens: inputTokens, output_tokens: outputTokens });
   }
 
+  // Reconvert tuple objects back to arrays
+  if (tupleSchema && fullText) {
+    try {
+      const parsed = JSON.parse(fullText) as unknown;
+      fullText = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+    } catch (e) { console.warn("[tuple-reconvert] collect JSON parse failed, passing through:", e); }
+  }
+
   // Build response parts: text + function calls
   const parts: GeminiPart[] = [];
   if (fullText) {

src/translation/codex-to-openai.ts

@@ -19,6 +19,7 @@ import type {
   ChatCompletionChunkToolCall,
 } from "../types/openai.js";
 import { iterateCodexEvents, EmptyResponseError, type UsageInfo } from "./codex-event-extractor.js";
+import { reconvertTupleValues } from "./tuple-schema.js";
 
 export type { UsageInfo };
 
@@ -39,11 +40,14 @@ export async function* streamCodexToOpenAI(
   onUsage?: (usage: UsageInfo) => void,
   onResponseId?: (id: string) => void,
   wantReasoning?: boolean,
+  tupleSchema?: Record<string, unknown> | null,
 ): AsyncGenerator<string> {
   const chunkId = `chatcmpl-${randomUUID().replace(/-/g, "").slice(0, 24)}`;
   const created = Math.floor(Date.now() / 1000);
   let hasToolCalls = false;
   let hasContent = false;
+  // When tupleSchema is set, buffer text deltas to reconvert at response.completed
+  let tupleTextBuffer = tupleSchema ? "" : null;
   // Track tool call indices by call_id
   const toolCallIndexMap = new Map<string, number>();
   let nextToolCallIndex = 0;
@@ -205,24 +209,65 @@ export async function* streamCodexToOpenAI(
       case "response.output_text.delta": {
         if (evt.textDelta) {
           hasContent = true;
-          yield formatSSE({
-            id: chunkId,
-            object: "chat.completion.chunk",
-            created,
-            model,
-            choices: [
-              {
-                index: 0,
-                delta: { content: evt.textDelta },
-                finish_reason: null,
-              },
-            ],
-          });
+          if (tupleTextBuffer !== null) {
+            // Buffer text for reconversion
+            tupleTextBuffer += evt.textDelta;
+          } else {
+            yield formatSSE({
+              id: chunkId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [
+                {
+                  index: 0,
+                  delta: { content: evt.textDelta },
+                  finish_reason: null,
+                },
+              ],
+            });
+          }
         }
         break;
       }
 
       case "response.completed": {
+        // Flush buffered tuple text as reconverted JSON
+        if (tupleTextBuffer !== null && tupleSchema && tupleTextBuffer) {
+          try {
+            const parsed = JSON.parse(tupleTextBuffer) as unknown;
+            const reconverted = reconvertTupleValues(parsed, tupleSchema);
+            yield formatSSE({
+              id: chunkId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [
+                {
+                  index: 0,
+                  delta: { content: JSON.stringify(reconverted) },
+                  finish_reason: null,
+                },
+              ],
+            });
+          } catch (e) {
+            console.warn("[tuple-reconvert] streaming JSON parse failed, emitting raw text:", e);
+            yield formatSSE({
+              id: chunkId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [
+                {
+                  index: 0,
+                  delta: { content: tupleTextBuffer },
+                  finish_reason: null,
+                },
+              ],
+            });
+          }
+        }
+
         if (evt.usage) onUsage?.(evt.usage);
         // Inject error text if stream completed with no content
         if (!hasContent) {
@@ -286,6 +331,7 @@ export async function collectCodexResponse(
   rawResponse: Response,
   model: string,
   wantReasoning?: boolean,
+  tupleSchema?: Record<string, unknown> | null,
 ): Promise<{ response: ChatCompletionResponse; usage: UsageInfo; responseId: string | null }> {
   const id = `chatcmpl-${randomUUID().replace(/-/g, "").slice(0, 24)}`;
   const created = Math.floor(Date.now() / 1000);
@@ -330,6 +376,14 @@ export async function collectCodexResponse(
     throw new EmptyResponseError(responseId, { input_tokens: promptTokens, output_tokens: completionTokens });
   }
 
+  // Reconvert tuple objects back to arrays in structured output
+  if (tupleSchema && fullText) {
+    try {
+      const parsed = JSON.parse(fullText) as unknown;
+      fullText = JSON.stringify(reconvertTupleValues(parsed, tupleSchema));
+    } catch (e) { console.warn("[tuple-reconvert] collect JSON parse failed, passing through:", e); }
+  }
+
   const hasToolCalls = toolCalls.length > 0;
   const message: ChatCompletionResponse["choices"][0]["message"] = {
     role: "assistant",

src/translation/gemini-to-codex.ts

@@ -14,7 +14,7 @@ import type {
 } from "../proxy/codex-api.js";
 import { parseModelName, getModelInfo } from "../models/model-store.js";
 import { getConfig } from "../config.js";
-import { buildInstructions, budgetToEffort, injectAdditionalProperties } from "./shared-utils.js";
+import { buildInstructions, budgetToEffort, prepareSchema } from "./shared-utils.js";
 import { geminiToolsToCodex, geminiToolConfigToCodex } from "./tool-format.js";
 
 /**
@@ -158,10 +158,15 @@ export function geminiContentsToMessages(
  *   - model (from URL) → resolved model ID
  *   - thinkingConfig → reasoning.effort
  */
+export interface GeminiTranslationResult {
+  codexRequest: CodexResponsesRequest;
+  tupleSchema: Record<string, unknown> | null;
+}
+
 export function translateGeminiToCodexRequest(
   req: GeminiGenerateContentRequest,
   geminiModel: string,
-): CodexResponsesRequest {
+): GeminiTranslationResult {
   // Extract system instructions
   let userInstructions: string;
   if (req.systemInstruction) {
@@ -233,17 +238,18 @@ export function translateGeminiToCodexRequest(
   }
 
   // Response format: translate responseMimeType + responseSchema → text.format
+  let tupleSchema: Record<string, unknown> | null = null;
   const mimeType = req.generationConfig?.responseMimeType;
   if (mimeType === "application/json") {
     const schema = req.generationConfig?.responseSchema;
     if (schema && Object.keys(schema).length > 0) {
-      // Codex strict mode requires additionalProperties: false on every object
-      const strictSchema = injectAdditionalProperties(schema as Record<string, unknown>);
+      const prepared = prepareSchema(schema as Record<string, unknown>);
+      tupleSchema = prepared.originalSchema;
       request.text = {
         format: {
           type: "json_schema",
           name: "gemini_schema",
-          schema: strictSchema,
+          schema: prepared.schema,
           strict: true,
         },
       };
@@ -252,5 +258,5 @@ export function translateGeminiToCodexRequest(
     }
   }
 
-  return request;
+  return { codexRequest: request, tupleSchema };
 }

src/translation/openai-to-codex.ts

@@ -10,7 +10,7 @@ import type {
 } from "../proxy/codex-api.js";
 import { parseModelName, getModelInfo } from "../models/model-store.js";
 import { getConfig } from "../config.js";
-import { buildInstructions, injectAdditionalProperties } from "./shared-utils.js";
+import { buildInstructions, prepareSchema } from "./shared-utils.js";
 import {
   openAIToolsToCodex,
   openAIToolChoiceToCodex,
@@ -78,9 +78,15 @@ function extractContent(
  *   - model → resolved model ID
  *   - reasoning_effort → reasoning.effort
  */
+export interface TranslationResult {
+  codexRequest: CodexResponsesRequest;
+  /** Original schema before tuple conversion — null if no tuples were found. */
+  tupleSchema: Record<string, unknown> | null;
+}
+
 export function translateToCodexRequest(
   req: ChatCompletionRequest,
-): CodexResponsesRequest {
+): TranslationResult {
   // Collect system/developer messages as instructions
   const systemMessages = req.messages.filter(
     (m) => m.role === "system" || m.role === "developer",
@@ -193,6 +199,7 @@ export function translateToCodexRequest(
   }
 
   // Response format: translate response_format → text.format
+  let tupleSchema: Record<string, unknown> | null = null;
   if (req.response_format && req.response_format.type !== "text") {
     if (req.response_format.type === "json_object") {
       request.text = { format: { type: "json_object" } };
@@ -200,13 +207,15 @@ export function translateToCodexRequest(
       req.response_format.type === "json_schema" &&
       req.response_format.json_schema
     ) {
+      const prepared = prepareSchema(
+        req.response_format.json_schema.schema as Record<string, unknown>,
+      );
+      tupleSchema = prepared.originalSchema;
       request.text = {
         format: {
           type: "json_schema",
           name: req.response_format.json_schema.name,
-          schema: injectAdditionalProperties(
-            req.response_format.json_schema.schema as Record<string, unknown>,
-          ),
+          schema: prepared.schema,
           ...(req.response_format.json_schema.strict !== undefined
             ? { strict: req.response_format.json_schema.strict }
             : {}),
@@ -215,5 +224,5 @@ export function translateToCodexRequest(
     }
   }
 
-  return request;
+  return { codexRequest: request, tupleSchema };
 }

src/translation/shared-utils.ts

@@ -8,6 +8,7 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 import { getConfig } from "../config.js";
 import { getConfigDir } from "../paths.js";
+import { hasTupleSchemas, convertTupleSchemas } from "./tuple-schema.js";
 
 let cachedDesktopContext: string | null = null;
 
@@ -75,6 +76,25 @@ export function injectAdditionalProperties(
   return walkSchema(structuredClone(schema), new Set());
 }
 
+/**
+ * Prepare a JSON Schema for Codex: convert tuple schemas (prefixItems) to
+ * equivalent object schemas, then inject additionalProperties: false.
+ *
+ * Returns the converted schema and the original (pre-conversion) schema if
+ * tuples were found (needed for response-side reconversion), or null otherwise.
+ */
+export function prepareSchema(
+  schema: Record<string, unknown>,
+): { schema: Record<string, unknown>; originalSchema: Record<string, unknown> | null } {
+  const cloned = structuredClone(schema);
+  if (!hasTupleSchemas(cloned)) {
+    return { schema: walkSchema(cloned, new Set()), originalSchema: null };
+  }
+  const originalSchema = structuredClone(schema);
+  convertTupleSchemas(cloned);
+  return { schema: walkSchema(cloned, new Set()), originalSchema };
+}
+
 function walkSchema(node: Record<string, unknown>, seen: Set<object>): Record<string, unknown> {
   // Cycle detection — stop if we've already visited this node
   if (seen.has(node)) return node;

src/translation/tuple-schema.ts

@@ -0,0 +1,207 @@
+/**
+ * Tuple schema conversion — bridges JSON Schema `prefixItems` (tuple) to
+ * object-based representation that Codex upstream accepts.
+ *
+ * Request side:  convertTupleSchemas() rewrites prefixItems → properties with numeric keys
+ * Response side: reconvertTupleValues() restores {"0":…,"1":…} back to […,…]
+ */
+
+type Schema = Record<string, unknown>;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// ── Detection ──────────────────────────────────────────────────────
+
+/** Returns true if the schema tree contains any `prefixItems` node. */
+export function hasTupleSchemas(schema: Schema): boolean {
+  return walk(schema, new Set());
+}
+
+function walk(node: Schema, seen: Set<object>): boolean {
+  if (seen.has(node)) return false;
+  seen.add(node);
+
+  if (Array.isArray(node.prefixItems)) return true;
+
+  // properties
+  if (isRecord(node.properties)) {
+    for (const v of Object.values(node.properties)) {
+      if (isRecord(v) && walk(v, seen)) return true;
+    }
+  }
+
+  // items
+  if (isRecord(node.items) && walk(node.items as Schema, seen)) return true;
+
+  // combinators
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(node[key])) {
+      for (const entry of node[key] as unknown[]) {
+        if (isRecord(entry) && walk(entry, seen)) return true;
+      }
+    }
+  }
+
+  // $defs / definitions
+  for (const key of ["$defs", "definitions"] as const) {
+    if (isRecord(node[key])) {
+      for (const v of Object.values(node[key] as Schema)) {
+        if (isRecord(v) && walk(v, seen)) return true;
+      }
+    }
+  }
+
+  // conditional
+  for (const key of ["if", "then", "else", "not"] as const) {
+    if (isRecord(node[key]) && walk(node[key] as Schema, seen)) return true;
+  }
+
+  return false;
+}
+
+// ── Request-side conversion ────────────────────────────────────────
+
+/**
+ * Recursively convert `prefixItems` tuple schemas to equivalent object schemas.
+ * Input must be a clone — this function mutates in place and returns the same reference.
+ */
+export function convertTupleSchemas(node: Schema): Schema {
+  return convertWalk(node, new Set());
+}
+
+function convertWalk(node: Schema, seen: Set<object>): Schema {
+  if (seen.has(node)) return node;
+  seen.add(node);
+
+  // Convert this node if it has prefixItems
+  if (Array.isArray(node.prefixItems)) {
+    const items = node.prefixItems as unknown[];
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const key = String(i);
+      properties[key] = isRecord(items[i]) ? convertWalk(items[i] as Schema, seen) : items[i];
+      required.push(key);
+    }
+
+    node.type = "object";
+    node.properties = properties;
+    node.required = required;
+    node.additionalProperties = false;
+    delete node.prefixItems;
+    delete node.items;
+    return node;
+  }
+
+  // Recurse into properties
+  if (isRecord(node.properties)) {
+    for (const [k, v] of Object.entries(node.properties)) {
+      if (isRecord(v)) node.properties[k] = convertWalk(v, seen);
+    }
+  }
+
+  // Recurse into items
+  if (isRecord(node.items)) {
+    node.items = convertWalk(node.items as Schema, seen);
+  }
+
+  // Recurse into combinators
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(node[key])) {
+      node[key] = (node[key] as unknown[]).map((entry) =>
+        isRecord(entry) ? convertWalk(entry, seen) : entry,
+      );
+    }
+  }
+
+  // Recurse into $defs / definitions
+  for (const key of ["$defs", "definitions"] as const) {
+    if (isRecord(node[key])) {
+      const defs = node[key] as Schema;
+      for (const [k, v] of Object.entries(defs)) {
+        if (isRecord(v)) defs[k] = convertWalk(v, seen);
+      }
+    }
+  }
+
+  // Recurse into conditional
+  for (const key of ["if", "then", "else", "not"] as const) {
+    if (isRecord(node[key])) {
+      node[key] = convertWalk(node[key] as Schema, seen);
+    }
+  }
+
+  return node;
+}
+
+// ── Response-side reconversion ─────────────────────────────────────
+
+/**
+ * Schema-guided recursive reconversion: turn {"0":…,"1":…} objects back to arrays
+ * wherever the *original* schema had `prefixItems`.
+ */
+export function reconvertTupleValues(data: unknown, schema: Schema, rootSchema?: Schema): unknown {
+  const root = rootSchema ?? schema;
+
+  // Resolve $ref
+  if (typeof schema.$ref === "string") {
+    const resolved = resolveRef(schema.$ref, root);
+    if (resolved) return reconvertTupleValues(data, resolved, root);
+    return data;
+  }
+
+  // Tuple node: original schema has prefixItems → data should be {"0":…,"1":…} �� convert to array
+  if (Array.isArray(schema.prefixItems) && isRecord(data)) {
+    const items = schema.prefixItems as unknown[];
+    const result: unknown[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const key = String(i);
+      const val = data[key];
+      const itemSchema = items[i];
+      result.push(isRecord(itemSchema) ? reconvertTupleValues(val, itemSchema, root) : val);
+    }
+    return result;
+  }
+
+  // Object with properties → recurse into each property
+  if (isRecord(schema.properties) && isRecord(data)) {
+    const result: Record<string, unknown> = { ...data };
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (key in result && isRecord(propSchema)) {
+        result[key] = reconvertTupleValues(result[key], propSchema, root);
+      }
+    }
+    return result;
+  }
+
+  // Array with items schema → recurse into each element
+  if (isRecord(schema.items) && Array.isArray(data)) {
+    return data.map((el) => reconvertTupleValues(el, schema.items as Schema, root));
+  }
+
+  // Combinators — try to find matching branch (heuristic: first branch that has prefixItems)
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const branch of schema[key] as unknown[]) {
+        if (isRecord(branch) && hasTupleSchemas(branch)) {
+          return reconvertTupleValues(data, branch, root);
+        }
+      }
+    }
+  }
+
+  return data;
+}
+
+function resolveRef(ref: string, root: Schema): Schema | undefined {
+  // Only handle internal refs: #/$defs/Name or #/definitions/Name
+  const match = ref.match(/^#\/(\$defs|definitions)\/(.+)$/);
+  if (!match) return undefined;
+  const defs = root[match[1]];
+  if (!isRecord(defs)) return undefined;
+  const resolved = defs[match[2]];
+  return isRecord(resolved) ? resolved : undefined;
+}