Skip to content

Commit fbda693

Browse files
committed
feat(models): add none/minimal as declared reasoning efforts; fix review findings
- none and minimal are valid declared reasoning_effort values: accepted and canonicalized by the API and CLI, kept by catalog sanitize, never implicit defaults, and excluded from the mock max/ultra repair for sentinel-only ladders - pi export maps the off level to none when declared; minimal maps to itself - GUI dialog offers the full real-effort set: none, minimal, low, medium, high, xhigh, max (ultra stays a catalog-only label) - CodeRabbit: inherited default gap-fill guarded by effectiveLadder membership, native-alias explicit-override ordering, CLI usage errors, single JSON parse per response, pi.md adapter-dependent reasoning semantics - CLI regression suite: parseReasoningArgs, edit '-'->null, config persistence, list-custom output
1 parent 74a1a7b commit fbda693

13 files changed

Lines changed: 378 additions & 41 deletions

File tree

‎docs-site/src/content/docs/guides/pi.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,13 @@ on. The export also emits a `thinkingLevelMap` that hides every pi level outside
115115
ladder (`null`), so pi never offers — and never sends — an effort the ladder does not contain.
116116
If you need a different mapping, hand-edit `thinkingLevelMap` afterwards as documented by Pi.
117117

118+
Treat `reasoning` as Pi-UI metadata: it is derived from the catalog ladder, not proof that the
119+
upstream natively supports a reasoning parameter. What the proxy actually sends for a given
120+
`reasoning_effort` value depends on the provider's adapter and model — it may pass the value
121+
through, translate it (wire aliases), clamp it to the configured ladder, emulate it, or omit it
122+
entirely (e.g. `noReasoningModels`). The boolean only controls whether Pi offers the control at
123+
all.
124+
118125
## Schema status
119126

120127
:::note[Unverified against a real install]

‎gui/src/pages/models-shared.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,14 @@ export interface ModelRow {
4242
reasoningEfforts?: string[];
4343
}
4444

45-
/** Codex ladder labels offered in the custom-model dialog. */
46-
export const REASONING_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max", "ultra"] as const;
45+
/**
46+
* Reasoning-effort labels offered in the custom-model dialog. The full set of real
47+
* `reasoning_effort` values (none, minimal, low, medium, high, xhigh, max). Deliberately
48+
* excludes `ultra`: that is a Codex catalog label for the multi-agent collab surface, not a
49+
* real `reasoning_effort` value — codex-rs converts it to `max` before any provider
50+
* request, and the catalog writer appends it to every non-empty ladder anyway.
51+
*/
52+
export const REASONING_EFFORT_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
4753

4854
export interface ProviderContextCapsResponse {
4955
cap?: number;

‎src/cli/models-runtime.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,17 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
7373
// "-" restores inheritance by clearing the stored ladder (null). An explicit empty
7474
// ladder ("no reasoning") has no CLI shorthand — use the dashboard for that state.
7575
if (reasoningEffortsRaw !== undefined) {
76-
patch.reasoningEfforts = reasoningEffortsRaw === "-" ? null : csv(reasoningEffortsRaw);
76+
if (reasoningEffortsRaw === "-") {
77+
patch.reasoningEfforts = null;
78+
} else {
79+
const values = csv(reasoningEffortsRaw);
80+
// csv() silently drops empty members; a value that normalizes to an empty list would
81+
// otherwise store an explicit "no reasoning" ladder the user never asked for.
82+
if (!values || values.length === 0) {
83+
throw new CliUsageError("--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (or \"-\" to inherit)", USAGE);
84+
}
85+
patch.reasoningEfforts = values;
86+
}
7787
}
7888
if (defaultEffortRaw !== undefined) patch.defaultReasoningEffort = defaultEffortRaw === "-" ? null : defaultEffortRaw;
7989
if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);

‎src/cli/models.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
55
import { createInterface } from "node:readline/promises";
66
import { syncModelsToCodex } from "../codex/sync";
77
import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
8-
import { canonicalizeReasoningEfforts, isCodexReasoningEffort } from "../reasoning-effort";
8+
import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../reasoning-effort";
99
import { routedSlug } from "../providers/slug-codec";
1010
import { findLiveProxy } from "../server/proxy-liveness";
1111
import type { OcxConfig, OcxCustomModel } from "../types";
@@ -34,11 +34,11 @@ export function parseReasoningArgs(
3434
} else {
3535
const parts = trimmed.split(",").map(value => value.trim());
3636
if (parts.length === 0 || parts.some(part => part === "")) {
37-
return { error: "--reasoning-efforts must be comma-separated values from low, medium, high, xhigh, max, ultra (or \"-\" to inherit)" };
37+
return { error: "--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (or \"-\" to inherit)" };
3838
}
39-
const invalid = parts.filter(value => !isCodexReasoningEffort(value));
39+
const invalid = parts.filter(value => !isDeclaredReasoningEffort(value));
4040
if (invalid.length > 0) {
41-
return { error: `unsupported reasoning effort: ${invalid.join(", ")} (allowed: low, medium, high, xhigh, max, ultra)` };
41+
return { error: `unsupported reasoning effort: ${invalid.join(", ")} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
4242
}
4343
reasoningEfforts = canonicalizeReasoningEfforts(parts);
4444
}
@@ -49,8 +49,8 @@ export function parseReasoningArgs(
4949
if (trimmed === "-") {
5050
defaultReasoningEffort = undefined;
5151
} else {
52-
if (!isCodexReasoningEffort(trimmed)) {
53-
return { error: `unsupported reasoning effort: ${trimmed} (allowed: low, medium, high, xhigh, max, ultra)` };
52+
if (!isDeclaredReasoningEffort(trimmed)) {
53+
return { error: `unsupported reasoning effort: ${trimmed} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
5454
}
5555
if (!reasoningEfforts || reasoningEfforts.length === 0) {
5656
return { error: "--default-reasoning-effort requires --reasoning-efforts" };

‎src/clients/config-export.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -883,6 +883,9 @@ function buildPiClientConfig(ctx: ExportContext): PiGeneratedConfig {
883883
entry.reasoning = true;
884884
const efforts = model.reasoningEfforts;
885885
entry.thinkingLevelMap = {
886+
// pi's off level maps to the declared `none` sentinel (the proxy omits the
887+
// reasoning parameter for it); hidden when the ladder does not declare none.
888+
off: efforts.includes("none") ? "none" : null,
886889
minimal: efforts.includes("minimal") ? "minimal" : null,
887890
low: efforts.includes("low") ? "low" : null,
888891
medium: efforts.includes("medium") ? "medium" : null,

‎src/codex/catalog/effort.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -153,8 +153,9 @@ export function applyReasoningLevels(
153153
// (no ultra->max client conversion) and codex-rs validates it by catalog membership,
154154
// so a missing max rung hard-fails spawn_agent effort overrides. The wire stays honest:
155155
// routed adapters clamp via clampToSupportedCodexEffort and natives via
156-
// nativeEffortClamp (max -> the model's real top rung).
157-
if (!preserveExact && efforts.length > 0) {
156+
// nativeEffortClamp (max -> the model's real top rung). A `none`-only ladder is NOT
157+
// reasoning-capable, so it must not grow synthetic top rungs.
158+
if (!preserveExact && efforts.length > 0 && efforts.some(effort => effort !== "none" && effort !== "minimal")) {
158159
const additions: string[] = [];
159160
if (!efforts.includes("max")) additions.push("max");
160161
if (!efforts.includes("ultra")) additions.push("ultra");
@@ -177,7 +178,9 @@ export function applyReasoningLevels(
177178
}
178179
entry.default_reasoning_level = defaultOverride && efforts.includes(defaultOverride)
179180
? defaultOverride
180-
: efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high" : efforts[0];
181+
: efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
182+
// Sentinels never become the implicit default when real rungs are declared.
183+
: efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
181184
}
182185

183186
export function isGpt56NativeSlug(slug: string): boolean {

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

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1774,20 +1774,27 @@ async function gatherRoutedModelsUncached(
17741774
...(cm.inputModalities
17751775
? { inputModalities: cm.inputModalities }
17761776
: codexForwardNativeCapabilityAlias ? { inputModalities: nativeInputModalities(cm.modelId) } : {}),
1777-
// Explicit custom-row ladder wins over the inherited provider row below: the merge only
1778-
// gap-fills, so a stored `[]` (explicit "no reasoning") or a declared ladder is kept
1779-
// verbatim instead of being replaced by the replaced row's metadata.
1780-
...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
1781-
...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
17821777
...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
1778+
// Native-alias defaults apply only where the custom row declares nothing: the explicit
1779+
// spreads below must win (later in object order), so a stored `[]` stays empty and a
1780+
// declared ladder is never replaced by the alias's native ladder.
17831781
...(codexForwardNativeCapabilityAlias
17841782
? {
17851783
codexForwardNativeCapabilityAlias: true,
1786-
reasoningEfforts: nativeReasoningEfforts(cm.modelId),
17871784
parallelToolCalls: nativeParallelToolCalls(cm.modelId),
1788-
...(nativeAliasDefaultEffort ? { defaultReasoningEffort: nativeAliasDefaultEffort } : {}),
1785+
...(Array.isArray(cm.reasoningEfforts)
1786+
? {}
1787+
: {
1788+
reasoningEfforts: nativeReasoningEfforts(cm.modelId),
1789+
...(nativeAliasDefaultEffort ? { defaultReasoningEffort: nativeAliasDefaultEffort } : {}),
1790+
}),
17891791
}
17901792
: {}),
1793+
// Explicit custom-row ladder wins over the inherited provider row below: the merge only
1794+
// gap-fills, so a stored `[]` (explicit "no reasoning") or a declared ladder is kept
1795+
// verbatim instead of being replaced by the replaced row's metadata.
1796+
...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
1797+
...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
17911798
};
17921799
// #962: the dedupe below drops the provider-derived row this custom row replaces. Inherit that
17931800
// row's provider capability metadata (reasoning ladder, default effort, parallel tool calls,
@@ -1796,13 +1803,19 @@ async function gatherRoutedModelsUncached(
17961803
// noReasoningModels model loses its empty ladder and the catalog synthesizes the generic one,
17971804
// which Codex then rejects for spawn_agent with effort "none".
17981805
const replaced = replacedByRoutedSlug.get(routedSlug(cm.provider, cm.modelId));
1806+
// The final ladder is what the catalog will advertise; the inherited default only rides
1807+
// along when it is actually a member — otherwise a provider default like "xhigh" would
1808+
// re-apply onto a narrower custom ladder and override the fallback in applyReasoningLevels.
1809+
const effectiveLadder = base.reasoningEfforts ?? replaced?.reasoningEfforts;
17991810
const merged: CatalogModel = replaced ? {
18001811
...base,
18011812
...(base.contextWindow === undefined && replaced.contextWindow !== undefined ? { contextWindow: replaced.contextWindow } : {}),
18021813
...(base.maxInputTokens === undefined && replaced.maxInputTokens !== undefined ? { maxInputTokens: replaced.maxInputTokens } : {}),
18031814
...(base.inputModalities === undefined && replaced.inputModalities !== undefined ? { inputModalities: replaced.inputModalities } : {}),
18041815
...(base.reasoningEfforts === undefined && replaced.reasoningEfforts !== undefined ? { reasoningEfforts: replaced.reasoningEfforts } : {}),
1805-
...(base.defaultReasoningEffort === undefined && replaced.defaultReasoningEffort !== undefined ? { defaultReasoningEffort: replaced.defaultReasoningEffort } : {}),
1816+
...(base.defaultReasoningEffort === undefined && replaced.defaultReasoningEffort !== undefined
1817+
&& Array.isArray(effectiveLadder) && effectiveLadder.includes(replaced.defaultReasoningEffort)
1818+
? { defaultReasoningEffort: replaced.defaultReasoningEffort } : {}),
18061819
...(base.parallelToolCalls === undefined && replaced.parallelToolCalls !== undefined ? { parallelToolCalls: replaced.parallelToolCalls } : {}),
18071820
...(base.supportsVerbosity === undefined && replaced.supportsVerbosity !== undefined ? { supportsVerbosity: replaced.supportsVerbosity } : {}),
18081821
...(base.supportsReasoningSummaries === undefined && replaced.supportsReasoningSummaries !== undefined ? { supportsReasoningSummaries: replaced.supportsReasoningSummaries } : {}),

‎src/reasoning-effort.ts‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,27 @@ export function isCodexReasoningEffort(effort: string): boolean {
2020
}
2121

2222
/**
23-
* Reorder any subset of the Codex ladder into canonical low..ultra order and drop
24-
* duplicates. Catalog `supported_reasoning_levels` follow the input order and the
25-
* fallback default picks the first entry, so non-canonical input ("high,low") would
26-
* otherwise leak a caller-chosen order into the catalog.
23+
* True for ladder members plus the `none`/`minimal` sentinels. Both are valid declared
24+
* efforts (OpenAI accepts `minimal`; Codex validates `none` against
25+
* `supported_reasoning_levels` for no-reasoning subagent spawns, #883/#962) but are NOT
26+
* part of the low..ultra ladder: they never appear in default ladders, ranks, or clamps
27+
* (`minimal` is mapped to `low` on the wire by requestToCodexEffort).
28+
*/
29+
export function isDeclaredReasoningEffort(effort: string): boolean {
30+
return effort === "none" || effort === "minimal" || CODEX_REASONING_SET.has(effort);
31+
}
32+
33+
/**
34+
* Reorder any declared subset (low..ultra, plus the optional `none`/`minimal` sentinels
35+
* first, in that order) into canonical order and drop duplicates. Catalog
36+
* `supported_reasoning_levels` follow the input order and the fallback default picks the
37+
* first entry, so a caller-chosen order would otherwise leak into the catalog.
2738
*/
2839
export function canonicalizeReasoningEfforts(values: readonly string[]): string[] {
2940
const seen = new Set(values);
30-
return CODEX_REASONING_ORDER.filter(effort => seen.has(effort));
41+
const ordered = CODEX_REASONING_ORDER.filter(effort => seen.has(effort));
42+
const sentinels = ["none", "minimal"].filter(effort => seen.has(effort));
43+
return [...sentinels, ...ordered];
3144
}
3245

3346
/**
@@ -77,7 +90,9 @@ export function sanitizeCodexReasoningEfforts(efforts: readonly string[] | undef
7790
const seen = new Set<string>();
7891
const out: string[] = [];
7992
for (const effort of efforts) {
80-
if (!CODEX_REASONING_SET.has(effort) || seen.has(effort)) continue;
93+
// `none`/`minimal` are valid declared sentinels, kept and sorted first (rank -1); they
94+
// never appear in the default ladder.
95+
if ((effort !== "none" && effort !== "minimal" && !CODEX_REASONING_SET.has(effort)) || seen.has(effort)) continue;
8196
seen.add(effort);
8297
out.push(effort);
8398
}

‎src/server/management/model-routes.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,11 @@ function readReasoningEfforts(raw: unknown): { values?: string[]; error?: string
4343
const values: string[] = [];
4444
for (const value of raw) {
4545
if (typeof value !== "string") return { error: "reasoningEfforts must contain only strings" };
46-
if (!isCodexReasoningEffort(value)) { rejected.push(value); continue; }
46+
if (!isDeclaredReasoningEffort(value)) { rejected.push(value); continue; }
4747
if (!values.includes(value)) values.push(value);
4848
}
4949
if (rejected.length > 0) {
50-
return { error: `unsupported reasoning effort: ${rejected.join(", ")} (allowed: low, medium, high, xhigh, max, ultra)` };
50+
return { error: `unsupported reasoning effort: ${rejected.join(", ")} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
5151
}
5252
// Canonical order: the catalog writes supported_reasoning_levels in input order and the
5353
// fallback default picks the first entry, so a caller-chosen order must not leak through.
@@ -58,8 +58,8 @@ function readReasoningEfforts(raw: unknown): { values?: string[]; error?: string
5858
function readDefaultReasoningEffort(raw: unknown, efforts: string[] | undefined): { value?: string; error?: string } {
5959
if (raw === undefined) return {};
6060
if (raw === null) return { value: undefined };
61-
if (typeof raw !== "string" || !isCodexReasoningEffort(raw)) {
62-
return { error: "defaultReasoningEffort must be one of: low, medium, high, xhigh, max, ultra" };
61+
if (typeof raw !== "string" || !isDeclaredReasoningEffort(raw)) {
62+
return { error: "defaultReasoningEffort must be one of: none, minimal, low, medium, high, xhigh, max, ultra" };
6363
}
6464
if (efforts === undefined || efforts.length === 0) {
6565
return { error: "defaultReasoningEffort requires a non-empty reasoningEfforts ladder" };
@@ -111,7 +111,7 @@ import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summa
111111
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
112112
import { getProviderRegistryEntry } from "../../providers/registry";
113113
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
114-
import { canonicalizeReasoningEfforts, isCodexReasoningEffort } from "../../reasoning-effort";
114+
import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../../reasoning-effort";
115115
import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
116116
import {
117117
clearDebugSettings,

‎tests/catalog-input-modality-enum.test.ts‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,21 @@ describe("custom-model API validates reasoning-effort ladders", () => {
263263
expect(persistCalls).toBe(1);
264264
});
265265

266+
test("POST accepts the none/minimal sentinels, canonicalized first", async () => {
267+
persistCalls = 0;
268+
const res = await callCustomModels("POST", {
269+
provider: "deepseek",
270+
modelId: "deepseek-v6",
271+
reasoningEfforts: ["max", "none", "low", "minimal"],
272+
defaultReasoningEffort: "none",
273+
});
274+
expect(res?.status).toBe(201);
275+
const payload = await res!.json() as { reasoningEfforts?: string[]; defaultReasoningEffort?: string };
276+
expect(payload.reasoningEfforts).toEqual(["none", "minimal", "low", "max"]);
277+
expect(payload.defaultReasoningEffort).toBe("none");
278+
expect(persistCalls).toBe(1);
279+
});
280+
266281
test("POST refuses a default effort outside the declared ladder", async () => {
267282
persistCalls = 0;
268283
const res = await callCustomModels("POST", {
@@ -326,12 +341,13 @@ describe("custom-model API validates reasoning-effort ladders", () => {
326341
// the generated catalog (GUI toggle-off path sends only reasoningEfforts).
327342
test("PUT ladder shrink drops a stored default that is no longer a member", async () => {
328343
persistCalls = 0;
329-
const seeded = await callCustomModels("PUT", {
344+
const seededRes = await callCustomModels("PUT", {
330345
reasoningEfforts: ["low", "high", "max"],
331346
defaultReasoningEffort: "max",
332347
}, "/api/custom-models/existing-uuid");
333-
expect(seeded?.status).toBe(200);
334-
expect((await seeded!.json() as { defaultReasoningEffort?: string }).defaultReasoningEffort).toBe("max");
348+
expect(seededRes?.status).toBe(200);
349+
const seeded = await seededRes!.json() as { defaultReasoningEffort?: string };
350+
expect(seeded.defaultReasoningEffort).toBe("max");
335351

336352
persistCalls = 0;
337353
const res = await callCustomModels("PUT", { reasoningEfforts: ["low"] }, "/api/custom-models/existing-uuid");
@@ -344,11 +360,11 @@ describe("custom-model API validates reasoning-effort ladders", () => {
344360

345361
test("PUT null-clear drops a stored default even when the body does not mention it", async () => {
346362
persistCalls = 0;
347-
const seeded = await callCustomModels("PUT", {
363+
const seededRes = await callCustomModels("PUT", {
348364
reasoningEfforts: ["low", "high"],
349365
defaultReasoningEffort: "high",
350366
}, "/api/custom-models/existing-uuid");
351-
expect(seeded?.status).toBe(200);
367+
expect(seededRes?.status).toBe(200);
352368

353369
persistCalls = 0;
354370
const res = await callCustomModels("PUT", { reasoningEfforts: null }, "/api/custom-models/existing-uuid");
@@ -361,11 +377,11 @@ describe("custom-model API validates reasoning-effort ladders", () => {
361377

362378
test("PUT explicit empty ladder also drops a stored default", async () => {
363379
persistCalls = 0;
364-
const seeded = await callCustomModels("PUT", {
380+
const seededRes = await callCustomModels("PUT", {
365381
reasoningEfforts: ["low", "high"],
366382
defaultReasoningEffort: "high",
367383
}, "/api/custom-models/existing-uuid");
368-
expect(seeded?.status).toBe(200);
384+
expect(seededRes?.status).toBe(200);
369385

370386
persistCalls = 0;
371387
const res = await callCustomModels("PUT", { reasoningEfforts: [] }, "/api/custom-models/existing-uuid");

0 commit comments

Comments
 (0)