Merge pull request #416 from code-yeongyu/fix/415-codex-reasoning-summary-payload-test

fix(ai): omit the Codex reasoning summary so compaction stops 400ing

Author: code-yeongyu

packages/ai/src/api/openai-codex-responses.ts

@@ -49,6 +49,7 @@ import { resolveHttpProxyUrlForTarget } from "../utils/node-http-proxy.ts";
 import { extractOpenAiCodexAccountId } from "../utils/openai-codex-auth.ts";
 import { uuidv7 } from "../utils/uuid.ts";
 import { createGrammarToolInputProperties } from "./constrained-sampling.ts";
+import { buildCodexReasoning, type CodexReasoningSummaryInput } from "./openai-codex-responses/reasoning.ts";
 import { clampOpenAIPromptCacheKey } from "./openai-prompt-cache.ts";
 import { convertResponsesMessages, convertResponsesTools, processResponsesStream } from "./openai-responses-shared.ts";
 import {
@@ -91,7 +92,7 @@ const CODEX_RESPONSE_STATUSES = new Set<CodexResponseStatus>([
 
 export interface OpenAICodexResponsesOptions extends StreamOptions {
 	reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-	reasoningSummary?: "auto" | "concise" | "detailed" | "off" | "on" | null;
+	reasoningSummary?: CodexReasoningSummaryInput;
 	serviceTier?: ResponseCreateParamsStreaming["service_tier"];
 	textVerbosity?: "low" | "medium" | "high";
 	toolChoice?: "auto" | "none" | "required";
@@ -110,7 +111,7 @@ interface RequestBody {
 	tool_choice?: OpenAICodexResponsesOptions["toolChoice"];
 	parallel_tool_calls?: boolean;
 	temperature?: number;
-	reasoning?: { effort?: string; summary?: string };
+	reasoning?: ReturnType<typeof buildCodexReasoning>;
 	service_tier?: ResponseCreateParamsStreaming["service_tier"];
 	text?: { verbosity?: string };
 	include?: string[];
@@ -595,17 +596,13 @@ function buildRequestBody(
 		});
 	}
 
-	if (reasoningEffort !== undefined && reasoningEffort !== null) {
-		body.reasoning = {
-			effort: reasoningEffort,
-			summary: options?.reasoningSummary === null ? "off" : (options?.reasoningSummary ?? "auto"),
-		};
-	} else if (reasoningEffort === undefined && model.reasoning && model.thinkingLevelMap?.off !== null) {
-		body.reasoning = {
-			effort: model.thinkingLevelMap?.off ?? "none",
-			summary: options?.reasoningSummary === null ? "off" : (options?.reasoningSummary ?? "auto"),
-		};
-	}
+	const reasoning = buildCodexReasoning(
+		reasoningEffort,
+		options?.reasoningSummary,
+		model.reasoning,
+		model.thinkingLevelMap?.off,
+	);
+	if (reasoning) body.reasoning = reasoning;
 
 	applyExtraBody(body, options?.extraBody, OPENAI_RESPONSES_RESERVED_BODY_KEYS);
 

packages/ai/src/api/openai-codex-responses/reasoning.ts

@@ -0,0 +1,51 @@
+export type CodexReasoningSummary = "auto" | "concise" | "detailed";
+export interface CodexReasoning {
+	effort?: string;
+	summary?: CodexReasoningSummary;
+}
+
+/** @deprecated Pass `null` to omit reasoning summaries. */
+type LegacyCodexReasoningSummaryOff = "off";
+
+/** @deprecated Pass `"auto"` to request the default reasoning summary. */
+type LegacyCodexReasoningSummaryOn = "on";
+
+export type CodexReasoningSummaryInput =
+	| CodexReasoningSummary
+	| LegacyCodexReasoningSummaryOff
+	| LegacyCodexReasoningSummaryOn
+	| null;
+
+export function normalizeCodexReasoningSummary(
+	reasoningSummary: CodexReasoningSummaryInput | undefined,
+): CodexReasoningSummary | undefined {
+	switch (reasoningSummary) {
+		case null:
+		case "off":
+			return undefined;
+		case undefined:
+		case "on":
+			return "auto";
+		default:
+			return reasoningSummary;
+	}
+}
+
+export function buildCodexReasoning(
+	reasoningEffort: string | null | undefined,
+	reasoningSummary: CodexReasoningSummaryInput | undefined,
+	modelSupportsReasoning: boolean,
+	thinkingOff: string | null | undefined,
+): CodexReasoning | undefined {
+	let effort: string;
+	if (reasoningEffort !== undefined && reasoningEffort !== null) {
+		effort = reasoningEffort;
+	} else if (reasoningEffort === undefined && modelSupportsReasoning && thinkingOff !== null) {
+		effort = thinkingOff ?? "none";
+	} else {
+		return undefined;
+	}
+
+	const summary = normalizeCodexReasoningSummary(reasoningSummary);
+	return { effort, ...(summary === undefined ? {} : { summary }) };
+}

packages/ai/src/changes.md

@@ -1,5 +1,33 @@
 # AI Source Changes
 
+## 2026-07-27 - Codex reasoning summary null omits the field instead of sending "off"
+
+### What changed and why
+
+- `api/openai-codex-responses.ts` `buildRequestBody()` and the internal
+  `api/openai-codex-responses/reasoning.ts` normalizer: `reasoningSummary: null` now omits the `summary`
+  field from `body.reasoning` instead of sending the literal string `"off"`. The Codex backend's
+  `ReasoningSummaryParam` accepts only `concise`, `detailed`, and `auto`, so every request carrying
+  `reasoningSummary: null` failed with a 400 `invalid_enum_value`. The coding-agent builtin compaction
+  (`summarizationReasoningOptions()`) passes exactly that value to keep summarization turns cheap, which
+  made compaction unusable on Codex models. The adapter now also preserves the shipped legacy union while
+  normalizing `"off"` to omission and `"on"` to `"auto"`. These semantics match the sibling adapters and
+  the official OpenAI Codex CLI reference client, whose `ReasoningSummary::None` is encoded as an absent
+  `summary` field for both ordinary and compaction requests. Current upstream pi-mono instead maps null to
+  `"auto"`, so this fork intentionally follows the official Codex wire contract rather than claiming
+  upstream parity.
+- An extension cannot fix this: the invalid value is produced inside the wire adapter's request builder,
+  below every extension hook.
+- `../test/openai-responses-thinking-matrix.test.ts`: pins both `buildRequestBody()` branches — explicit
+  `reasoningEffort` and the thinking-off fallback — across null, legacy `"off"` / `"on"`, and `"auto"`.
+
+### Expected merge conflict zones
+
+- LOW: `api/openai-codex-responses.ts` `buildRequestBody()` reasoning block and the internal
+  `api/openai-codex-responses/reasoning.ts` normalizer. Upstream writes
+  `summary: options.reasoningSummary ?? "auto"` without the null branch; a clean upstream touch of these
+  two object literals should resolve by keeping the null-omit spread.
+
 ## 2026-07-27 - Retry Cloudflare 522 connection timeouts
 
 ### What changed and why

packages/ai/test/openai-responses-thinking-matrix.test.ts

@@ -80,6 +80,49 @@ describe("OpenAI Responses thinking matrix", () => {
 		expect(payload).toMatchObject({ reasoning: { effort: "none", summary: "auto" } });
 	});
 
+	it.each([
+		["null", null, undefined],
+		["off", "off", undefined],
+		["on", "on", "auto"],
+		["auto", "auto", "auto"],
+	] as const)("normalizes Codex %s summary on the explicit-effort path", async (_, reasoningSummary, expectedSummary) => {
+		const payload = await capturePayload((onPayload) =>
+			streamOpenAICodexResponses(getModel("openai-codex", "gpt-5.6-sol"), context, {
+				apiKey: "test-key",
+				transport: "sse",
+				reasoningEffort: "low",
+				reasoningSummary,
+				onPayload,
+			}),
+		);
+
+		expect(payload.reasoning).toEqual({
+			effort: "low",
+			...(expectedSummary ? { summary: expectedSummary } : {}),
+		});
+	});
+
+	it.each([
+		["null", null, undefined],
+		["off", "off", undefined],
+		["on", "on", "auto"],
+		["auto", "auto", "auto"],
+	] as const)("normalizes Codex %s summary on the thinking-off fallback", async (_, reasoningSummary, expectedSummary) => {
+		const payload = await capturePayload((onPayload) =>
+			streamOpenAICodexResponses(getModel("openai-codex", "gpt-5.6-sol"), context, {
+				apiKey: "test-key",
+				transport: "sse",
+				reasoningSummary,
+				onPayload,
+			}),
+		);
+
+		expect(payload.reasoning).toEqual({
+			effort: "none",
+			...(expectedSummary ? { summary: expectedSummary } : {}),
+		});
+	});
+
 	it("omits Codex reasoning when the catalog says thinking cannot be disabled", async () => {
 		const model = {
 			...getModel("openai-codex", "gpt-5.6-sol"),

packages/coding-agent/test/compaction/summarization-reasoning-payload.test.ts

@@ -93,13 +93,11 @@ const payloadCases = [
 		name: "OpenAI Responses",
 		model: { ...getModel("openai", "gpt-5.4"), baseUrl: "http://127.0.0.1:9" },
 		effort: "low",
-		summary: undefined,
 	},
 	{
 		name: "Codex Responses",
 		model: { ...getModel("openai-codex", "gpt-5.4"), baseUrl: "http://127.0.0.1:9" },
 		effort: "low",
-		summary: "off",
 	},
 	{
 		name: "Azure Responses",
@@ -108,19 +106,18 @@ const payloadCases = [
 			baseUrl: "https://test-resource.openai.azure.com/openai/v1",
 		},
 		effort: "low",
-		summary: undefined,
 	},
 ] as const;
 
 describe("compaction summarization provider payloads", () => {
-	it.each(payloadCases)("uses the cheapest legal effort without a summary for $name", async ({
-		model,
-		effort,
-		summary,
-	}) => {
+	// Every Responses-family adapter must omit `reasoning.summary` when compaction
+	// asks for no summary. The Codex backend rejects a string sentinel such as
+	// "off" with `[ReasoningSummaryParam] [invalid_enum_value]`, which aborted
+	// compaction outright (issue #415).
+	it.each(payloadCases)("uses the cheapest legal effort without a summary for $name", async ({ model, effort }) => {
 		const payload = await captureSummaryPayload(model);
 		expect(payload.reasoning?.effort).toBe(effort);
-		expect(payload.reasoning?.summary).toBe(summary);
+		expect(payload.reasoning).not.toHaveProperty("summary");
 	});
 
 	it("uses low reasoning for Kimi when its catalog rejects minimal", async () => {