@didim365/agent-cli-core 0.1.0 → 0.1.2

package/dist/docs/ai_adapter/working_history/Phase3_M3.2.B_OpenAIStreamConverter_20260210.md

@@ -1,204 +0,0 @@
-# M3.2.B 작업 결과서 — OpenAI 스트림 변환기 구현
-
-- **작업일**: 2026-02-10
-- **브랜치**: `DID/v0.1`
-- **상태**: ✅ 완료
-
-## 작업 목표
-
-M3.2.A에서 스텁(`[]` 반환)으로 남겨둔 `convertStreamEvent()`를 TDD로 완전
-구현하고, `supportsStreaming`을 `true`로 전환하여 OpenAI 스트리밍을 활성화한다.
-
-1. `OpenAiStreamState` 확장 (`finishedEmitted` 플래그)
-2. `convertStreamEvent()` 완전 구현 (text delta, tool call 축적/발행, finish
-   reason, usage-only 청크)
-3. `supportsStreaming: true` + capability 가드 제거
-4. 테스트 25건 추가 + adapter 스트리밍 테스트 3건 추가
-
-## 사전 분석
-
-### OpenAI vs Claude 스트림 구조 차이
-
-| 항목                | Claude                                                  | OpenAI                                                        |
-| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
-| Tool call 시작/종료 | `content_block_start` / `content_block_stop`            | 없음 — `delta.tool_calls[].index`로 추적                      |
-| Tool call 발행 시점 | `content_block_stop` 마다 개별 발행                     | `finish_reason='tool_calls'`에서 일괄 발행                    |
-| Usage 위치          | `message_start` (input) + `message_delta` (output)      | 최종 청크의 `usage` 필드 (단일)                               |
-| Finished/MessageEnd | `message_delta` → Finished, `message_stop` → MessageEnd | `finish_reason` 청크 → Finished, usage-only 청크 → MessageEnd |
-
-### 핵심 설계 결정
-
-1. **Tool call 발행**: `finish_reason='tool_calls'` 시 state에 축적된 모든 tool
-   call 일괄 발행
-2. **Finished 이벤트**: `finish_reason` 비null 시 즉시 발행 (usage 없이)
-3. **MessageEnd 이벤트**: usage-only 최종 청크(빈 `choices[]` + `usage`)에서
-   usage와 함께 발행
-4. **`extractUsage` 재사용**: 기존 private 메서드가 `response['usage']` 드릴다운
-   → 청크 전체를 `{ usage }` 형태로 전달하면 동일 동작
-5. **`finishedEmitted` 플래그**: usage-only 청크에서 Finished 중복 발행 방지
-
-## 작업 순서 및 결과
-
-| 순서 | 작업                                        | 테스트 수        | 결과     |
-| ---- | ------------------------------------------- | ---------------- | -------- |
-| 1    | Tidy First: State 확장 (구조적 변경)        | 1 (기존 수정)    | 40 PASS  |
-| 2    | RED: converter.test.ts 스트림 테스트 25건   | +25              | 19 FAIL  |
-| 3    | GREEN: convertStreamEvent 구현              | 65               | 65 PASS  |
-| 4    | Adapter: streaming 활성화 + 테스트 업데이트 | +3 (기존 2 삭제) | 30 PASS  |
-| 5    | Quality Gate                                | 102 + 673        | ALL PASS |
-
-## 변경 파일 상세
-
-### 수정 파일
-
-| 파일                                 | 변경 내용                                                                                           |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| `providers/openai/converter.ts`      | `OpenAiStreamState.finishedEmitted` 추가, `convertStreamEvent()` 완전 구현, 3개 private helper 추가 |
-| `providers/openai/converter.test.ts` | 스트림 변환 테스트 25건 추가, import 확장                                                           |
-| `providers/openai/adapter.ts`        | `supportsStreaming: true`, capability 가드 제거, 미사용 import 정리                                 |
-| `providers/openai/adapter.test.ts`   | capability 테스트 `true`로 변경, guard 테스트 → streaming 동작 테스트 3건 교체                      |
-
-### 구현 상세 — converter.ts
-
-**신규 필드**: `OpenAiStreamState.finishedEmitted: boolean`
-
-**신규 메서드**:
-
-- `convertStreamEvent()` — 메인 스트림 변환 로직
-- `handleUsageOnlyChunk()` — 빈 choices + usage → Finished(조건부) + MessageEnd
-- `accumulateToolCalls()` — index 기반 tool call delta 축적
-- `emitToolCalls()` — state의 모든 tool call → ToolCallRequest 이벤트로 변환
-
-**변환 로직 순서**:
-
-1. `choices` 없음 → 빈 배열 (malformed 방어)
-2. `choices[]` 비어있음 + `usage` 있음 → `handleUsageOnlyChunk`
-3. `choices[]` 비어있음 + `usage` 없음 → 빈 배열
-4. `delta.content` 비empty → TextDelta
-5. `delta.tool_calls` 있음 → `accumulateToolCalls`
-6. `finish_reason` 비null:
-   - `'tool_calls'` / `'function_call'` → `emitToolCalls` + Finished
-   - 기타 → Finished (기존 `mapFinishReason` 재사용)
-7. `finishedEmitted = true` 설정
-
-## 테스트 현황
-
-### converter.test.ts — 65 tests (기존 40 + 신규 25)
-
-| 카테고리                  | 테스트 수 | 검증 내용                                                         |
-| ------------------------- | --------- | ----------------------------------------------------------------- |
-| (기존) Request/Response   | 40        | M3.2.A에서 구현된 테스트 유지                                     |
-| Text delta (T1-T5)        | 5         | non-null→TextDelta, null→빈, empty→빈, role-only→빈, content+role |
-| Tool call 축적 (T6-T9)    | 4         | init state, arguments 축적, 연속 append, 병렬 index 추적          |
-| Tool call 발행 (T10-T13)  | 4         | finish_reason=tool_calls, 병렬 일괄, invalid JSON→{}, empty→{}    |
-| Finish reason (T14-T17)   | 4         | stop→end_turn, length→max_tokens, content_filter, flag 확인       |
-| Usage-only 청크 (T18-T21) | 4         | MessageEnd+usage, Finished미발행→둘다, cached_tokens, usage없음   |
-| 통합 시퀀스 (T22-T23)     | 2         | 텍스트 전체 스트림, tool call 전체 스트림                         |
-| 엣지 케이스 (T24-T25)     | 2         | 빈 객체, choices undefined                                        |
-
-### adapter.test.ts — 30 tests (기존 27 - 2 삭제 + 3 추가 + 2 수정)
-
-| 변경 | 상세                                                                           |
-| ---- | ------------------------------------------------------------------------------ |
-| 수정 | capability `supportsStreaming` 기대값 `false` → `true`                         |
-| 삭제 | UnsupportedFeatureError guard 테스트 2건 (더 이상 guard 없음)                  |
-| 추가 | SDK stream 파라미터 검증 (stream=true, stream_options), 에러 yield, validation |
-
-## Quality Gate
-
-| 항목          | 결과                     |
-| ------------- | ------------------------ |
-| TypeCheck     | ✅ PASS                  |
-| ESLint        | ✅ PASS                  |
-| OpenAI 테스트 | ✅ 3 files / 102 passed  |
-| Provider 회귀 | ✅ 33 files / 673 passed |
-
-**변화**: 33 files / 647 → 33 files / 673 (+26 tests: 스트림 25 + adapter 1)
-
-## 설계 결정
-
-### Tool call 일괄 발행 (vs Claude 개별 발행)
-
-- **결정**: `finish_reason='tool_calls'` 시점에 state 축적된 모든 tool call
-  한번에 발행
-- **근거**: OpenAI API는 Claude와 달리 `content_block_stop` 이벤트가 없음. Tool
-  call 완성 시점을 알 수 있는 유일한 시그널이 `finish_reason`. index 정렬하여
-  순서 보장.
-
-### extractUsage 재사용
-
-- **결정**: 비스트림 `fromOpenAiResponse`용으로 작성된 `extractUsage()`를
-  스트림에서도 `{ usage }` 래핑하여 재사용
-- **근거**: OpenAI usage 구조가 비스트림/스트림 동일 (`prompt_tokens`,
-  `completion_tokens`, `prompt_tokens_details.cached_tokens`). DRY 원칙.
-
-### finishedEmitted 플래그
-
-- **결정**: state에 `finishedEmitted` 불린 추가
-- **근거**: usage-only 최종 청크 도착 시 이미 `finish_reason` 청크에서
-  Finished가 발행되었는지 확인 필요. 미발행 시 (비정상 스트림) Finished를 보충
-  발행하여 이벤트 프로토콜 보장.
-
-### capability 가드 제거
-
-- **결정**: `supportsStreaming` 체크 가드를 `generateContentStream`에서 제거
-- **근거**: M3.2.A에서 스텁 보호용으로 추가한 임시 가드. 이제
-  `convertStreamEvent`가 완전 구현되었으므로 dead code.
-  `supportsStreaming: true`이면 가드 절대 실행 안 됨.
-
-## 커밋 이력
-
-| 커밋        | 메시지                                                                                    |
-| ----------- | ----------------------------------------------------------------------------------------- |
-| `1badf7030` | `refactor(providers): extend OpenAiStreamState for stream tracking`                       |
-| `6dcd503a0` | `feat(providers): M3.2.B — OpenAI 스트림 변환기 구현 + streaming 활성화`                  |
-| `b5d1246b2` | `fix(providers): M3.2.B 리뷰 반영 — accumulateToolCalls 방어 + choices 가드 + 테스트 3건` |
-| `619d9df17` | `fix(providers): M3.2.B 2차 리뷰 반영 — choices[0] nullish 가드 + 테스트 R4`              |
-
-## 리뷰 반영
-
-### 제시된 이슈 및 검증 결과
-
-| #   | 심각도 | 이슈                                                                                                                   | 검증 결과                                                                                 | 조치                                                      |
-| --- | ------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| 1   | 중간   | `accumulateToolCalls`에서 동일 id 포함 delta가 다시 오면 `state.currentToolCalls[idx]`를 재초기화하여 기존 축적분 소실 | ✅ 확인 — 실제 API는 continuation에 id=null이므로 발생 가능성 매우 낮지만, 방어 코드 필요 | `if (tc['id'] && !existing)` 조건으로 기존 엔트리 보호    |
-| 2   | 중간   | continuation chunk에 뒤늦게 name이 오는 경우 반영 안 됨                                                                | ✅ 확인 — 실제 API는 첫 chunk에만 name 전달하지만, 방어적으로 반영 필요                   | `else if (existing)` 분기에 `name` 업데이트 로직 추가     |
-| 3   | 낮음   | `choices`가 배열이 아닌 객체일 경우 `choices.length` 접근 시 예외 발생 가능                                            | ✅ 확인 — `{ choices: { index: 0 } }` 같은 malformed chunk에서 예외 발생                  | `!Array.isArray(choices)` 가드 추가                       |
-| 4   | 낮음   | `choices[0]`만 처리하여 multi-choice 무시                                                                              | ℹ️ 의도적 설계 — agent streaming은 n=1 전제                                               | 주석 명확화: "n=1 assumed for agent streaming"            |
-| 5   | 참고   | CLI 런타임 경로가 Gemini 고정                                                                                          | ℹ️ 기 문서화 — M3.2.A 결과서에 이미 기록                                                  | 추가 조치 없음                                            |
-| 6   | 낮음   | `choices: [undefined]` 형태의 malformed chunk에서 `choices[0]['delta']` 접근 시 예외 발생                              | ✅ 확인 — `choices[0]` 자체가 undefined일 때 crash                                        | `choices[0]` nullish 가드 추가 (`if (!choice) return []`) |
-
-### 추가 테스트 (R1-R4)
-
-| 테스트 | 검증 내용                                                                      |
-| ------ | ------------------------------------------------------------------------------ |
-| R1     | duplicate id가 있는 continuation delta가 기존 축적 arguments를 보존하는지 검증 |
-| R2     | continuation chunk에 late name이 있을 때 state에 반영되는지 검증               |
-| R3     | `choices`가 non-array 객체일 때 예외 없이 빈 배열 반환 검증                    |
-| R4     | `choices: [undefined]`일 때 예외 없이 빈 배열 반환 검증                        |
-
-### Quality Gate (리뷰 반영 후)
-
-| 항목          | 결과                     |
-| ------------- | ------------------------ |
-| TypeCheck     | ✅ PASS                  |
-| ESLint        | ✅ PASS                  |
-| OpenAI 테스트 | ✅ 3 files / 106 passed  |
-| Provider 회귀 | ✅ 33 files / 677 passed |
-
-**변화**: 33 files / 673 → 33 files / 677 (+4 tests: R1, R2, R3, R4)
-
-## 알려진 제한사항
-
-### CLI 런타임 경로 Gemini 고정 (M3.2.A에서 이어짐)
-
-M3.2.A 결과서에 기록된 제한사항 유지. CLI의 메인 채팅 루프가 legacy Gemini
-메서드만 호출하므로, OpenAI 스트리밍이 adapter 레벨에서 완성되었더라도 CLI에서는
-아직 사용 불가. M3.4+ CLI 통합 마일스톤에서 해결 예정.
-
-## 향후 작업
-
-- **M3.3**: OpenAI-Compatible(vLLM/sLM) 어댑터 템플릿 — OpenAI SDK 재사용,
-  baseURL 동적 설정
-- **M3.4+**: CLI 통합 — provider-independent ChatSession 인터페이스 + DI로
-  non-Gemini 런타임 지원

package/dist/docs/ai_adapter/working_history/Phase3_M3.3.2_/353/252/250/353/215/270/355/205/234/355/224/214/353/246/277/355/233/205/353/263/264/354/231/204_20260211.md

@@ -1,106 +0,0 @@
-# Phase3 M3.3.2 모델별 템플릿 훅 보완 작업 결과서
-
-- 작업일: 2026-02-11
-- 범위: `### 3.3.2 모델별 템플릿 훅` 리뷰 이슈 반영
-- 대상 코드:
-  - `packages/core/src/providers/openai-compatible/promptBuilder.ts`
-  - `packages/core/src/providers/openai-compatible/promptBuilder.test.ts`
-  - `packages/core/src/providers/openai-compatible/index.ts`
-  - `docs/ai_adapter/todolist/phase3_provider_extension_todolist.md`
-
----
-
-## 1) 리뷰 이슈 검증 결과
-
-| #   | 이슈                                                | 심각도 | 검증 판정  | 조치                                                                                                             |
-| --- | --------------------------------------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------- |
-| 1   | PromptBuilder 프로덕션 미사용(Dead code export)     | 높음   | 정확(의도) | 코드 변경 없음. `promptBuilder.ts` JSDoc에 "extension point, 기본 chat runtime 미연결" 명시                      |
-| 2   | Mistral `<<SYS>>` 형식 사용(Llama2 형식)            | 중간   | 정확       | `<<SYS>>` 제거. system 메시지를 첫 user turn에 plain prepend 방식으로 변경                                       |
-| 3   | `createPromptBuilderForModel` 매칭 범위 부족/오매칭 | 중간   | 정확       | 모델 매칭 규칙 보강: `mixtral`→Mistral, `meta-llama/` 일반 매칭 제거, `llama-2`/`llama-guard`는 fallback(ChatML) |
-| 4   | Mistral tool role 처리 불명확                       | 낮음   | 정확       | tool role을 assistant와 분리 처리. `Tool result:`를 사용자 컨텍스트 turn으로 삽입                                |
-| 5   | 오매칭/경계 케이스 테스트 부재                      | 낮음   | 정확       | 회귀 테스트 6건 추가(LLama2, Mixtral, Llama-Guard, Llama3 vision, 대소문자 등)                                   |
-
----
-
-## 2) 상세 수정 내용
-
-### 2.1 PromptBuilder 의도 명시 (Issue 1)
-
-- `promptBuilder.ts` 모듈 상단 주석에 다음을 명시:
-  - extension point로 공개됨
-  - 기본 `/v1/chat/completions` 경로에는 현재 직접 연결되지 않음
-
-### 2.2 Mistral 템플릿 보정 (Issue 2, 4)
-
-- 기존:
-  - system 메시지 임베딩에 `<<SYS>> ... <</SYS>>` 사용
-  - tool role을 assistant와 동일 branch에서 처리
-- 변경:
-  - system 메시지는 첫 user turn 앞에 plain text prepend
-  - system-only 입력은 `<s>[INST] {system} [/INST]`
-  - tool role은 `<s>[INST] Tool result:\n... [/INST]` 형태로 별도 context turn
-    처리
-
-### 2.3 모델 훅 매칭 보강 (Issue 3)
-
-- 기존 매칭:
-  - `llama-3`, `llama3`, `meta-llama/` → Llama3
-  - `mistral` → Mistral
-- 변경 매칭:
-  - `mixtral`, `mistral` → Mistral
-  - `llama-3`, `llama3` → Llama3
-  - 그 외 → ChatML
-- 효과:
-  - `meta-llama/Llama-2-*` 오매칭 제거
-  - `Mixtral-*` fallback 오매칭 제거
-
-### 2.4 공개 API 유지
-
-- `openai-compatible/index.ts`에서 PromptBuilder 관련 export 유지:
-  - `ChatMLPromptBuilder`
-  - `Llama3PromptBuilder`
-  - `MistralPromptBuilder`
-  - `createPromptBuilderForModel`
-  - `PromptBuilder` type
-
----
-
-## 3) 테스트 보강 및 결과
-
-### 3.1 추가/수정 테스트
-
-- 파일: `promptBuilder.test.ts`
-- 총 테스트: 23건 통과
-- 신규 검증 케이스:
-  - `Mixtral-8x7B-Instruct` → `MistralPromptBuilder`
-  - `meta-llama/Llama-2-70b-chat-hf` → `ChatMLPromptBuilder`
-  - `llama-3.2-vision-instruct` → `Llama3PromptBuilder`
-  - `meta-llama/Llama-Guard-3-8B` → `ChatMLPromptBuilder`
-  - 대소문자 혼합(`META-LLAMA/LLAMA-3-8B`) 매칭
-  - Mistral tool role 처리 시 출력 포맷 검증
-
-### 3.2 실행 결과
-
-```bash
-npm test --workspace @google/gemini-cli-core -- src/providers/openai-compatible/promptBuilder.test.ts
-# PASS: 23 tests
-
-npm run typecheck --workspace @google/gemini-cli-core
-# PASS
-```
-
----
-
-## 4) 계획서 반영
-
-- `phase3_provider_extension_todolist.md`의 3.3.2 상태는 기존 완료(`✅`) 유지.
-- 완료 근거가 되는 구현/테스트를 이번 보완 작업으로 확정.
-
----
-
-## 5) 남은 주의사항
-
-- PromptBuilder 훅은 현재 기본 `/v1/chat/completions` 실행 경로에 직접 연결되지
-  않음.
-- 향후 raw `/v1/completions` 경로를 활성화할 때, 모델별 공식 템플릿 스펙
-  재검증이 필요.

package/dist/docs/ai_adapter/working_history/Phase3_M3.3_OpenAICompatibleAdapter_20260211.md

@@ -1,251 +0,0 @@
-# M3.3: OpenAI-Compatible(vLLM/sLM) 어댑터 구현 작업 결과서
-
-- **작업일**: 2026-02-11
-- **브랜치**: `DID/v0.1`
-- **상태**: ✅ Complete
-
----
-
-## 1. 작업 범위
-
-M3.3 전체 — OpenAI 호환 API 서버(vLLM, TGI, LM Studio, Ollama) 지원 어댑터 구현.
-
-| 섹션                | 항목 수 | 완료   | 연기  | 비고                                   |
-| ------------------- | ------- | ------ | ----- | -------------------------------------- |
-| 3.3.0 사전 준비     | 1       | 1      | 0     | Bootstrap 등록                         |
-| 3.3.1 Adapter 구현  | 6       | 6      | 0     | 상속 + capabilities + testConnection   |
-| 3.3.2 템플릿 훅     | 4       | 2      | 2     | Llama3/Mistral 서버 사이드 처리로 연기 |
-| 3.3.3 호환성 테스트 | 4       | 4      | 0     | vLLM/TGI/LM Studio/Ollama 시나리오     |
-| **합계**            | **15**  | **13** | **2** |                                        |
-
----
-
-## 2. 핵심 설계 결정
-
-### 2.1 Tidy First 불필요
-
-`OpenAiAdapter`의 `converter`(private)와 `classifyError`(private)는 상속된
-메서드(`generateContent`, `generateContentStream`) 내부에서 사용되므로,
-서브클래스가 직접 접근할 필요 없음. `client`는 이미 `protected`. → 구조적 변경
-커밋 없이 바로 동작 변경 진행.
-
-### 2.2 상속 전략
-
-```
-BaseAdapter (abstract)
-  └── OpenAiAdapter (converter + classifyError + generate*)
-        └── OpenAiCompatibleAdapter (providerName + capabilities + testConnection)
-```
-
-- `OpenAiAdapter`의 전체 로직(변환, 스트리밍, 에러 분류) 재사용
-- 오버라이드: `providerName`, `capabilities`, `testConnection()`만 추가
-
-### 2.3 Custom Headers 아키텍처
-
-`AdapterConfig`/`ProviderSelection` 인터페이스 수정 없이, bootstrap factory
-내부에서 `LLM_CUSTOM_HEADERS`(JSON), `LLM_API_KEY_HEADER` 환경변수를 직접 읽어
-OpenAI SDK `defaultHeaders`로 주입.
-
-### 2.4 보수적 Capabilities
-
-로컬 모델은 imageInput/toolCalls를 지원하지 않을 수 있으므로 보수적 기본값 설정.
-`config['capabilities']`로 partial override 지원.
-
-```typescript
-const DEFAULTS: LlmProviderCapabilities = {
-  supportsStreaming: true,
-  supportsToolCalls: true,
-  supportsImageInput: false, // 보수적
-  supportsTokenCount: false, // 로컬 서버 미지원
-  supportsThought: false, // 로컬 서버 미지원
-  maxContextLength: 32_768, // 보수적
-  maxOutputTokens: 4_096, // 보수적
-};
-```
-
-### 2.5 PromptBuilder 최소 구현
-
-vLLM/TGI/Ollama는 `/v1/chat/completions` 엔드포인트에서 서버 사이드 chat
-template 처리. `PromptBuilder` 인터페이스 + `ChatMLPromptBuilder`만 구현,
-Llama3/Mistral template은 연기.
-
----
-
-## 3. 신규 파일
-
-| #   | 파일                                                          | 유형     | 테스트 수 |
-| --- | ------------------------------------------------------------- | -------- | --------- |
-| 1   | `providers/openai-compatible/bootstrap.ts`                    | 프로덕션 | —         |
-| 2   | `providers/openai-compatible/bootstrap.test.ts`               | 테스트   | 10        |
-| 3   | `providers/openai-compatible/adapter.ts`                      | 프로덕션 | —         |
-| 4   | `providers/openai-compatible/adapter.test.ts`                 | 테스트   | 15        |
-| 5   | `providers/openai-compatible/index.ts`                        | 프로덕션 | —         |
-| 6   | `providers/openai-compatible/promptBuilder.ts`                | 프로덕션 | —         |
-| 7   | `providers/openai-compatible/promptBuilder.test.ts`           | 테스트   | 5         |
-| 8   | `providers/openai-compatible/__tests__/compatibility.test.ts` | 테스트   | 12        |
-
-## 4. 수정 파일
-
-| #   | 파일                                                    | 변경 내용                                                |
-| --- | ------------------------------------------------------- | -------------------------------------------------------- |
-| 1   | `providers/index.ts`                                    | `OpenAiCompatible` 네임스페이스 export 추가              |
-| 2   | `core/contentGenerator.ts`                              | `bootstrapOpenAiCompatibleProvider()` import + 호출 추가 |
-| 3   | `providers/__tests__/multiProvider.integration.test.ts` | 4번째 provider `openai-compatible` 추가 (11 tests)       |
-
----
-
-## 5. 테스트 결과
-
-### 5.1 신규 테스트 (42 tests)
-
-```
-✓ bootstrap.test.ts          (10 tests)  — 등록, 중복 방지, SDK 옵션, custom headers
-✓ adapter.test.ts            (15 tests)  — 구조, capabilities, generate, stream, testConnection
-✓ promptBuilder.test.ts       (5 tests)  — ChatML 포맷 (single/multi/empty)
-✓ compatibility.test.ts      (12 tests)  — vLLM(4) + TGI(3) + LM Studio(2) + Ollama(3)
-```
-
-### 5.2 통합 테스트 (11 tests)
-
-```
-✓ multiProvider.integration.test.ts  (11 tests)  — 4-provider switching + concurrent
-```
-
-### 5.3 회귀 테스트
-
-| 범위                      | 결과          |
-| ------------------------- | ------------- |
-| OpenAI 기존 (106 tests)   | ✅ All passed |
-| Core 전체 (386+1 tests)   | ✅ All passed |
-| Providers 통합 (53 tests) | ✅ All passed |
-| Lint                      | ✅ Clean      |
-| Typecheck                 | ✅ Clean      |
-
----
-
-## 6. 연기 항목
-
-| ID      | 항목                 | 사유                                                |
-| ------- | -------------------- | --------------------------------------------------- |
-| 3.3.2.2 | Llama3 ChatTemplate  | 서버 사이드에서 `/v1/chat/completions` 시 자동 적용 |
-| 3.3.2.3 | Mistral ChatTemplate | 서버 사이드에서 `/v1/chat/completions` 시 자동 적용 |
-
-향후 raw `/v1/completions` 지원 시 구현 필요.
-
----
-
-## 7. 이슈 및 해결
-
-### 7.1 apiKey 빈 문자열
-
-OpenAI SDK가 빈 apiKey를 거부할 수 있으므로, 로컬 서버용으로 `'not-needed'`
-placeholder 사용.
-
-### 7.2 ESLint array-type / object-shorthand
-
-`Array<LlmEvent>` → `LlmEvent[]`, `async function*` →
-`async *[Symbol.asyncIterator]()` 수정.
-
----
-
-## 8. 리뷰 반영 (2026-02-11)
-
-### 8.1 높음: LLM_API_KEY_HEADER 중복 Authorization 방지
-
-**문제**: `LLM_API_KEY_HEADER` 설정 시 커스텀 헤더에 API key를 넣으면서도,
-`apiKey`를 그대로 SDK에 전달하여 `Authorization: Bearer` 헤더가 중복 주입됨.
-
-**1차 수정**: `useCustomAuthHeader` 플래그 도입. 커스텀 auth 헤더 사용 시 SDK
-`apiKey`를 `'not-needed'`로 설정하여 기본 Authorization 헤더 억제.
-
-**2차 수정 (8.6)**: `apiKey: 'not-needed'`만으로는
-`Authorization: Bearer not-needed` 헤더가 여전히 생성됨 확인. OpenAI SDK
-`buildHeaders`(`client.mjs:462-484`)는 `authHeaders` → `defaultHeaders` 순서로
-병합하며, `headers.mjs:57-59`에서 `null` 값은 해당 헤더를 삭제함.
-`defaultHeaders`에 `Authorization: null`을 추가하여 `Authorization` 헤더를
-완전히 제거.
-
-**테스트 추가**: `should suppress default apiKey when LLM_API_KEY_HEADER is set`
-(검증: `apiKey: 'not-needed'` + `defaultHeaders.Authorization: null`)
-
-### 8.2 중간: signal 미전달 (오인 — 수정 불필요)
-
-**검증 결과**: OpenAI SDK `create(body, options?: RequestOptions)`는 2번째
-인자에 `{ signal: AbortSignal }` 전달을 지원함. 우리 코드는 이미
-`create(params, { signal })` 로 전달 중이며, `OpenAiClient` 인터페이스도
-`options?` 파라미터를 포함. `OpenAiCompatibleAdapter`는 `OpenAiAdapter`를
-상속하므로 동일 경로로 signal 전달됨.
-
-**결론**: 추가 수정 불필요.
-
-### 8.3 중간: default model gpt-4o → 'default' 변경
-
-**문제**: `DEFAULT_PROVIDER_MODELS[OpenAICompatible]`이 `'gpt-4o'`여서, 로컬
-서버에 `gpt-4o`를 요청하면 모델 미존재 에러 발생.
-
-**수정**: `'gpt-4o'` → `'default'`로 변경. 로컬 서버는 `model: 'default'` 시
-로드된 첫 번째 모델을 사용하거나 모델명을 무시함. `LLM_MODEL` env var가 있으면
-항상 우선 사용되므로, `'default'`는 최후 폴백으로만 동작.
-
-### 8.4 낮음: baseUrl 누락 시 생성자 가드
-
-**문제**: `ProviderFactory.create('openai-compatible', {})` 호출 시 baseUrl 없이
-생성되어 의도치 않게 기본 OpenAI 엔드포인트로 향할 수 있음.
-
-**수정**: `OpenAiCompatibleAdapter` 생성자에 `baseUrl` 필수 검증 추가. 누락 시
-명확한 에러 메시지와 함께 throw.
-
-**테스트 추가**: `should throw when baseUrl is missing`
-
-### 8.5 1차 리뷰 반영 후 테스트 결과
-
-| 범위                         | 결과          |
-| ---------------------------- | ------------- |
-| openai-compatible (44 tests) | ✅ All passed |
-| Providers 전체 (811 tests)   | ✅ All passed |
-| Lint                         | ✅ Clean      |
-| Build                        | ✅ Success    |
-
-### 8.6 2차 리뷰: Authorization 헤더 완전 제거
-
-**문제**: 1차 수정에서 `apiKey: 'not-needed'`를 SDK에 전달했으나, SDK 내부에서
-`Authorization: Bearer not-needed` 헤더가 여전히 생성됨.
-`new OpenAI({ apiKey: 'not-needed' }).authHeaders({})` 결과:
-`{ Authorization: 'Bearer not-needed' }` → 일부 서버에서 인증 충돌 가능.
-
-**원인 분석**: OpenAI SDK `buildHeaders`(`client.mjs:462-484`)는 다음 순서로
-병합:
-`idempotency → base → authHeaders → defaultHeaders → bodyHeaders → options.headers`.
-`authHeaders`는 `apiKey`로부터 `Authorization: Bearer <key>`를 자동 생성.
-
-**해결**: SDK의 `headers.mjs:57-59`에서 `null` 값은 해당 키를 삭제하는 메커니즘
-발견. `defaultHeaders`에 `Authorization: null`을 설정하면, 먼저 병합된
-`authHeaders`의 `Authorization`이 삭제됨.
-
-**수정 내용** (`bootstrap.ts`):
-
-```typescript
-const sdkHeaders: Record<string, string | null> = { ...defaultHeaders };
-if (useCustomAuthHeader) {
-  sdkHeaders['Authorization'] = null;
-}
-```
-
-**테스트 업데이트**: `Authorization: null` 포함 검증 추가.
-
-### 8.7 2차 리뷰 반영 후 테스트 결과
-
-| 범위                         | 결과          |
-| ---------------------------- | ------------- |
-| openai-compatible (44 tests) | ✅ All passed |
-| Providers 전체 (811 tests)   | ✅ All passed |
-| Lint                         | ✅ Clean      |
-| Typecheck                    | ✅ Clean      |
-| Build                        | ✅ Success    |
-
----
-
-## 9. 다음 단계
-
-- M3.4.B (잔여): OpenAI-Compatible E2E 테스트 + 문서 상세화
-- Phase 3 완료 후 → Phase 4 (통합/안정화)