@didim365/agent-cli-core 0.1.0

package/dist/docs/00_project/ai_adapter/working_history/Phase2_M2.2_EventMapper/352/265/254/355/230/204_20260207.md

@@ -0,0 +1,372 @@
+# Phase 2: M2.2 GeminiChat 스트리밍 분해 및 합성기 적용 작업 결과서
+
+> 📅 **작업일**: 2026-02-07 📚 **Phase**: Phase 2 - M2.2 🎯 **목표**: Gemini
+> 스트리밍 이벤트를 프로바이더 독립 이벤트로 매핑 및 스트림 변환 유틸리티 구축
+> 🔗 **이전 작업**:
+> [Phase2_M2.1_ContentGenerator인터페이스재정의\_20260207.md](./Phase2_M2.1_ContentGenerator인터페이스재정의_20260207.md)
+> 🔗 **관련 문서**:
+> [phase2_core_refactoring_todolist.md](../todolist/phase2_core_refactoring_todolist.md) -
+> M2.2
+
+---
+
+## 📋 작업 요약
+
+### 2.2.1 EventMapper 구현 ✅
+
+| 항목                                 | 상태 | 비고                     |
+| ------------------------------------ | :--: | ------------------------ |
+| GeminiEventMapper 클래스 생성        |  ✅  | 451줄                    |
+| Content → TextDelta 매핑             |  ✅  | traceId 전파             |
+| Thought → ThoughtDelta 매핑          |  ✅  | subject/description 반영 |
+| ToolCallRequest 매핑                 |  ✅  | 모든 필드 매핑           |
+| ToolCallResponse 매핑                |  ✅  | responseParts 보존       |
+| ToolCallConfirmation 매핑            |  ✅  | 다형성 처리              |
+| Error/Finished/Retry 매핑            |  ✅  | FinishReason 변환 포함   |
+| 나머지 8개 이벤트 매핑               |  ✅  | 18개 전체 매핑 완료      |
+| 역방향 매핑 (LlmEvent → GeminiEvent) |  ✅  | 12개 이벤트 역방향 지원  |
+
+### 2.2.1 리뷰 수정 ✅
+
+| 이슈                       | 수정 내역                                                      |
+| -------------------------- | -------------------------------------------------------------- |
+| 메서드명 혼란              | `toLlmFinishReasonToGemini` → `toGeminiFinishReason` 이름 변경 |
+| 테스트 커버리지 부족       | 엣지 케이스 9개 추가 (20 → 29 테스트)                          |
+| ToolCallResponse 정보 손실 | `responseParts` 원본 보존 (JSON.stringify 제거)                |
+| 확인 이벤트 기본값 오류    | `confirmed` 미존재시 `false` 반환 (기존 `true`)                |
+| Citation 위치 정보 더미값  | `startIndex`/`endIndex` 생략 (LlmCitation 타입 optional화)     |
+| Agent 이벤트 컨텍스트 손실 | `systemMessage`, `contextCleared` 필드 추가                    |
+| 역방향 매핑 제한           | 에러 메시지에 지원 이벤트 목록 문서화                          |
+
+**추가 엣지 케이스 테스트** (20개 → 29개):
+
+- Finished without usageMetadata
+- SAFETY → content_filter FinishReason 매핑
+- Error without status code
+- ChatCompressed with null value
+- ToolCallResponse with error
+- Unknown GeminiEventType → Error fallback
+- 역방향: Finished → Finished (usage 포함)
+- 역방향: ThoughtDelta → Thought
+- 역방향: 미지원 타입 throw 검증
+
+### 2.2.2 StreamEvent → LlmEvent 전환 ✅
+
+| 항목                                        | 상태 | 비고                                |
+| ------------------------------------------- | :--: | ----------------------------------- |
+| StreamEvent 사용처 전체 스캔                |  ✅  | turn.ts 12개, client.ts 24개 참조점 |
+| 스트림 변환 유틸리티 (`streamConverter.ts`) |  ✅  | 2개 함수 (78줄)                     |
+| `loopDetectionService.addAndCheckLlm()`     |  ✅  | LlmEvent 수용, 기존 상태 공유       |
+| client.ts 마이그레이션 코멘트               |  ✅  | TODO(M2.3) 코멘트 추가              |
+| `StreamEvent` / `addAndCheck` @deprecated   |  ✅  | JSDoc 마킹 완료                     |
+
+### 2.2.2a StreamEventType 통합 전략 ✅
+
+| 항목                                               | 상태 | 비고                               |
+| -------------------------------------------------- | :--: | ---------------------------------- |
+| `StreamEventType` enum 분석                        |  ✅  | 4종, geminiChat.ts 정의            |
+| `CHUNK` 1:N 분해 → 직접 매핑 불가 확인             |  ✅  | 설계 결정: Turn 출력 레벨 변환     |
+| `RETRY/STOPPED/BLOCKED` → 기존 Turn 경유 경로 확인 |  ✅  | GeminiEventType → EventMapper 경로 |
+| `StreamEventType` @deprecated 마킹                 |  ✅  | geminiChat.ts JSDoc 추가           |
+
+### 2.2.3 StreamAssembler 적용 ✅
+
+| 항목                                | 상태 | 비고                               |
+| ----------------------------------- | :--: | ---------------------------------- |
+| GeminiChat 스트림 처리 로직 분석    |  ✅  | Turn → client 파이프라인 파악      |
+| `createGeminiStreamPipeline()` 구현 |  ✅  | EventMapper + StreamAssembler 통합 |
+| `GeminiStreamPipeline` 인터페이스   |  ✅  | stream + assembler 이중 접근       |
+| 텍스트 델타 합성 검증               |  ✅  | 다수 Content → text 연결           |
+| 툴 콜 델타 합성 검증                |  ✅  | 단일/다수 ToolCallRequest 수집     |
+| Usage 정보 누적 검증                |  ✅  | Finished(usageMetadata) → usage    |
+| 통합 테스트                         |  ✅  | 15개 테스트 (geminiStream.test.ts) |
+
+---
+
+## 📁 파일 변경 사항
+
+### 신규 파일
+
+| 파일                                       | 설명                             |
+| ------------------------------------------ | -------------------------------- |
+| `providers/gemini/eventMapper.ts`          | GeminiEventMapper 클래스 (451줄) |
+| `providers/gemini/eventMapper.test.ts`     | EventMapper TDD 테스트 (29개)    |
+| `providers/gemini/streamConverter.ts`      | 스트림 변환 유틸리티 (78줄)      |
+| `providers/gemini/streamConverter.test.ts` | StreamConverter TDD 테스트 (5개) |
+| `providers/gemini/geminiStream.ts`         | 통합 파이프라인 유틸리티 (90줄)  |
+| `providers/gemini/geminiStream.test.ts`    | 통합 파이프라인 테스트 (15개)    |
+
+### 수정 파일
+
+| 파일                                    | 변경 내용                                                                                                     |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `providers/gemini/index.ts`             | GeminiEventMapper, convertGeminiStream, convertGeminiStreamWithReturn, createGeminiStreamPipeline export 추가 |
+| `providers/events.ts`                   | Agent 이벤트 필드 추가, Citation optional화, result 타입 확장                                                 |
+| `services/loopDetectionService.ts`      | `addAndCheckLlm(LlmEvent)` 메서드 추가, `addAndCheck` @deprecated 마킹, LlmEvent import 추가                  |
+| `services/loopDetectionService.test.ts` | addAndCheckLlm 테스트 6개 추가 (47 → 53 테스트)                                                               |
+| `core/geminiChat.ts`                    | `StreamEventType`, `StreamEvent` @deprecated JSDoc 추가                                                       |
+| `core/client.ts`                        | `loopDetector.addAndCheck()` 호출부에 TODO(M2.3) 마이그레이션 코멘트                                          |
+
+---
+
+## 🗺️ 이벤트 매핑 구조
+
+### 정방향 매핑 (18종: Gemini → LlmEvent)
+
+| GeminiEventType           | LlmEventType          |
+| ------------------------- | --------------------- |
+| Content                   | TextDelta             |
+| Thought                   | ThoughtDelta          |
+| ToolCallRequest           | ToolCallRequest       |
+| ToolCallResponse          | ToolCallResponse      |
+| ToolCallConfirmation      | ToolCallConfirmation  |
+| Error                     | Error                 |
+| Finished                  | Finished              |
+| Retry                     | Retry                 |
+| UserCancelled             | UserCancelled         |
+| ChatCompressed            | ChatCompressed        |
+| LoopDetected              | LoopDetected          |
+| MaxSessionTurns           | MaxSessionTurns       |
+| ContextWindowWillOverflow | ContextWindowOverflow |
+| InvalidStream             | InvalidStream         |
+| ModelInfo                 | ModelInfo             |
+| AgentExecutionStopped     | AgentStopped          |
+| AgentExecutionBlocked     | AgentBlocked          |
+| Citation                  | Citation              |
+
+### 역방향 매핑 (12종: LlmEvent → Gemini)
+
+TextDelta, ThoughtDelta, Error, UserCancelled, Retry, LoopDetected,
+MaxSessionTurns, InvalidStream, Finished, AgentStopped, AgentBlocked, ModelInfo
+
+> ToolCallRequest/Response/Confirmation은 역방향 미지원 (context enrichment
+> 필요)
+
+---
+
+## 🏗️ 설계 결정
+
+### StreamEventType.CHUNK 1:N 분해
+
+```
+StreamEvent.CHUNK (GenerateContentResponse)
+  → turn.ts 분해 → N개 GeminiEventType 이벤트
+    → EventMapper → N개 LlmEvent
+```
+
+CHUNK는 `GenerateContentResponse`를 포함하며, Turn이 텍스트/thoughts/tool
+calls/citations 등으로 다수 분해. 따라서 StreamEventType → LlmEvent 직접 매핑은
+불가하며, **변환 경계는 Turn 출력 레벨**(`ServerGeminiStreamEvent` →
+`LlmEvent`)에 설정.
+
+### 스트림 변환 유틸리티
+
+| 함수                                       | 용도                                                             |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `convertGeminiStream()`                    | `AsyncGenerator<ServerGeminiStreamEvent>` → `LlmEventStream`     |
+| `convertGeminiStreamWithReturn<TReturn>()` | return value 보존 (client.ts의 `AsyncGenerator<..., Turn>` 대응) |
+
+### loopDetectionService 이중 지원
+
+`addAndCheck()` (Gemini)와 `addAndCheckLlm()` (LlmEvent)가 동일한 내부 상태
+공유:
+
+- `toolCallRepetitionCount`, `lastToolCallKey`
+- `streamContentHistory`, `contentStats`
+- `loopDetected`, `disabledForSession`
+
+→ 마이그레이션 기간 중 두 API 혼용 가능
+
+---
+
+## ✅ 테스트 결과
+
+### M2.2 전체 테스트
+
+```
+eventMapper.test.ts          : 29 passed
+streamConverter.test.ts      :  5 passed
+loopDetectionService.test.ts : 53 passed (47 기존 + 6 신규)
+geminiStream.test.ts         : 15 passed (M2.2.3 통합 테스트)
+streamAssembler.test.ts      : 22 passed (기존, 회귀 확인)
+────────────────────────────────────────
+합계                          : 124 passed
+```
+
+### TypeScript 컴파일
+
+```
+npx tsc --noEmit -p packages/core/tsconfig.json
+→ 에러 없음 (clean)
+```
+
+---
+
+## 🐛 이슈 및 해결
+
+### 이슈 1: 메서드명 혼란 (`toLlmFinishReasonToGemini`)
+
+- **증상**: 메서드명에 `toLlm`과 `ToGemini`가 동시에 포함되어 방향이 불명확
+- **원인**: 초기 네이밍 시 실수
+- **해결**: `toGeminiFinishReason`으로 이름 변경 (역방향 매핑임을 명확히)
+
+### 이슈 2: 테스트에서 string literal vs enum 타입 불일치
+
+- **증상**: `addAndCheckLlm` 테스트에서 `'tool_call_request' as const` 사용 시
+  TypeScript 에러
+- **원인**: `LlmEvent` 유니온 타입은 `LlmEventType` enum 값을 요구
+- **해결**: 모든 테스트 이벤트에 `LlmEventType.ToolCallRequest` 등 enum 값 사용,
+  `LlmEvent` 타입 어노테이션 추가
+
+---
+
+## 📝 다음 작업
+
+- [x] **M2.2.3**: StreamAssembler 적용 — EventMapper + StreamAssembler 통합
+      파이프라인
+- [x] **M2.2.4**: Gemini 에러 매핑 — errorClassifier + EventMapper isRetryable
+- [ ] **M2.3**: Turn/Client 레벨 LlmEvent 전환 (processTurn → LlmEvent 스트림)
+
+### 다음 작업에 전달할 이슈
+
+| 이슈                                    | 영향                                          | 대응 방안                                     |
+| --------------------------------------- | --------------------------------------------- | --------------------------------------------- |
+| `client.ts`의 24개 GeminiEventType 참조 | M2.3 전환 시 대규모 변경 예상                 | convertGeminiStreamWithReturn 활용            |
+| `turn.ts`의 12개 이벤트 생성점          | Turn 반환 타입 변경 시 영향 범위 큼           | 단계적 전환 (내부 유지 → 출력만 변환)         |
+| `ToolCallResponse.name = ''` 설계       | caller가 ToolCallRequestInfo로 name 보강 필요 | M2.3에서 enrichment 로직 검토                 |
+| `createGeminiStreamPipelineWithReturn`  | client.ts의 Turn return value 보존 필요       | M2.3에서 WithReturn 변형 추가                 |
+| InvalidStream reason 미전파             | turn.ts가 reason 없이 이벤트 생성             | M2.3에서 turn.ts InvalidStreamError.type 전달 |
+
+---
+
+### 2.2.4 Gemini 에러 매핑 ✅
+
+| 항목                             | 상태 | 비고                                   |
+| -------------------------------- | :--: | -------------------------------------- |
+| Gemini SDK 에러 타입 분석        |  ✅  | StructuredError, ApiError, retry.ts    |
+| errorClassifier.ts 구현          |  ✅  | HTTP status → LlmErrorType 매핑        |
+| EventMapper mapErrorEvent 개선   |  ✅  | isRetryable 설정 (classifyGeminiError) |
+| InvalidStream reason 인프라 준비 |  ✅  | types.ts + EventMapper (M2.3 연동용)   |
+| Rate limit 매핑 (429)            |  ✅  | RATE_LIMIT, isRetryable: true          |
+| Auth 매핑 (401/403)              |  ✅  | AUTHENTICATION, isRetryable: false     |
+| index.ts export 추가             |  ✅  | classifyGeminiError, type 내보내기     |
+
+**신규 파일**:
+
+| 파일                                       | 설명                        |
+| ------------------------------------------ | --------------------------- |
+| `providers/gemini/errorClassifier.ts`      | Gemini 에러 분류기 (~70줄)  |
+| `providers/gemini/errorClassifier.test.ts` | 에러 분류 TDD 테스트 (10개) |
+
+**수정 파일**:
+
+| 파일                                   | 변경 내용                                                        |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `providers/gemini/eventMapper.ts`      | mapErrorEvent에 isRetryable, mapInvalidStreamEvent에 reason 전파 |
+| `providers/gemini/eventMapper.test.ts` | isRetryable 테스트 4개 + InvalidStream reason 테스트 2개 추가    |
+| `providers/gemini/types.ts`            | ServerGeminiInvalidStreamEvent에 optional reason 추가            |
+| `providers/gemini/index.ts`            | classifyGeminiError, GeminiErrorClassification export 추가       |
+
+---
+
+### 2.2.5 Telemetry 포맷 변경 ✅
+
+| 항목                               | 상태 | 비고                                         |
+| ---------------------------------- | :--: | -------------------------------------------- |
+| 현재 Telemetry semantic 분석       |  ✅  | types.ts 4개, semantic.ts 6개 @google/genai  |
+| `LlmTokenUsage` 확장               |  ✅  | `thoughtTokens`, `toolTokens` optional 추가  |
+| `llmTokenUsageToGenAIUsage()` 구현 |  ✅  | LlmTokenUsage → GenAIUsageDetails 변환       |
+| `genAIUsageToLlmTokenUsage()` 구현 |  ✅  | GenAIUsageDetails → LlmTokenUsage 역변환     |
+| `ProviderApiResponseEvent` 구현    |  ✅  | LlmTokenUsage 수용 + provider 필드           |
+| `ProviderApiErrorEvent` 구현       |  ✅  | provider 필드 포함 에러 이벤트               |
+| index.ts export 추가               |  ✅  | telemetryBridge 내보내기                     |
+| 라운드트립 변환 검증               |  ✅  | LlmTokenUsage ↔ GenAIUsageDetails 왕복 일치 |
+
+**신규 파일**:
+
+| 파일                                | 설명                               |
+| ----------------------------------- | ---------------------------------- |
+| `providers/telemetryBridge.ts`      | provider-agnostic telemetry 브릿지 |
+| `providers/telemetryBridge.test.ts` | TDD 테스트 (13개)                  |
+
+**수정 파일**:
+
+| 파일                 | 변경 내용                                            |
+| -------------------- | ---------------------------------------------------- |
+| `providers/types.ts` | `LlmTokenUsage`에 `thoughtTokens`, `toolTokens` 추가 |
+| `providers/index.ts` | telemetryBridge export 추가                          |
+
+**Telemetry `@google/genai` 의존성 분석 결과**:
+
+| 파일                    | @google/genai imports                                                                   | M2.2.5 범위      | 잔여 (M2.7)                |
+| ----------------------- | --------------------------------------------------------------------------------------- | ---------------- | -------------------------- |
+| `telemetry/types.ts`    | `Content`, `Candidate`, `GenerateContentConfig`, `GenerateContentResponseUsageMetadata` | UsageMetadata ✅ | Content, Candidate, Config |
+| `telemetry/semantic.ts` | `FinishReason`, `Candidate`, `Content`, `ContentUnion`, `Part`, `PartUnion`             | —                | 전체 (M2.7)                |
+
+---
+
+## ✅ 테스트 결과
+
+### M2.2 전체 테스트
+
+```
+telemetryBridge.test.ts      : 13 passed (M2.2.5 신규)
+errorClassifier.test.ts      : 10 passed (기존, 회귀 확인)
+eventMapper.test.ts          : 35 passed (기존, 회귀 확인)
+streamConverter.test.ts      :  5 passed (기존, 회귀 확인)
+loopDetectionService.test.ts : 53 passed (기존, 회귀 확인)
+geminiStream.test.ts         : 15 passed (기존, 회귀 확인)
+streamAssembler.test.ts      : 22 passed (기존, 회귀 확인)
+────────────────────────────────────────
+합계                          : 153 passed
+```
+
+### providers/ 전체 테스트
+
+```
+providers/ 디렉토리 전체: 297 passed (18 test files)
+```
+
+### TypeScript 컴파일
+
+```
+npx tsc --noEmit -p packages/core/tsconfig.json
+→ 에러 없음 (clean)
+```
+
+---
+
+## 🔖 커밋 정보
+
+| 순서 | 커밋 ID     | 설명                                                |
+| ---- | ----------- | --------------------------------------------------- |
+| 1    | `819cadbd8` | M2.2.1 리뷰 수정 + M2.2.2 스트림 변환 + @deprecated |
+| 2    | `06e426ae5` | M2.2.3 StreamAssembler 적용 — 통합 파이프라인       |
+| 3    | `128ede2b9` | M2.2.4 Gemini 에러 매핑 — errorClassifier 구현      |
+| 4    | 3af6fbfb6   | M2.2.5 Telemetry 포맷 변경 — telemetryBridge 구현   |
+
+---
+
+## ✅ 완료 기준 체크
+
+- [x] 모든 테스트 통과 (153개 M2.2 + 297개 providers/)
+- [x] TypeScript 컴파일 에러 없음
+- [x] 체크리스트 최종 확인 (2.2.1 ✅, 2.2.2 ✅, 2.2.2a ✅, 2.2.3 ✅, 2.2.4 ✅,
+      2.2.5 ✅)
+- [x] 작업 결과서 업데이트
+- [x] 커밋: 3af6fbfb6 (feat), f92e7ac79 (docs)
+- [x] 이슈 전달: 다음 작업(M2.3)에 전달할 이슈 문서화
+
+---
+
+### 다음 작업에 전달할 이슈 (M2.2.5 추가분)
+
+| 이슈                                             | 영향                                                   | 대응 방안                                              |
+| ------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ |
+| `telemetry/types.ts` Content/Candidate 잔여 결합 | ApiRequestEvent, ApiResponseEvent 시그니처 Gemini 전용 | M2.7에서 Provider-agnostic prompt/response 스키마 도입 |
+| `telemetry/semantic.ts` 전체 Gemini 결합         | toInputMessages/toOutputMessages 등 Part 기반          | M2.7에서 LlmContent 기반 변환기로 교체                 |
+| `loggingContentGenerator.ts` Gemini 타입 사용    | ApiResponseEvent 생성 시 UsageMetadata 직접 전달       | M2.3에서 ProviderApiResponseEvent 사용으로 전환        |
+
+---
+
+**최종 상태**: ✅ M2.2 전체 완료 (2.2.1~2.2.5)

package/dist/docs/00_project/ai_adapter/working_history/Phase2_M2.3_GeminiAdapter/352/265/254/355/230/204_20260208.md

@@ -0,0 +1,205 @@
+# Phase 2: M2.3 GeminiAdapter 구현 및 동등성 검증 작업 결과서
+
+> 📅 **작업일**: 2026-02-08 📚 **Phase**: Phase 2 - M2.3 🎯 **목표**:
+> GeminiAdapter/Converter 구현 + 레거시 경로와 동등성 검증 + 기능 플래그 🔗
+> **이전 작업**:
+> [Phase2_M2.2_EventMapper구현\_20260207.md](./Phase2_M2.2_EventMapper구현_20260207.md)
+> 🔗 **관련 문서**:
+> [phase2_core_refactoring_todolist.md](../todolist/phase2_core_refactoring_todolist.md) -
+> M2.3
+
+---
+
+## 📋 작업 요약
+
+### 2.3.2 GeminiConverter ✅
+
+| 항목                                                               | 상태 | 비고                                     |
+| ------------------------------------------------------------------ | :--: | ---------------------------------------- |
+| toGeminiContents (LlmMessage[] → Content[])                        |  ✅  | system/user/assistant 분리               |
+| toGeminiParts (LlmContent[] → Part[])                              |  ✅  | text/image/tool_call/tool_result/thought |
+| toGeminiRequest (LlmGenerateRequest → GenerateContentParameters)   |  ✅  | config 내부에 모든 설정 배치             |
+| toGeminiTools (LlmToolDefinition[] → Tool[])                       |  ✅  | functionDeclarations 래핑                |
+| toGeminiToolConfig (LlmToolChoice → ToolConfig)                    |  ✅  | auto/none/required/specific              |
+| fromGeminiResponse (GenerateContentResponse → LlmGenerateResponse) |  ✅  | text/functionCall/inlineData             |
+| fromGeminiParts (Part[] → LlmContent[])                            |  ✅  | 역방향 변환                              |
+| mapStopReason (FinishReason → LlmStopReason)                       |  ✅  | STOP/MAX_TOKENS/SAFETY/RECITATION        |
+
+**테스트**: 33개 (geminiConverter.test.ts)
+
+### 2.3.1 GeminiAdapter ✅
+
+| 항목                            | 상태 | 비고                                            |
+| ------------------------------- | :--: | ----------------------------------------------- |
+| BaseAdapter 상속                |  ✅  | providerName='gemini'                           |
+| GeminiModelsApi DI 인터페이스   |  ✅  | generateContent/Stream/countTokens/embedContent |
+| generateContent (non-streaming) |  ✅  | converter 경유, validateRequest                 |
+| generateContentStream           |  ✅  | AsyncGenerator<LlmEvent>, bind 패턴             |
+| countTokens                     |  ✅  | override + models.countTokens 위임              |
+| capabilities 선언               |  ✅  | streaming/tools/image/embedding/thought 지원    |
+| config validation               |  ✅  | null config 거부, apiKey 없이도 허용 (ADC)      |
+
+**테스트**: 15개 (geminiAdapter.test.ts)
+
+### 2.3.3 동등성 검증 ✅
+
+| 항목                       | 상태 | 비고                                   |
+| -------------------------- | :--: | -------------------------------------- |
+| 2.3.3.1 기본 대화 동등성   |  ✅  | content/stopReason/usage 비교          |
+| 2.3.3.2 스트리밍 동등성    |  ✅  | text_delta/finished 이벤트 비교        |
+| 2.3.3.3 도구 호출 동등성   |  ✅  | name/arguments 일치 검증               |
+| 2.3.3.4 이미지 입력 동등성 |  ✅  | inlineData 변환 일치 검증              |
+| 2.3.3.5 에러 처리 동등성   |  ✅  | 에러 분류/retryable 일치               |
+| 2.3.3.6 Rate limit 동등성  |  ✅  | 429/503 retryable 검증                 |
+| 2.3.3.7 18개 이벤트 동등성 |  ✅  | 전체 GeminiEventType→LlmEventType 매핑 |
+
+**테스트**: 37개 (geminiParity.test.ts)
+
+### 2.3.4 기능 플래그 ✅
+
+| 항목                                 | 상태 | 비고                            |
+| ------------------------------------ | :--: | ------------------------------- |
+| 2.3.4.1 ENABLE_MULTI_PROVIDER 플래그 |  ✅  | env var 기반, true/1/false/0    |
+| 2.3.4.2 플래그 기반 경로 분기        |  ✅  | legacy vs new 경로 분기         |
+| 2.3.4.3 런타임 전환 테스트           |  ✅  | setMultiProviderOverride/clear  |
+| 2.3.4.4 폴백 로직 구현               |  ✅  | withFallback(primary, fallback) |
+
+**테스트**: 16개 (featureFlag.test.ts)
+
+---
+
+## 📊 검증 결과
+
+| 검증 항목           |       결과        | 비고                                |
+| ------------------- | :---------------: | ----------------------------------- |
+| 전체 테스트         | ✅ 4720/4720 pass | 기존 4610 + 신규 110 (리뷰 수정 후) |
+| TypeScript 컴파일   |      ✅ 클린      | tsc --noEmit 0 errors               |
+| ESLint              |      ✅ 통과      | pre-commit hook 통과                |
+| 기존 기능 100% 동작 |        ✅         | 기존 테스트 전체 통과               |
+| 18개 이벤트 동등성  |        ✅         | 전체 매핑 검증 완료                 |
+| 기능 플래그 연결    |        ✅         | 프로덕션 실행 경로 연결 확인        |
+
+---
+
+## 📁 파일 목록
+
+### 신규 생성
+
+| 파일                                       | 용도                           | LOC  |
+| ------------------------------------------ | ------------------------------ | ---- |
+| `providers/gemini/converter.ts`            | Llm ↔ Gemini SDK 타입 변환기  | ~340 |
+| `providers/gemini/adapter.ts`              | BaseAdapter 확장 Gemini 어댑터 | ~210 |
+| `providers/gemini/featureFlag.ts`          | 멀티 프로바이더 기능 플래그    | ~75  |
+| `providers/gemini/geminiConverter.test.ts` | Converter TDD 테스트           | ~575 |
+| `providers/gemini/geminiAdapter.test.ts`   | Adapter TDD 테스트             | ~320 |
+| `providers/gemini/geminiParity.test.ts`    | 동등성 검증 테스트             | ~570 |
+| `providers/gemini/featureFlag.test.ts`     | 기능 플래그 테스트             | ~155 |
+| `providers/gemini/adapterBridge.ts`        | 기능 플래그 → 실행 경로 연결   | ~105 |
+| `providers/gemini/adapterBridge.test.ts`   | AdapterBridge TDD 테스트       | ~227 |
+
+### 수정
+
+| 파일                        | 변경 내용                                                         |
+| --------------------------- | ----------------------------------------------------------------- |
+| `providers/gemini/index.ts` | GeminiAdapter, GeminiConverter, featureFlag, adapterBridge export |
+| `core/contentGenerator.ts`  | createAdapterBridge 연결 (googleGenAI.models 래핑)                |
+
+---
+
+## 🔑 핵심 설계 결정
+
+### 1. GenerateContentParameters SDK 구조
+
+**문제**: 설계 문서(§3.3.2)의 API shape과 실제 SDK 타입이 다름 **해결**:
+`node_modules/@google/genai/dist/genai.d.ts` 직접 확인 후 수정
+
+```
+실제 구조: { model, contents, config?: GenerateContentConfig }
+config 내부: systemInstruction, tools, toolConfig, temperature, maxOutputTokens, ...
+```
+
+### 2. GeminiModelsApi DI 인터페이스
+
+테스트에서 실제 SDK 인스턴스 없이 모킹 가능하도록 인터페이스 추출.
+`Record<string, unknown>` 파라미터 타입으로 SDK 타입 변환 단순화.
+
+### 3. no-this-alias ESLint 규칙
+
+`const self = this` 대신 `bind(this)` 패턴 사용:
+
+```typescript
+const convertChunk = this.convertChunkToEvents.bind(this);
+```
+
+### 4. ContentListUnion 타입 처리
+
+SDK의 `contents` 필드가 `ContentListUnion` (union type)이라 배열 인덱스 접근
+불가. 테스트에서 `as Array<{ parts?: unknown[] }>` 캐스팅으로 해결.
+
+---
+
+## 🔄 리뷰 후 수정 사항
+
+### 이슈: 기능 플래그 프로덕션 코드 미연결
+
+**지적 내용**: `isMultiProviderEnabled()`와 `withFallback()`가
+테스트/re-export에서만 사용되고, 실제 실행 경로에 연결되지 않음. 플래그 ON/OFF가
+실행 경로를 변경하지 않음.
+
+**검증 결과**: 확인됨 — grep 결과 featureFlag.ts, featureFlag.test.ts,
+index.ts에서만 참조.
+
+**수정 내용**:
+
+| 항목                       | 상태 | 비고                                               |
+| -------------------------- | :--: | -------------------------------------------------- |
+| `adapterBridge.ts` 신규    |  ✅  | createAdapterBridge 함수, BridgeableGenerator 타입 |
+| `adapterBridge.test.ts`    |  ✅  | 10개 테스트 (flag ON/OFF, legacy/llm\* 검증)       |
+| `contentGenerator.ts` 수정 |  ✅  | createAdapterBridge 실행 경로 연결                 |
+| `index.ts` export 추가     |  ✅  | createAdapterBridge, BridgeableGenerator           |
+
+**실행 경로 변경**:
+
+```
+Before: googleGenAI.models → LoggingContentGenerator
+After:  googleGenAI.models → createAdapterBridge → LoggingContentGenerator
+        (flag OFF: 패스스루, flag ON: llm* 메서드 추가)
+```
+
+**검증**: 4720/4720 tests pass, TypeScript clean
+
+---
+
+## ⚠️ 다음 마일스톤 이월 사항
+
+### M2.4로 이월
+
+| 항목                                                  | 우선순위 | 비고                              |
+| ----------------------------------------------------- | -------- | --------------------------------- |
+| ModelConfigService LlmGenerateConfig 호환             | 높음     | GenerateContentConfig 의존성 해결 |
+| loggingContentGenerator ProviderApiResponseEvent 전환 | 중간     | M2.2에서 이월                     |
+| client.ts GeminiEventType 참조 정리                   | 중간     | M2.2에서 이월                     |
+| turn.ts 이벤트 생성점 전환                            | 중간     | M2.2에서 이월                     |
+
+---
+
+## 📌 커밋 정보
+
+| 커밋 | 해시      | 설명                                                    |
+| ---- | --------- | ------------------------------------------------------- |
+| feat | 91a8f1e5e | feat(providers): M2.3 GeminiAdapter 구현 및 동등성 검증 |
+| docs | 58fd15b1c | docs: M2.3 작업 결과서 및 체크리스트 업데이트           |
+| feat | a5a81c60e | feat(providers): M2.3 리뷰 수정 — AdapterBridge 연결    |
+| docs | 15f69a79c | docs: M2.3 작업 결과서 리뷰 수정 사항 반영              |
+
+---
+
+## ✅ 체크리스트
+
+- [x] 본작업 완료: 2.3.1 + 2.3.2 + 2.3.3 + 2.3.4
+- [x] 테스트: 101개 신규, 398개 전체 통과
+- [x] TypeScript 컴파일: 클린
+- [x] ESLint: 통과 (pre-commit hook)
+- [x] 커밋: 91a8f1e5e (feat), 58fd15b1c (docs)
+- [x] 리뷰 이슈 수정: adapterBridge 추가, contentGenerator.ts 연결
+- [x] 리뷰 수정 후 검증: 4720/4720 tests, TS clean