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

[jpr5]

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

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@copilotkit/aimock@139

commit: be60203

[tombeckenham]

Tried wiring this into TanStack AI's E2E suite (uses geminiTextInteractions() from @tanstack/ai-gemini/experimental, which serializes via the official @google/genai SDK types) and hit a wire-format mismatch: every request with Turn[] input returns 404 No fixture matched even when the fixture's userMessage is correct.

Root cause

src/gemini-interactions.ts (~lines 100–114) reads turn.parts when parsing Turn[] input. But the SDK's Interactions.Turn type is:

interface Turn {
  role?: string
  content?: string | Array<Content_2>
}

— the field is content, not parts. When turn.parts is undefined, the code falls into the empty-content branch and pushes { role: "user", content: "" }, so userMessage matching never finds the actual text.

Repro (your PR's aimock + a single fixture matching userMessage: "hello")

# 1. String input — matches ✅
curl -s -X POST :4011/v1beta/interactions -H 'content-type: application/json' \
  -d '{"model":"gemini-2.5-flash","input":"hello","stream":false}'

# 2. Turn[] with .parts — matches ✅ (what aimock expects today)
curl -s -X POST :4011/v1beta/interactions -H 'content-type: application/json' \
  -d '{"model":"gemini-2.5-flash","input":[{"role":"user","parts":[{"type":"text","text":"hello"}]}],"stream":false}'

# 3. Turn[] with .content — misses ❌ (what the official SDK actually sends)
curl -s -X POST :4011/v1beta/interactions -H 'content-type: application/json' \
  -d '{"model":"gemini-2.5-flash","input":[{"role":"user","content":[{"type":"text","text":"hello"}]}],"stream":false}'
# {"error":{"code":"NOT_FOUND","message":"No fixture matched"}}

The 60 new unit tests all pass because they use the parts shape — i.e. they're testing a shape no real SDK consumer can produce.

Suggested fix

1. In geminiInteractionsToCompletionRequest, prefer turn.content (matching the SDK), and treat string-vs-array on content like the current code treats parts. Optional fallback to parts for any pre-existing hand-written fixtures.
2. Update gemini-interactions.test.ts Turn-shaped inputs to { role, content: [...] }.
3. Re-record any captured fixtures against the real Gemini API to lock the actual wire format.

Happy to follow up with a patch if useful — once that lands the TanStack stateful-interactions.spec.ts E2E should pass; the rest of the integration (interactionId surfaced via the gemini.interactionId CUSTOM event, chained on the next turn via modelOptions.previous_interaction_id) is wired up and exercises both fixtures end-to-end.

[jpr5]

@tombeckenham Back to you sir. LMK.