fix(combos): hop on a definite zero-output context overflow

src/combos/failover.ts

@@ -401,11 +401,15 @@ export function comboFailureCooldownScope(
 ): ComboFailureCooldownScope {
   const code = normalizedFailureCode(options?.code);
   // Request-shape refusals first: an oversized request must not cool a healthy target.
+  // A native transport can surface a zero-output model overflow as a generic
+  // upstream_server_error carrying precise context-window prose, so consult the bounded
+  // message classifier too: that target is healthy, the turn was simply too large for it.
   if (
     status === 413
     || REQUEST_SHAPE_FAILURE_CODES.has(code)
     || isRequestLocalFreePromptCap(status, message, options?.code)
     || isProviderTargetContextOverflow(status, message, options?.code)
+    || isDefiniteContextOverflow(status, message)
     || isRequestLocalTargetIncompatibility(status, message, options?.code)
   ) return "none";
   if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider";
@@ -451,13 +455,85 @@ function isProviderTargetContextOverflow(
     && /\bprompt\s+\d+\s*>\s*\d+\s+maximum context length\b/i.test(message);
 }
 
+/** A status can carry a verdict about the REQUEST; 401/403/429 speak about the credential. */
+const CONTEXT_VERDICT_STATUSES: ReadonlySet<number> = new Set([400, 413, 422]);
+
+/**
+ * Phrases a provider emits when the INPUT does not fit this model's context window. Matched
+ * against the innermost provider message only, so an unrelated refusal that merely quotes one
+ * of these tokens in a code field cannot authorize a replay.
+ */
+const DEFINITE_CONTEXT_OVERFLOW_PHRASES = [
+  "exceeds the context window",
+  "exceed the context window",
+  "context window exceeded",
+  "context length exceeded",
+  "maximum context length",
+  "maximum context window",
+  "too many tokens",
+];
+
+/** Wrapper envelopes unwrapped before the leaf message is read. */
+const MAX_CONTEXT_OVERFLOW_ENVELOPES = 4;
+
+function isDefiniteContextOverflowMessage(text: string): boolean {
+  const normalized = text.toLowerCase();
+  return normalized === "context_length_exceeded"
+    || DEFINITE_CONTEXT_OVERFLOW_PHRASES.some(phrase => normalized.includes(phrase));
+}
+
+/**
+ * Confirm a context overflow from the provider MESSAGE rather than from a code token that
+ * merely appears somewhere in the envelope. An upstream controls both fields and can emit a
+ * contradictory pair -- `context_length_exceeded` beside `Unsupported parameter: user` -- and
+ * that is not evidence the turn is too large for this model. `classifyError` reads the whole
+ * blob, which is exactly the looseness this must not inherit.
+ *
+ * A JSON-shaped body that fails to parse is truncated or corrupt, not prose: `classificationText`
+ * is capped at 500 characters by `normalizeUpstreamErrorText` before it reaches this function, so
+ * a long envelope arrives here as a JSON prefix. Reading that prefix as plain text would let an
+ * arbitrary field that happens to sit in the first 500 bytes authorize a hop, so it fails closed.
+ *
+ * Only the exact proxy wrapper is unwrapped, within a fixed envelope budget and 16,384 characters.
+ */
+function isDefiniteContextOverflow(status: number, message: string): boolean {
+  if (!CONTEXT_VERDICT_STATUSES.has(status) && status < 500) return false;
+  if (message.length > 16_384) return false;
+  let text = message.trim();
+  // One pass per unwrapped envelope, plus one for the leaf the last envelope yields.
+  for (let unwrapped = 0; unwrapped <= MAX_CONTEXT_OVERFLOW_ENVELOPES; unwrapped += 1) {
+    const providerPrefix = /^Provider error \d{3}:\s*/.exec(text);
+    if (providerPrefix) text = text.slice(providerPrefix[0].length).trim();
+    if (!text.startsWith("{")) return isDefiniteContextOverflowMessage(text);
+    if (unwrapped === MAX_CONTEXT_OVERFLOW_ENVELOPES) return false;
+    let payload: unknown;
+    try { payload = JSON.parse(text); } catch { return false; }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+    const record = payload as Record<string, unknown>;
+    const response = record.response && typeof record.response === "object" && !Array.isArray(record.response)
+      ? record.response as Record<string, unknown>
+      : undefined;
+    const source = [record.error, response?.error, response?.last_error, record.last_error, record]
+      .find((candidate): candidate is Record<string, unknown> =>
+        !!candidate && typeof candidate === "object" && !Array.isArray(candidate)
+        && typeof (candidate as Record<string, unknown>).message === "string");
+    if (!source) return false;
+    text = (source.message as string).trim();
+  }
+  return false;
+}
+
 export function comboFailureDecision(
   status: number,
   message: string,
   options?: { code?: string | null },
 ): ComboFailureDecision {
   if (status === 499) return "stop";
   if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  // Structured form of the same hard refusal. The prose test above misses it when the origin
+  // reports the code out of band, and every hop rule below -- including the context-overflow
+  // one -- must stay subordinate to it.
+  if (normalizedFailureCode(options?.code) === "origin_rejected") return "stop";
   // The origin may already be executing this turn (the Codex WebSocket relay sent the create
   // frame and never saw a response event). Hopping would send the same request to a second
   // target while the first may still be generating; the honest status goes to the client.
@@ -476,6 +552,15 @@ export function comboFailureDecision(
   // (for example 5059 + invalid_request_prompt_too_long). That is evidence that this
   // target is too small, not that every later combo target is incapable of serving it.
   if (isProviderTargetContextOverflow(status, message, options?.code)) return "hop";
+  // A definite context-window refusal is target-local inside a heterogeneous combo: this model
+  // cannot hold the turn, but a later target may have a larger window. Two boundaries keep this
+  // safe. It is reached only after cancellation, structured origin/cyber refusals and
+  // non-replayable post-send codes have already stopped. And it only ever classifies a failure
+  // the combo stream preflight already proved emitted no output: `comboStreamPayloadCommitsOutput`
+  // commits the child on any text, tool call or unknown event, and only a zero-output terminal
+  // becomes a failure response at all, so a turn whose text the client already saw is never
+  // reclassified here.
+  if (isDefiniteContextOverflow(status, message)) return "hop";
   // A local input-admission refusal (#1524) says "this candidate cannot fit the request",
   // not "the request is impossible": the next candidate may have a larger context window.
   //

structure/runtime.md

@@ -427,9 +427,13 @@ Translated audio/file admission follows the [final-adapter input contract](adapt
 
 `src/combos/failover.ts` treats three intact HTTP 400 invalid-request envelopes as request-local incompatibilities: exactly `Unsupported parameter: user`; `unsupported_value` naming `reasoning.effort` or `reasoning_effort` with an explicit unsupported-value message; and `param: input` with a bounded model-scoped `does not support image inputs` message. A null provider code is accepted only for that observed image envelope. Only the exact proxy wrapper is unwrapped, within three envelopes and 16,384 characters; conflicting codes, malformed/truncated envelopes and reflected JSON do not gain hop permission.
 
-The combo may advance to its next eligible unattempted target before output commitment. It records no target/provider cooldown for these request-local mismatches and does not silently drop reasoning controls or raise `none` to a supported rung. Cancellation, origin/cyber-policy rejection, non-replayable post-send errors and the existing streaming commit boundary stay authoritative. Other invalid requests remain terminal.
+The combo may advance to its next eligible unattempted target before output commitment. It records no target/provider cooldown for these request-local mismatches and does not silently drop reasoning controls or raise `none` to a supported rung. Cancellation, origin/cyber-policy rejection, non-replayable post-send errors and the existing streaming commit boundary stay authoritative. Apart from the definite context overflow below, other invalid requests remain terminal.
 
-Regression coverage: `tests/responses/responses-forward-prompt-envelope.test.ts`, `tests/routing/router-combo-failover-classification.test.ts`, and `tests/server/server-combo-failover-e2e.test.ts`.
+A definite context-window overflow is the fourth request-local verdict. A heterogeneous combo mixes windows, so "this turn does not fit THIS model" is not "this turn is impossible", and stopping at the first undersized target burned the ladder on turns a later target could hold. Evidence must come from the innermost provider message: `classifyError` remaps any occurrence of `context window`, `context length`, `maximum context` or `too many tokens` anywhere in the blob, and inheriting that looseness would let a `context_length_exceeded` token sitting in a `code` field beside `Unsupported parameter: user` authorize a replay. `src/combos/failover.ts` therefore unwraps only the exact proxy wrapper, within four envelopes and 16,384 characters, and reads the leaf message. A JSON-shaped body that does not parse fails closed, because `normalizeUpstreamErrorText` caps `classificationText` at 500 characters and a long envelope arrives here as a prefix. The verdict is admitted only for statuses that speak about the request — 400, 413, 422 and 5xx — so a 401/403 body that merely quotes context prose keeps its provider-wide cooldown instead of being rescored as request-shaped. Structured `origin_rejected`, cyber policy and the non-replayable post-send codes are all tested before it.
+
+This is also why the classifier cannot duplicate visible output. A streaming child reaches combo classification only through `preflightComboStreamResponse`, which commits the child on any text, tool call or unknown event and synthesizes a failure envelope only for a zero-output terminal, so a turn whose text or tool call the client already saw is never reclassified as a hop.
+
+Regression coverage: `tests/responses/responses-forward-prompt-envelope.test.ts`, `tests/routing/router-combo-failover-classification.test.ts`, `tests/routing/routing-policy-fallback.test.ts`, `tests/helpers/combo-context-overflow-cases.ts`, and `tests/server/server-combo-failover-e2e.test.ts`.
 
 ## Combo default effort precedence
 

tests/codex-integration/combos.test.ts

@@ -900,7 +900,7 @@ describe("combo failure policy and advancement", () => {
     for (const status of [401, 403, 404, 408, 429, 500, 503]) {
       expect(comboFailureDecision(status, "provider failure")).toBe("hop");
     }
-    expect(comboFailureDecision(400, "context_length_exceeded")).toBe("stop");
+    expect(comboFailureDecision(400, "context_length_exceeded")).toBe("hop");
     expect(comboFailureDecision(403, '{"code":"origin_rejected"}')).toBe("stop");
     expect(comboFailureDecision(413, "request too large")).toBe("stop");
     expect(comboFailureDecision(409, "conflict")).toBe("stop");
@@ -919,9 +919,14 @@ describe("combo failure policy and advancement", () => {
     // verdict by echoing the token, so that shape must NOT hop.
     expect(comboFailureDecision(413, 'refused', { code: 'input_admission_refused' })).toBe('hop');
     expect(comboFailureDecision(400, 'upstream mentions input_admission_refused in prose')).toBe('stop');
-    // An UPSTREAM context verdict still stops: retrying that elsewhere is guesswork, and a
-    // generic 413 with no structured code keeps its existing conservative handling.
-    expect(comboFailureDecision(400, "context_length_exceeded")).toBe("stop");
+    // An UPSTREAM context verdict is target-local in a heterogeneous combo: this model cannot
+    // hold the turn, but a later one may have a larger window. The whole message being the bare
+    // token is unambiguous evidence; a generic 413 with no context signal stays conservative.
+    expect(comboFailureDecision(400, "context_length_exceeded")).toBe("hop");
+    // Evidence has to come from the MESSAGE. A context code beside an unrelated refusal is a
+    // contradictory envelope, and a hard structured refusal outranks the context verdict.
+    expect(comboFailureDecision(400, "ordinary invalid request", { code: "context_length_exceeded" })).toBe("stop");
+    expect(comboFailureDecision(502, "context window exceeded", { code: "origin_rejected" })).toBe("stop");
     const providerHardCap = JSON.stringify({ error: {
       message: "Prompt 346030 > 262144 maximum context length",
       type: "invalid_request_prompt_too_long",

tests/helpers/combo-context-overflow-cases.ts

@@ -0,0 +1,123 @@
+import { expect, test } from "bun:test";
+import type { OcxConfig, OcxProviderConfig } from "../../src/types";
+
+interface ComboHarness<Server> {
+  serve(handler: () => Response | Promise<Response>): Server;
+  baseUrl(server: Server): string;
+  chatSuccess(text: string, model?: string): Response;
+  chatStream(text: string): Response;
+  provider(adapter: string, url: string, apiKey: string, extra?: Partial<OcxProviderConfig>): OcxProviderConfig;
+  comboConfig(providers: OcxConfig["providers"]): OcxConfig;
+  post(config: OcxConfig, raw?: Record<string, unknown>): Promise<Response>;
+  collectSse(response: Response): Promise<unknown[]>;
+}
+
+const OVERFLOW_PROSE =
+  "Your input exceeds the context window of this model. Please adjust your input and try again.";
+
+function sse(frames: Array<[string, Record<string, unknown>]>): Response {
+  const body = frames
+    .map(([event, data]) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+    .join("");
+  return new Response(body, { headers: { "content-type": "text/event-stream" } });
+}
+
+/** Register under the caller's isolated homes, mock state and server cleanup hooks. */
+export function registerComboContextOverflowCases<Server>({
+  serve, baseUrl, chatSuccess, chatStream, provider, comboConfig, post, collectSse,
+}: ComboHarness<Server>): void {
+  test("context overflow advances while exhausted retryable targets return the sanitized last status", async () => {
+    let backupHits = 0;
+    const context = serve(() => Response.json(
+      { error: { code: "context_length_exceeded", message: "too many tokens" } },
+      { status: 400 },
+    ));
+    const larger = serve(() => {
+      backupHits += 1;
+      return chatSuccess("larger context fallback");
+    });
+    const advanced = await post(comboConfig({
+      a: provider("openai-chat", baseUrl(context), "key-a"),
+      b: provider("openai-chat", baseUrl(larger), "key-b"),
+    }));
+    expect(advanced.status).toBe(200);
+    expect(backupHits).toBe(1);
+    expect(await advanced.text()).toContain("larger context fallback");
+
+    const order: string[] = [];
+    const first = serve(() => {
+      order.push("a");
+      return new Response("secret sk-a-should-redact", { status: 503 });
+    });
+    const last = serve(() => {
+      order.push("b");
+      return Response.json({ error: { message: "missing model" } }, { status: 404 });
+    });
+    const exhausted = await post(comboConfig({
+      a: provider("openai-chat", baseUrl(first), "key-a"),
+      b: provider("openai-chat", baseUrl(last), "key-b"),
+    }));
+    expect(exhausted.status).toBe(404);
+    expect(order).toEqual(["a", "b"]);
+    expect(await exhausted.text()).not.toContain("sk-a-should-redact");
+  });
+
+  test("zero-output context overflow 502 hops to a healthy combo target", async () => {
+    let backupHits = 0;
+    const capped = serve(() => sse([
+      ["response.created", { type: "response.created", response: { id: "resp_context", status: "in_progress" } }],
+      ["response.failed", { type: "response.failed", response: {
+        id: "resp_context",
+        status: "failed",
+        error: { type: "server_error", code: "upstream_server_error", message: OVERFLOW_PROSE },
+      } }],
+    ]));
+    const backup = serve(() => {
+      backupHits += 1;
+      return chatStream("larger context backup");
+    });
+    const response = await post(comboConfig({
+      a: provider("openai-responses", baseUrl(capped), "key-a"),
+      b: provider("openai-chat", baseUrl(backup), "key-b"),
+    }), { stream: true });
+    expect(response.status).toBe(200);
+    expect(backupHits).toBe(1);
+    expect(JSON.stringify(await collectSse(response))).toContain("larger context backup");
+  });
+
+  test("context overflow after committed output never replays on another target", async () => {
+    // The boundary the hop verdict depends on. Once any text or tool call has reached the
+    // client, the stream preflight commits the child and the failure never becomes a combo
+    // classification at all -- so the same context prose that hops above must not hop here.
+    let backupHits = 0;
+    const committed = serve(() => sse([
+      ["response.created", { type: "response.created", response: { id: "resp_committed", status: "in_progress" } }],
+      ["response.output_item.added", { type: "response.output_item.added", output_index: 0, item: {
+        id: "msg_committed", type: "message", role: "assistant", status: "in_progress", content: [],
+      } }],
+      ["response.output_text.delta", {
+        type: "response.output_text.delta", item_id: "msg_committed", output_index: 0, content_index: 0,
+        delta: "already visible",
+      }],
+      ["response.failed", { type: "response.failed", response: {
+        id: "resp_committed",
+        status: "failed",
+        error: { type: "server_error", code: "upstream_server_error", message: OVERFLOW_PROSE },
+      } }],
+    ]));
+    const backup = serve(() => {
+      backupHits += 1;
+      return chatStream("must not run");
+    });
+    const response = await post(comboConfig({
+      a: provider("openai-responses", baseUrl(committed), "key-a"),
+      b: provider("openai-chat", baseUrl(backup), "key-b"),
+    }), { stream: true });
+    expect(response.status).toBe(200);
+    const frames = JSON.stringify(await collectSse(response));
+    expect(backupHits).toBe(0);
+    expect(frames).toContain("already visible");
+    expect(frames).not.toContain("must not run");
+  });
+}
+