Skip to content

Commit e6739e5

Browse files
committed
fix(google): validate candidate, content and part containers
#1332 made a malformed nested candidate terminal on the streaming path, on the rule that a claimed response is not padding. Three containers in the same adapter never got that rule, and each fails a different way. `content.parts` is read straight into a `for...of` in both parsers, so a container that is not an array of objects escapes as a raw `TypeError` — `{} is not iterable`, or `null is not an object` on `part.thoughtSignature`. The buffered `parseResponse` call site in `src/server/responses/core.ts` wraps the call in try/finally with no catch, so the exception leaves the turn unstructured. A `parts: "txt"` is worse than a crash: a string is iterable, so it is consumed character by character and the turn completes empty. `candidate.content` was never inspected at all. `content?.parts` reads `undefined` from any non-record, so a candidate shaped `content: [{ parts: [...] }]` — a plausible shape from anything that mirrors the request's repeated `contents` — dropped its own text and reported success. The buffered parser also never checked `candidates[0]`. `[null]`, `[5]` and `["x"]` all reached a bare `done`, reporting a claimed-but-malformed candidate to the caller as a successful empty turn — the opposite of what the same adapter does when streaming. A non-array `candidates` was not checked either: `"abc"` passed the emptiness check because its `length` is 3, and `{}`/`5` were reported as an absent candidate list rather than a malformed one. All three now terminate through the existing adapter error channel, carrying the structural reason, the part index and the offending value's type — never its contents. Absence stays legal, including the encodings of it that are not records: an absent, `null` or empty `parts`; an absent, `null` or empty-array `content` (`[]` is how a JSON writer with no distinct empty-object form spells an empty object, and it already means "no parts"); and an absent, `null` or empty `candidates`.
1 parent 03735ec commit e6739e5

3 files changed

Lines changed: 266 additions & 9 deletions

File tree

‎docs-site/src/content/docs/reference/adapters.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,12 @@ of the HTTP retry loop.
116116
opaque `thoughtSignature` values so tool-result continuations retain Gemini reasoning continuity.
117117
The signature cache is snapshotted to the config directory, so continuations also survive proxy
118118
restarts.
119+
- **Malformed response shapes fail closed.** A claimed candidate, its `content`, or its
120+
`content.parts` that is not the documented container terminates the turn with a
121+
`google response contained invalid …` error naming the structural reason and the offending
122+
value's type — never its contents. Absence is not corruption: an absent, `null` or empty
123+
`candidates`, `content` or `parts` still completes the turn normally, and a root `data: null`
124+
keepalive frame is still skipped as padding.
119125
- **Inline image output:** when the model is one of the explicit image-capable chat IDs
120126
(`gemini-3.1-flash-image`, `gemini-2.0-flash-preview-image-generation`, or
121127
`gemini-3-pro-image-preview`), the adapter sends `responseModalities: ["TEXT", "IMAGE"]`.

‎src/adapters/google.ts‎

Lines changed: 110 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,67 @@ function googlePartTextEvent(part: GoogleResponsePart): AdapterEvent | undefined
372372
: { type: "text_delta", text: part.text };
373373
}
374374

375+
interface InvalidGoogleShapeDiagnostic {
376+
reason: "content_not_object" | "parts_not_array" | "part_not_object";
377+
partIndex?: number;
378+
valueType: string;
379+
}
380+
381+
function isGoogleRecord(value: unknown): value is Record<string, unknown> {
382+
return value !== null && typeof value === "object" && !Array.isArray(value);
383+
}
384+
385+
function googleStructuralValueType(value: unknown): string {
386+
if (value === null) return "null";
387+
return Array.isArray(value) ? "array" : typeof value;
388+
}
389+
390+
/**
391+
* A candidate's `content` is claimed model output inside a well-formed frame, so it is governed by
392+
* the #1332 nested-shape rule (fail closed) rather than #1240's root-frame padding rule (skip).
393+
*
394+
* Absence stays legal, and so does one encoding of it: an empty array is how a JSON writer with no
395+
* distinct empty-object form spells an empty `content`, and it already behaves as "no parts". A
396+
* NON-empty array is the opposite case — `content?.parts` silently reads `undefined` from it, so a
397+
* candidate shaped `content: [{ parts: [...] }]` dropped its own text and completed as an empty
398+
* turn.
399+
*/
400+
function diagnoseGoogleContent(content: unknown): InvalidGoogleShapeDiagnostic | undefined {
401+
if (content === undefined || content === null || isGoogleRecord(content)) return undefined;
402+
if (Array.isArray(content) && content.length === 0) return undefined;
403+
return { reason: "content_not_object", valueType: googleStructuralValueType(content) };
404+
}
405+
406+
/**
407+
* `content.parts` sits one rung below the candidate guard added in #1332, and both parsers
408+
* consumed it unchecked: `for (const part of {})` throws `{} is not iterable`, and a `[null]`
409+
* element throws on `part.thoughtSignature`. A `parts` that is absent or `null` keeps its existing
410+
* skip — only a present, non-null container is validated.
411+
*/
412+
function diagnoseGoogleParts(parts: unknown): InvalidGoogleShapeDiagnostic | undefined {
413+
if (!Array.isArray(parts)) {
414+
return { reason: "parts_not_array", valueType: googleStructuralValueType(parts) };
415+
}
416+
for (let partIndex = 0; partIndex < parts.length; partIndex++) {
417+
const part: unknown = parts[partIndex];
418+
if (!isGoogleRecord(part)) {
419+
return { reason: "part_not_object", partIndex, valueType: googleStructuralValueType(part) };
420+
}
421+
}
422+
return undefined;
423+
}
424+
425+
function invalidGoogleShapeEvent(
426+
diagnostic: InvalidGoogleShapeDiagnostic,
427+
): Extract<AdapterEvent, { type: "error" }> {
428+
const at = diagnostic.partIndex !== undefined ? `; partIndex=${diagnostic.partIndex}` : "";
429+
const subject = diagnostic.reason === "content_not_object" ? "content" : "content parts";
430+
return {
431+
type: "error",
432+
message: `google response contained invalid ${subject} (${diagnostic.reason}${at}; valueType=${diagnostic.valueType})`,
433+
};
434+
}
435+
375436
export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapter {
376437
// Per-request closure: resolveAdapter builds a fresh adapter per request (server.ts), so buildRequest
377438
// can stash the CCA model/session for parseStream's reasoning-replay observation.
@@ -684,7 +745,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
684745
return "terminate";
685746
}
686747
const candidate = rawCandidate as {
687-
content?: { parts?: unknown[] };
748+
content?: unknown;
688749
finishReason?: string;
689750
};
690751

@@ -693,7 +754,24 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
693754
sawTerminalSignal = true;
694755
}
695756

696-
const parts = candidate.content?.parts as GoogleResponsePart[] | undefined;
757+
// One rung below the candidate guard above, same rule: this is claimed content, not
758+
// padding, so it fails closed rather than being iterated or silently dropped (#1325).
759+
const rawContent: unknown = candidate.content;
760+
const invalidContent = diagnoseGoogleContent(rawContent);
761+
if (invalidContent) {
762+
yield invalidGoogleShapeEvent(invalidContent);
763+
return "terminate";
764+
}
765+
const rawParts: unknown = isGoogleRecord(rawContent) ? rawContent.parts : undefined;
766+
let parts: GoogleResponsePart[] | undefined;
767+
if (rawParts !== undefined && rawParts !== null) {
768+
const invalidParts = diagnoseGoogleParts(rawParts);
769+
if (invalidParts) {
770+
yield invalidGoogleShapeEvent(invalidParts);
771+
return "terminate";
772+
}
773+
parts = rawParts as GoogleResponsePart[];
774+
}
697775
// Record Gemini thought signatures for the next stateless tool-result turn. Vertex and
698776
// Antigravity use separate model namespaces so opaque provider state cannot cross routes.
699777
const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
@@ -924,23 +1002,46 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
9241002
}
9251003
const events: AdapterEvent[] = [];
9261004

927-
const candidates = json.candidates as { content?: { parts?: GoogleResponsePart[] }; finishReason?: string }[] | undefined;
1005+
const rawCandidates: unknown = json.candidates;
1006+
// Parity with the streaming path, which has rejected a non-array `candidates` since #1332.
1007+
// Buffered accepted `"abc"` outright (`"abc".length` is 3, so the emptiness check below
1008+
// passed and `candidates[0]` was the character `"a"`), and reported `{}`/`5` as an absent
1009+
// candidate list rather than a malformed one.
1010+
if (rawCandidates !== undefined && rawCandidates !== null && !Array.isArray(rawCandidates)) {
1011+
return finish([{ type: "error", message: "google response contained invalid candidates" }]);
1012+
}
1013+
const candidates = rawCandidates as { finishReason?: string }[] | undefined;
9281014
if (!candidates?.length) {
9291015
return finish([{ type: "error", message: "google response contained no candidates" }]);
9301016
}
1017+
const rawCandidate: unknown = candidates[0];
1018+
if (rawCandidate === null || typeof rawCandidate !== "object" || Array.isArray(rawCandidate)) {
1019+
// The streaming parser already treats this as terminal protocol corruption (#1325/#1332).
1020+
// Buffered returned a bare `done`, so a claimed-but-malformed candidate was reported to
1021+
// the caller as a successful empty turn.
1022+
return finish([{ type: "error", message: "google response contained invalid candidates" }]);
1023+
}
1024+
const candidate = rawCandidate as { content?: unknown; finishReason?: string };
9311025
let toolCallsStarted = 0;
9321026
const imageBudget = createImageBudget();
933-
if (candidates?.[0]?.content?.parts) {
1027+
const rawContent: unknown = candidate.content;
1028+
const invalidContent = diagnoseGoogleContent(rawContent);
1029+
if (invalidContent) return finish([invalidGoogleShapeEvent(invalidContent)]);
1030+
const rawParts: unknown = isGoogleRecord(rawContent) ? rawContent.parts : undefined;
1031+
if (rawParts !== undefined && rawParts !== null) {
1032+
const invalidParts = diagnoseGoogleParts(rawParts);
1033+
if (invalidParts) return finish([invalidGoogleShapeEvent(invalidParts)]);
1034+
const parts = rawParts as GoogleResponsePart[];
9341035
// Non-streaming Google-family response: observe thought signatures for the next turn,
9351036
// using the same transport-scoped namespace as the streaming path.
9361037
const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
9371038
const replaySession = provider.googleMode === "cloud-code-assist" ? antigravitySession : vertexReplaySession;
9381039
if ((provider.googleMode === "cloud-code-assist" || provider.googleMode === "vertex")
9391040
&& replayModel && replaySession) {
940-
observeAntigravityReplay(replayModel, replaySession, candidates[0].content.parts as unknown[]);
1041+
observeAntigravityReplay(replayModel, replaySession, parts as unknown[]);
9411042
}
9421043
let pendingThoughtSig: string | undefined;
943-
for (const part of candidates[0].content.parts) {
1044+
for (const part of parts) {
9441045
const sig = part.thoughtSignature ?? part.thought_signature;
9451046
if (part.thought === true && sig && isLikelyRealThoughtSignature(sig)) {
9461047
pendingThoughtSig = sig;
@@ -979,16 +1080,16 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
9791080
// Fail-closed truncation, same as the stream path: a non-stream turn cut off mid tool call
9801081
// (MAX_TOKENS / MALFORMED_FUNCTION_CALL) surfaces an error instead of a silent done.
9811082
if ((provider.googleMode === "vertex" || provider.googleMode === "cloud-code-assist")
982-
&& isVertexTruncatedTurn(candidates?.[0]?.finishReason, toolCallsStarted)) {
983-
return finish([{ type: "error", message: vertexTruncationErrorMessage(candidates?.[0]?.finishReason) }]);
1083+
&& isVertexTruncatedTurn(candidate.finishReason, toolCallsStarted)) {
1084+
return finish([{ type: "error", message: vertexTruncationErrorMessage(candidate.finishReason) }]);
9841085
}
9851086

9861087
const usage = json.usageMetadata as Record<string, number> | undefined;
9871088
// Mirror the streaming path: a buffered turn cut off by the token limit or a content filter
9881089
// must carry its stop reason, or the bridge sees a clean `done` and reports the truncated
9891090
// turn as completed — and, on a compaction turn, installs the half-written summary as
9901091
// replacement history (#422).
991-
const finishReason = candidates?.[0]?.finishReason as string | undefined;
1092+
const finishReason = candidate.finishReason as string | undefined;
9921093
const stopReason = finishReason === "MAX_TOKENS"
9931094
? "max_tokens"
9941095
: ["SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII"].includes(finishReason ?? "")

‎tests/google-hardening.test.ts‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,156 @@ describe("google provider hardening", () => {
127127
expect(events.some(event => event.type === "done")).toBe(false);
128128
});
129129

130+
// `content.parts` sits one rung below the candidate guard above. It is claimed model output
131+
// inside a well-formed frame, so it follows the same fail-closed rule rather than #1240's
132+
// root-frame padding rule. Before this, each of these escaped as a raw TypeError.
133+
const invalidPartsCases: [string, unknown, string][] = [
134+
["an object container", {}, "google response contained invalid content parts (parts_not_array; valueType=object)"],
135+
["a number container", 5, "google response contained invalid content parts (parts_not_array; valueType=number)"],
136+
["a string container", "txt", "google response contained invalid content parts (parts_not_array; valueType=string)"],
137+
["a null element", [null], "google response contained invalid content parts (part_not_object; partIndex=0; valueType=null)"],
138+
["a number element", [5], "google response contained invalid content parts (part_not_object; partIndex=0; valueType=number)"],
139+
["an array element", [[]], "google response contained invalid content parts (part_not_object; partIndex=0; valueType=array)"],
140+
["a bad element after a good one", [{ text: "hi" }, null], "google response contained invalid content parts (part_not_object; partIndex=1; valueType=null)"],
141+
];
142+
143+
for (const [label, parts, message] of invalidPartsCases) {
144+
test(`${label} in content.parts is a terminal stream error`, async () => {
145+
const events = await collect(createGoogleAdapter(provider()).parseStream(
146+
sseResponse([
147+
{ candidates: [{ content: { parts } }] },
148+
{ candidates: [{ finishReason: "STOP" }] },
149+
]),
150+
));
151+
152+
expect(events).toEqual([{ type: "error", message }]);
153+
expect(events.some(event => event.type === "done")).toBe(false);
154+
});
155+
156+
test(`${label} in content.parts is a terminal non-streaming error`, async () => {
157+
const events = await createGoogleAdapter(provider()).parseResponse!(
158+
new Response(JSON.stringify({ candidates: [{ content: { parts }, finishReason: "STOP" }] }), { status: 200 }),
159+
);
160+
161+
expect(events).toEqual([{ type: "error", message }]);
162+
expect(events.some(event => event.type === "done")).toBe(false);
163+
});
164+
}
165+
166+
// `content` itself has the same status as `parts`: claimed output the parser cannot read. The
167+
// one tolerated non-record form is an empty array, which is how a JSON writer with no distinct
168+
// empty-object form spells an empty `content`. A NON-empty array is where the payload used to
169+
// disappear: `content?.parts` reads `undefined` from it, so the candidate completed empty.
170+
const invalidContentCases: [string, unknown, string][] = [
171+
["a number", 5, "google response contained invalid content (content_not_object; valueType=number)"],
172+
["a string", "txt", "google response contained invalid content (content_not_object; valueType=string)"],
173+
["a boolean", true, "google response contained invalid content (content_not_object; valueType=boolean)"],
174+
["a non-empty array holding the payload", [{ parts: [{ text: "lost" }] }], "google response contained invalid content (content_not_object; valueType=array)"],
175+
];
176+
177+
for (const [label, content, message] of invalidContentCases) {
178+
test(`${label} as candidate content is a terminal stream error`, async () => {
179+
const events = await collect(createGoogleAdapter(provider()).parseStream(
180+
sseResponse([
181+
{ candidates: [{ content }] },
182+
{ candidates: [{ finishReason: "STOP" }] },
183+
]),
184+
));
185+
186+
expect(events).toEqual([{ type: "error", message }]);
187+
expect(events.some(event => event.type === "done")).toBe(false);
188+
});
189+
190+
test(`${label} as candidate content is a terminal non-streaming error`, async () => {
191+
const events = await createGoogleAdapter(provider()).parseResponse!(
192+
new Response(JSON.stringify({ candidates: [{ content, finishReason: "STOP" }] }), { status: 200 }),
193+
);
194+
195+
expect(events).toEqual([{ type: "error", message }]);
196+
expect(events.some(event => event.type === "done")).toBe(false);
197+
});
198+
}
199+
200+
test("a malformed nested candidate is a terminal non-streaming error too", async () => {
201+
// The streaming parser has rejected these since #1332; the buffered parser returned a bare
202+
// `done`, reporting a claimed-but-malformed candidate to the caller as a successful empty turn.
203+
for (const candidates of [[null], [5], ["x"], [[]]]) {
204+
const events = await createGoogleAdapter(provider()).parseResponse!(
205+
new Response(JSON.stringify({ candidates }), { status: 200 }),
206+
);
207+
208+
expect(events).toEqual([{ type: "error", message: "google response contained invalid candidates" }]);
209+
}
210+
});
211+
212+
test("a non-array candidates container is rejected rather than counted", async () => {
213+
// `"abc".length` is 3, so the emptiness check passed and `candidates[0]` was the character
214+
// `"a"`; `{}` and `5` were reported as an absent candidate list rather than a malformed one.
215+
for (const candidates of ["abc", {}, 5, true]) {
216+
const events = await createGoogleAdapter(provider()).parseResponse!(
217+
new Response(JSON.stringify({ candidates }), { status: 200 }),
218+
);
219+
220+
expect(events).toEqual([{ type: "error", message: "google response contained invalid candidates" }]);
221+
}
222+
});
223+
224+
test("absent, null and empty containers stay legal on both paths", async () => {
225+
// Absence is not corruption: a finish-only chunk, an explicit `null`, and an empty array are
226+
// all ordinary shapes and must keep completing the turn.
227+
for (const candidate of [
228+
{ finishReason: "STOP" },
229+
{ content: null, finishReason: "STOP" },
230+
{ content: [], finishReason: "STOP" },
231+
{ content: {}, finishReason: "STOP" },
232+
{ content: { parts: null }, finishReason: "STOP" },
233+
{ content: { parts: [] }, finishReason: "STOP" },
234+
]) {
235+
const streamEvents = await collect(createGoogleAdapter(provider()).parseStream(
236+
sseResponse([{ candidates: [candidate] }]),
237+
));
238+
const responseEvents = await createGoogleAdapter(provider()).parseResponse!(
239+
new Response(JSON.stringify({ candidates: [candidate] }), { status: 200 }),
240+
);
241+
242+
expect(streamEvents.some(event => event.type === "error")).toBe(false);
243+
expect(streamEvents.at(-1)?.type).toBe("done");
244+
expect(responseEvents).toEqual([{ type: "done", usage: undefined }]);
245+
}
246+
});
247+
248+
test("an absent candidates list is still reported as absent, not malformed", async () => {
249+
for (const body of [{}, { candidates: null }, { candidates: [] }]) {
250+
const events = await createGoogleAdapter(provider()).parseResponse!(
251+
new Response(JSON.stringify(body), { status: 200 }),
252+
);
253+
254+
expect(events).toEqual([{ type: "error", message: "google response contained no candidates" }]);
255+
}
256+
});
257+
258+
test("well-formed parts still stream and buffer unchanged", async () => {
259+
const payload = {
260+
candidates: [{
261+
content: { parts: [{ text: "visible" }, { functionCall: { name: "lookup", args: { q: 1 } } }] },
262+
finishReason: "STOP",
263+
}],
264+
};
265+
266+
const streamEvents = await collect(createGoogleAdapter(provider()).parseStream(sseResponse([payload])));
267+
const responseEvents = await createGoogleAdapter(provider()).parseResponse!(
268+
new Response(JSON.stringify(payload), { status: 200 }),
269+
);
270+
271+
for (const events of [streamEvents, responseEvents]) {
272+
expect(events).toContainEqual({ type: "text_delta", text: "visible" });
273+
expect(events.some(event => event.type === "tool_call_start" && event.name === "lookup")).toBe(true);
274+
expect(events).toContainEqual({ type: "tool_call_delta", arguments: JSON.stringify({ q: 1 }) });
275+
expect(events.at(-1)?.type).toBe("done");
276+
expect(events.some(event => event.type === "error")).toBe(false);
277+
}
278+
});
279+
130280
test("EOF residual data frame without a trailing newline is parsed", async () => {
131281
const events = await collect(createGoogleAdapter(provider()).parseStream(
132282
new Response('data:{"candidates":[{"content":{"parts":[{"text":"final"}]},"finishReason":"STOP"}]}', {

0 commit comments

Comments
 (0)