후속(provider): Gemini Interactions API 채택 스파이크 — generateContent 대비 이점/비용 평가

[pdw96]

배경 / 문제

현재 Google provider 는 Gemini generateContent / streamGenerateContent REST 엔드포인트 위에 직접 구현돼 있다.

• 엔드포인트·요청 빌드: src/main/core/providers/google.ts:23 (BASE = '.../v1beta/models'), src/main/core/providers/google.ts:362 (method = streaming ? 'streamGenerateContent?alt=sse' : 'generateContent'), :364 (url = ${BASE}/${model}:${method}).
• 요청 본문 조립(contents / systemInstruction / generationConfig / tools / toolConfig)은 src/main/core/providers/google.ts:325–358.
• 응답 파싱(버퍼)·SSE 스트림 파싱은 각각 src/main/core/providers/google.ts:383–418, readStream :203–300.
• thinkingConfig 세대별 방언 정규화(2.5=thinkingBudget·3=thinkingLevel)는 src/main/core/providers/google.ts:60–76, thoughtSignature verbatim 왕복은 mapParts :126–174 및 toToolUse :108–112.

이 구현은 generateContent 의 stateless 한 "매 호출 전체 대화 재전송" 모델에 묶여 있다. Gemini Interactions API 는 (컷오프 갭 분석에서 신규로 식별된) 서버측 상태/멀티턴을 다르게 다루는 별도 표면으로, 채택 시 위 요청 빌드·응답 파싱 전반이 영향을 받는다. 다만 현 시점에서 Interactions API 채택이 실제로 어떤 측정 가능한 이점을 주는지(레이턴시·토큰·코드 단순화)와 마이그레이션 비용이 정량적으로 확인되지 않았다. 이 이슈는 구현이 아니라 스파이크(평가) 성격이다.

추가로 확인된 사실: provider 추상화 경계(ApiProvider.chat → ChatResult, src/main/core/providers/types.ts:124,:206)가 와이어 포맷을 완전히 캡슐화한다. 호출자(loop.ts·api-session.ts)는 ChatResult 만 소비하고 엔드포인트를 모른다. 즉 마이그레이션이 일어나더라도 표면은 google.ts 한 파일에 격리된다(registry.ts:18 의 분기만 그대로 사용).

범위

스파이크(구현 전 평가)에 한정한다.

• Gemini Interactions API 의 현재 wire 계약 확인 — 엔드포인트, 요청/응답 스키마, 스트리밍 방식, 인증(x-goog-api-key 동일 여부). context7 / ai.google.dev 1차 출처로 컷오프 이후 현행 문서 검증(이름·존재 여부 포함 — 아래 근거의 refute 가능성 참조).
• 현 generateContent 경로가 의존하는 기능들이 Interactions 에서 동등 지원되는지 매핑: function calling(tools/toolConfig), 구조화 출력(responseSchema+400 폴백 sendWithSchemaFallback), thinkingConfig 세대별 방언, thoughtSignature verbatim 왕복, SSE 스트리밍 델타, usage 메타, 프롬프트 차단(promptFeedback) 표면화.
• 이점 정량화: stateless 전체 재전송 대비 입력 토큰/레이턴시 절감, 코드 단순화(예: mapParts thoughtSignature 왕복 로직 축소 여부) 측정 또는 추정.
• 마이그레이션 비용 추정: google.ts 변경 범위, providers.test.ts 의 Google 테스트(약 60+ 케이스, :1140–2264) 재작성 규모, ChatResult 계약 무회귀 보장 가능성.
• 결론 산출: 채택/보류/드롭 권고 + (채택 시) 후속 구현 이슈 분할안. 스파이크 결과를 이 이슈 또는 메타: 백로그 우선순위 / 로드맵 (코드 검증 기반) #27 에 기록.

근거

• 점수(7차 재랭킹): value 3 / effort 5 / risk 4 — Later(큰 작업) 등급.
• 우선순위: 낮음. effort 5(전체 요청/응답 경로 재작성·테스트 대량 재작성)와 risk 4(검증된 thoughtSignature 왕복·구조화 출력 폴백·스트림 파싱이 회귀에 노출)가 value 3 을 압도한다. 7차 재랭킹의 Now/Next 착수순(anthropic 1h-cache-ttl → gemini① 2.5-budget → dev-hygiene#14)에 들지 못한 후순위 항목이다.
• 정직한 downgrade/refute 이력: 이 항목은 2026-06-15 컷오프 갭 분석에서 "Gemini Interactions API"로 신규 등재됐으나, 같은 분석의 종합 시사점이 "신규 다수 refuted/강제함수0 → 진짜 무블록 가치는 typed-linting/react-hooks/safeStorage" 였다. 즉 컷오프 신규 항목 다수가 실제 갭 검증에서 기각·강등됐고, 본 항목도 "큰 작업" Later 로 분류돼 보수적으로 다뤄야 한다.
• 코드가 로드맵 노트와 충돌하지 않음: 노트의 "현 generateContent 경로 대비 이점/마이그레이션 비용을 스파이크로 평가" 전제는 코드와 일치한다(google.ts 가 generateContent 기반임을 :23,:362 에서 확인). 다만 "Interactions API"의 현행 존재·정확한 이름·성숙도는 코드로 검증 불가하므로, 스파이크 1단계에서 1차 출처로 반드시 재확인해야 한다(모델 capability 갭은 착수 전 현행 문서로 검증한다는 메모리 규율 적용). 만약 해당 API 가 부재/미성숙/이점 미미로 확인되면 이 이슈는 드롭한다.

의존성

없음. (provider 추상화가 와이어를 격리하므로 다른 이슈를 블로킹하지 않으며, 다른 이슈에 의해 블로킹되지도 않는다. 단, 코드 변경 충돌을 피하려면 gemini① 2.5-budget thinkingBudget 후속이 resolveThinkingConfig :67 를 건드린 뒤 착수하는 편이 깔끔하다 — 강제 의존은 아님.)

완료 조건

• Interactions API 의 현행 wire 계약과 generateContent 대비 기능 동등성 매핑이 1차 출처 근거와 함께 문서화됨.
• 이점(토큰/레이턴시/코드 단순화)과 마이그레이션 비용(코드·테스트 규모)이 정량 또는 명시적 추정으로 제시됨.
• 채택/보류/드롭 권고가 근거와 함께 기록됨. 채택 권고 시 후속 구현 이슈로 분할되고, 이 이슈는 스파이크로 클로즈됨.
• (스파이크이므로) 프로덕션 코드·테스트 변경 없음 — google.ts 는 건드리지 않는다.

참조

• 코드: src/main/core/providers/google.ts (전체 — 특히 :23,:60–76,:126–174,:203–300,:325–418), src/main/core/providers/registry.ts:18, src/main/core/providers/types.ts:124,:206,:240(sendWithSchemaFallback).
• 테스트(마이그레이션 영향 규모 기준): src/main/core/providers/providers.test.ts:1140–2264 (Google 케이스 다수).
• 로드맵: 이슈 메타: 백로그 우선순위 / 로드맵 (코드 검증 기반) #27 — "컷오프 신규 하이라이트: … Gemini Interactions API …", Later 티어 "Gemini Interactions API · MCP Tasks · MCP Streamable HTTP transport".
• 외부 문서(스파이크 시 검증): ai.google.dev Gemini API 레퍼런스 / @google/genai SDK — context7 우선.

[pdw96]

8차 재랭킹(2026-06-18) Drop 확정. context7 현행 문서 + 코드 대조:

• Gemini Interactions API 는 실재하나 pre-GA Beta.
• server-side state(previous_interaction_id 등)가 Fleet 의 stateless ChatTurn[] 계약(src/main/core/providers/types.ts:218-219)·loop-owned client-side context(loop.ts 매 턴 전체 history 재전송)와 구조적 충돌. feat(context-management): provider-중립 context management — 도구루프 turns 누적 경계 (#27 cutoff-gap) #64 context_management 와도 충돌.
• 강제 함수(must-have) 0 · provider 추상화가 generateContent 위에 안정적 → 측정 가능한 이점 부재.
  ∴ tier:later → drop. 권위 기록 = 메타: 백로그 우선순위 / 로드맵 (코드 검증 기반) #27 「## 코드 검증 핵심 통찰 (8차)」.