Skip to content

Commit 4dd570b

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. The two candidate errors #1332 already emitted get the same treatment, so one diagnostic type covers every rung; the wording #1332 chose is kept as the message prefix, so an existing log grep still matches. Going the other way, the streaming parser was treating a `null` `candidates` container as corruption and terminating on it. That is the #1219 failure mode one rung in: a `{"candidates":null}` frame between a content delta and the finish chunk killed a turn whose answer had already fully arrived, while the same stream with the key absent or the array empty completed. `null` now joins absence, as it already does on the buffered side. 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` — while a non-null, non-array `candidates` stays terminal.
1 parent 03735ec commit 4dd570b

3 files changed

Lines changed: 345 additions & 14 deletions

File tree

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,15 @@ 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 handled separately from corruption: an absent,
123+
`null` or empty `content` or `parts` still completes the turn normally, a streaming chunk whose
124+
`candidates` is absent, `null` or empty is skipped so the turn completes on a later terminal
125+
frame, and a buffered response that carries no candidate at all returns
126+
`google response contained no candidates`. A root `data: null` keepalive frame is still skipped as
127+
padding.
119128
- **Inline image output:** when the model is one of the explicit image-capable chat IDs
120129
(`gemini-3.1-flash-image`, `gemini-2.0-flash-preview-image-generation`, or
121130
`gemini-3-pro-image-preview`), the adapter sends `responseModalities: ["TEXT", "IMAGE"]`.

‎src/adapters/google.ts‎

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

375+
interface InvalidGoogleShapeDiagnostic {
376+
reason:
377+
| "candidates_not_array"
378+
| "candidate_not_object"
379+
| "content_not_object"
380+
| "parts_not_array"
381+
| "part_not_object";
382+
partIndex?: number;
383+
valueType: string;
384+
}
385+
386+
function isGoogleRecord(value: unknown): value is Record<string, unknown> {
387+
return value !== null && typeof value === "object" && !Array.isArray(value);
388+
}
389+
390+
function googleStructuralValueType(value: unknown): string {
391+
if (value === null) return "null";
392+
return Array.isArray(value) ? "array" : typeof value;
393+
}
394+
395+
/**
396+
* A candidate's `content` is claimed model output inside a well-formed frame, so it is governed by
397+
* the #1332 nested-shape rule (fail closed) rather than #1240's root-frame padding rule (skip).
398+
*
399+
* Absence stays legal, and so does one encoding of it: an empty array is how a JSON writer with no
400+
* distinct empty-object form spells an empty `content`, and it already behaves as "no parts". A
401+
* NON-empty array is the opposite case — `content?.parts` silently reads `undefined` from it, so a
402+
* candidate shaped `content: [{ parts: [...] }]` dropped its own text and completed as an empty
403+
* turn.
404+
*/
405+
function diagnoseGoogleContent(content: unknown): InvalidGoogleShapeDiagnostic | undefined {
406+
if (content === undefined || content === null || isGoogleRecord(content)) return undefined;
407+
if (Array.isArray(content) && content.length === 0) return undefined;
408+
return { reason: "content_not_object", valueType: googleStructuralValueType(content) };
409+
}
410+
411+
/**
412+
* `content.parts` sits one rung below the candidate guard added in #1332, and both parsers
413+
* consumed it unchecked: `for (const part of {})` throws `{} is not iterable`, and a `[null]`
414+
* element throws on `part.thoughtSignature`. A `parts` that is absent or `null` keeps its existing
415+
* skip — only a present, non-null container is validated.
416+
*/
417+
function diagnoseGoogleParts(parts: unknown): InvalidGoogleShapeDiagnostic | undefined {
418+
if (!Array.isArray(parts)) {
419+
return { reason: "parts_not_array", valueType: googleStructuralValueType(parts) };
420+
}
421+
for (let partIndex = 0; partIndex < parts.length; partIndex++) {
422+
const part: unknown = parts[partIndex];
423+
if (!isGoogleRecord(part)) {
424+
return { reason: "part_not_object", partIndex, valueType: googleStructuralValueType(part) };
425+
}
426+
}
427+
return undefined;
428+
}
429+
430+
function invalidGoogleShapeEvent(
431+
diagnostic: InvalidGoogleShapeDiagnostic,
432+
): Extract<AdapterEvent, { type: "error" }> {
433+
const at = diagnostic.partIndex !== undefined ? `; partIndex=${diagnostic.partIndex}` : "";
434+
// The subject names the rung that failed, so an operator reading a log can tell a broken
435+
// candidate list from a well-formed candidate whose parts are broken. The candidate subject keeps
436+
// the exact wording #1332 introduced as its prefix, so an existing grep still matches.
437+
const subject = diagnostic.reason === "candidates_not_array" || diagnostic.reason === "candidate_not_object"
438+
? "candidates"
439+
: diagnostic.reason === "content_not_object"
440+
? "content"
441+
: "content parts";
442+
return {
443+
type: "error",
444+
message: `google response contained invalid ${subject} (${diagnostic.reason}${at}; valueType=${diagnostic.valueType})`,
445+
};
446+
}
447+
375448
export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapter {
376449
// Per-request closure: resolveAdapter builds a fresh adapter per request (server.ts), so buildRequest
377450
// can stash the CCA model/session for parseStream's reasoning-replay observation.
@@ -669,22 +742,34 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
669742
sawTerminalSignal = true;
670743
}
671744
const rawCandidates = root.candidates;
672-
if (rawCandidates === undefined) return "continue";
745+
// `null` is an absence encoding, not corruption, and terminating on it is the #1219
746+
// failure mode one rung in: a `{"candidates":null}` frame arriving between a content
747+
// delta and the finish chunk killed a turn whose answer had already fully arrived. An
748+
// absent key and an empty array are already skipped here; `null` joins them. A non-null
749+
// non-array container is still claimed structure the parser cannot read, and stays
750+
// terminal.
751+
if (rawCandidates === undefined || rawCandidates === null) return "continue";
673752
if (!Array.isArray(rawCandidates)) {
674-
yield { type: "error", message: "google response contained invalid candidates" };
753+
yield invalidGoogleShapeEvent({
754+
reason: "candidates_not_array",
755+
valueType: googleStructuralValueType(rawCandidates),
756+
});
675757
return "terminate";
676758
}
677759
if (rawCandidates.length === 0) return "continue";
678760
const rawCandidate = rawCandidates[0];
679-
if (rawCandidate === null || typeof rawCandidate !== "object" || Array.isArray(rawCandidate)) {
761+
if (!isGoogleRecord(rawCandidate)) {
680762
// Unlike a root `data: null` keepalive, this is a claimed response candidate. Treat it
681763
// as terminal protocol corruption so the turn cannot complete after silently losing
682764
// a candidate or tool call (#1325).
683-
yield { type: "error", message: "google response contained invalid candidates" };
765+
yield invalidGoogleShapeEvent({
766+
reason: "candidate_not_object",
767+
valueType: googleStructuralValueType(rawCandidate),
768+
});
684769
return "terminate";
685770
}
686771
const candidate = rawCandidate as {
687-
content?: { parts?: unknown[] };
772+
content?: unknown;
688773
finishReason?: string;
689774
};
690775

@@ -693,7 +778,24 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
693778
sawTerminalSignal = true;
694779
}
695780

696-
const parts = candidate.content?.parts as GoogleResponsePart[] | undefined;
781+
// One rung below the candidate guard above, same rule: this is claimed content, not
782+
// padding, so it fails closed rather than being iterated or silently dropped (#1325).
783+
const rawContent: unknown = candidate.content;
784+
const invalidContent = diagnoseGoogleContent(rawContent);
785+
if (invalidContent) {
786+
yield invalidGoogleShapeEvent(invalidContent);
787+
return "terminate";
788+
}
789+
const rawParts: unknown = isGoogleRecord(rawContent) ? rawContent.parts : undefined;
790+
let parts: GoogleResponsePart[] | undefined;
791+
if (rawParts !== undefined && rawParts !== null) {
792+
const invalidParts = diagnoseGoogleParts(rawParts);
793+
if (invalidParts) {
794+
yield invalidGoogleShapeEvent(invalidParts);
795+
return "terminate";
796+
}
797+
parts = rawParts as GoogleResponsePart[];
798+
}
697799
// Record Gemini thought signatures for the next stateless tool-result turn. Vertex and
698800
// Antigravity use separate model namespaces so opaque provider state cannot cross routes.
699801
const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
@@ -924,23 +1026,52 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
9241026
}
9251027
const events: AdapterEvent[] = [];
9261028

927-
const candidates = json.candidates as { content?: { parts?: GoogleResponsePart[] }; finishReason?: string }[] | undefined;
1029+
const rawCandidates: unknown = json.candidates;
1030+
// Parity with the streaming path, which has rejected a non-array `candidates` since #1332.
1031+
// Buffered accepted `"abc"` outright (`"abc".length` is 3, so the emptiness check below
1032+
// passed and `candidates[0]` was the character `"a"`), and reported `{}`/`5` as an absent
1033+
// candidate list rather than a malformed one.
1034+
if (rawCandidates !== undefined && rawCandidates !== null && !Array.isArray(rawCandidates)) {
1035+
return finish([invalidGoogleShapeEvent({
1036+
reason: "candidates_not_array",
1037+
valueType: googleStructuralValueType(rawCandidates),
1038+
})]);
1039+
}
1040+
const candidates = rawCandidates as { finishReason?: string }[] | undefined;
9281041
if (!candidates?.length) {
9291042
return finish([{ type: "error", message: "google response contained no candidates" }]);
9301043
}
1044+
const rawCandidate: unknown = candidates[0];
1045+
if (!isGoogleRecord(rawCandidate)) {
1046+
// The streaming parser already treats this as terminal protocol corruption (#1325/#1332).
1047+
// Buffered returned a bare `done`, so a claimed-but-malformed candidate was reported to
1048+
// the caller as a successful empty turn.
1049+
return finish([invalidGoogleShapeEvent({
1050+
reason: "candidate_not_object",
1051+
valueType: googleStructuralValueType(rawCandidate),
1052+
})]);
1053+
}
1054+
const candidate = rawCandidate as { content?: unknown; finishReason?: string };
9311055
let toolCallsStarted = 0;
9321056
const imageBudget = createImageBudget();
933-
if (candidates?.[0]?.content?.parts) {
1057+
const rawContent: unknown = candidate.content;
1058+
const invalidContent = diagnoseGoogleContent(rawContent);
1059+
if (invalidContent) return finish([invalidGoogleShapeEvent(invalidContent)]);
1060+
const rawParts: unknown = isGoogleRecord(rawContent) ? rawContent.parts : undefined;
1061+
if (rawParts !== undefined && rawParts !== null) {
1062+
const invalidParts = diagnoseGoogleParts(rawParts);
1063+
if (invalidParts) return finish([invalidGoogleShapeEvent(invalidParts)]);
1064+
const parts = rawParts as GoogleResponsePart[];
9341065
// Non-streaming Google-family response: observe thought signatures for the next turn,
9351066
// using the same transport-scoped namespace as the streaming path.
9361067
const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
9371068
const replaySession = provider.googleMode === "cloud-code-assist" ? antigravitySession : vertexReplaySession;
9381069
if ((provider.googleMode === "cloud-code-assist" || provider.googleMode === "vertex")
9391070
&& replayModel && replaySession) {
940-
observeAntigravityReplay(replayModel, replaySession, candidates[0].content.parts as unknown[]);
1071+
observeAntigravityReplay(replayModel, replaySession, parts as unknown[]);
9411072
}
9421073
let pendingThoughtSig: string | undefined;
943-
for (const part of candidates[0].content.parts) {
1074+
for (const part of parts) {
9441075
const sig = part.thoughtSignature ?? part.thought_signature;
9451076
if (part.thought === true && sig && isLikelyRealThoughtSignature(sig)) {
9461077
pendingThoughtSig = sig;
@@ -979,16 +1110,16 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
9791110
// Fail-closed truncation, same as the stream path: a non-stream turn cut off mid tool call
9801111
// (MAX_TOKENS / MALFORMED_FUNCTION_CALL) surfaces an error instead of a silent done.
9811112
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) }]);
1113+
&& isVertexTruncatedTurn(candidate.finishReason, toolCallsStarted)) {
1114+
return finish([{ type: "error", message: vertexTruncationErrorMessage(candidate.finishReason) }]);
9841115
}
9851116

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

0 commit comments

Comments
 (0)