Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / gemini-protocol-adapter

Gemini protocol adapter

The Gemini protocol adapter presents the generateContent and streamGenerateContent contracts while using the shared routing and provider system underneath. It keeps Gemini content, tool calls, reasoning state, token usage, errors, and stream completion meaningful when the selected provider speaks Chat, Messages, Responses, or native Gemini. See Protocol adapters, Conversation history replay and correction, and API gateway for the surrounding systems.

Request boundary

The request boundary accepts a Gemini-shaped body and keeps the model name in the URL as the route key. It validates the body before provider execution, then passes a native Gemini request to routing without changing caller-owned history.

Request shape

The Gemini request model accepts ordered contents, optional text-only systemInstruction, function declarations, tool choice, and generation controls. Each content part has one meaning: text, image data, function call, function result, or a replay signature. Strict fields and Gemini camel-case aliases prevent unsupported request data from reaching a provider. The route accepts generateContent for JSON and streamGenerateContent only with alt=sse.

References: src/…/routes.py• L66-126 src/…/models.py• L14-35 src/…/models.py• L37-99 src/…/models.py• L226-256

Routing boundary

The router resolves the URL model to a provider model and records the public model separately from the upstream model. The provider layer can send this request to native Gemini or translate other public request protocols into Gemini before opening the upstream stream. The executor estimates input tokens and opens the provider stream through the same fallback and recovery lifecycle used by the other public protocols.

This boundary means a Gemini client does not need to know which provider wire is active. A provider can receive Chat, native Messages, Responses, or native Gemini input while the client always receives Gemini candidates.

References: src/…/routing.py• L103-108 src/…/routing.py• L382-392 src/…/execution.py• L375-430 src/…/execution.py• L448-629 src/…/client.py• L141-286

History replay

History replay lets a later Gemini request continue a prior response without sending foreign provider state as if it were local state. Gemini carries adapter-issued replay data in thoughtSignature, while the source request remains unchanged.

History validation

History normalization checks function-call ownership and replay metadata before conversion. It assigns missing call IDs, matches function results to one pending call by ID or unique name, and rejects duplicate, orphaned, ambiguous, or unresolved calls. It also rejects caller-native signatures because the gateway can safely replay only its own bundle format.

References: src/…/history.py• L10-21 src/…/history.py• L22-65 src/…/history.py• L66-81

Replay projection

An adapter-issued signature contains a response identity, provider-owned reasoning records, tool-call metadata, and an optional digest for echoed visible thoughts. The request converter projects these records into the target wire as redacted thinking, encrypted Responses reasoning, or structured Chat reasoning. It restores Chat tool metadata only when provider, endpoint, connection, and model provenance is accepted.

The projection uses a fresh request copy. Same-connection native data can continue provider work; foreign data becomes safe context or stays out of the request. The native Gemini provider applies the same history checks before sending a request and can build a continuation request after a recoverable stream failure. This follows the wider history replay rule that native state must not cross an incompatible provider boundary.

References: src/…/replay.py• L22-51 src/…/replay.py• L54-97 src/…/replay.py• L100-152 src/…/request.py• L108-132 src/…/transport.py• L148-185 src/…/transport.py• L330-345

Web search replay

Completed Messages WebSearch turns can return in later requests while preserving the original Gemini tool-call order. The adapter checks that every visible search call has one matching result, then uses a signed Gemini replay record to restore the hidden function call and turn the saved result into a Gemini function response.

When no signed Gemini record exists, the adapter replaces search blocks with safe history text instead of sending them as executable tool state. When a signed record exists, it validates the hidden tool name, query, call count, and call order before restoring the turn. Ordinary client tool calls remain in place, so a turn can contain both client calls and automatic search calls.

The restored history yields the assistant turn and a following user turn for search results. The native converter then joins those results with other tool results in the original function-call order. Incomplete, duplicated, or mismatched search history becomes a Gemini conversion error rather than an invented tool result.

References: src/…/web_search_replay.py• L17-65 src/…/web_search_replay.py• L75-144 src/…/native_request.py• L331-340 src/…/native_request.py• L369-426

Content and tool conversion

The adapter converts one Gemini conversation into the request shape required by the selected provider protocol. It preserves order and links tool results to their calls instead of treating the request as a set of unrelated fields.

Content mapping

Text becomes user or assistant text in every destination. For native Gemini requests, supported cross-protocol image parts must be base64 data URLs and become inline image data; unsupported image detail and other image forms are rejected. Function results become functionResponse parts with text or structured output, and result images remain attached to the function result. System text is placed in the destination's system or instruction field.

The converter rejects content that has no faithful destination. Native Gemini conversion also rejects unsupported provider fields, non-text system content, and empty or unresolved tool history rather than dropping it. When Google AI Studio is the selected provider, the provider adapter turns Chat, Messages, and Responses requests into the native Gemini body before transport.

References: src/…/request.py• L42-59 src/…/request.py• L177-240 src/…/request.py• L250-258 src/…/native_request.py• L34-77 src/…/native_request.py• L169-178 src/…/native_request.py• L318-484 src/…/native_request.py• L487-632 src/…/client.py• L153-165 src/…/client.py• L208-212 src/…/client.py• L239-243

Tool mapping

Gemini function declarations become provider function tools with a portable name, description, and JSON schema. The adapter includes historical call names when it builds the request-wide name map, so a provider alias can be decoded back to the Gemini name. Tool choice maps AUTO, NONE, and ANY to the closest destination mode.

The native Gemini conversion path accepts function tools but cannot enforce strict schemas, provider-hosted tools, or disabled parallel calls. It keeps call IDs and names across function results, requires each result to match one earlier call, and rejects unsupported declaration fields. Function calls are emitted only from structured provider tool events. Their arguments must finish as finite JSON objects. An undeclared provider function, changed streamed arguments, or invalid argument shape becomes a conversion failure rather than a client-visible call that cannot be replayed.

Native Gemini output follows the same declaration check before it is projected to another client protocol.

References: src/…/request.py• L78-98 src/…/request.py• L259-290 src/…/native_request.py• L134-150 src/…/native_request.py• L243-315 src/…/native_request.py• L337-484 src/…/native_request.py• L527-632 src/…/response.py• L35-51 src/…/messages_stream.py• L76-99 src/…/responses_stream.py• L243-271 src/…/stream.py• L157-184

Generation controls

Sampling, output limits, stop sequences, and structured output are mapped only when the destination can represent them. Gemini schemas are normalized to JSON Schema while preserving constraints such as required fields, nullability, and nested properties. Unsupported controls produce an explicit conversion error instead of being dropped.

The native Gemini path maps common controls to generationConfig, including output limits, sampling values, stop sequences, and JSON or schema output formats. It rejects structured output formats that it cannot express and leaves provider-specific controls out of the request when the source protocol does not define a native equivalent.

References: src/…/request.py• L294-367 src/…/schema.py• L39-112 src/…/native_request.py• L153-166 src/…/native_request.py• L260-315 src/…/native_request.py• L429-484 src/…/native_request.py• L583-632 src/…/transport.py• L867-883 src/…/transport.py• L195-203

Reasoning and token handling

Gemini reasoning is an optional part of the candidate stream and a separate form of provider state for later turns. The adapter keeps visible thought text separate from opaque replay data, then maps provider usage into Gemini names.

Reasoning controls

thinkingBudget and thinkingLevel become the shared reasoning policy. A zero budget disables reasoning, a positive budget enables it with a limit, a negative budget enables it without a fixed limit, and a level becomes an effort preference. includeThoughts controls whether thought text is sent to the client; it does not discard the provider-owned replay record needed for history.

The route may apply a configured reasoning preference to a fallback candidate. The fallback request removes the client computation control before the new policy is applied, so one candidate does not inherit stale controls from another. Native Gemini requests keep an equivalent native policy when one is already present; cross-protocol requests set thought visibility from the shared policy. Native Gemini requests and requests translated for a native Gemini provider receive the same shared policy before transport.

References: src/…/models.py• L137-164 src/…/response.py• L54-117 src/…/native_request.py• L91-131 src/…/reasoning.py• L61-92 src/…/client.py• L153-176 src/…/client.py• L271-275

Token accounting

Input token handling is a bounded estimate used before provider execution. It counts text, function calls, function results, and tool declarations; it does not treat image bytes as ordinary text. Provider usage takes precedence at completion when it is valid.

Gemini usage names include promptTokenCount, candidatesTokenCount, totalTokenCount, cachedContentTokenCount, and thoughtsTokenCount. When a provider reports reasoning tokens with output tokens, the adapter subtracts reasoning from candidate output so the two fields do not count the same tokens twice.

References: src/…/tokens.py• L10-32 src/…/messages_stream.py• L100-145 src/…/responses_stream.py• L282-309 src/…/gemini_output.py• L107-132 src/…/stream.py• L273-309

Response delivery

The adapter uses one Gemini candidate format for both streamed and non-streamed calls. Provider-specific event streams are translated into data: JSON frames, while the non-streaming path consumes those same frames and folds them into one completed response.

Candidate frames

Each public frame carries the response ID, public model version, and candidate content when content is available. Text and thought deltas become Gemini parts. Completed function calls become functionCall parts. The final frame carries a Gemini finish reason and, when available, usage metadata and one opaque thoughtSignature for replay.

The provider stream presenters cover the upstream families:

  • Chat output converts shared Chat deltas into Gemini parts.
  • Messages output validates native block order and maps text, thinking, and tool blocks.
  • Responses output joins text snapshots and deltas, completes reasoning items, and closes function calls.
  • Native Gemini output validates one candidate and projects text, thoughts, and function calls to the requested client protocol. A native Gemini client can receive the upstream candidate shape directly.

References: src/…/gemini_output.py• L18-35 src/…/gemini_output.py• L67-105 src/…/messages_stream.py• L14-45 src/…/responses_stream.py• L14-58 src/…/stream.py• L64-227

Stream completion

The stream contract is a sequence of data: JSON frames with no provider event names. A successful stream ends with a candidate finish reason. The accumulator merges adjacent text or thought parts of the same kind and rejects data after completion or a stream that ends without a finish reason.

For a non-streaming request, the handler first creates the same managed stream and then aggregates it into one JSON response. This keeps streamed and non-streamed calls aligned for part order, tool validation, reasoning signatures, finish reasons, and usage. The native transport also requires an SSE content type and decodes the upstream events before the common stream rules apply.

References: src/…/response.py• L17-32 src/…/response.py• L152-207 src/…/gemini.py• L54-87 src/…/transport.py• L186-214 src/…/stream.py• L230-245

Delivery recovery

The shared delivery state records what Gemini content the client already received. If a provider fails after a safe text prefix, recovery can continue or hand off without repeating that prefix. It stops when the delivered state contains unsafe opaque data, released tool work, or too much retained replay evidence.

The native Gemini transport uses this state for early retry and continuation. It holds back output until recovery is safe, preserves only bounded native response data, and closes the upstream attempt before it starts a continuation.

References: src/…/stream_delivery.py• L13-80 src/…/response.py• L68-87 tests/…/test_gemini_delivery.py• L15-39 src/…/transport.py• L148-160 src/…/transport.py• L249-345

Error translation

The Gemini boundary turns validation, conversion, provider, and stream failures into Google-shaped error objects. The public error preserves an HTTP code and a Gemini status name without exposing provider-specific error internals.

Error envelopes

A request conversion error becomes HTTP 400 with INVALID_ARGUMENT. Application failures and execution failures use their mapped HTTP status and a Gemini status value such as UNAVAILABLE, RESOURCE_EXHAUSTED, or DEADLINE_EXCEEDED. Error text is passed through the shared safe-message boundary before it is returned.

The native Gemini stream maps an upstream error payload to a classified execution failure. Authentication, permission, rate-limit, request, and upstream failures keep their HTTP status and retry meaning until the public Gemini error boundary formats them.

References: src/…/errors.py• L6-27 src/…/gemini.py• L92-122 src/…/stream.py• L64-88

Stream failure boundary

The API reads the first stream frame before it commits to a streaming response. A failure before that frame becomes an HTTP JSON error. A failure after output starts becomes one final Gemini data frame with the error object, then the managed response closes and releases its request resources.

The native transport treats a malformed or non-SSE upstream response as a provider protocol failure. It can retry or continue only when the shared delivery state says that doing so will not duplicate visible output or released tool work.

References: src/…/response_streams.py• L191-219 src/…/response_streams.py• L398-430 src/…/response_streams.py• L56-131 src/…/transport.py• L205-214 src/…/transport.py• L315-363

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep Gemini field aliases, duplicate-key checks, URL model parsing, and alt rules aligned so invalid input fails before provider execution.
  • When a content part changes, update all three request destinations and all three provider stream presenters.
  • When native request conversion changes, check image form, system content, tool-result order, source-protocol field limits, and output formatting together.
  • When tool identity or schema rules change, update declarations, historical calls, forced choices, provider aliases, and returned function calls together.
  • When replay data changes, keep thoughtSignature validation, provenance checks, thought echo suppression, and provider-specific replay projection aligned.
  • When WebSearch history changes, keep visible search IDs, hidden Gemini call names, signed native call order, saved result payloads, and ordinary client tool calls aligned.
  • When reasoning controls change, check client policy, fallback policy, provider request fields, thought visibility, and usage subtraction together.
  • When finish or usage fields change, check both stream frames and non-stream aggregation for translated and native Gemini output.
  • When native Gemini transport changes, preserve SSE decoding, one-candidate handling, upstream error classification, attempt cleanup, and continuation rules.
  • When failure handling changes, preserve the pre-start HTTP contract, post-start terminal frame, safe message rule, and response-resource cleanup.

Important failure modes

TriggerConsequenceGuard
A request uses an unsupported field, generation control, or content formThe provider request cannot preserve Gemini meaningStrict request models and destination conversion raise an invalid-argument error before inference
A cross-protocol image is not a base64 data URL or uses unsupported detailNative Gemini cannot build valid inline image dataNative conversion accepts only data URLs and auto or absent image detail
A function result cannot be matched to one earlier callTool history can attach output to the wrong callHistory normalization requires a valid ID or one unique name match
A provider returns an undeclared function or non-object argumentsThe client can receive a tool call that it cannot safely executeStream presenters decode request-scoped names and validate finite JSON objects
A native Gemini response contains multiple candidates, unsupported output parts, grounding, or citation dataThe requested client protocol cannot represent the result safelyThe native presenter accepts one candidate and rejects unsupported content or metadata
A replay signature is caller-native, malformed, conflicting, or from an unsafe sourceForeign provider state can fail upstream or leak into the wrong accountOnly FCC-issued bundles are accepted and provenance is checked before metadata restore
WebSearch history has a missing, duplicate, or mismatched resultThe next request can lose a search result or replay the wrong hidden callThe replay adapter requires one result per visible search and checks signed call names, queries, count, and order
A provider reports reasoning and output tokens in one totalGemini candidate usage can double count reasoningFinal usage subtracts valid reasoning tokens from candidate output tokens
A provider stream ends without a finish reason or sends data after completionNon-stream output can look successful or contain an invalid extra frameThe accumulator requires completion and rejects post-terminal data
A native upstream response is not an SSE stream or its event data is malformedThe adapter cannot safely apply the public stream contractTransport checks the content type and the shared event reader validates stream data
A provider fails before the first public frameThe client receives a malformed or empty stream responseThe API returns a normal Gemini HTTP error before stream commitment
A provider fails after public content or tool work is releasedRetrying can duplicate visible output or tool workDelivery evidence limits recovery to safe retained prefixes and stops unsafe cases

Key files

FileWhy to read it
src/…/routes.pyDefines Gemini URL parsing, authentication, validation, and response lifetime ownership.
src/…/gemini.pyConnects routing, execution, streaming, aggregation, and Gemini error output.
src/…/models.pyDefines the supported Gemini request, content, tool, reasoning, and generation concepts.
src/…/history.pyDefines function-call matching and replay-bundle checks for Gemini history.
src/…/request.pyShows how Gemini content, tools, schemas, controls, and replay become provider requests.
src/…/native_request.pyShows how Chat, Messages, and Responses inputs become native Gemini contents, tools, generation settings, and replayable WebSearch history.
src/…/web_search_replay.pyDefines how completed Messages WebSearch turns become validated Gemini tool history.
src/…/replay.pyDefines the Gemini thought-signature bundle and safe Chat metadata restoration.
src/…/response.pyDefines Gemini frames, replay output, function-argument validation, and non-stream aggregation.
src/…/messages_stream.pyMaps native Messages stream blocks into Gemini candidate parts.
src/…/responses_stream.pyMaps Responses events, reasoning items, and function calls into Gemini output.
src/…/gemini_output.pyShows the Chat stream presenter and final usage and finish mapping.
src/…/client.pyConnects public request protocols to native Gemini request bodies and shared reasoning policy.
src/…/stream.pyProjects native Gemini candidates into public output or returns the native candidate contract.
src/…/transport.pyOwns native Gemini HTTP streaming, history correction, retries, continuation, and cleanup.
src/…/execution.pyShows Gemini token estimation, provider selection, fallback, and recovery entry points.
src/…/response_streams.pyDefines first-frame commitment, terminal Gemini error frames, and cleanup.