fix(gateway): stop dropping caller tools and provider response fields - #3569

Two silent drops on /v1/chat/completions. Both were found the same way: the request was accepted, something in it was discarded, and the caller was billed for a reply that could not do the job.

The problem

A tool the provider runs itself was dropped. Gemini's provider-executed tools are written as a bare {"google_search": {}}, with no type to declare. The translation skipped any entry that was not a function, and with no function declarations left it omitted tools entirely — the request went upstream with no tools at all. Asked to answer from search results it was never given the tool to fetch, the model returned nothing: HTTP 200, empty content, finishReason: STOP, zero output tokens, prompt tokens billed, four runs in a row.

The Tool.Raw escape hatch did not catch it. Tool.UnmarshalJSON kept the caller's bytes only when a type was present and not "function", so an entry with no type at all reached the provider as an empty function and was skipped. The Anthropic path forwards its server tools through exactly that field, so the pattern existed and Gemini could not use it.

Any response field outside the canonical struct was dropped. The gateway rebuilds every response on models.ChatCompletionResponse, so a field it does not name is lost. Perplexity sends citations and search_results beside the choices and its own counters inside usage; none of it reached the caller. Streaming dropped the same fields.

The asymmetry is the argument: ChatCompletionRequest has kept unknown fields and forwarded them to providers since it was written. The gateway promised pass-through in one direction only.

The change

• models/passthrough.go captures and replays unknown fields for ChatCompletionResponse, StreamChunk and Usage. The known keys are read from the struct tags rather than listed by hand, so a field added to a struct cannot drift out of its own capture — the request side's hand-written list is the hazard being avoided. A key the struct names always wins: a stale captured copy would undo whatever the gateway normalized.
• Gemini forwards googleSearch, googleSearchRetrieval, urlContext and codeExecution, each in its own tools entry beside the caller's functions, in either spelling, carrying the caller's own config so a retrieval config survives.
• Grounding sources come back as url_citation annotations — the shape OpenAI's own web search uses, and the one the Anthropic provider already builds from its citations. Without this, enabling the tool would return grounded text with no way to see where it came from, which is the reason for asking.
• A request whose tool entries are all unservable is refused with 400 unsupported_tool, before a concurrency slot is taken.

Why the refusal is narrow

My first version refused any unservable entry. That breaks a configuration the gateway offers: a model alias or failover group can span providers, so a caller sending Anthropic's web_search_20250305 alongside their own functions would have the request fail on whichever member is Gemini — and 400 is not in DefaultFailoverStatusCodes (429, 500, 502, 503, 504), so there would be no falling through to the next provider either. It would turn a silent drop into an outright failure for a working setup.

So the refusal fires only when nothing survives, which is the reported case and the only one where silence is unambiguously wrong: the request would reach the provider with no tools and the model would answer as if the capability had never been asked for. When some tools survive, the model still has something to work with and the dropped entries are logged at WARN.

Behaviour changes to know about

1. A request whose tools are all unservable now fails instead of being answered without them.
2. A declared type other than "function" is taken at its word, even when the entry also names a function. OpenAI's older assistants types do that ({"type": "retrieval", "function": {...}}). The obvious reading of my first patch declared such an entry to the model as a callable function, which would have it call something nobody implements.
3. A tool entry naming no function now reaches the provider as the caller wrote it. {"type": "function"} with no name used to be re-marshalled as {"type":"function","function":{"name":""}}; it now travels verbatim. This changes what the openai and anthropic providers send upstream for a malformed entry — both upstreams reject it either way, but the error text comes from the caller's own bytes. There is a test pinning this.
4. Responses carry provider fields they did not carry before. A client that rejects unknown fields strictly will see more of them.

Tests

19 cases. Every behaviour case was run against origin/dev first and fails there for the right reason:

• google_search reaches the provider — on dev: no tools were sent at all; body was [contents generationConfig], the reported bug verbatim
• all four tools, both spellings, a retrieval config forwarded as written, and the {"type": "google_search"} form (6 cases)
• functions and a server tool travel together in two entries — on dev: 1 entry
• an all-unservable request is refused and the upstream is never called (3 cases)
• an unservable tool beside a surviving one does not fail the request (2 cases; the function variant passes on dev too, since the outcome there is the same drop — it is a guard against the refusal firing, not a regression test)
• a nameless function entry keeps the caller's bytes — on dev: {"type":"function","function":{"name":""}}
• grounding sources become annotations with the URL, title and text extent — on dev: dropped
• Perplexity's citations, search_results and extra usage counters survive a round trip — on dev: every one dropped
• the same for a stream chunk
• guards that pass on both trees: a response with nothing extra serializes byte-for-byte as before, a reply with no grounding carries no annotations key, and a known key is never captured or merged back

Full gateway suite green, 82 packages. go vet clean on the packages touched. gofmt clean on every file in the diff. Merged together with #3568 and #3570 on top of dev: no conflicts, build clean, 83 packages green.

(internal/models/errors_test.go has a pre-existing go vet complaint about a deliberate json.Unmarshal(..., nil); untouched here.)

E2E: exempt (harness-gap the e2e stack cannot configure a Gemini provider or a tool policy)

e2e/lib/managed-mock.ts admits only the logging, providers and server sections and pins the provider set to openai alone with api_format: openai against the deterministic mock. So no Gemini provider can exist in the e2e stack, no tool_policy section can be configured, and the mock returns a fixed OpenAI-shaped body with no provider-specific fields — which is every surface this PR touches. Covered by Go tests: provider-level assertions on the body sent upstream, and policy-level assertions through the real toolpolicy.ProcessRequest.