fix(responses): strip max_output_tokens only where the backend rejects it

docs-site/src/content/docs/reference/proxy-formats.md

@@ -192,6 +192,9 @@ top-level `instructions`, and `truncation` is removed because that destination r
 Responses shapes. Other Responses destinations preserve them.
 The same canonical boundary removes nested client-only `prompt_cache_breakpoint` markers and drops
 `item_reference` entries only on `store: false` continuations; tool call/result pairing is unchanged.
+`metadata` is removed on every forward route for compatibility with the canonical ChatGPT backend, which rejects it. `max_output_tokens`
+is removed only on that canonical route, which rejects the field outright; every other forward destination
+receives the caller's output cap unchanged, but the cap bounds the turn only when the destination enforces it.
 
 Image file IDs are provider-scoped references, not portable image bytes. Responses passthrough
 retains them; translating adapters receive an `[image: file_id]` text marker for file-only image

scripts/test-layout/layout.json

@@ -1217,6 +1217,7 @@
     "openai-provider-option-tooling.test.ts": "adapters/openai",
     "openai-provider-option.test.ts": "adapters/openai",
     "openai-responses-passthrough.test.ts": "responses",
+    "responses-forward-output-cap.test.ts": "responses",
     "opencode-cli.test.ts": "providers",
     "opencode-free-provider.test.ts": "providers",
     "opencode-go-deepseek.test.ts": "providers",

src/adapters/openai-responses/canonical-forward.ts

@@ -64,20 +64,27 @@ export function stripStatefulResponsesParams(body: unknown): unknown {
 }
 
 /**
- * Remove top-level parameters the ChatGPT backend (`authMode: "forward"`) rejects
- * with `{"detail":"Unsupported parameter: …"}` (strict allowlist). Codex CLI never
+ * Remove top-level parameters a forward destination rejects with
+ * `{"detail":"Unsupported parameter: …"}` (strict allowlist). Codex CLI never
  * sends these — it controls output length via `reasoning.effort` — but third-party
  * Responses API clients (GJC, SDK wrappers) include `max_output_tokens` per the
- * public spec. `metadata` is likewise absent from the allowlist. No-op when the
- * body carries neither field, keeping the common Codex path allocation-free.
+ * public spec. No-op when the body carries none of the dropped fields, keeping the
+ * common Codex path allocation-free.
+ *
+ * The canonical ChatGPT backend rejects `metadata`, so the forwarding path removes it on every
+ * forward route for compatibility.
+ * `max_output_tokens` does not: it is the caller's cost cap on the turn, and a
+ * self-hosted or third-party gateway may honour it — dropping it there silently
+ * removes the cap. Only the canonical ChatGPT backend rejects it outright, so only
+ * `canonical` callers strip it.
  */
-export function stripUnsupportedForwardParams(body: unknown): unknown {
+export function stripUnsupportedForwardParams(body: unknown, canonical: boolean): unknown {
   if (!isPlainObject(body)) return body;
-  const hasMot = Object.prototype.hasOwnProperty.call(body, "max_output_tokens");
-  const hasMeta = Object.prototype.hasOwnProperty.call(body, "metadata");
-  if (!hasMot && !hasMeta) return body;
-  const { max_output_tokens: _mot, metadata: _meta, ...rest } = body;
-  return rest;
+  const drop = canonical ? (["metadata", "max_output_tokens"] as const) : (["metadata"] as const);
+  if (!drop.some(key => Object.hasOwn(body, key))) return body;
+  const next: Record<string, unknown> = { ...body };
+  for (const key of drop) delete next[key];
+  return next;
 }
 
 /** Sampling controls the canonical ChatGPT backend rejects; other forward gateways accept them. */

src/adapters/openai-responses/passthrough.ts

@@ -324,9 +324,11 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         outBody = normalizeResponsesToolResultAdjacency(outBody);
       }
       if (forward) {
-        outBody = stripUnsupportedForwardParams(outBody);
-        // Only the canonical ChatGPT backend rejects the retired field; a self-hosted or
-        // third-party forward gateway may still accept it, so this must not be widened.
+        // `metadata` is stripped on every forward route for compatibility with the canonical backend.
+        // `max_output_tokens` is stripped only when this provider is the canonical backend.
+        outBody = stripUnsupportedForwardParams(outBody, isCanonicalOpenAiForwardProvider(provider));
+        // Only the canonical ChatGPT backend rejects the canonical-only fields below; a self-hosted
+        // or third-party forward gateway may accept them, so this guard must not be widened.
         if (isCanonicalOpenAiForwardProvider(provider)) {
           outBody = stripCanonicalForwardSamplingParams(outBody);
           outBody = stripDeprecatedPromptCacheRetention(outBody, parsed.modelId);

tests/fixtures/test-layout-expected.json

@@ -1043,6 +1043,7 @@
   "openai-provider-option-tooling.test.ts": "adapters/openai",
   "openai-provider-option.test.ts": "adapters/openai",
   "openai-responses-passthrough.test.ts": "responses",
+  "responses-forward-output-cap.test.ts": "responses",
   "opencode-cli.test.ts": "providers",
   "opencode-free-provider.test.ts": "providers",
   "opencode-go-deepseek.test.ts": "providers",

tests/responses/responses-forward-output-cap.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { createResponsesPassthroughAdapter as createResponsesPassthroughAdapterProduction } from "../../src/adapters/openai-responses";
+import { withTestTranslatorBudget } from "../helpers/translator-budget";
+
+const createResponsesPassthroughAdapter = (
+  ...args: Parameters<typeof createResponsesPassthroughAdapterProduction>
+) => withTestTranslatorBudget(createResponsesPassthroughAdapterProduction(...args));
+
+const meta = { headers: new Headers({ authorization: "Bearer token" }) };
+const rawBody = {
+  model: "gpt-5.6-sol",
+  input: [{ role: "user", content: [{ type: "input_text", text: "ping" }] }],
+  stream: true,
+  store: false,
+  max_output_tokens: 32000,
+  metadata: { user_id: "u-1" },
+  reasoning: { effort: "low" },
+};
+
+describe("OpenAI Responses forward output cap", () => {
+  test("noncanonical forward mode keeps the caller's max_output_tokens cap", () => {
+    const adapter = createResponsesPassthroughAdapter({
+      adapter: "openai-responses",
+      baseUrl: "https://gateway.internal.example/v1",
+      authMode: "forward" as const,
+    });
+    const request = adapter.buildRequest({
+      modelId: "gpt-5.6-sol",
+      context: { messages: [] },
+      stream: true,
+      options: {},
+      _rawBody: { ...rawBody },
+    }, meta);
+    const body = JSON.parse(request.body) as Record<string, unknown>;
+
+    expect(body.max_output_tokens).toBe(32000);
+    expect(body).not.toHaveProperty("metadata");
+  });
+});