Skip to content

Commit 5d5016b

Browse files
ahamkara-Nhlidge-jun
authored andcommitted
fix(chat): surface thinking traces on Chat Completions
Chat Completions clients such as Grok Build send reasoning_effort but not reasoning.summary. The internal Responses parser hides thinking unless summary is set and is not none, so delta.reasoning_content never reached the client. Default summary to auto when the client asked for effort, honor explicit summary / include_reasoning, and leave requests with no reasoning knobs unchanged.
1 parent 875bb70 commit 5d5016b

4 files changed

Lines changed: 95 additions & 3 deletions

File tree

‎docs-site/src/content/docs/guides/grok-build.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,13 @@ in Codex. Models with an empty tier list keep no effort control, matching Codex
6161
behavior. Native GPT-5.6 entries are separate: they preserve and expose their pinned
6262
upstream reasoning ladders rather than provider-configured routed metadata.
6363

64+
Grok Build talks to opencodex over Chat Completions and sends `reasoning_effort` when
65+
the ladder is advertised. The Chat Completions inbound translator defaults the internal
66+
Responses `reasoning.summary` to `auto` in that case, so thinking traces reach Grok as
67+
`delta.reasoning_content` instead of being hidden. Set `include_reasoning: false` (or
68+
`reasoning.summary: "none"`) if a client wants the model to think without returning the
69+
trace.
70+
6471
## Authentication note
6572

6673
Grok Build requires a non-empty API key for custom models even on loopback. The injected

‎docs-site/src/content/docs/reference/proxy-formats.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,14 @@ non-empty `messages` array. It translates system, user, assistant, and tool mess
155155
Responses items; translates function tools, tool choice, images, reasoning effort, and supported
156156
response formats; runs the normal Responses routing pipeline; then translates the result back.
157157

158+
Reasoning is part of that translation. `reasoning_effort` (or `reasoning.effort`) becomes
159+
internal `reasoning.effort`. Because the Responses parser hides thinking unless
160+
`reasoning.summary` is set and is not `none`, Chat Completions requests that ask for an
161+
effort default to `reasoning.summary: "auto"` so thinking streams back as
162+
`delta.reasoning_content`. Clients can still hide traces with `include_reasoning: false` or
163+
`reasoning.summary: "none"`, and an explicit `reasoning.summary` of `auto`, `concise`,
164+
`detailed`, or `none` is preserved.
165+
158166
Structured output is part of that translation: `response_format` with `json_object` or
159167
`json_schema` is forwarded to routed `openai-chat` models. On `POST /v1/responses` the
160168
equivalent request field is `text.format`: native Responses routes preserve it in the raw

‎src/chat/inbound.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ function isRec(v: unknown): v is Rec {
1414
}
1515

1616
const OUTPUT_CONFIG_EFFORTS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
17+
const OUTPUT_CONFIG_SUMMARIES = new Set(["auto", "concise", "detailed", "none"]);
1718

1819
function contentToText(content: unknown): string {
1920
if (typeof content === "string") return content;
@@ -205,6 +206,22 @@ function resolveReasoningEffort(raw: Rec): string | undefined {
205206
return undefined;
206207
}
207208

209+
/**
210+
* Chat Completions clients (Grok Build, Copilot, OpenAI-compatible SDKs) expect
211+
* `delta.reasoning_content` whenever the model thinks. The internal Responses
212+
* parser hides thinking unless `reasoning.summary` is set and is not `"none"`.
213+
* Map the common Chat Completions knobs onto that field. When the client only
214+
* sent an effort, default the summary to `"auto"` so traces are not swallowed.
215+
*/
216+
function resolveReasoningSummary(raw: Rec): string | undefined {
217+
if (raw.include_reasoning === false) return "none";
218+
if (raw.include_reasoning === true) return "auto";
219+
if (isRec(raw.reasoning) && typeof raw.reasoning.summary === "string" && OUTPUT_CONFIG_SUMMARIES.has(raw.reasoning.summary)) {
220+
return raw.reasoning.summary;
221+
}
222+
return undefined;
223+
}
224+
208225
/**
209226
* Translate an OpenAI Chat Completions request body into a /v1/responses request body.
210227
* Throws ChatCompletionsRequestError (-> 400) on malformed input.
@@ -286,7 +303,13 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
286303
if (raw.metadata !== undefined) body.metadata = raw.metadata;
287304

288305
const effort = resolveReasoningEffort(raw);
289-
if (effort) body.reasoning = { effort };
306+
const summary = resolveReasoningSummary(raw);
307+
if (effort || summary !== undefined) {
308+
body.reasoning = {
309+
...(effort ? { effort } : {}),
310+
summary: summary ?? "auto",
311+
};
312+
}
290313

291314
const text = responseFormatToText(raw.response_format);
292315
if (text) body.text = text;

‎tests/chat-completions-endpoint.test.ts‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { waitForNativeMainStartupGate } from "../src/codex/native-profile-startup";
2-
import { afterEach, beforeEach, expect, test } from "bun:test";
2+
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
33
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
44
import { tmpdir } from "node:os";
55
import { join } from "node:path";
@@ -10,6 +10,7 @@ import type { OcxConfig, OcxProviderConfig } from "../src/types";
1010
import { installIsolatedCodexHome, type IsolatedCodexHome } from "./helpers/isolated-codex-home";
1111
import { chatCompletionsToResponsesBody, ChatCompletionsRequestError } from "../src/chat/inbound";
1212
import { chatCompletionsUsage } from "../src/chat/outbound";
13+
import { parseRequest } from "../src/responses/parser";
1314
import { createTestTranslatorBudget } from "./helpers/translator-budget";
1415
import type { TranslatorBudget } from "../src/lib/translator-budget";
1516
import {
@@ -218,7 +219,7 @@ test("chatCompletionsToResponsesBody maps messages/tools/system", () => {
218219
expect(body.stream).toBe(true);
219220
expect(body.instructions).toBe("be brief");
220221
expect(body.max_output_tokens).toBe(64);
221-
expect(body.reasoning).toEqual({ effort: "high" });
222+
expect(body.reasoning).toEqual({ effort: "high", summary: "auto" });
222223
expect(body.tool_choice).toBe("auto");
223224
expect(Array.isArray(body.tools)).toBe(true);
224225
expect((body.tools as Array<Record<string, unknown>>)[0]).toMatchObject({ type: "function", name: "lookup" });
@@ -228,6 +229,59 @@ test("chatCompletionsToResponsesBody maps messages/tools/system", () => {
228229
expect(input.some(i => i.type === "function_call_output" && i.call_id === "call_1")).toBe(true);
229230
});
230231

232+
describe("chatCompletionsToResponsesBody reasoning summary", () => {
233+
test("defaults summary to auto when the client only sent reasoning_effort", () => {
234+
const body = chatCompletionsToResponsesBody({
235+
model: "opencode-go/deepseek-v4-flash",
236+
messages: [{ role: "user", content: "What is 17*19?" }],
237+
reasoning_effort: "max",
238+
});
239+
expect(body.reasoning).toEqual({ effort: "max", summary: "auto" });
240+
const parsed = parseRequest(body);
241+
expect(parsed.options.hideThinkingSummary).not.toBe(true);
242+
expect(parsed.options.reasoning).toBe("max");
243+
});
244+
245+
test("preserves an explicit reasoning.summary", () => {
246+
const body = chatCompletionsToResponsesBody({
247+
model: "mock/test-model",
248+
messages: [{ role: "user", content: "hi" }],
249+
reasoning: { effort: "high", summary: "concise" },
250+
});
251+
expect(body.reasoning).toEqual({ effort: "high", summary: "concise" });
252+
});
253+
254+
test("include_reasoning false hides thinking even when effort is set", () => {
255+
const body = chatCompletionsToResponsesBody({
256+
model: "mock/test-model",
257+
messages: [{ role: "user", content: "hi" }],
258+
reasoning_effort: "high",
259+
include_reasoning: false,
260+
});
261+
expect(body.reasoning).toEqual({ effort: "high", summary: "none" });
262+
expect(parseRequest(body).options.hideThinkingSummary).toBe(true);
263+
});
264+
265+
test("include_reasoning true requests a visible summary without an effort", () => {
266+
const body = chatCompletionsToResponsesBody({
267+
model: "mock/test-model",
268+
messages: [{ role: "user", content: "hi" }],
269+
include_reasoning: true,
270+
});
271+
expect(body.reasoning).toEqual({ summary: "auto" });
272+
expect(parseRequest(body).options.hideThinkingSummary).not.toBe(true);
273+
});
274+
275+
test("omits reasoning when the client sent no reasoning knobs", () => {
276+
const body = chatCompletionsToResponsesBody({
277+
model: "mock/test-model",
278+
messages: [{ role: "user", content: "hi" }],
279+
});
280+
expect(body.reasoning).toBeUndefined();
281+
expect(parseRequest(body).options.hideThinkingSummary).toBe(true);
282+
});
283+
});
284+
231285
test("chatCompletionsToResponsesBody rejects missing model", () => {
232286
expect(() => chatCompletionsToResponsesBody({ messages: [{ role: "user", content: "x" }] }))
233287
.toThrow(ChatCompletionsRequestError);

0 commit comments

Comments
 (0)