Skip to content

Commit 7de03fb

Browse files
codexEran
authored andcommitted
feat(reasoning): learn a refused effort rung and replay once
A routed upstream can refuse a rung the catalog advertises because the ladder describes the model, not the account (max on muse-spark-1.3-contributor needs an active Muse Code subscription). The request path now detects that refusal in the 400/403 error body, records it, and replays once at the next lower published rung in both recovery loops; later turns clamp before dispatch. The attempt is logged with recovery kind reasoning-effort-downgrade and the same-target cache is invalidated so the replay carries the downgraded effort.
1 parent 9b1e2e1 commit 7de03fb

4 files changed

Lines changed: 286 additions & 1 deletion

File tree

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# 260912 — A refused reasoning rung is learned and replayed once
2+
3+
## Decision
4+
5+
When a routed upstream answers 400/403 and names reasoning effort in the body, the pipeline records
6+
that (provider, model, effort) as refused, replays the request once at the next lower published rung,
7+
and keeps the rung out of every later ladder (see the metadata record in
8+
devlog/_plan/260912_reasoning_metadata/). The attempt is logged with recovery kind
9+
reasoning-effort-downgrade, so requestedEffort and effectiveEffort stay distinguishable in usage.
10+
11+
## Why the ladder is not enough
12+
13+
The published ladder describes the model, not the account. Live 2026-09-12:
14+
muse-spark-1.3-contributor answered 400 for max with
15+
16+
Error from provider (Console Go): Upstream request failed: [invalid_request_error]
17+
reasoning_effort max requires an active Muse Code subscription for model
18+
muse-spark-1.3-contributor.
19+
20+
while xhigh answered 200. Clamping against the published ladder removes that case before dispatch,
21+
but any entitlement-driven refusal for a published rung would otherwise fail the turn outright.
22+
23+
## Shape
24+
25+
- Detection is narrow on purpose: 400/403 only, the body must be complete and display-safe (the same
26+
contract as the other rejection peeks), and the text has to name reasoning effort. An unrelated 400
27+
never triggers a replay, which keeps the single extra send honest.
28+
- One replay per request, guarded per recovery loop. The streamed passthroughRecovery loop and the
29+
non-streamed recovery loop both carry the same block, matching the file's existing convention that
30+
recovery kinds stay in sync across the two.
31+
- Before the rebuild the parsed effort is replaced and the same-target cache is invalidated
32+
(invalidateSameTargetRequest), because that cache keys on parsed identity and would otherwise
33+
replay the original body byte-for-byte.
34+
- No new failure surface: when the refusal is the only rung (or every lower rung is known-refused),
35+
the original error is returned untouched.
36+
37+
## Evidence
38+
39+
tests/responses/responses-reasoning-effort-downgrade.test.ts (4 cases, mocked upstream):
40+
pre-dispatch clamp, learn-then-replay on the non-streamed path, learn-then-replay on the streamed
41+
path, and no replay for an unrelated 400. tests/responses runs 2040 pass / 0 fail with the change.

‎src/server/responses/core.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,7 @@ import {
291291
} from "../lifecycle";
292292
import { redactSecretString, sanitizeLogMetadataString } from "../../lib/redact";
293293
import { readBoundedResponseBody } from "../../lib/bounded-body";
294+
import { isReasoningEffortRejection, planReasoningEffortDowngrade } from "../../providers/reasoning-metadata";
294295
import {
295296
ENCRYPTED_FUNCTION_OUTPUT_REJECTION,
296297
isRateLimitOrQuotaFailureMessage,
@@ -830,6 +831,28 @@ export function shouldAttemptOpaqueBlobRecovery(args: {
830831
&& isSelfIdentifiedOpaqueBlobRejection(args.errorBody);
831832
}
832833

834+
/**
835+
* Peek the upstream error body for the reasoning-effort downgrade. Only 400/403 are considered
836+
* and the body must be complete and display-safe, the same contract the other rejection peeks
837+
* use. The match is deliberately narrow: the upstream has to name reasoning effort, so an
838+
* unrelated 400 never triggers a replay.
839+
*/
840+
async function reasoningEffortRejectionText(
841+
response: Response,
842+
alreadyAttempted: boolean,
843+
signal: AbortSignal,
844+
): Promise<string | undefined> {
845+
if (alreadyAttempted) return undefined;
846+
if (response.status !== 400 && response.status !== 403) return undefined;
847+
try {
848+
const body = await readBoundedResponseBody(response.clone(), { signal });
849+
if (!body.displaySafe || body.truncated) return undefined;
850+
return isReasoningEffortRejection(body.text) ? body.text : undefined;
851+
} catch {
852+
return undefined;
853+
}
854+
}
855+
833856
async function opaqueBlobRejectionBodyForRecovery(
834857
response: Response,
835858
outboundBody: string | undefined,
@@ -5334,6 +5357,8 @@ async function handleResponsesInner(
53345357
}
53355358

53365359
const opaqueBlobRecoveryGuard: OpaqueBlobRecoveryGuard = { attempted: false };
5360+
// At most one reasoning-effort downgrade per request.
5361+
const reasoningEffortDowngradeGuard: { attempted: boolean } = { attempted: false };
53375362
let oauth401ReplayAttempted = false;
53385363
let codex401ReplayKind: "main" | "stored" | null = null;
53395364
const rateLimitPolicy = rateLimitRetryPolicyFor(route.provider);
@@ -5887,6 +5912,35 @@ async function handleResponsesInner(
58875912
logCtx.terminalIncompleteReason = preflightLog.terminalIncompleteReason;
58885913
}
58895914
}
5915+
// Reasoning-effort downgrade: a rung the catalog still advertises can be refused upstream --
5916+
// the metadata records the model's ladder, not this account's entitlement (a Muse Code
5917+
// subscription gates max on muse-spark-1.3-contributor, for example). Learn the refusal so
5918+
// later turns clamp before dispatch, then replay once at the next lower published rung
5919+
// instead of failing the turn; requestedEffort/effectiveEffort keep both values in usage.
5920+
if (!reasoningEffortDowngradeGuard.attempted) {
5921+
const rejectionText = await reasoningEffortRejectionText(
5922+
upstreamResponse,
5923+
reasoningEffortDowngradeGuard.attempted,
5924+
upstream.signal,
5925+
);
5926+
const downgrade = rejectionText === undefined
5927+
? undefined
5928+
: planReasoningEffortDowngrade({
5929+
provider: route.provider,
5930+
modelId: parsed.modelId,
5931+
requested: parsed.options.reasoning,
5932+
rejectionText,
5933+
});
5934+
if (downgrade) {
5935+
reasoningEffortDowngradeGuard.attempted = true;
5936+
parsed.options.reasoning = downgrade.effort;
5937+
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
5938+
const result = await rebuildAndRefetch("reasoning-effort-downgrade");
5939+
if ("failed" in result) return result.failed;
5940+
upstreamResponse = result;
5941+
continue passthroughRecovery;
5942+
}
5943+
}
58905944
break;
58915945
}
58925946
const headers = sanitizePassthroughHeaders(upstreamResponse.headers);
@@ -7482,6 +7536,8 @@ async function handleResponsesInner(
74827536
};
74837537
// Keep recovery kinds in sync with the native Responses `passthroughRecovery:` loop above.
74847538
recovery: for (;;) {
7539+
// At most one reasoning-effort downgrade per request.
7540+
const reasoningEffortDowngradeGuard: { attempted: boolean } = { attempted: false };
74857541
if (
74867542
upstreamResponse.status === 401
74877543
&& isOAuth401ReplayProvider
@@ -7760,6 +7816,34 @@ async function handleResponsesInner(
77607816
upstreamResponse = result;
77617817
continue recovery;
77627818
}
7819+
// Reasoning-effort downgrade, mirroring the passthroughRecovery loop above: learn the
7820+
// refused rung, then replay once at the next published one.
7821+
if (!reasoningEffortDowngradeGuard.attempted) {
7822+
const rejectionText = await reasoningEffortRejectionText(
7823+
upstreamResponse,
7824+
reasoningEffortDowngradeGuard.attempted,
7825+
upstream.signal,
7826+
);
7827+
const downgrade = rejectionText === undefined
7828+
? undefined
7829+
: planReasoningEffortDowngrade({
7830+
provider: route.provider,
7831+
modelId: parsed.modelId,
7832+
requested: parsed.options.reasoning,
7833+
rejectionText,
7834+
});
7835+
if (downgrade) {
7836+
reasoningEffortDowngradeGuard.attempted = true;
7837+
parsed.options.reasoning = downgrade.effort;
7838+
// The same-target cache keys on parsed identity, so a mutated effort needs a token bump.
7839+
invalidateSameTargetRequest();
7840+
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
7841+
const result = await rebuildAndRefetch("reasoning-effort-downgrade");
7842+
if ("failed" in result) return result.failed;
7843+
upstreamResponse = result;
7844+
continue recovery;
7845+
}
7846+
}
77637847
break;
77647848
}
77657849
if (!upstreamResponse.ok) {

‎src/usage/log.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,8 @@ export type AttemptRecoveryKind =
7171
| "oauth-account-429"
7272
| "image-413"
7373
| "opaque-blob-rejection"
74-
| "empty-completion";
74+
| "empty-completion"
75+
| "reasoning-effort-downgrade";
7576

7677
/** Request-time upstream credential class, never a credential or account identifier. */
7778
export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
@@ -311,6 +312,7 @@ const ATTEMPT_RECOVERY_KINDS = new Set<AttemptRecoveryKind>([
311312
"image-413",
312313
"opaque-blob-rejection",
313314
"empty-completion",
315+
"reasoning-effort-downgrade",
314316
]);
315317
const USAGE_STATUSES = new Set<UsageStatus>([
316318
"reported",
Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
2+
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { handleResponses } from "../../src/server/responses/core";
6+
import { resetReasoningMetadataCachesForTests } from "../../src/providers/reasoning-metadata";
7+
import type { RequestLogContext } from "../../src/server/request-log";
8+
import type { OcxConfig } from "../../src/types";
9+
10+
/**
11+
* Rejected-rung learning on the request path: a rung the catalog advertises can still be refused
12+
* upstream because the ladder describes the model, not this account's entitlement (max on
13+
* muse-spark-1.3-contributor needs an active Muse Code subscription). The pipeline must learn the
14+
* refusal, replay once at the next published rung, and never replay an unrelated 400.
15+
*/
16+
17+
const originalFetch = globalThis.fetch;
18+
const originalOpenCodexHome = process.env.OPENCODEX_HOME;
19+
const MODEL = "muse-spark-1.3-contributor";
20+
const REFUSAL = JSON.stringify({
21+
error: {
22+
param: "reasoning.effort",
23+
type: "invalid_request_error",
24+
message: "Error from provider (Console Go): Upstream request failed: [invalid_request_error] reasoning_effort max requires an active Muse Code subscription for model muse-spark-1.3-contributor.",
25+
},
26+
});
27+
const UNRELATED = JSON.stringify({ error: { type: "invalid_request_error", message: "Invalid upload request." } });
28+
29+
let testDir = "";
30+
31+
function writeSnapshot(values: string[]): void {
32+
writeFileSync(join(testDir, "reasoning-metadata-cache.json"), JSON.stringify({
33+
version: 1,
34+
fetchedAt: Date.now(),
35+
source: "test",
36+
providers: { "opencode-go": { [MODEL]: { reasoning: true, options: [{ type: "effort", values }] } } },
37+
}));
38+
}
39+
40+
function config(): OcxConfig {
41+
return {
42+
defaultProvider: "first",
43+
providers: {
44+
first: {
45+
adapter: "openai-chat",
46+
baseUrl: "https://opencode.ai/zen/go/v1",
47+
authMode: "key",
48+
apiKey: "test-key",
49+
},
50+
},
51+
} as OcxConfig;
52+
}
53+
54+
function request(stream = false): Request {
55+
return new Request("http://localhost/v1/responses", {
56+
method: "POST",
57+
headers: { "content-type": "application/json" },
58+
body: JSON.stringify({
59+
model: "first/" + MODEL,
60+
stream,
61+
store: false,
62+
reasoning: { effort: "max" },
63+
input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "go" }] }],
64+
}),
65+
});
66+
}
67+
68+
function success(): Response {
69+
return Response.json({ id: "resp-ok", object: "response", status: "completed", model: MODEL, output: [] });
70+
}
71+
72+
beforeEach(() => {
73+
testDir = mkdtempSync(join(tmpdir(), "ocx-reasoning-downgrade-"));
74+
process.env.OPENCODEX_HOME = testDir;
75+
resetReasoningMetadataCachesForTests();
76+
});
77+
78+
afterEach(() => {
79+
globalThis.fetch = originalFetch;
80+
resetReasoningMetadataCachesForTests();
81+
if (originalOpenCodexHome === undefined) delete process.env.OPENCODEX_HOME;
82+
else process.env.OPENCODEX_HOME = originalOpenCodexHome;
83+
rmSync(testDir, { recursive: true, force: true });
84+
});
85+
86+
describe("rejected reasoning rungs", () => {
87+
test("clamps a rung the model does not publish before dispatch", async () => {
88+
writeSnapshot(["minimal", "low", "medium", "high", "xhigh"]);
89+
const outbound: Array<Record<string, unknown>> = [];
90+
globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
91+
outbound.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
92+
return success();
93+
}) as typeof fetch;
94+
const logCtx: RequestLogContext = { model: "", provider: "" };
95+
96+
const response = await handleResponses(request(), config(), logCtx);
97+
await response.text();
98+
99+
expect(response.status).toBe(200);
100+
expect(outbound).toHaveLength(1);
101+
expect(outbound[0]?.reasoning_effort).toBe("xhigh");
102+
});
103+
104+
test("learns the refusal and replays once at the next published rung", async () => {
105+
writeSnapshot(["low", "high", "max"]);
106+
const outbound: Array<Record<string, unknown>> = [];
107+
globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
108+
outbound.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
109+
return outbound.length === 1
110+
? new Response(REFUSAL, { status: 400, headers: { "content-type": "application/json" } })
111+
: success();
112+
}) as typeof fetch;
113+
const logCtx: RequestLogContext = { model: "", provider: "" };
114+
115+
const response = await handleResponses(request(), config(), logCtx);
116+
await response.text();
117+
118+
expect(outbound).toHaveLength(2);
119+
expect(outbound[0]?.reasoning_effort).toBe("max");
120+
expect(outbound[1]?.reasoning_effort).toBe("high");
121+
expect(logCtx.activeAttempt?.recoveryKinds).toEqual(["reasoning-effort-downgrade"]);
122+
});
123+
124+
test("does not replay an unrelated 400", async () => {
125+
writeSnapshot(["low", "high", "max"]);
126+
const outbound: Array<Record<string, unknown>> = [];
127+
globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
128+
outbound.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
129+
return new Response(UNRELATED, { status: 400, headers: { "content-type": "application/json" } });
130+
}) as typeof fetch;
131+
const logCtx: RequestLogContext = { model: "", provider: "" };
132+
133+
const response = await handleResponses(request(), config(), logCtx);
134+
await response.text();
135+
136+
expect(outbound).toHaveLength(1);
137+
expect(response.ok).toBe(false);
138+
expect(logCtx.activeAttempt?.recoveryKinds ?? []).toEqual([]);
139+
});
140+
test("replays once on the streamed passthrough path too", async () => {
141+
writeSnapshot(["low", "high", "max"]);
142+
const outbound: Array<Record<string, unknown>> = [];
143+
globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
144+
outbound.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
145+
return outbound.length === 1
146+
? new Response(REFUSAL, { status: 400, headers: { "content-type": "application/json" } })
147+
: success();
148+
}) as typeof fetch;
149+
const logCtx: RequestLogContext = { model: "", provider: "" };
150+
151+
const response = await handleResponses(request(true), config(), logCtx);
152+
await response.text();
153+
154+
expect(outbound).toHaveLength(2);
155+
expect(outbound[1]?.reasoning_effort).toBe("high");
156+
expect(logCtx.activeAttempt?.recoveryKinds).toEqual(["reasoning-effort-downgrade"]);
157+
});
158+
});

0 commit comments

Comments
 (0)