feat: Gemini Interactions API record/replay (issue #136) (#139)

## Summary

Adds full record/replay support for Google's Gemini Interactions API
(`POST /v1beta/interactions`), the stateful conversation endpoint used
by TanStack AI's `geminiTextInteractions()` adapter. 12th LLM provider.

- **New handler** (`src/gemini-interactions.ts`): request conversion,
response builders, SSE stream writer with data-only format, multi-turn
sequencing via `previous_interaction_id`
- **SDK wire-format conformance**: prefers `content` over `parts` (Turn
field) and `result` over `output` (function_result field), matching the
official `@google/genai` SDK types with backwards-compat fallback
- **Drift detection**: canonical drift tests with SDK shape
triangulation
- **Recorder integration**: `buildFixtureResponse` Interactions
detection + stream collapse
- **63 tests** (2682 total) covering input conversion, response
builders, SSE streaming, stream collapse, fixture matching, wire-format
conformance, and edge cases

Closes #136

## Test plan

- [x] `pnpm test` — 2682 passed, 36 skipped, 0 failed
- [x] `pnpm run format:check` — clean
- [x] `pnpm run lint` — clean
- [x] `npx tsc --noEmit` — clean
- [x] CR converged (R1: 2 findings fixed, R2: 0 findings)

Author: jpr5

DRIFT.md

@@ -77,6 +77,7 @@ When a `critical` drift is detected:
    - OpenAI Responses API → `src/responses.ts` (`buildTextResponse`, `buildToolCallResponse`, `buildTextStreamEvents`, `buildToolCallStreamEvents`)
    - Anthropic Claude → `src/messages.ts` (`buildClaudeTextResponse`, `buildClaudeToolCallResponse`, `buildClaudeTextStreamEvents`, `buildClaudeToolCallStreamEvents`)
    - Google Gemini → `src/gemini.ts` (`buildGeminiTextResponse`, `buildGeminiToolCallResponse`, `buildGeminiTextStreamChunks`, `buildGeminiToolCallStreamChunks`)
+   - Gemini Interactions → `src/gemini-interactions.ts` (`buildInteractionsTextResponse`, `buildInteractionsToolCallResponse`, `buildInteractionsTextSSEEvents`, `buildInteractionsToolCallSSEEvents`)
 
 2. **Update the builder** — add or modify the field to match the real API shape.
 
@@ -106,7 +107,18 @@ When a model is deprecated:
 
 ## WebSocket Drift Coverage
 
-In addition to the 19 existing drift tests (16 HTTP response-shape + 3 model deprecation), WebSocket drift tests cover aimock's WS protocols (4 verified + 2 canary = 6 WS tests):
+In addition to the 23 existing drift tests (20 HTTP response-shape + 3 model deprecation), WebSocket drift tests cover aimock's WS protocols (4 verified + 2 canary = 6 WS tests):
+
+### Gemini Interactions API (Beta)
+
+The Gemini Interactions API (`/v1beta/interactions`) is covered by 4 drift tests in `gemini-interactions.drift.ts`:
+
+- Non-streaming text shape
+- Streaming text event sequence
+- Non-streaming tool call shape
+- Streaming tool call event sequence
+
+Uses `describe.skipIf(!GOOGLE_API_KEY)` like other Gemini tests. The Interactions API is in Beta — shapes may shift as Google iterates on the endpoint.
 
 | Protocol            | Text | Tool Call | Real Endpoint                                                       | Status     |
 | ------------------- | ---- | --------- | ------------------------------------------------------------------- | ---------- |
@@ -163,4 +175,4 @@ The fix workflow also supports `workflow_dispatch` for manual runs.
 
 ## Cost
 
-~25 API calls per run (16 HTTP response-shape + 3 model listing + 6 WS including canaries) using the cheapest available models (`gpt-4o-mini`, `gpt-4o-mini-realtime-preview`, `claude-haiku-4-5-20251001`, `gemini-2.5-flash`) with 10-100 max tokens each. Under $0.15/week at daily cadence. When Gemini Live text-capable models become available, the 2 canary tests will become full drift tests, increasing real WS connections from 4 to 6.
+~29 API calls per run (20 HTTP response-shape + 3 model listing + 6 WS including canaries) using the cheapest available models (`gpt-4o-mini`, `gpt-4o-mini-realtime-preview`, `claude-haiku-4-5-20251001`, `gemini-2.5-flash`) with 10-100 max tokens each. Under $0.20/week at daily cadence. When Gemini Live text-capable models become available, the 2 canary tests will become full drift tests, increasing real WS connections from 4 to 6.

README.md

@@ -35,22 +35,22 @@ await mock.stop();
 
 aimock mocks everything your AI app talks to:
 
-| Tool           | What it mocks                                                                                           | Docs                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| **LLMock**     | OpenAI (Chat/Responses/Realtime), Claude, Gemini (REST/Live), Bedrock, Azure, Vertex AI, Ollama, Cohere | [Providers](https://aimock.copilotkit.dev/docs)     |
-| **MCPMock**    | MCP tools, resources, prompts with session management                                                   | [MCP](https://aimock.copilotkit.dev/mcp-mock)       |
-| **A2AMock**    | Agent-to-agent protocol with SSE streaming                                                              | [A2A](https://aimock.copilotkit.dev/a2a-mock)       |
-| **AGUIMock**   | AG-UI agent-to-UI event streams for frontend testing                                                    | [AG-UI](https://aimock.copilotkit.dev/agui-mock)    |
-| **VectorMock** | Pinecone, Qdrant, ChromaDB compatible endpoints                                                         | [Vector](https://aimock.copilotkit.dev/vector-mock) |
-| **Services**   | Tavily search, Cohere rerank, OpenAI moderation                                                         | [Services](https://aimock.copilotkit.dev/services)  |
+| Tool           | What it mocks                                                                                                        | Docs                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **LLMock**     | OpenAI (Chat/Responses/Realtime), Claude, Gemini (REST/Live/Interactions), Bedrock, Azure, Vertex AI, Ollama, Cohere | [Providers](https://aimock.copilotkit.dev/docs)     |
+| **MCPMock**    | MCP tools, resources, prompts with session management                                                                | [MCP](https://aimock.copilotkit.dev/mcp-mock)       |
+| **A2AMock**    | Agent-to-agent protocol with SSE streaming                                                                           | [A2A](https://aimock.copilotkit.dev/a2a-mock)       |
+| **AGUIMock**   | AG-UI agent-to-UI event streams for frontend testing                                                                 | [AG-UI](https://aimock.copilotkit.dev/agui-mock)    |
+| **VectorMock** | Pinecone, Qdrant, ChromaDB compatible endpoints                                                                      | [Vector](https://aimock.copilotkit.dev/vector-mock) |
+| **Services**   | Tavily search, Cohere rerank, OpenAI moderation                                                                      | [Services](https://aimock.copilotkit.dev/services)  |
 
 Run them all on one port with `npx @copilotkit/aimock --config aimock.json`, or use the programmatic API to compose exactly what you need.
 
 ## Features
 
 - **[Record & Replay](https://aimock.copilotkit.dev/record-replay)** — Proxy real APIs, save as fixtures, replay deterministically forever
 - **[Multi-turn Conversations](https://aimock.copilotkit.dev/multi-turn)** — Record and replay multi-turn traces with tool rounds; match distinct turns via `turnIndex`, `hasToolResult`, `toolCallId`, `sequenceIndex`, or custom predicates
-- **[11 LLM Providers](https://aimock.copilotkit.dev/docs)** — OpenAI Chat, OpenAI Responses, OpenAI Realtime, Claude, Gemini, Gemini Live, Azure, Bedrock, Vertex AI, Ollama, Cohere — full streaming support
+- **[12 LLM Providers](https://aimock.copilotkit.dev/docs)** — OpenAI Chat, OpenAI Responses, OpenAI Realtime, Claude, Gemini, Gemini Live, Gemini Interactions, Azure, Bedrock, Vertex AI, Ollama, Cohere — full streaming support
 - **Multimedia APIs** — [image generation](https://aimock.copilotkit.dev/images) (DALL-E, Imagen), [text-to-speech](https://aimock.copilotkit.dev/speech), [audio transcription](https://aimock.copilotkit.dev/transcription), [video generation](https://aimock.copilotkit.dev/video)
 - **[MCP](https://aimock.copilotkit.dev/mcp-mock) / [A2A](https://aimock.copilotkit.dev/a2a-mock) / [AG-UI](https://aimock.copilotkit.dev/agui-mock) / [Vector](https://aimock.copilotkit.dev/vector-mock)** — Mock every protocol your AI agents use
 - **[Chaos Testing](https://aimock.copilotkit.dev/chaos-testing)** — 500 errors, malformed JSON, mid-stream disconnects at any probability

docs/docs/index.html

@@ -306,7 +306,10 @@ <h2>The Suite</h2>
           <tbody>
             <tr>
               <td>LLM Providers</td>
-              <td>OpenAI, Claude, Gemini, Bedrock, Azure, Vertex AI, Ollama, Cohere</td>
+              <td>
+                OpenAI, Claude, Gemini, Gemini Interactions, Bedrock, Azure, Vertex AI, Ollama,
+                Cohere
+              </td>
               <td><a href="/chat-completions">Docs &rarr;</a></td>
             </tr>
             <tr>

docs/fixtures/index.html

@@ -547,6 +547,7 @@ <h2>Provider Support Matrix</h2>
               <th>OpenAI Responses</th>
               <th>Claude</th>
               <th>Gemini</th>
+              <th>Gemini Int.</th>
               <th>Vertex AI</th>
               <th>Bedrock</th>
               <th>Azure</th>
@@ -566,6 +567,7 @@ <h2>Provider Support Matrix</h2>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
+              <td>Yes</td>
             </tr>
             <tr>
               <td>Tool Calls</td>
@@ -578,6 +580,7 @@ <h2>Provider Support Matrix</h2>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
+              <td>Yes</td>
             </tr>
             <tr>
               <td>Content + Tool Calls</td>
@@ -590,6 +593,7 @@ <h2>Provider Support Matrix</h2>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
+              <td>Yes</td>
             </tr>
             <tr>
               <td>Streaming</td>
@@ -598,6 +602,7 @@ <h2>Provider Support Matrix</h2>
               <td>SSE</td>
               <td>SSE</td>
               <td>SSE</td>
+              <td>SSE</td>
               <td>Binary EventStream</td>
               <td>SSE</td>
               <td>NDJSON</td>
@@ -609,6 +614,7 @@ <h2>Provider Support Matrix</h2>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
+              <td>&mdash;</td>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
@@ -626,6 +632,7 @@ <h2>Provider Support Matrix</h2>
               <td>&mdash;</td>
               <td>&mdash;</td>
               <td>&mdash;</td>
+              <td>&mdash;</td>
             </tr>
             <tr>
               <td>Response Overrides</td>
@@ -634,6 +641,7 @@ <h2>Provider Support Matrix</h2>
               <td>Yes</td>
               <td>Yes</td>
               <td>Yes</td>
+              <td>Yes</td>
               <td>&mdash;</td>
               <td>Yes<sup>*</sup></td>
               <td>&mdash;</td>