From a0b8300475391b3e1fdd2f09a3f055cf09066968 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sun, 4 Oct 2026 00:35:21 +0800 Subject: [PATCH 1/2] fix(#2011): floor output-budget caps so max_tokens is always an integer Since 0.1.181 the input estimate can carry a fraction (image pixel-prior billing, #1843, adds ctx.imageTokens to the estimate), so clampOutputBudget produced a fractional cap that clampOutgoingOutput wrote verbatim into the wire's max_tokens / max_completion_tokens / max_output_tokens. Those fields are integer-typed on every protocol; strict upstreams rejected the whole turn with `max_tokens: Input should be a valid integer` (400) or `Endpoint is unavailable.` (422). Guarantee an integer at both layers so no caller can emit a fractional count: clampOutputBudget floors the cap (keeps log == wire), and writeOutputBudget coerces at the sole writer (also guards the restore path + future callers). No-op for whole-number estimates, so v<=0.1.180 behavior is byte-identical. Regression tests anchor to the exact 0.1.181 production values. Fixes #2011 --- src/server/budget.ts | 8 ++- src/server/side-request.ts | 8 ++- tests/issue2011-integer-output-budget.test.ts | 66 +++++++++++++++++++ 3 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 tests/issue2011-integer-output-budget.test.ts diff --git a/src/server/budget.ts b/src/server/budget.ts index c54c678511..d56aab689c 100644 --- a/src/server/budget.ts +++ b/src/server/budget.ts @@ -182,7 +182,13 @@ export function estimateWireOverhead(protocol: "anthropic" | "openai" | "respons * which is preflight/self-heal territory, not output starvation). */ export function clampOutputBudget(requested: number, inputEstimate: number, nativeWindow: number): number | undefined { const margin = Math.max(OUTPUT_CLAMP_MIN_MARGIN, Math.ceil(inputEstimate * OUTPUT_CLAMP_MARGIN_PCT)); - const cap = nativeWindow - inputEstimate - margin; + // #2011: max_tokens / max_completion_tokens / max_output_tokens are integer-typed on every + // wire protocol. Since 0.1.181 inputEstimate can carry a fraction (image pixel-prior billing, + // #1843, adds ctx.imageTokens to the estimate), which made this cap fractional and strict + // upstreams rejected the whole turn with `max_tokens: Input should be a valid integer`. Floor + // at the decision point so the emitted budget is always an integer (floor <= exact headroom, + // so input+output <= window still holds). + const cap = Math.floor(nativeWindow - inputEstimate - margin); if (cap < OUTPUT_CLAMP_FLOOR || cap >= requested) return undefined; return cap; } diff --git a/src/server/side-request.ts b/src/server/side-request.ts index 71745fe2b8..b167e02c3f 100644 --- a/src/server/side-request.ts +++ b/src/server/side-request.ts @@ -136,12 +136,16 @@ export function readOutputBudget(parsed: Record, field: OutputB } export function writeOutputBudget(parsed: Record, field: OutputBudgetField, value: number): void { + // #2011: output-budget fields are integer-typed on every wire protocol. Coerce at this + // sole writer so NO caller can emit a fractional token count — the clamp path already + // floors, but this also guards the restore path and any future caller at the type boundary. + const tokens = Number.isInteger(value) ? value : Math.floor(value); if (field !== "generationConfig.maxOutputTokens") { - parsed[field] = value; + parsed[field] = tokens; return; } const gen = parsed.generationConfig; - parsed.generationConfig = { ...(gen && typeof gen === "object" ? (gen as Record) : {}), maxOutputTokens: value }; + parsed.generationConfig = { ...(gen && typeof gen === "object" ? (gen as Record) : {}), maxOutputTokens: tokens }; } // #1840: one-shot "restore has no ceiling" warnings, keyed by MODEL (the fact diff --git a/tests/issue2011-integer-output-budget.test.ts b/tests/issue2011-integer-output-budget.test.ts new file mode 100644 index 0000000000..251d3108cf --- /dev/null +++ b/tests/issue2011-integer-output-budget.test.ts @@ -0,0 +1,66 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +process.env.NODE_ENV = "test"; + +import { clampOutputBudget } from "../src/server/budget.ts"; +import { writeOutputBudget } from "../src/server/side-request.ts"; + +// #2011: since 0.1.181 inputEstimate can carry a fraction (e.g. 85032.5), so the +// #453 output clamp produced a FRACTIONAL cap that was written verbatim into the wire's +// max_tokens / max_completion_tokens / max_output_tokens. Those fields are integer-typed on +// every protocol, so strict upstreams rejected the whole turn with +// 400 {"error":{"type":"server_error","message":"Upstream request failed: max_tokens: Input should be a valid integer"}} +// or 422 "...Endpoint is unavailable." +// The fix guarantees an integer at BOTH layers: the clamp decision point (clampOutputBudget) +// and the sole wire writer (writeOutputBudget), so no caller can ever emit a fractional count. + +// ---- clampOutputBudget: the decision point ---------------------------------- + +test("#2011 clampOutputBudget: fractional inputEstimate yields an INTEGER cap", () => { + // Exact values from the 0.1.181 production log (#2011): each produced a fractional + // max_tokens that a strict upstream rejected. margin = max(2048, ceil(est*0.05)). + const capA = clampOutputBudget(384_000, 85_032.5, 200_000); + assert.ok(capA !== undefined, "must clamp"); + assert.ok(Number.isInteger(capA!), `cap must be an integer (got ${capA})`); + assert.equal(capA!, 110_715, "floor of exact headroom (window - input - margin)"); + assert.ok((capA ?? 0) + 85_032.5 <= 200_000, "input + clamped output never exceeds the window"); + + const capB = clampOutputBudget(384_000, 99_364.25, 200_000); + assert.ok(Number.isInteger(capB!), `cap must be an integer (got ${capB})`); + assert.equal(capB!, 95_666, "floor of exact headroom"); +}); + +test("#2011 clampOutputBudget: integer inputEstimate is unchanged by the floor (no drift)", () => { + // Regression guard against over-correcting: with whole-number estimates the cap must be + // byte-identical to the pre-fix behavior (existing #453 repro shape). + const margin = Math.max(2048, Math.ceil(130_000 * 0.05)); + assert.equal(clampOutputBudget(131_072, 130_000, 262_144), 262_144 - 130_000 - margin); +}); + +// ---- writeOutputBudget: the sole wire writer -------------------------------- + +test("#2011 writeOutputBudget: fractional token counts are written as integers (all field shapes)", () => { + // Values straight from the 0.1.181 log so the regression is anchored to real incidents. + const flat: Record = {}; + writeOutputBudget(flat, "max_tokens", 110_715.5); + assert.equal(flat.max_tokens, 110_715, "OpenAI chat max_tokens floored to integer"); + + const mc: Record = {}; + writeOutputBudget(mc, "max_completion_tokens", 95_666.75); + assert.equal(mc.max_completion_tokens, 95_666, "OpenAI responses max_completion_tokens floored"); + + const resp: Record = {}; + writeOutputBudget(resp, "max_output_tokens", 88_015.5); + assert.equal(resp.max_output_tokens, 88_015, "Responses-API max_output_tokens floored"); + + const gemini: Record = {}; + writeOutputBudget(gemini, "generationConfig.maxOutputTokens", 157_518.5); + assert.equal((gemini.generationConfig as Record).maxOutputTokens, 157_518, "Gemini generationConfig.maxOutputTokens floored"); +}); + +test("#2011 writeOutputBudget: integer values pass through unchanged (no drift)", () => { + const body: Record = {}; + writeOutputBudget(body, "max_tokens", 40_000); + assert.equal(body.max_tokens, 40_000, "whole-number budget is untouched"); +}); From aa21543104b884765c5b6965c4ee364283f0b69c Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sun, 4 Oct 2026 00:52:14 +0800 Subject: [PATCH 2/2] docs(#2011): correct fractional-source attribution in clampOutputBudget comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The fraction since v0.1.181 comes from #1843 L1's learned per-route image cost (learnedImageReserve, cache-ledger.ts — EMA over observed/nImages usage samples), which takes precedence over the integer pixel/byte priors (#488). The old wording credited 'image pixel-prior billing' for adding ctx.imageTokens, but those priors are integers and ctx.imageTokens landed much earlier. --- src/server/budget.ts | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/server/budget.ts b/src/server/budget.ts index d56aab689c..00e8614b72 100644 --- a/src/server/budget.ts +++ b/src/server/budget.ts @@ -183,11 +183,13 @@ export function estimateWireOverhead(protocol: "anthropic" | "openai" | "respons export function clampOutputBudget(requested: number, inputEstimate: number, nativeWindow: number): number | undefined { const margin = Math.max(OUTPUT_CLAMP_MIN_MARGIN, Math.ceil(inputEstimate * OUTPUT_CLAMP_MARGIN_PCT)); // #2011: max_tokens / max_completion_tokens / max_output_tokens are integer-typed on every - // wire protocol. Since 0.1.181 inputEstimate can carry a fraction (image pixel-prior billing, - // #1843, adds ctx.imageTokens to the estimate), which made this cap fractional and strict - // upstreams rejected the whole turn with `max_tokens: Input should be a valid integer`. Floor - // at the decision point so the emitted budget is always an integer (floor <= exact headroom, - // so input+output <= window still holds). + // wire protocol. Since v0.1.181 inputEstimate can carry a fraction: #1843 L1's learned + // per-route image cost (learnedImageReserve in cache-ledger.ts — an EMA over + // observed/nImages usage samples) takes precedence over the integer pixel/byte priors + // (#488) when fresh matching evidence exists, which made this cap fractional and strict + // upstreams rejected the whole turn with `max_tokens: Input should be a valid integer`. + // Floor at the decision point so the emitted budget is always an integer (floor <= exact + // headroom, so input+output <= window still holds). const cap = Math.floor(nativeWindow - inputEstimate - margin); if (cap < OUTPUT_CLAMP_FLOOR || cap >= requested) return undefined; return cap;