Skip to content

Commit 6613bde

Browse files
committed
feat(catalog): per-model preserveExactReasoningRungs to stop synthetic max/ultra rungs (#1870)
1 parent eca18d0 commit 6613bde

8 files changed

Lines changed: 171 additions & 3 deletions

File tree

‎docs-site/src/content/docs/reference/configuration/providers.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,8 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
9696
| `refreshPolicy?` | `"proactive" \| "lazy-only" \| "disabled"` | Override this OAuth provider's Token Guardian policy. |
9797
| `reasoningEfforts?` | `string[]` | Provider-wide Codex reasoning labels to advertise and send. For `google`-adapter providers, a configured ladder also asserts `thinkingLevel` capability: direct and Vertex non-image requests send the selected effort as `generationConfig.thinkingConfig.thinkingLevel`, while Cloud Code Assist uses its envelope-specific path. |
9898
| `modelReasoningEfforts?` | `Record<string, string[]>` | Per-model labels. An empty list hides effort control. As with `reasoningEfforts`, each configured `google`-adapter ladder asserts `thinkingLevel` capability; direct and Vertex non-image requests use the flat Gemini path, while Cloud Code Assist sends it under its request envelope. |
99+
| `preserveExactReasoningRungs?` | `boolean` | Suppress the synthetic `max`/`ultra` rungs that opencodex normally appends to every reasoning-capable routed model. When `true`, the catalog advertises exactly the configured `reasoningEfforts` / `modelReasoningEfforts` ladder so the Codex picker reflects a model's real capability. This only changes catalog metadata and picker display — routed request handling and adapter wire behavior are unchanged, and unsupported requested efforts are still clamped. Removing `max` can hard-fail subagent `spawn_agent` effort overrides, which codex-rs validates against catalog membership — enable only for models that genuinely lack the top rungs. |
100+
| `modelPreserveExactReasoningRungs?` | `Record<string, boolean>` | Per-model override for `preserveExactReasoningRungs`. |
99101
| `modelSupportsReasoningSummaries?` | `Record<string, boolean>` | Set a model to `false` to stop advertising summaries and strip summary-delivery fields. |
100102
| `modelReasoningSummaryDelivery?` | `Record<string, "sequential" \| "sequential_cutoff" \| "concurrent" \| "concurrent_cutoff">` | Per-model Responses delivery enum; rewrites an existing delivery field. |
101103
| `modelAdapters?` | `Record<string, string>` | Per-model `openai-chat` or `openai-responses` wire override for mixed-wire gateways. Explicit entries beat registry defaults. The OpenCode Go preset selects Responses for `gpt-5.6-luna` while leaving sibling models on their documented wires; DeepSeek can select native Responses for `deepseek-v4-flash`; and GitHub Copilot declares Responses-only defaults for its GPT-5 family (`gpt-5.3-codex`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`) because those models reject `/chat/completions` for agent traffic. Models without a built-in default (for example `gpt-5.4-nano`) can be opted in here. Single-wire upstream pins and canonical ChatGPT forward reject overrides. |

‎src/codex/catalog/parsing.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,11 @@ export interface CatalogModel {
109109
owned_by?: string;
110110
reasoningEfforts?: string[];
111111
defaultReasoningEffort?: string;
112+
/**
113+
* Suppress the synthetic `max`/`ultra` top rungs so the catalog advertises exactly
114+
* `reasoningEfforts` (mirrors `OcxProviderConfig.preserveExactReasoningRungs`).
115+
*/
116+
preserveExactReasoningRungs?: boolean;
112117
contextWindow?: number;
113118
maxInputTokens?: number;
114119
contextCap?: number;

‎src/codex/catalog/provider-fetch.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -646,9 +646,15 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
646646
}
647647
const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
648648
const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
649+
const preserveExactReasoningRungs = modelRecordValue(prov.modelPreserveExactReasoningRungs, model.id)
650+
?? prov.preserveExactReasoningRungs;
649651
const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
650652
const supportsServiceTier = serviceTierSupportForModel(prov, model.id, name);
651-
const { supportsServiceTier: _staleServiceTier, ...modelWithoutServiceTier } = model;
653+
const {
654+
supportsServiceTier: _staleServiceTier,
655+
preserveExactReasoningRungs: _stalePreserveExactReasoningRungs,
656+
...modelWithoutServiceTier
657+
} = model;
652658
// 已发现窗口只允许被配置值压低;缺窗口时,已开的 Context cap 就是实际窗口。
653659
const discoveredWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
654660
? model.contextWindow
@@ -669,6 +675,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
669675
}
670676
: {}),
671677
...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
678+
...(preserveExactReasoningRungs === true ? { preserveExactReasoningRungs: true } : {}),
672679
...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
673680
...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
674681
...(prov.adapter === "kiro" ? { supportsVerbosity: false } : {}),

‎src/codex/catalog/sync.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,9 @@ export function deriveEntry(
285285
const codexForwardNativeCapabilityAlias = model?.codexForwardNativeCapabilityAlias === true
286286
? upstreamNativeEntry(model.id)
287287
: null;
288+
const preserveExactReasoningRungs = preserveExact
289+
|| codexForwardNativeCapabilityAlias !== null
290+
|| model?.preserveExactReasoningRungs === true;
288291
const isRouted = model !== undefined;
289292
if (!isRouted && !slug.includes("/")) {
290293
// Supported native slug covered by the upstream snapshot: use the REAL entry (exact
@@ -326,7 +329,7 @@ export function deriveEntry(
326329
e,
327330
model?.reasoningEfforts,
328331
model?.defaultReasoningEffort,
329-
preserveExact || codexForwardNativeCapabilityAlias !== null,
332+
preserveExactReasoningRungs,
330333
);
331334
// This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
332335
// native tool/search/responses-lite contract while preserving the routed slug and wire id.
@@ -376,7 +379,7 @@ export function deriveEntry(
376379
};
377380
if (isRouted) {
378381
applyRoutedCodexToolMode(entry, model?.codexToolMode);
379-
applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
382+
applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExactReasoningRungs);
380383
}
381384
else {
382385
applyReasoningLevels(entry, isGpt56NativeSlug(slug) ? undefined : ["low", "medium", "high", "xhigh"]);

‎src/config.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,6 +714,8 @@ const providerConfigSchema = z.object({
714714
fastWire: fastWireSchema.nullable().optional(),
715715
supportsServiceTier: z.boolean().optional(),
716716
modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
717+
preserveExactReasoningRungs: z.boolean().optional(),
718+
modelPreserveExactReasoningRungs: z.record(z.string().min(1), z.boolean()).optional(),
717719
preserveResponsesReasoningContent: z.boolean().optional(),
718720
allowPrivateNetwork: z.boolean().optional(),
719721
// The management API accepts `null` as "clear this", so a config written before the POST
@@ -1513,6 +1515,25 @@ const configSchema = z.object({
15131515
message: serviceTierModelsError,
15141516
});
15151517
}
1518+
const preserveExactReasoningRungsError = booleanRecordConfigError(
1519+
(provider as { modelPreserveExactReasoningRungs?: unknown }).modelPreserveExactReasoningRungs,
1520+
"modelPreserveExactReasoningRungs",
1521+
);
1522+
if (preserveExactReasoningRungsError) {
1523+
ctx.addIssue({
1524+
code: "custom",
1525+
path: ["providers", redactSecretString(name), "modelPreserveExactReasoningRungs"],
1526+
message: preserveExactReasoningRungsError,
1527+
});
1528+
}
1529+
if ((provider as { preserveExactReasoningRungs?: unknown }).preserveExactReasoningRungs !== undefined
1530+
&& typeof (provider as { preserveExactReasoningRungs?: unknown }).preserveExactReasoningRungs !== "boolean") {
1531+
ctx.addIssue({
1532+
code: "custom",
1533+
path: ["providers", redactSecretString(name), "preserveExactReasoningRungs"],
1534+
message: "preserveExactReasoningRungs must be a boolean",
1535+
});
1536+
}
15161537
const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
15171538
(provider as { modelReasoningSummaryDelivery?: unknown }).modelReasoningSummaryDelivery,
15181539
(provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,

‎src/providers/model-rename-migration.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ const MODEL_KEYED_RECORDS = [
8888
"modelReasoningEfforts",
8989
"modelDefaultReasoningEfforts",
9090
"modelReasoningEffortMap",
91+
"modelPreserveExactReasoningRungs",
9192
] as const;
9293

9394
/** Provider fields that are flat lists of model ids. */

‎src/types/provider.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -324,6 +324,19 @@ export interface OcxProviderConfig {
324324
reasoningEfforts?: string[];
325325
/** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
326326
modelReasoningEfforts?: Record<string, string[]>;
327+
/**
328+
* Suppress the synthetic `max`/`ultra` reasoning rungs that `applyReasoningLevels`
329+
* appends to every reasoning-capable routed model. When true, the catalog advertises
330+
* exactly the configured `reasoningEfforts` / `modelReasoningEfforts` ladder instead of
331+
* padding the top rungs, so the Codex picker reflects the model's real capability.
332+
*
333+
* Tradeoff: subagent `spawn_agent` sends `max` directly and codex-rs validates it
334+
* against catalog membership, so removing `max` can hard-fail that path for the affected
335+
* models. Enable only for models that cannot actually serve the synthetic top rungs.
336+
*/
337+
preserveExactReasoningRungs?: boolean;
338+
/** Per-model override for `preserveExactReasoningRungs`. */
339+
modelPreserveExactReasoningRungs?: Record<string, boolean>;
327340
/** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
328341
modelDefaultReasoningEfforts?: Record<string, string>;
329342
/**
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
import { describe, expect, test } from "bun:test";
2+
import { applyProviderConfigHints, buildCatalogEntries } from "../src/codex/catalog";
3+
import type { OcxProviderConfig } from "../src/types";
4+
5+
function nativeTemplate(): Record<string, unknown> {
6+
return {
7+
slug: "gpt-5.5",
8+
display_name: "gpt-5.5",
9+
description: "Native GPT model",
10+
priority: 1,
11+
visibility: "list",
12+
base_instructions: "You are Codex, a coding agent based on GPT-5.",
13+
supported_reasoning_levels: [
14+
{ effort: "low", description: "native low" },
15+
{ effort: "medium", description: "native medium" },
16+
{ effort: "high", description: "native high" },
17+
{ effort: "xhigh", description: "native xhigh" },
18+
],
19+
};
20+
}
21+
22+
function provider(overrides: Partial<OcxProviderConfig> = {}): OcxProviderConfig {
23+
return {
24+
adapter: "openai-chat",
25+
baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
26+
apiKey: "sk-test",
27+
modelReasoningEfforts: { "qwen3.8-max": ["low", "medium", "xhigh"] },
28+
...overrides,
29+
};
30+
}
31+
32+
function advertisedLevels(entry: Record<string, unknown> | undefined): string[] {
33+
const rows = (entry?.supported_reasoning_levels ?? []) as { effort?: string }[];
34+
return rows.map(level => level.effort).filter((effort): effort is string => typeof effort === "string");
35+
}
36+
37+
function hintedQwen(prov: OcxProviderConfig): Record<string, unknown> {
38+
const hinted = applyProviderConfigHints(
39+
"alibaba-token-plan-intl",
40+
prov,
41+
{ id: "qwen3.8-max", provider: "alibaba-token-plan-intl" },
42+
);
43+
const entries = buildCatalogEntries(nativeTemplate(), [], [hinted]);
44+
return entries.find(e => e.slug === "alibaba-token-plan-intl/qwen3.8-max") ?? {};
45+
}
46+
47+
describe("#1870 preserveExactReasoningRungs", () => {
48+
test("provider-wide flag suppresses synthetic max/ultra rungs", () => {
49+
const entry = hintedQwen(provider({ preserveExactReasoningRungs: true }));
50+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh"]);
51+
});
52+
53+
test("per-model flag scopes suppression to the named model", () => {
54+
const entry = hintedQwen(provider({
55+
modelPreserveExactReasoningRungs: { "qwen3.8-max": true },
56+
}));
57+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh"]);
58+
});
59+
60+
test("synthetic max/ultra rungs remain advertised by default", () => {
61+
const entry = hintedQwen(provider());
62+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh", "max", "ultra"]);
63+
});
64+
65+
test("per-model false overrides a provider-wide true", () => {
66+
const entry = hintedQwen(provider({
67+
preserveExactReasoningRungs: true,
68+
modelPreserveExactReasoningRungs: { "qwen3.8-max": false },
69+
}));
70+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh", "max", "ultra"]);
71+
});
72+
73+
test("re-hinting a cached model clears a stale exact-rung flag", () => {
74+
const flagged = applyProviderConfigHints(
75+
"alibaba-token-plan-intl",
76+
provider({ preserveExactReasoningRungs: true }),
77+
{ id: "qwen3.8-max", provider: "alibaba-token-plan-intl" },
78+
);
79+
expect(flagged.preserveExactReasoningRungs).toBe(true);
80+
81+
// A cached model produced by an earlier hint pass still carries the flag;
82+
// re-hinting with a config that resolves to false must clear it.
83+
const cleared = applyProviderConfigHints(
84+
"alibaba-token-plan-intl",
85+
provider(),
86+
flagged,
87+
);
88+
expect(cleared.preserveExactReasoningRungs).toBeUndefined();
89+
const entries = buildCatalogEntries(nativeTemplate(), [], [cleared]);
90+
const entry = entries.find(e => e.slug === "alibaba-token-plan-intl/qwen3.8-max");
91+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh", "max", "ultra"]);
92+
});
93+
94+
test("empty or none reasoning ladders never grow synthetic rungs regardless of flag", () => {
95+
const entryEmpty = hintedQwen(provider({
96+
modelReasoningEfforts: { "qwen3.8-max": [] },
97+
preserveExactReasoningRungs: false,
98+
}));
99+
expect(advertisedLevels(entryEmpty)).toEqual([]);
100+
101+
const entryNone = hintedQwen(provider({
102+
modelReasoningEfforts: { "qwen3.8-max": ["none"] },
103+
preserveExactReasoningRungs: false,
104+
}));
105+
expect(advertisedLevels(entryNone)).toEqual(["none"]);
106+
});
107+
108+
test("exact-rung flag preserves custom default reasoning effort within the ladder", () => {
109+
const entry = hintedQwen(provider({
110+
preserveExactReasoningRungs: true,
111+
modelDefaultReasoningEfforts: { "qwen3.8-max": "xhigh" },
112+
}));
113+
expect(advertisedLevels(entry)).toEqual(["low", "medium", "xhigh"]);
114+
expect(entry.default_reasoning_level).toBe("xhigh");
115+
});
116+
});

0 commit comments

Comments
 (0)