diag(google): describe the Antigravity wire request without its contents (#5008)

devlog/_plan/260919_5008_antigravity_turn_ordering/000_upstream_contract_evidence.md

@@ -0,0 +1,107 @@
+# #5008 — what the upstream actually validates
+
+Evidence gathered for the intermittent first-send 400 on `google-antigravity/gemini-3.8-flash`:
+"Please ensure that function call turn comes immediately after a user turn or after a function
+response turn." Sources are public and primary where one exists. Nothing here is a fix, and one
+finding contradicts an assumption the investigation started from.
+
+## Where the error comes from
+
+It is a Google service-layer `400 INVALID_ARGUMENT`, not a client-library check. The public Go,
+Python and Node clients carry the content types and serializers but not this string or its
+validator.
+
+- Direct Gemini API, same string:
+  <https://discuss.ai.google.dev/t/about-the-gemini-api-400-please-ensure-that-function-call-turns-come-immediately-after-a-user-turn-or-after-a-function-response-turn-error/46213>
+- Vertex/gRPC, `io.grpc.StatusRuntimeException: INVALID_ARGUMENT` then the same string:
+  <https://stackoverflow.com/questions/78574345/invalid-argument-using-langchain4j-tools-with-gemini-model>
+- The converse validator captured from `generativelanguage.googleapis.com/...:generateContent`:
+  "Please ensure that function response turn comes immediately after a function call turn."
+  <https://github.com/google-gemini/deprecated-generative-ai-js/issues/267>
+- The exact string captured from `daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent`:
+  <https://github.com/router-for-me/CLIProxyAPI/issues/4959>
+
+For ordinary `generateContent` the validated object is the submitted `contents[]`, which Google
+describes as holding "the conversation history and the latest request"
+(<https://ai.google.dev/api/generate-content>).
+
+## The ordering the upstream considers valid
+
+The canonical loop is `user` then `model` carrying `functionCall` then `user` carrying every
+matching `functionResponse`.
+
+- A `user` turn carrying `functionResponse` parts counts as a function-response turn; current
+  Google examples use `role: "user"` for it, where older ones used `role: "function"`. That churn
+  explains contradictory cookbook examples.
+  <https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/tools/function-calling>
+- Parallel calls need exactly one response each, together in the immediately following turn:
+  "Return exactly one `FunctionResponse` for each `FunctionCall` received."
+  <https://ai.google.dev/gemini-api/docs/whats-new-gemini-3.5>
+- Calls and responses must not interleave. Google documents `FC1 + signature, FC2, FR1, FR2` as
+  valid and `FC1, FR1, FC2, FR2` as a 400.
+  <https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures>
+- **A model text-only turn immediately followed by a separate model `functionCall` turn is
+  invalid**: the call turn then follows a model turn, which is exactly what the error rejects.
+  Same-role adjacency is not forbidden by the protobuf schema, which only constrains role values,
+  but it is unsafe around function calling.
+
+## The finding that contradicts the starting assumption
+
+The issue was narrowed on the grounds that the reporter's A-F matrix all returned 200, so the
+translator's adjacency handling was unlikely to be at fault. Case A is exactly the shape above —
+`model(text)` then `model(functionCall)` — and the upstream contract says that shape is invalid.
+A near-identical report exists against another Antigravity proxy: Gemini 3.6/3.7 Flash failed
+after several tool rounds because a converted reasoning carrier became a model turn immediately
+before another model `functionCall`, while clean tool ordering and plain chat worked
+(<https://github.com/router-for-me/CLIProxyAPI/issues/4959>).
+
+`messagesToGeminiFormat` can emit that pair today: it pushes one `model` turn per assistant
+message, so a text-only assistant message followed by an assistant message carrying tool calls
+serializes as two adjacent model turns. That is a sourced structural candidate, and it is the
+first one this investigation has. It is not proof: a 200 on the reporter's isolated case A is a
+real observation too, and the two together suggest the rule is enforced conditionally rather than
+uniformly. Nothing here establishes which condition.
+
+Related long-session corruption mechanisms, all of them client-side rather than server-state:
+
+- orphaned `functionResponse` after a model turn carrying a call plus empty text was dropped:
+  <https://github.com/google-gemini/gemini-cli/issues/26956>
+- a projected request that began with model tool turns after MCP calls and large masked outputs:
+  <https://github.com/google-gemini/gemini-cli/issues/26472>
+- checkpoint/resume during pending tool execution producing incomplete call/response batches:
+  <https://github.com/google-gemini/gemini-cli/issues/4403>
+
+Gemini 3.5 Flash has separate intermittent function-call failures with large arguments, but those
+surface as `MAX_TOKENS` or `MALFORMED_FUNCTION_CALL`, not this ordering error
+(<https://github.com/googleapis/js-genai/issues/1619>).
+
+## The session-state hypothesis is unproven
+
+Cloud Code Assist demonstrably receives both the full history and a session identifier: Gemini
+CLI sends `contents: toContents(req.contents)` alongside `session_id: sessionId` and comments
+"Use sessionId as trajectoryId"
+(<https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/code_assist/converter.ts>,
+<https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/code_assist/server.ts>).
+A captured Antigravity request carries `contents`, `sessionId` and `requestType: "agent"` together
+(<https://github.com/router-for-me/CLIProxyAPI/issues/1675>).
+
+What no public source establishes is that `sessionId` indexes an authoritative server-side
+conversation ledger, or that Cloud Code Assist validates `contents[]` against one. Google
+documents the opposite default for stateless operation — "you must pass the full history of the
+conversation" — and exposes server-side continuation separately through the Interactions API's
+`previous_interaction_id` (<https://ai.google.dev/gemini-api/docs/function-calling>).
+"trajectoryId" is equally compatible with telemetry, agent association or routing.
+
+## Verdict
+
+Public evidence explains the error as validation of the serialized tool-call history, and it
+supplies several long-session corruption mechanisms on the client side. It does not explain an
+intermittent first-send 400 when the exact final Cloud Code Assist payload is independently
+valid. Server/client state divergence remains a hypothesis. The issue should stay open.
+
+## What was built on this evidence
+
+`src/adapters/google-wire-shape.ts` (PR #5079) projects the structure of the compiled request
+without its contents, so the next occurrence can be described from the request that actually
+failed. Its `call-turn-after-model-turn` class is the shape named above; the projection reports
+it and does not act on it. No translator change was made.

scripts/test-layout/layout.json

@@ -778,6 +778,7 @@
     "google-vertex-stream.test.ts": "adapters/google",
     "google-vertex-thought-signature.test.ts": "adapters/google",
     "google-wire-compiler.test.ts": "adapters/google",
+    "google-wire-shape.test.ts": "adapters/google",
     "grok-attribution.test.ts": "providers/xai",
     "grok-config-inject.test.ts": "providers/xai",
     "grok-effort-inject.test.ts": "providers/xai",

src/adapters/google-antigravity-replay.ts

@@ -629,7 +629,7 @@ export function antigravityUsesReplayCache(model: string): boolean {
  * neither the wire metadata nor the replay cache can supply a real one, this is the official
  * validator-bypass token.
  */
-const THOUGHT_SIGNATURE_BYPASS = "skip_thought_signature_validator";
+export const THOUGHT_SIGNATURE_BYPASS = "skip_thought_signature_validator";
 
 /**
  * True when the model speaks the Gemini wire dialect that requires a thought signature on the

src/adapters/google-antigravity-wire.ts

@@ -77,7 +77,7 @@ export function antigravitySessionId(parsed: OcxParsedRequest): string {
   //
   // Clients that send no thread header keep the text anchor and its instability; this is a scoped
   // repair, not a universal one.
-  const text = clientThreadAnchor(parsed) ?? firstUserText(parsed);
+  const text = codexThreadAnchor(parsed).preimage ?? firstUserText(parsed);
   if (!text) return `-${Math.floor(Math.random() * 9e18).toString()}`;
   const digest = createHash("sha256").update(text, "utf8").digest();
   const masked = digest.readBigUInt64BE(0) & 0x7fffffffffffffffn;
@@ -96,7 +96,10 @@ export function antigravitySessionId(parsed: OcxParsedRequest): string {
  * functionCall identity (name+args), so a shared id does not misattribute them. Instability, not
  * collision, is the failure mode this function exists to prevent.
  */
-function clientThreadAnchor(parsed: OcxParsedRequest): string | undefined {
+function codexThreadAnchor(parsed: OcxParsedRequest): {
+  kind: "parent-and-own" | "parent-only" | "absent";
+  preimage?: string;
+} {
   // `_clientThreadId` carries `x-codex-parent-thread-id`, which every parallel child of one
   // parent presents identically, so anchoring on it alone collapsed concurrent children onto a
   // single upstream Cloud Code Assist session (#5033).
@@ -113,9 +116,9 @@ function clientThreadAnchor(parsed: OcxParsedRequest): string | undefined {
   // survive both compaction and restart.
   const own = parsed._codexOwnThreadId?.trim();
   const parent = parsed._clientThreadId?.trim();
-  if (own && parent) return `codex-thread:${parent}\u0000${own}`;
+  if (own && parent) return { kind: "parent-and-own", preimage: `codex-thread:${parent}\u0000${own}` };
   // Parent-only clients keep the anchor they already had.
-  if (parent) return `codex-thread:${parent}`;
+  if (parent) return { kind: "parent-only", preimage: `codex-thread:${parent}` };
   // A parentless ROOT deliberately omits the parent header. `src/server/context-history.ts` says
   // so in as many words: root model requests use (session-id=root, thread-id=root) and do not
   // fabricate a parent key. It has no pair to key on, and #5054's claim that a root presents
@@ -125,7 +128,28 @@ function clientThreadAnchor(parsed: OcxParsedRequest): string | undefined {
   // preference: durable Antigravity replay state is keyed by model plus session id, and moving a
   // root's anchor on upgrade strands every signature stored under the old session — the exact
   // instability this derivation exists to avoid, introduced while fixing sharing.
-  return undefined;
+  return { kind: "absent" };
+}
+
+/**
+ * Which class of anchor {@link antigravitySessionId} derives this request's session id from.
+ *
+ * The id itself identifies a live conversation and is a Google-visible wire value, so it is not
+ * something a user can paste into a public bug report. The class is: it distinguishes the four
+ * stability regimes above — a Codex parent/child pair, a parent-only client, the content-derived
+ * text anchor that compaction can move, and the random fallback that changes every turn — while
+ * carrying no identity at all.
+ *
+ * It reads the SAME decision the id derivation reads, so the two cannot disagree about which
+ * regime a request is in. What it does not do is change how the id itself is derived: nothing
+ * about a Google-visible wire value moves because a diagnostic wants to describe it.
+ */
+export type AntigravitySessionAnchor = "parent-and-own" | "parent-only" | "text" | "none";
+
+export function antigravitySessionAnchor(parsed: OcxParsedRequest): AntigravitySessionAnchor {
+  const anchor = codexThreadAnchor(parsed);
+  if (anchor.kind !== "absent") return anchor.kind;
+  return firstUserText(parsed) ? "text" : "none";
 }
 
 /** A Gemini content part as it appears in an Antigravity request body. */

src/adapters/google-wire-compiler.ts

@@ -208,10 +208,25 @@ function functionDeclarations(root: JsonObject): JsonObject[] {
   });
 }
 
+/**
+ * Upstream INVALID_ARGUMENT text blaming a tool or function declaration schema.
+ *
+ * Shared with the diagnostic error classifier so the repair path and the description of why a
+ * request was rejected cannot drift into disagreeing about the same payload.
+ */
+export function isGoogleToolSchemaErrorText(errorPayload: string): boolean {
+  return /(?:input[_ ]schema|json schema|function[_ ]declarations?|x-mcp-header)/i.test(errorPayload);
+}
+
+/** Upstream INVALID_ARGUMENT text blaming the thinking configuration. */
+export function isGoogleThinkingConfigErrorText(errorPayload: string): boolean {
+  return /thinking[_ ]?(?:config|level)/i.test(errorPayload);
+}
+
 /** Build a changed request for one known-safe replay of an INVALID_ARGUMENT response. */
 export function repairGoogleInvalidRequestBody(body: string, errorPayload: string): string | undefined {
-  const schemaError = /(?:input[_ ]schema|json schema|function[_ ]declarations?|x-mcp-header)/i.test(errorPayload);
-  const thinkingError = /thinking[_ ]?(?:config|level)/i.test(errorPayload);
+  const schemaError = isGoogleToolSchemaErrorText(errorPayload);
+  const thinkingError = isGoogleThinkingConfigErrorText(errorPayload);
   if (!schemaError && !thinkingError) return undefined;
   let parsed: unknown;
   try {