Skip to content

Commit d31950e

Browse files
committed
fix(responses): backfill missing ids on output items for strict decoders
Some relays omit the required id on message, reasoning, and function_call output items, so strict decoders reject the response even after #1941. Synthesize a stable msg_ocx_N / rs_ocx_N / fc_ocx_N id keyed on output_index, and never overwrite an id the upstream actually sent. Carries @bet4it's #2131 implementation and tests. One correction on top: an absent or malformed output_index collapsed to 0, so two such items both became msg_ocx_0 - duplicate ids, which is the defect this backfill exists to prevent. An unusable index now falls back to a monotonic ordinal based far above any plausible real index, so a synthesized id cannot collide with an index-derived one. The well-formed path is unchanged and still produces the stable index-derived id. Locale docs are limited to the English source here; the translated guides in the original PR were uneven and locale parity is not this change's thesis. Closes #2131
1 parent cd8f9b8 commit d31950e

3 files changed

Lines changed: 244 additions & 17 deletions

File tree

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

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ title: Grok Build
33
description: Use any opencodex-routed model from xAI's Grok Build CLI — models are auto-registered into ~/.grok/config.toml while the proxy runs.
44
---
55

6-
opencodex serves an OpenAI-compatible `POST /v1/chat/completions` (and `/v1/responses`) on its
7-
local port, and Grok Build supports custom models against OpenAI-compatible servers. Starting
8-
with this integration, opencodex registers its whole visible catalog into Grok Build
9-
automatically — no manual config editing required.
6+
opencodex serves an OpenAI-compatible `POST /v1/responses` on its local port, and Grok Build
7+
supports custom models against OpenAI-compatible servers. Starting with this integration,
8+
opencodex registers its whole visible catalog into Grok Build automatically — no manual config
9+
editing required.
1010

1111
## Auto-registration
1212

@@ -18,7 +18,7 @@ into `~/.grok/config.toml`:
1818
[model.ocx-gpt-5-6-sol]
1919
model = "gpt-5.6-sol"
2020
base_url = "http://127.0.0.1:10100/v1"
21-
api_backend = "chat_completions"
21+
api_backend = "responses"
2222
api_key = "opencodex-loopback"
2323
name = "OCX gpt-5.6-sol"
2424
# ... one [model.ocx-*] table per visible model ...
@@ -61,12 +61,11 @@ 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. An explicit `reasoning.summary` wins when both knobs are present.
64+
Grok Build talks to opencodex over the Responses API. When the route advertises a reasoning
65+
ladder, the Responses passthrough forwards `reasoning.summary` as configured, so thinking
66+
traces reach Grok natively as Responses reasoning items. Set `reasoning.summary: "none"` if
67+
a client wants the model to think without returning the trace. An explicit `reasoning.summary`
68+
wins over the route default.
7069

7170
## Authentication note
7271

‎src/server/responses/responses-field-backfill.ts‎

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,46 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
2929
return !!value && typeof value === "object" && !Array.isArray(value);
3030
}
3131

32+
/** Wire prefixes for Responses output item ids, matching OpenAI's id shapes. */
33+
const ITEM_ID_PREFIXES: Readonly<Record<string, string>> = {
34+
message: "msg_",
35+
reasoning: "rs_",
36+
function_call: "fc_",
37+
web_search_call: "ws_",
38+
file_search_call: "fs_",
39+
code_interpreter_call: "ci_",
40+
computer_call: "cc_",
41+
image_gen_call: "ig_",
42+
};
43+
44+
/**
45+
* Backfill a required id on an output item when absent. Strict Responses
46+
* decoders (e.g. grok-build serde types) fail with "missing field id" when a
47+
* message or reasoning item has no id, which some upstream relays omit. The
48+
* generated id is deterministic per (type, output index) so it stays stable
49+
* across streaming events that reference the same item.
50+
*/
51+
function backfillItemId(item: Record<string, unknown>, outputIndex: number): Record<string, unknown> {
52+
if (typeof item.id === "string" && item.id.length > 0) return item;
53+
const type = typeof item.type === "string" ? item.type : "";
54+
const prefix = Object.prototype.hasOwnProperty.call(ITEM_ID_PREFIXES, type) ? ITEM_ID_PREFIXES[type] : "item_";
55+
return { ...item, id: prefix + "ocx_" + outputIndex };
56+
}
57+
58+
/**
59+
* Monotonic ordinal for an event whose `output_index` is absent or malformed.
60+
*
61+
* Starts far above any plausible real index so a synthesized id can never collide with an
62+
* index-derived one inside the same response. Process-global rather than per-response because
63+
* this module is stateless by design and the value only has to be unique, not meaningful.
64+
*/
65+
const SYNTHETIC_ITEM_ORDINAL_BASE = 1_000_000;
66+
let syntheticItemOrdinal = 0;
67+
function nextSyntheticItemOrdinal(): number {
68+
syntheticItemOrdinal += 1;
69+
return SYNTHETIC_ITEM_ORDINAL_BASE + syntheticItemOrdinal;
70+
}
71+
3272
/**
3373
* Backfill annotations: [] on an output_text content part if missing.
3474
* Returns the same object reference if no change is needed.
@@ -60,14 +100,16 @@ function backfillContentArray(content: unknown): unknown {
60100

61101
/**
62102
* Walk an output item and backfill output_text parts in its content.
103+
* Also backfills a missing required id on the item itself.
63104
* Returns the same object reference if nothing changed.
64105
*/
65-
function backfillOutputItem(item: unknown): unknown {
106+
function backfillOutputItem(item: unknown, outputIndex: number): unknown {
66107
if (!isPlainObject(item)) return item;
67108
const content = item.content;
68109
const repaired = backfillContentArray(content);
69-
if (repaired === content) return item;
70-
return { ...item, content: repaired };
110+
const withId = backfillItemId(item, outputIndex);
111+
if (repaired === content && withId === item) return item;
112+
return { ...withId, ...(repaired === content ? {} : { content: repaired }) };
71113
}
72114

73115
/**
@@ -79,9 +121,9 @@ function backfillResponseOutput(response: unknown): unknown {
79121
const output = response.output;
80122
if (!Array.isArray(output)) return response;
81123
let changed = false;
82-
const repaired = output.map((item) => {
124+
const repaired = output.map((item, idx) => {
83125
if (!isPlainObject(item)) return item;
84-
const next = backfillOutputItem(item);
126+
const next = backfillOutputItem(item, idx);
85127
if (next !== item) changed = true;
86128
return next;
87129
});
@@ -100,7 +142,15 @@ function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
100142
// output_item.added / output_item.done: item.content[] -> output_text parts
101143
if ((type === "response.output_item.added" || type === "response.output_item.done")
102144
&& isPlainObject(event.item)) {
103-
const item = backfillOutputItem(event.item);
145+
const rawIndex = event.output_index;
146+
// A malformed or absent `output_index` must not collapse to 0: two such events would then
147+
// both synthesize `msg_ocx_0`, and duplicate ids are the very thing this backfill exists to
148+
// prevent. Fall back to a per-process counter so the synthesized id stays unique. Position
149+
// is not recoverable in that case, but a unique id is what strict decoders require, and a
150+
// well-formed stream still gets the stable index-derived id.
151+
const item = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0
152+
? backfillOutputItem(event.item, rawIndex)
153+
: backfillOutputItem(event.item, nextSyntheticItemOrdinal());
104154
if (item !== event.item) {
105155
next = { ...next, item };
106156
changed = true;

‎tests/responses-field-backfill.test.ts‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,4 +170,182 @@ describe("responses-field-backfill", () => {
170170
expect(result.output[0].content[3].annotations).toBe("not-an-array");
171171
expect(result.output[0].content[4].annotations).toEqual({ unexpected: true });
172172
});
173+
174+
test("backfills missing ids on response.completed output items", () => {
175+
const event = {
176+
type: "response.completed",
177+
sequence_number: 42,
178+
response: {
179+
id: "resp_1",
180+
object: "response",
181+
status: "completed",
182+
output: [
183+
{ type: "reasoning", summary: [{ type: "summary_text", text: "thinking" }] },
184+
{
185+
type: "message",
186+
role: "assistant",
187+
status: "completed",
188+
content: [{ type: "output_text", text: "hello" }],
189+
},
190+
{
191+
type: "function_call",
192+
call_id: "call_1",
193+
name: "todo_write",
194+
arguments: "{}",
195+
},
196+
],
197+
},
198+
};
199+
const [out] = apply(sseBlock(event));
200+
const parsed = parseData([out])[0];
201+
expect(parsed.response.output[0].id).toBe("rs_ocx_0");
202+
expect(parsed.response.output[1].id).toBe("msg_ocx_1");
203+
expect(parsed.response.output[2].id).toBe("fc_ocx_2");
204+
});
205+
206+
test("preserves existing item ids", () => {
207+
const event = {
208+
type: "response.completed",
209+
sequence_number: 42,
210+
response: {
211+
id: "resp_1",
212+
object: "response",
213+
status: "completed",
214+
output: [
215+
{ type: "message", id: "msg_real", role: "assistant", content: [{ type: "output_text", text: "hi" }] },
216+
],
217+
},
218+
};
219+
const [out] = apply(sseBlock(event));
220+
const parsed = parseData([out])[0];
221+
expect(parsed.response.output[0].id).toBe("msg_real");
222+
});
223+
224+
test("uses output_index when backfilling output_item.done id", () => {
225+
const event = {
226+
type: "response.output_item.done",
227+
output_index: 3,
228+
item: {
229+
type: "message",
230+
role: "assistant",
231+
status: "completed",
232+
content: [{ type: "output_text", text: "hi" }],
233+
},
234+
};
235+
const [out] = apply(sseBlock(event));
236+
const parsed = parseData([out])[0];
237+
expect(parsed.item.id).toBe("msg_ocx_3");
238+
});
239+
240+
test("falls back to item_ prefix for inherited type names", () => {
241+
const event = {
242+
type: "response.output_item.done",
243+
output_index: 0,
244+
item: {
245+
type: "toString",
246+
role: "assistant",
247+
status: "completed",
248+
content: [{ type: "output_text", text: "hi" }],
249+
},
250+
};
251+
const [out] = apply(sseBlock(event));
252+
const parsed = parseData([out])[0];
253+
expect(parsed.item.id).toBe("item_ocx_0");
254+
});
255+
256+
test("an invalid output_index still yields a well-formed synthesized id", () => {
257+
for (const badIndex of [-1, 1.5, NaN, Infinity, "0", null, undefined]) {
258+
const event = {
259+
type: "response.output_item.done",
260+
output_index: badIndex,
261+
item: {
262+
type: "message",
263+
role: "assistant",
264+
status: "completed",
265+
content: [{ type: "output_text", text: "hi" }],
266+
},
267+
};
268+
const [out] = apply(sseBlock(event));
269+
const parsed = parseData([out])[0];
270+
expect(parsed.item.id).toMatch(/^msg_ocx_\d+$/);
271+
}
272+
});
273+
274+
test("two items with an unusable output_index do not collide on one id", () => {
275+
// Collapsing an unusable index to 0 would synthesize `msg_ocx_0` twice, which is the
276+
// duplicate-id defect this backfill exists to prevent. Position is unrecoverable here;
277+
// uniqueness is not optional.
278+
const event = (text: string) => ({
279+
type: "response.output_item.done",
280+
item: {
281+
type: "message",
282+
role: "assistant",
283+
status: "completed",
284+
content: [{ type: "output_text", text }],
285+
},
286+
});
287+
const first = parseData(apply(sseBlock(event("one"))))[0];
288+
const second = parseData(apply(sseBlock(event("two"))))[0];
289+
290+
expect(first.item.id).toMatch(/^msg_ocx_\d+$/);
291+
expect(second.item.id).toMatch(/^msg_ocx_\d+$/);
292+
expect(first.item.id).not.toBe(second.item.id);
293+
});
294+
295+
test("a well-formed output_index still produces the stable index-derived id", () => {
296+
const event = {
297+
type: "response.output_item.done",
298+
output_index: 3,
299+
item: {
300+
type: "message",
301+
role: "assistant",
302+
status: "completed",
303+
content: [{ type: "output_text", text: "hi" }],
304+
},
305+
};
306+
// Stability across events referencing the same item is the whole point of index-derivation,
307+
// so the fallback must not leak into the well-formed path.
308+
expect(parseData(apply(sseBlock(event)))[0].item.id).toBe("msg_ocx_3");
309+
expect(parseData(apply(sseBlock(event)))[0].item.id).toBe("msg_ocx_3");
310+
});
311+
312+
test("backfillResponsesFieldsJson backfills missing ids on output items", () => {
313+
const response = {
314+
id: "resp_1",
315+
object: "response",
316+
status: "completed",
317+
output: [
318+
{ type: "reasoning", summary: [{ type: "summary_text", text: "thinking" }] },
319+
{
320+
type: "message",
321+
role: "assistant",
322+
status: "completed",
323+
content: [{ type: "output_text", text: "hello" }],
324+
},
325+
{
326+
type: "function_call",
327+
call_id: "call_1",
328+
name: "todo_write",
329+
arguments: "{}",
330+
},
331+
],
332+
};
333+
const result = JSON.parse(backfillResponsesFieldsJson(JSON.stringify(response))) as typeof response;
334+
expect(result.output[0].id).toBe("rs_ocx_0");
335+
expect(result.output[1].id).toBe("msg_ocx_1");
336+
expect(result.output[2].id).toBe("fc_ocx_2");
337+
});
338+
339+
test("backfillResponsesFieldsJson preserves existing item ids", () => {
340+
const response = {
341+
id: "resp_1",
342+
object: "response",
343+
status: "completed",
344+
output: [
345+
{ type: "message", id: "msg_real", role: "assistant", content: [{ type: "output_text", text: "hi" }] },
346+
],
347+
};
348+
const result = JSON.parse(backfillResponsesFieldsJson(JSON.stringify(response))) as typeof response;
349+
expect(result.output[0].id).toBe("msg_real");
350+
});
173351
});

0 commit comments

Comments
 (0)