@didim365/agent-cli-core 0.1.0

package/dist/docs/00_project/ai_adapter/04-integration-design.md

@@ -0,0 +1,1934 @@
+# 04. DidimAIStudio 연동 설계
+
+## 4.1 개요
+
+### 4.1.1 목적
+
+Gemini CLI의 Multi-LLM Provider Adapter 설계를 DidimAIStudio 솔루션과 연동하여
+다음 목표를 달성합니다:
+
+1.  **프로바이더 통합**: 두 시스템의 LLM 프로바이더 지원을 통합
+2.  **설정 공유**: 모델 설정 및 API 키를 일관되게 관리
+3.  **기능 재사용**: DidimAIStudio의 13+ 프로바이더 지원을 gemini-cli에서 활용
+4.  **양방향 통신**: CLI ↔ 서버 간 원활한 데이터 교환
+
+### 4.1.2 DidimAIStudio 솔루션 구조
+
+> **소스코드 경로**: `/DidimAIStudio` **인프라 구성**:
+> `/DidimAIStudio/infra/compose/docker-compose.base.yml`
+
+DidimAIStudio는 마이크로서비스 아키텍처로 구성되어 있으며, Gemini CLI 연동에
+핵심적인 서비스는 다음과 같습니다:
+
+#### 핵심 서비스
+
+| 서비스               | 포트 | 역할                                      | 소스 경로                    |
+| -------------------- | ---- | ----------------------------------------- | ---------------------------- |
+| **scenario-gateway** | 8008 | API 게이트웨이, API-Key 인증, 요청 라우팅 | `/services/scenario-gateway` |
+| **agents**           | 8003 | LLM 실행 엔진, 시나리오/워크플로우 처리   | `/services/agents`           |
+
+#### 관련 서비스
+
+| 서비스        | 포트 | 역할               |
+| ------------- | ---- | ------------------ |
+| auth          | 8000 | 사용자 인증/인가   |
+| models        | 8001 | 모델 프로파일 관리 |
+| indexing      | 8002 | 문서 인덱싱/RAG    |
+| cloud-storage | 8006 | 파일 스토리지      |
+| mcp-tools     | 8007 | MCP 도구 서버      |
+
+### 4.1.3 시스템 비교
+
+| 구분           | Gemini CLI                  | DidimAIStudio                   |
+| -------------- | --------------------------- | ------------------------------- |
+| **역할**       | 클라이언트 CLI              | 서버 마이크로서비스             |
+| **언어**       | TypeScript                  | Python                          |
+| **프레임워크** | Node.js + Ink               | FastAPI + LangGraph             |
+| **프로바이더** | Gemini (+ 어댑터 확장 예정) | 13+ (OpenAI, Claude, Gemini 등) |
+| **스트리밍**   | AsyncGenerator              | SSE (Server-Sent Events)        |
+| **설정 저장**  | 환경변수 + 로컬 파일        | Database + 환경변수             |
+| **게이트웨이** | -                           | scenario-gateway (API-Key 인증) |
+
+### 4.1.4 연동 범위
+
+**In Scope (1차)**:
+
+- 공통 타입 시스템 정의
+- scenario-gateway를 통한 API 연동
+- 메시지 형식 변환
+- 프로바이더 설정 동기화
+- 토큰 사용량 추적 통합
+
+**Out of Scope (향후)**:
+
+- 실시간 양방향 동기화
+- 분산 트레이싱 통합
+- 공유 메모리 시스템
+
+## 4.2 연동 아키텍처
+
+### 4.2.1 전체 구조
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              User                                        │
+└─────────────────────────────────┬───────────────────────────────────────┘
+                                  │
+                    ┌─────────────┴─────────────┐
+                    │                           │
+                    ▼                           ▼
+┌───────────────────────────────┐   ┌───────────────────────────────────┐
+│         Gemini CLI            │   │     DidimAIStudio Web App         │
+│       (Terminal Client)       │   │        (Browser Client)           │
+└───────────────┬───────────────┘   └─────────────────┬─────────────────┘
+                │                                     │
+                │                                     │
+                ▼                                     │
+┌───────────────────────────────────────────────────────────────────────┐
+│                         Integration Layer                              │
+│  ┌─────────────────────────────────────────────────────────────────┐  │
+│  │                    DidimAIStudioAdapter                          │  │
+│  │                    (gemini-cli 내부)                             │  │
+│  │                                                                  │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
+│  │  │   Request    │  │   Response   │  │   Stream     │           │  │
+│  │  │  Converter   │  │  Converter   │  │  Adapter     │           │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
+│  └─────────────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────┬───────────────────────────────────┘
+                                    │
+                                    │ HTTP/SSE
+                                    ▼
+┌───────────────────────────────────────────────────────────────────────┐
+│                 DidimAIStudio Solution (Microservices)                 │
+│                                                                        │
+│  ┌─────────────────────────────────────────────────────────────────┐  │
+│  │              scenario-gateway (Port 8008)                        │  │
+│  │              API-Key 인증 게이트웨이                              │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
+│  │  │  /invoke     │  │ /invoke/sse  │  │/invoke/sse/  │           │  │
+│  │  │  (REST)      │  │ (Streaming)  │  │  improved    │           │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
+│  │            ↓              ↓              ↓                       │  │
+│  │  ┌─────────────────────────────────────────────────┐            │  │
+│  │  │ - API-Key 검증 (ApiKeyAuthMiddleware)           │            │  │
+│  │  │ - IP 검증, Rate Limiting                        │            │  │
+│  │  │ - x-thread-id 헤더 처리 (새 Thread vs 기존)     │            │  │
+│  │  │ - WebSocket Key (qa_id) 발급                    │            │  │
+│  │  └─────────────────────────────────────────────────┘            │  │
+│  └──────────────────────────────┬──────────────────────────────────┘  │
+│                                 │ HTTP/SSE                             │
+│                                 ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐  │
+│  │                  agents (Port 8003)                              │  │
+│  │                  LLM 실행 엔진                                    │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
+│  │  │ /v1/invoke   │  │/v1/invoke/sse│  │/v1/websocket │           │  │
+│  │  │              │  │ /improved    │  │   -keys      │           │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
+│  │                                    │                             │  │
+│  │  ┌─────────────────────────────────▼───────────────────────────┐│  │
+│  │  │                  LangGraph Runtime                           ││  │
+│  │  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐    ││  │
+│  │  │  │ OpenAI │ │ Claude │ │ Gemini │ │Bedrock │ │ vLLM   │... ││  │
+│  │  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘    ││  │
+│  │  └─────────────────────────────────────────────────────────────┘│  │
+│  └─────────────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2.2 서비스 간 통신 흐름
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    요청 흐름 (Request Flow)                               │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────┐                                                        │
+│  │ Gemini CLI  │                                                        │
+│  │ (Request)   │                                                        │
+│  └──────┬──────┘                                                        │
+│         │                                                               │
+│         │ POST /api/v1/invoke/sse                                       │
+│         │ Headers: Authorization: Bearer <API-KEY>                       │
+│         │          x-thread-id: <thread-id> (optional)                  │
+│         │ Body: { "chat": "사용자 메시지" }                              │
+│         ▼                                                               │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │              scenario-gateway (:8008)                            │   │
+│  │                                                                  │   │
+│  │  1. API-Key 검증 (ApiKeyAuthMiddleware)                         │   │
+│  │  2. passport_data 추출 (user_id, my_scenario_id)                │   │
+│  │  3. x-thread-id 헤더 확인:                                       │   │
+│  │     - 없음: 새 Thread + qa_id 생성 (POST /v1/websocket-keys)    │   │
+│  │     - 있음: 기존 Thread에 qa_id 발급 (/v1/websocket-keys/with-thread-id) │
+│  │  4. AgentsInvokeRequest 구성                                     │   │
+│  └──────────────────────────────┬──────────────────────────────────┘   │
+│                                 │                                       │
+│         POST http://agents:8003/v1/invoke/sse                          │
+│         Body: {                                                         │
+│           "scenario_my_page_id": 123,                                  │
+│           "user_id": "user-uuid",                                       │
+│           "thread_id": "thread-uuid",                                   │
+│           "qa_id": "qa-uuid",                                          │
+│           "message": "사용자 메시지",                                   │
+│           "attachments": null                                          │
+│         }                                                               │
+│                                 ▼                                       │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    agents (:8003)                                │   │
+│  │                                                                  │   │
+│  │  1. 시나리오 조회 (scenario_my_page_id)                         │   │
+│  │  2. LangGraph 워크플로우 실행                                   │   │
+│  │  3. SSE 스트리밍 응답 생성                                      │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2.3 연동 모드
+
+#### 모드 A: Direct Provider (기본)
+
+gemini-cli가 직접 LLM API를 호출합니다.
+
+```
+Gemini CLI ──► Provider Adapter ──► LLM API (OpenAI/Claude/Gemini)
+```
+
+**사용 시나리오**: 단독 CLI 사용, 빠른 응답 필요
+
+**설정**:
+
+```typescript
+// 환경변수 또는 config에서 설정
+LLM_PROVIDER=gemini  // gemini | claude | openai | vllm
+GEMINI_API_KEY=...
+```
+
+> ⚠️ **Direct 모드 구현 상태**: 현재 `03-technical-design.md`의 GeminiAdapter,
+> ClaudeAdapter, OpenAIAdapter 설계에 해당합니다. DidimAIStudioAdapter와는
+> 별개의 코드 경로입니다.
+
+#### 모드 B: Gateway Mode (DidimAIStudio 연동)
+
+gemini-cli가 DidimAIStudio를 통해 LLM API를 호출합니다.
+
+```
+Gemini CLI ──► DidimAIStudioAdapter ──► scenario-gateway ──► agents ──► LLM API
+```
+
+**사용 시나리오**:
+
+- DidimAIStudio의 고급 기능 활용 (에이전트 워크플로우, 메모리)
+- 중앙 집중식 API 키 관리
+- 사용량 추적 및 비용 관리
+
+**설정**:
+
+```typescript
+// 환경변수 또는 config에서 설정
+LLM_PROVIDER=didim
+DIDIM_BASE_URL=http://localhost:8008
+DIDIM_API_KEY=...
+```
+
+> ⚠️ **엔드포인트 선택 (M2 관련)**:
+>
+> - `/api/v1/invoke/sse`: 기본 SSE 스트리밍
+> - `/api/v1/invoke/sse/improved`: LangGraph 세분화 SSE (권장)
+>
+> 현재 어댑터는 **`/api/v1/invoke/sse/improved`를 사용**합니다.
+
+### 4.2.4 데이터 흐름
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Request Flow                                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────┐     ┌─────────────────┐     ┌─────────────────────┐    │
+│  │ User Input  │────▶│ LlmGenerateReq  │────▶│ ScenarioSSERequestDTO│    │
+│  │ (CLI)       │     │ (gemini-cli)    │     │ (scenario-gateway)  │    │
+│  └─────────────┘     └─────────────────┘     └───────────┬─────────┘    │
+│                                                          │              │
+│                                                          ▼              │
+│                                              ┌─────────────────────┐    │
+│                                              │ AgentsInvokeRequest │    │
+│                                              │ (agents service)    │    │
+│                                              └───────────┬─────────┘    │
+│                                                          │              │
+│                                                          ▼              │
+│                                              ┌─────────────────────┐    │
+│                                              │ LangGraph Runtime   │    │
+│                                              │ Processing          │    │
+│                                              └─────────────────────┘    │
+│                                                          │              │
+├─────────────────────────────────────────────────────────────────────────┤
+│                          Response Flow                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                          │              │
+│                                                          ▼              │
+│  ┌─────────────┐     ┌─────────────────┐     ┌─────────────────────┐    │
+│  │ CLI Output  │◀────│ LlmStreamEvent  │◀────│ SSE Events          │    │
+│  │ (Stream)    │     │ (gemini-cli)    │     │ (message_partial,   │    │
+│  └─────────────┘     └─────────────────┘     │ message_complete,   │    │
+│                                              │ done, error)        │    │
+│                                              └─────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## 4.3 공통 타입 시스템
+
+### 4.3.1 DidimAIStudio 실제 DTO 구조
+
+> **소스 참조**: `/services/scenario-gateway/app/dto/agents_dto.py`
+
+#### scenario-gateway 입력 DTO
+
+```python
+# ScenarioSSERequestDTO - Gemini CLI → scenario-gateway
+class ScenarioSSERequestDTO(BaseModel):
+    chat: str  # 채팅 메시지 (1-10000자)
+```
+
+#### agents 서비스 요청 DTO
+
+```python
+# AgentsInvokeRequest - scenario-gateway → agents
+class AgentsInvokeRequest(BaseModel):
+    scenario_my_page_id: int      # 시나리오 마이페이지 ID
+    user_id: str                  # 사용자 ID
+    thread_id: str                # 대화 흐름 구분 ID
+    qa_id: str                    # 질문-응답 단위 ID
+    message: str                  # 사용자 메시지 (1-50000자)
+    attachments: Optional[List[str]]  # 첨부파일 URL 목록
+```
+
+#### agents 서비스 응답 DTO
+
+```python
+# AgentsInvokeResponse - agents → scenario-gateway
+class AgentsInvokeResponse(BaseModel):
+    qa_id: str                    # 질문-응답 단위 ID
+    message: Optional[str]        # 텍스트 응답
+    attachments: Optional[List[str]]  # 첨부파일 URL 목록
+    status: Optional[str]         # success|error|processing|timeout
+    error_code: Optional[str]     # 오류 코드
+```
+
+### 4.3.2 타입 매핑 테이블
+
+#### 메시지 타입
+
+| Gemini CLI             | DidimAIStudio             | 설명        |
+| ---------------------- | ------------------------- | ----------- |
+| `LlmMessage`           | `BaseMessage` (LangChain) | 기본 메시지 |
+| `LlmTextContent`       | `message: str`            | 텍스트 내용 |
+| `LlmImageContent`      | `attachments: List[str]`  | 이미지 URL  |
+| `LlmToolCallContent`   | `ToolCall` (LangGraph)    | 도구 호출   |
+| `LlmToolResultContent` | `ToolMessage` (LangGraph) | 도구 결과   |
+
+#### 요청/응답 타입
+
+| Gemini CLI            | DidimAIStudio (scenario-gateway) | DidimAIStudio (agents) | 비고                  |
+| --------------------- | -------------------------------- | ---------------------- | --------------------- |
+| `LlmGenerateRequest`  | `ScenarioSSERequestDTO`          | `AgentsInvokeRequest`  | ⚠️ chat 필드만 전달됨 |
+| `LlmGenerateResponse` | SSE `done` event                 | `AgentsInvokeResponse` |                       |
+| `LlmStreamEvent`      | SSE Events                       | SSE Events             |                       |
+| `LlmTokenUsage`       | `token_summary`                  | `total_tokens`         |                       |
+
+> ⚠️ **제한사항**:
+>
+> - `LlmGenerateRequest`의 `messages[]`, `tools[]`, `systemInstruction`은 현재
+>   gateway API로 전달 불가
+> - Multi-turn 컨텍스트는 서버 측 thread 관리에 의존
+
+#### SSE 이벤트 타입 매핑
+
+| Gemini CLI `LlmStreamEvent.type` | DidimAIStudio SSE Event | 설명           | 비고                |
+| -------------------------------- | ----------------------- | -------------- | ------------------- |
+| `content_delta`                  | `message`, `content`    | 텍스트 청크    |                     |
+| `content_delta`                  | `message_partial`       | 토큰 스트리밍  | improved SSE        |
+| `content_delta` (metadata)       | `message_metadata`      | 실행 컨텍스트  | improved SSE        |
+| `content_delta` (metadata)       | `process`               | 노드 진행 상황 | improved SSE        |
+| `message_end`                    | `done`                  | 응답 완료      | threadId, qaId 포함 |
+| `error`                          | `error`                 | 에러 발생      |                     |
+
+> ⚠️ **tool_call_delta 미지원**: 현재 gateway API는 tool 정보를 입/출력하지
+> 않으므로 `tool_call_delta` 이벤트는 발생하지 않습니다.
+
+#### 완료 상태 매핑
+
+| Gemini CLI `LlmStopReason` | DidimAIStudio SSE Event  |
+| -------------------------- | ------------------------ |
+| `end_turn`                 | `done` event             |
+| `max_tokens`               | `done` with truncation   |
+| `tool_use`                 | `process` (tool_start)   |
+| `content_filter`           | `error` (CONTENT_FILTER) |
+| `error`                    | `error` event            |
+
+### 4.3.3 공통 인터페이스 정의
+
+#### TypeScript (gemini-cli)
+
+```typescript
+// packages/core/src/providers/didim/types.ts
+
+/**
+ * DidimAIStudio 연동을 위한 공통 타입
+ * 실제 DidimAIStudio DTO 구조 기반
+ */
+
+// scenario-gateway 입력 (POST /api/v1/invoke/sse)
+export interface ScenarioSSERequestDTO {
+  chat: string; // 채팅 메시지 (1-10000자)
+}
+
+// agents 서비스 요청 (내부 통신용, scenario-gateway → agents)
+export interface AgentsInvokeRequest {
+  scenario_my_page_id: number; // 시나리오 마이페이지 ID
+  user_id: string; // 사용자 ID
+  thread_id: string; // 대화 흐름 구분 ID
+  qa_id: string; // 질문-응답 단위 ID
+  message: string; // 사용자 메시지
+  attachments?: string[] | null; // 첨부파일 URL 목록
+}
+
+// agents 서비스 응답
+export interface AgentsInvokeResponse {
+  qa_id: string;
+  message?: string | null;
+  attachments?: string[] | null;
+  status?: 'success' | 'error' | 'processing' | 'timeout';
+  error_code?: string | null;
+}
+
+// WebSocket Key 생성 DTO
+export interface WebSocketKeyCreateDTO {
+  user_id: string;
+  scenario_my_page_id?: number;
+}
+
+// WebSocket Key 응답 DTO
+export interface WebSocketKeyResponseDTO {
+  id: number;
+  user_id: string;
+  scenario_my_page_id?: number;
+  thread_id: string; // 스레드 ID
+  qa_id: string; // QA ID
+  created_at: string;
+  updated_at: string;
+}
+
+// SSE 이벤트 타입
+export type DidimSSEEventType =
+  | 'message' // 기본 메시지 청크
+  | 'content' // 콘텐츠 청크
+  | 'message_partial' // 토큰 스트리밍 (improved)
+  | 'message_complete' // 메시지 완료 (improved)
+  | 'message_metadata' // 실행 컨텍스트 (improved)
+  | 'process' // 노드 진행 상황 (improved)
+  | 'done' // 응답 완료
+  | 'error'; // 에러
+
+// SSE 청크 데이터
+export interface SSEChatChunk {
+  chunk?: string;
+  scenario_id?: string;
+  thread_id?: string;
+}
+
+// SSE 완료 데이터
+export interface SSEDoneData {
+  message: string;
+  scenario_id: string;
+  thread_id: string;
+  qa_id: string;
+}
+
+// SSE 에러 데이터
+export interface SSEErrorData {
+  error: string;
+  error_code?: string;
+}
+
+// 채팅 응답 (비스트리밍)
+export interface ChatResponse {
+  response: string;
+  scenario_id: string;
+  thread_id: string;
+  timestamp: string;
+}
+```
+
+#### Python (DidimAIStudio) - 신규 연동 API용
+
+```python
+# services/agents/app/schemas/integration/gemini_cli.py
+
+from pydantic import BaseModel
+from typing import Optional, Union, List, Dict, Any
+from enum import Enum
+
+class LlmStopReason(str, Enum):
+    END_TURN = "end_turn"
+    MAX_TOKENS = "max_tokens"
+    STOP_SEQUENCE = "stop_sequence"
+    TOOL_USE = "tool_use"
+    CONTENT_FILTER = "content_filter"
+    ERROR = "error"
+
+class LlmTextContent(BaseModel):
+    type: str = "text"
+    text: str
+
+class LlmImageContent(BaseModel):
+    type: str = "image"
+    source: Dict[str, str]  # type, mediaType, data
+
+class LlmToolCallContent(BaseModel):
+    type: str = "tool_call"
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+class LlmMessage(BaseModel):
+    role: str  # user, assistant, system, tool
+    content: List[Union[LlmTextContent, LlmImageContent, LlmToolCallContent]]
+    name: Optional[str] = None
+    tool_call_id: Optional[str] = None
+
+class LlmGenerateRequest(BaseModel):
+    """Gemini CLI 요청 형식"""
+    model: str
+    messages: List[LlmMessage]
+    system_instruction: Optional[str] = None
+    tools: Optional[List[Dict]] = None
+    tool_choice: Optional[str] = None
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    stop_sequences: Optional[List[str]] = None
+    top_p: Optional[float] = None
+    top_k: Optional[int] = None
+
+class LlmTokenUsage(BaseModel):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+    cached_tokens: Optional[int] = None
+
+class LlmGenerateResponse(BaseModel):
+    """Gemini CLI 응답 형식"""
+    id: str
+    content: List[Union[LlmTextContent, LlmToolCallContent]]
+    model: str
+    stop_reason: LlmStopReason
+    usage: LlmTokenUsage
+    raw_response: Optional[Dict] = None
+```
+
+## 4.4 어댑터 구현
+
+### 4.4.1 DidimAIStudio 실제 API 엔드포인트
+
+> **소스 참조**:
+>
+> - `/services/scenario-gateway/app/api/v1/endpoints/scenario_api.py`
+> - `/services/agents/app/api/v1/router.py`
+
+#### scenario-gateway 엔드포인트 (Port 8008)
+
+| 메서드 | 경로                          | 설명                      |
+| ------ | ----------------------------- | ------------------------- |
+| POST   | `/api/v1/invoke`              | 비스트리밍 채팅 요청      |
+| POST   | `/api/v1/invoke/sse`          | SSE 스트리밍 채팅         |
+| POST   | `/api/v1/invoke/sse/improved` | LangGraph 호환 세분화 SSE |
+| GET    | `/health`                     | 헬스 체크                 |
+| GET    | `/metrics`                    | Prometheus 메트릭         |
+
+#### agents 엔드포인트 (Port 8003) - 내부 통신
+
+| 메서드 | 경로                                | 설명                     |
+| ------ | ----------------------------------- | ------------------------ |
+| POST   | `/v1/invoke`                        | 비스트리밍 실행          |
+| POST   | `/v1/invoke/sse`                    | SSE 스트리밍 실행        |
+| POST   | `/v1/invoke/sse/improved`           | 세분화 SSE 스트리밍      |
+| POST   | `/v1/websocket-keys`                | 새 Thread + qa_id 생성   |
+| POST   | `/v1/websocket-keys/with-thread-id` | 기존 Thread에 qa_id 발급 |
+| POST   | `/v1/chats`                         | 채팅 종료 (토큰 집계)    |
+| GET    | `/v1/scenarios`                     | 시나리오 조회            |
+| GET    | `/v1/threads`                       | Thread 조회              |
+
+### 4.4.2 DidimAIStudio 어댑터 (gemini-cli)
+
+```typescript
+// packages/core/src/providers/didim/adapter.ts
+
+import { BaseAdapter, AdapterConfig } from '../baseAdapter';
+import {
+  LlmGenerateRequest,
+  LlmGenerateResponse,
+  LlmStream,
+  LlmStreamEvent,
+  ProviderCapabilities,
+} from '../types';
+import {
+  ScenarioSSERequestDTO,
+  ChatResponse,
+  SSEDoneData,
+  SSEErrorData,
+  DidimSSEEventType,
+} from './types';
+import { DidimTypeConverter } from './converter';
+
+export interface DidimAdapterConfig extends AdapterConfig {
+  baseUrl: string; // scenario-gateway URL (예: http://localhost:8008)
+  apiKey: string; // API Key (Bearer 토큰)
+  threadId?: string; // 기존 대화 스레드 ID (선택적)
+}
+
+export class DidimAIStudioAdapter extends BaseAdapter {
+  readonly providerName = 'didim-aistudio';
+  /**
+   * Capabilities - 실제 scenario-gateway API 지원 범위 기반
+   *
+   * ⚠️ 제한사항:
+   * - Tool/Attachment는 현재 ScenarioSSERequestDTO(chat만 수신)로 전달 불가
+   * - Embedding/TokenCount는 사후 추정값만 제공 (사전 API 없음)
+   * - System message는 시나리오 설정에 포함되어야 함 (요청 시 전달 불가)
+   */
+  readonly capabilities: ProviderCapabilities = {
+    supportsStreaming: true,
+    supportsToolCalls: false, // ⚠️ 현재 gateway API로 tool 정보 전달 불가
+    supportsImageInput: false, // ⚠️ attachments는 gateway 내부에서만 처리
+    supportsImageGeneration: false,
+    supportsEmbedding: false, // ⚠️ Didim API에 사전 embedding endpoint 없음
+    supportsTokenCount: false, // ⚠️ 사전 token count API 없음 (추정값만 가능)
+    supportsSystemMessage: false, // ⚠️ 시나리오 설정에 포함, 요청 시 전달 불가
+    maxContextLength: 200_000, // 시나리오에 설정된 모델에 따라 다름
+    maxOutputTokens: 32_768,
+  };
+
+  private converter: DidimTypeConverter;
+  private config: DidimAdapterConfig;
+  private currentThreadId?: string;
+
+  constructor(config: DidimAdapterConfig) {
+    super(config);
+    this.config = config;
+    this.converter = new DidimTypeConverter();
+    this.currentThreadId = config.threadId;
+  }
+
+  /**
+   * ⚠️ 알려진 제한사항 (H3):
+   * - ScenarioSSERequestDTO가 "chat" 필드만 받으므로, 마지막 사용자 메시지만 전송됨
+   * - 시스템 메시지, 이전 대화 히스토리, 도구 컨텍스트는 전달되지 않음
+   * - Multi-turn 품질은 DidimAIStudio 서버 측 thread 관리에 의존
+   *
+   * TODO: 전용 API 확장 시 LlmGenerateRequest 전체를 전달하도록 개선
+   */
+  async generateContent(
+    request: LlmGenerateRequest,
+    options?: GenerateOptions,
+  ): Promise<LlmGenerateResponse> {
+    // 마지막 사용자 메시지만 추출 (API 제약으로 인한 제한)
+    const chatMessage = this.converter.extractLastUserMessage(request);
+
+    const response = await fetch(`${this.config.baseUrl}/api/v1/invoke`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.config.apiKey}`,
+        ...(this.currentThreadId && { 'x-thread-id': this.currentThreadId }),
+      },
+      body: JSON.stringify({ chat: chatMessage }),
+      signal: options?.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Didim AI generation failed: ${response.statusText}`);
+    }
+
+    const data: ChatResponse = await response.json();
+
+    // thread_id 저장 (다음 요청에 사용)
+    this.currentThreadId = data.thread_id;
+
+    return this.converter.toChatResponseToLlm(data, request.model);
+  }
+
+  async generateContentStream(
+    request: LlmGenerateRequest,
+    options?: GenerateOptions,
+  ): Promise<LlmStream> {
+    this.validateRequest(request);
+    return this.createSSEStream(request, options);
+  }
+
+  async countTokens(request: LlmGenerateRequest): Promise<LlmTokenCount> {
+    // DidimAIStudio는 응답 시 토큰 정보 제공
+    // 사전 카운트는 추정값 사용
+    const text = this.converter.extractText(request);
+    return { totalTokens: Math.ceil(text.length / 4) };
+  }
+
+  private async *createSSEStream(
+    request: LlmGenerateRequest,
+    options?: GenerateOptions,
+  ): LlmStream {
+    const chatMessage = this.converter.extractLastUserMessage(request);
+
+    const response = await fetch(
+      `${this.config.baseUrl}/api/v1/invoke/sse/improved`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`,
+          Accept: 'text/event-stream',
+          ...(this.currentThreadId && { 'x-thread-id': this.currentThreadId }),
+        },
+        body: JSON.stringify({ chat: chatMessage }),
+        signal: options?.signal,
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(`SSE connection failed: ${response.statusText}`);
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new Error('No response body');
+    }
+
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // 완전한 SSE 이벤트 추출 (\n\n로 구분)
+        while (buffer.includes('\n\n')) {
+          const eventEnd = buffer.indexOf('\n\n');
+          const completeEvent = buffer.substring(0, eventEnd);
+          buffer = buffer.substring(eventEnd + 2);
+
+          if (completeEvent.trim()) {
+            const event = this.parseSSEEvent(completeEvent);
+            if (event) {
+              // thread_id 저장
+              if (event.threadId) {
+                this.currentThreadId = event.threadId;
+              }
+              yield this.converter.toStreamEvent(event);
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /**
+   * SSE 이벤트 파싱 (M1 개선)
+   * - 다중 data: 라인 지원
+   * - event: 없는 기본 이벤트 처리
+   * - \r\n 및 \n 구분자 모두 처리
+   */
+  private parseSSEEvent(eventText: string): ParsedSSEEvent | null {
+    // \r\n과 \n 모두 지원
+    const lines = eventText.replace(/\r\n/g, '\n').split('\n');
+    let eventType: string | null = null;
+    const dataLines: string[] = [];
+    let eventId: string | null = null;
+
+    for (const line of lines) {
+      if (line.startsWith('event:')) {
+        eventType = line.substring(6).trim();
+      } else if (line.startsWith('data:')) {
+        // 다중 data: 라인 수집
+        dataLines.push(line.substring(5).trim());
+      } else if (line.startsWith('id:')) {
+        eventId = line.substring(3).trim();
+      }
+    }
+
+    // data 라인들을 줄바꿈으로 결합
+    const data = dataLines.join('\n');
+
+    // event: 없이 data:만 있는 SSE도 처리 (기본 이벤트)
+    if (!data) return null;
+    if (!eventType) eventType = 'message'; // 기본 이벤트 타입
+
+    try {
+      const parsed = JSON.parse(data);
+      return {
+        eventType,
+        data: parsed,
+        eventId,
+        // H1 수정: data에서 threadId 추출
+        threadId: parsed.thread_id || parsed.threadId,
+        qaId: parsed.qa_id || parsed.qaId,
+      };
+    } catch {
+      return { eventType, data: { chunk: data }, eventId };
+    }
+  }
+}
+
+interface ParsedSSEEvent {
+  eventType: string;
+  data: any;
+  eventId: string | null;
+  threadId?: string; // H1: data에서 추출된 threadId
+  qaId?: string; // data에서 추출된 qaId
+}
+```
+
+### 4.4.3 타입 변환기 (gemini-cli)
+
+```typescript
+// packages/core/src/providers/didim/converter.ts
+
+import {
+  LlmGenerateRequest,
+  LlmGenerateResponse,
+  LlmMessage,
+  LlmStreamEvent,
+  LlmStopReason,
+  LlmTextContent,
+  LlmTokenUsage,
+} from '../types';
+import {
+  ChatResponse,
+  SSEDoneData,
+  SSEErrorData,
+  DidimSSEEventType,
+} from './types';
+
+export class DidimTypeConverter {
+  /**
+   * 마지막 사용자 메시지 추출
+   */
+  extractLastUserMessage(request: LlmGenerateRequest): string {
+    const userMessages = request.messages.filter((m) => m.role === 'user');
+    if (userMessages.length === 0) return '';
+
+    const lastMessage = userMessages[userMessages.length - 1];
+    const texts = lastMessage.content
+      .filter((c): c is LlmTextContent => c.type === 'text')
+      .map((c) => c.text);
+
+    return texts.join('\n');
+  }
+
+  /**
+   * 전체 텍스트 추출 (토큰 카운트용)
+   */
+  extractText(request: LlmGenerateRequest): string {
+    const texts: string[] = [];
+    for (const message of request.messages) {
+      for (const content of message.content) {
+        if (content.type === 'text') {
+          texts.push((content as LlmTextContent).text);
+        }
+      }
+    }
+    return texts.join('\n');
+  }
+
+  /**
+   * 첨부 파일 URL 추출
+   */
+  extractAttachments(messages: LlmMessage[]): string[] {
+    const attachments: string[] = [];
+    for (const message of messages) {
+      for (const content of message.content) {
+        if (content.type === 'image' && content.source?.type === 'url') {
+          attachments.push(content.source.data);
+        }
+      }
+    }
+    return attachments;
+  }
+
+  /**
+   * ChatResponse → LlmGenerateResponse 변환
+   */
+  toChatResponseToLlm(
+    response: ChatResponse,
+    model: string,
+  ): LlmGenerateResponse {
+    return {
+      id: response.thread_id,
+      content: [{ type: 'text', text: response.response }],
+      model,
+      stopReason: 'end_turn' as LlmStopReason,
+      usage: {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+      },
+    };
+  }
+
+  /**
+   * SSE 이벤트 → LlmStreamEvent 변환
+   */
+  toStreamEvent(event: {
+    eventType: string;
+    data: any;
+    eventId: string | null;
+  }): LlmStreamEvent {
+    const { eventType, data } = event;
+
+    switch (eventType) {
+      case 'message':
+      case 'content':
+      case 'message_partial':
+        // 텍스트 청크
+        return {
+          type: 'content_delta',
+          delta: { text: data.chunk || data.message || '' },
+        };
+
+      case 'message_complete':
+        // 도구 완료 또는 메시지 완료
+        if (data.process_name) {
+          return {
+            type: 'tool_call_delta',
+            delta: {
+              toolCall: {
+                type: 'tool_call',
+                id: data.id || 'unknown',
+                name: data.process_name,
+                arguments: data.process_output || {},
+              },
+            },
+          };
+        }
+        return {
+          type: 'content_delta',
+          delta: { text: data.message || '' },
+        };
+
+      case 'message_metadata':
+        // 실행 컨텍스트 (improved SSE)
+        return {
+          type: 'content_delta',
+          delta: {},
+          metadata: {
+            langgraphNode: data.langgraph_node,
+            step: data.step,
+            model: data.model,
+          },
+        };
+
+      case 'process':
+        // 노드 진행 상황
+        return {
+          type: 'content_delta',
+          delta: {},
+          metadata: {
+            processName: data.process_name,
+            processType: data.process_type,
+          },
+        };
+
+      case 'done':
+        // 응답 완료
+        const doneData = data as SSEDoneData;
+        return {
+          type: 'message_end',
+          usage: {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+          },
+          threadId: doneData.thread_id,
+          qaId: doneData.qa_id,
+        };
+
+      case 'error':
+        // 에러
+        const errorData = data as SSEErrorData;
+        return {
+          type: 'error',
+          error: {
+            type: errorData.error_code || 'unknown',
+            message: errorData.error,
+          },
+        };
+
+      default:
+        return {
+          type: 'content_delta',
+          delta: {},
+        };
+    }
+  }
+}
+```
+
+### 4.4.4 기존 API 활용 방안 (DidimAIStudio)
+
+> **핵심**: Gemini CLI는 scenario-gateway의 기존 API를 그대로 활용합니다. 별도의
+> `/gemini-cli` 전용 API를 만들지 않고, 기존 `/api/v1/invoke/sse` 엔드포인트를
+> 사용합니다.
+
+#### 기존 API 흐름 (scenario_api.py)
+
+```python
+# /services/scenario-gateway/app/api/v1/endpoints/scenario_api.py
+
+# 현재 구조:
+# POST /api/v1/invoke/sse
+#   1. API-Key 인증 (ApiKeyAuthMiddleware)
+#   2. passport_data에서 user_id, my_scenario_id 추출
+#   3. x-thread-id 헤더 확인 → WebSocket Key 생성/조회
+#   4. AgentsInvokeRequest 구성
+#   5. agents 서비스 호출 (http://agents:8003/v1/invoke/sse)
+#   6. SSE 스트리밍 응답 전달
+
+@router.post("/invoke/sse")
+async def scenario_request_sse(
+    request_data: ScenarioSSERequestDTO,  # { "chat": "메시지" }
+    request: Request,
+    x_thread_id: str = Header(None, alias="x-thread-id"),
+    x_dooray_info_key: str = Header(None, alias="x-dooray-info-key")
+):
+    # ... 기존 구현 활용
+```
+
+#### Gemini CLI 연동 시 추가 고려사항
+
+1. **API-Key 발급**: Gemini CLI 사용자에게 DidimAIStudio API-Key 발급
+2. **시나리오 매핑**: 사용자별 기본 시나리오 설정 또는 CLI에서 지정
+3. **응답 포맷**: 기존 SSE 응답을 그대로 사용하되, gemini-cli에서 파싱
+
+#### 옵션: Gemini CLI 전용 API (선택적 확장)
+
+```python
+# /services/scenario-gateway/app/api/v1/endpoints/gemini_cli_api.py (선택적)
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from typing import AsyncGenerator
+import json
+
+from app.schemas.integration.gemini_cli import (
+    LlmGenerateRequest,
+    LlmGenerateResponse,
+    LlmStreamEvent,
+)
+from app.service.integration.gemini_cli_service import GeminiCLIService
+from app.core.auth import get_api_key_user
+
+router = APIRouter(prefix="/api/v1/gemini-cli", tags=["gemini-cli"])
+
+@router.post("/generate")
+async def generate_content(
+    request: LlmGenerateRequest,
+    current_user = Depends(get_api_key_user),
+    service: GeminiCLIService = Depends()
+) -> LlmGenerateResponse:
+    """
+    Gemini CLI 호환 콘텐츠 생성 API (비스트리밍)
+    LlmGenerateRequest 형식을 직접 받아 처리
+    """
+    return await service.generate(request, current_user)
+
+
+@router.post("/generate/stream")
+async def generate_content_stream(
+    request: LlmGenerateRequest,
+    current_user = Depends(get_api_key_user),
+    service: GeminiCLIService = Depends()
+) -> StreamingResponse:
+    """
+    Gemini CLI 호환 콘텐츠 생성 API (스트리밍)
+    LlmStreamEvent 형식으로 응답
+    """
+    async def event_generator() -> AsyncGenerator[str, None]:
+        async for event in service.generate_stream(request, current_user):
+            yield f"data: {json.dumps(event.dict())}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+```
+
+### 4.4.5 연동 서비스 (DidimAIStudio - 선택적 확장용)
+
+```python
+# /services/scenario-gateway/app/service/integration/gemini_cli_service.py
+
+from typing import AsyncGenerator
+import uuid
+import httpx
+import json
+
+from app.schemas.integration.gemini_cli import (
+    LlmGenerateRequest,
+    LlmGenerateResponse,
+    LlmStreamEvent,
+    LlmTokenUsage,
+    LlmTextContent,
+    LlmStopReason,
+)
+from app.dto.agents_dto import AgentsInvokeRequest, AgentsInvokeResponse
+from app.service.integration.gemini_cli_converter import GeminiCLIConverter
+
+# 내부 agents 서비스 URL
+AGENTS_URL_SSE = "http://agents:8003/v1/invoke/sse/improved"
+
+
+class GeminiCLIService:
+    def __init__(self, converter: GeminiCLIConverter):
+        self.converter = converter
+
+    async def generate(
+        self,
+        request: LlmGenerateRequest,
+        user
+    ) -> LlmGenerateResponse:
+        """비스트리밍 콘텐츠 생성"""
+        # 스트리밍으로 전체 응답 수집
+        full_content = ""
+        total_tokens = 0
+
+        async for event in self.generate_stream(request, user):
+            if event.type == "content_delta" and event.delta:
+                full_content += event.delta.get("text", "")
+            if event.usage:
+                total_tokens = event.usage.total_tokens
+
+        return LlmGenerateResponse(
+            id=str(uuid.uuid4()),
+            content=[LlmTextContent(type="text", text=full_content)],
+            model=request.model,
+            stop_reason=LlmStopReason.END_TURN,
+            usage=LlmTokenUsage(
+                prompt_tokens=0,
+                completion_tokens=0,
+                total_tokens=total_tokens
+            )
+        )
+
+    async def generate_stream(
+        self,
+        request: LlmGenerateRequest,
+        user
+    ) -> AsyncGenerator[LlmStreamEvent, None]:
+        """스트리밍 콘텐츠 생성"""
+        # Gemini CLI 요청 → AgentsInvokeRequest 변환
+        agents_request = self.converter.to_agents_request(request, user)
+
+        # agents 서비스 스트리밍 호출
+        async with httpx.AsyncClient(timeout=200.0) as client:
+            async with client.stream(
+                "POST",
+                AGENTS_URL_SSE,
+                json=agents_request.model_dump(),
+                headers={"Content-Type": "application/json"}
+            ) as response:
+                response.raise_for_status()
+
+                buffer = ""
+                async for chunk in response.aiter_bytes():
+                    buffer += chunk.decode('utf-8', errors='ignore')
+
+                    while '\n\n' in buffer:
+                        event_end = buffer.find('\n\n')
+                        complete_event = buffer[:event_end]
+                        buffer = buffer[event_end + 2:]
+
+                        if complete_event.strip():
+                            event = self._parse_sse_event(complete_event)
+                            if event:
+                                yield self.converter.to_stream_event(event)
+
+    async def count_tokens(
+        self,
+        request: LlmGenerateRequest,
+        user
+    ) -> int:
+        """토큰 수 계산"""
+        text = self.converter.extract_text(request)
+        return len(text) // 4
+
+    def _parse_sse_event(self, event_text: str) -> dict | None:
+        """SSE 이벤트 파싱"""
+        lines = event_text.split('\n')
+        event_type = None
+        data = None
+
+        for line in lines:
+            if line.startswith('event: '):
+                event_type = line[7:]
+            elif line.startswith('data: '):
+                try:
+                    data = json.loads(line[6:])
+                except json.JSONDecodeError:
+                    data = {"chunk": line[6:]}
+
+        if event_type and data:
+            return {"event_type": event_type, "data": data}
+        return None
+```
+
+### 4.4.6 변환기 (DidimAIStudio - 선택적 확장용)
+
+```python
+# /services/scenario-gateway/app/service/integration/gemini_cli_converter.py
+
+from typing import List, Dict, Any, Optional
+import uuid
+
+from app.schemas.integration.gemini_cli import (
+    LlmGenerateRequest,
+    LlmMessage,
+    LlmStreamEvent,
+    LlmStopReason,
+)
+from app.dto.agents_dto import AgentsInvokeRequest
+
+
+class GeminiCLIConverter:
+    """Gemini CLI ↔ DidimAIStudio 형식 변환"""
+
+    def to_agents_request(
+        self,
+        request: LlmGenerateRequest,
+        user
+    ) -> AgentsInvokeRequest:
+        """LlmGenerateRequest → AgentsInvokeRequest"""
+        # 마지막 사용자 메시지 추출
+        last_message = self._extract_last_user_message(request.messages)
+
+        # 첨부 파일 추출
+        attachments = self._extract_attachments(request.messages)
+
+        return AgentsInvokeRequest(
+            scenario_my_page_id=user.default_scenario_id,
+            user_id=str(user.id),
+            thread_id=str(uuid.uuid4()),
+            qa_id=str(uuid.uuid4()),
+            message=last_message,
+            attachments=attachments if attachments else None
+        )
+
+    def to_stream_event(self, event: dict) -> LlmStreamEvent:
+        """SSE 이벤트 → LlmStreamEvent"""
+        event_type = event.get("event_type")
+        data = event.get("data", {})
+
+        handlers = {
+            "message": self._handle_message,
+            "content": self._handle_message,
+            "message_partial": self._handle_partial,
+            "message_complete": self._handle_complete,
+            "message_metadata": self._handle_metadata,
+            "process": self._handle_process,
+            "done": self._handle_done,
+            "error": self._handle_error,
+        }
+
+        handler = handlers.get(event_type, self._handle_unknown)
+        return handler(data)
+
+    def extract_text(self, request: LlmGenerateRequest) -> str:
+        """요청에서 전체 텍스트 추출"""
+        texts = []
+        for message in request.messages:
+            for content in message.content:
+                if content.type == "text":
+                    texts.append(content.text)
+        return "\n".join(texts)
+
+    # === Private Methods ===
+
+    def _extract_last_user_message(
+        self,
+        messages: List[LlmMessage]
+    ) -> str:
+        """마지막 사용자 메시지 추출"""
+        user_messages = [m for m in messages if m.role == "user"]
+        if not user_messages:
+            return ""
+
+        last = user_messages[-1]
+        texts = [c.text for c in last.content if c.type == "text"]
+        return "\n".join(texts)
+
+    def _extract_attachments(
+        self,
+        messages: List[LlmMessage]
+    ) -> List[str]:
+        """이미지 URL 등 첨부 파일 추출"""
+        attachments = []
+        for message in messages:
+            for content in message.content:
+                if content.type == "image":
+                    if content.source.get("type") == "url":
+                        attachments.append(content.source["data"])
+        return attachments
+
+    def _handle_message(self, data: dict) -> LlmStreamEvent:
+        """message/content 이벤트 처리"""
+        chunk = data.get("chunk", data.get("message", ""))
+        return LlmStreamEvent(
+            type="content_delta",
+            delta={"text": str(chunk)}
+        )
+
+    def _handle_partial(self, data: dict) -> LlmStreamEvent:
+        """message_partial 이벤트 처리 (토큰 스트리밍)"""
+        return LlmStreamEvent(
+            type="content_delta",
+            delta={"text": data.get("message", "")}
+        )
+
+    def _handle_complete(self, data: dict) -> LlmStreamEvent:
+        """message_complete 이벤트 처리"""
+        if data.get("process_name"):
+            # 도구 완료
+            return LlmStreamEvent(
+                type="tool_call_delta",
+                delta={
+                    "toolCall": {
+                        "type": "tool_call",
+                        "id": str(uuid.uuid4()),
+                        "name": data.get("process_name", "unknown"),
+                        "arguments": {}
+                    }
+                }
+            )
+        return self._handle_message(data)
+
+    def _handle_metadata(self, data: dict) -> LlmStreamEvent:
+        """message_metadata 이벤트 처리"""
+        return LlmStreamEvent(
+            type="content_delta",
+            delta={},
+            metadata={
+                "langgraph_node": data.get("langgraph_node"),
+                "step": data.get("step"),
+                "model": data.get("model")
+            }
+        )
+
+    def _handle_process(self, data: dict) -> LlmStreamEvent:
+        """process 이벤트 처리"""
+        return LlmStreamEvent(
+            type="content_delta",
+            delta={},
+            metadata={
+                "process_name": data.get("process_name"),
+                "process_type": data.get("process_type")
+            }
+        )
+
+    def _handle_done(self, data: dict) -> LlmStreamEvent:
+        """done 이벤트 처리"""
+        return LlmStreamEvent(
+            type="message_end",
+            usage={
+                "promptTokens": 0,
+                "completionTokens": 0,
+                "totalTokens": data.get("total_tokens", 0)
+            },
+            thread_id=data.get("thread_id"),
+            qa_id=data.get("qa_id")
+        )
+
+    def _handle_error(self, data: dict) -> LlmStreamEvent:
+        """error 이벤트 처리"""
+        return LlmStreamEvent(
+            type="error",
+            error={
+                "type": data.get("error_code", "unknown"),
+                "message": data.get("error", "Unknown error")
+            }
+        )
+
+    def _handle_unknown(self, data: dict) -> LlmStreamEvent:
+        """알 수 없는 이벤트 처리"""
+        return LlmStreamEvent(type="content_delta", delta={})
+```
+
+## 4.5 설정 및 인증
+
+### 4.5.1 gemini-cli 설정
+
+```typescript
+// packages/core/src/providers/didim/config.ts
+
+export interface DidimIntegrationConfig {
+  enabled: boolean;
+  baseUrl: string; // scenario-gateway URL (예: http://localhost:8008)
+  apiKey: string; // DidimAIStudio API-Key (시나리오별 발급)
+  threadId?: string; // 기존 대화 스레드 ID (선택적)
+
+  // 선택적 설정
+  timeout?: number;
+  retries?: number;
+
+  // 모드 선택
+  mode: 'direct' | 'gateway'; // direct: 직접 API, gateway: DidimAI 경유
+}
+
+// 환경 변수
+// DIDIM_AI_ENABLED=true
+// DIDIM_AI_BASE_URL=http://scenario-gateway:8008  # 또는 외부 URL
+// DIDIM_AI_API_KEY=your-scenario-api-key         # 시나리오별 API-Key
+// DIDIM_AI_MODE=gateway
+```
+
+### 4.5.2 settings.json 확장
+
+```json
+{
+  "provider": {
+    "default": "gemini",
+    "gemini": { ... },
+    "claude": { ... },
+
+    "didim-aistudio": {
+      "enabled": true,
+      "baseUrl": "http://scenario-gateway:8008",
+      "apiKey": "${DIDIM_AI_API_KEY}",
+      "mode": "gateway"
+    }
+  }
+}
+```
+
+### 4.5.3 API-Key 기반 인증
+
+DidimAIStudio는 시나리오별 API-Key 인증을 사용합니다.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        API-Key 인증 흐름                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  1. API-Key 발급                                                        │
+│     DidimAIStudio 웹 UI → 시나리오 설정 → API-Key 생성                  │
+│                                                                          │
+│  2. API-Key 구조 (JWT)                                                  │
+│     {                                                                    │
+│       "user_id": "user-uuid",                                           │
+│       "api_key_metadata": {                                             │
+│         "my_scenario_id": 123,                                          │
+│         ...                                                             │
+│       },                                                                │
+│       ...                                                               │
+│     }                                                                   │
+│                                                                          │
+│  3. 요청 시 헤더                                                        │
+│     Authorization: Bearer <API-KEY>                                     │
+│                                                                          │
+│  4. 인증 처리 (scenario-gateway)                                        │
+│     ApiKeyAuthMiddleware → passport_data 추출 → request.state 저장      │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.5.4 DidimAIStudio 환경 변수 (참고)
+
+```python
+# /services/scenario-gateway/app/config/environment.py
+
+class Settings(BaseSettings):
+    # 서비스 설정
+    app_name: str = "Scenario Gate Service"
+    app_version: str = "1.0.0"
+    host: str = "0.0.0.0"
+    port: int = 8008
+
+    # 환경
+    app_env: str = "development"  # development, production
+    debug: bool = True
+
+    # CORS
+    cors_allow_origins: List[str] = ["*"]
+    cors_allow_credentials: bool = True
+    cors_allow_methods: List[str] = ["*"]
+    cors_allow_headers: List[str] = ["*"]
+
+    # Redis
+    redis_url: str = "redis://cache:6379/0"
+
+    # 동기화 간격
+    stategraph_sync_interval: int = 60
+    ip_whitelist_sync_interval: int = 60
+```
+
+## 4.6 프로바이더 매핑
+
+### 4.6.1 프로바이더 ID 매핑
+
+```typescript
+// packages/core/src/providers/didim/providerMapping.ts
+
+/**
+ * Gemini CLI 프로바이더 ID ↔ DidimAIStudio 프로바이더 ID 매핑
+ */
+export const PROVIDER_MAPPING = {
+  // Gemini CLI → DidimAIStudio
+  gemini: 'google',
+  claude: 'anthropic',
+  openai: 'openai',
+  gpt: 'openai',
+
+  // DidimAIStudio 전용
+  bedrock: 'bedrock',
+  azure: 'azure_openai',
+  mistral: 'mistral',
+  groq: 'groq',
+  naver: 'naver',
+  vllm: 'vllm',
+  together: 'together',
+  cohere: 'cohere',
+  fireworks: 'fireworks',
+  huggingface: 'huggingface',
+};
+
+/**
+ * 모델 이름에서 프로바이더 추론
+ */
+export function detectProvider(modelName: string): string {
+  const name = modelName.toLowerCase();
+
+  if (name.includes('gpt-') || name.includes('o1-')) return 'openai';
+  if (name.includes('claude')) return 'anthropic';
+  if (name.includes('gemini')) return 'google';
+  if (name.includes('mistral')) return 'mistral';
+  if (name.includes('llama')) return 'meta';
+  if (name.includes('command')) return 'cohere';
+
+  return 'unknown';
+}
+```
+
+### 4.6.2 토큰 필드 매핑 통합
+
+```python
+# app/service/chat/provider_manager.py (확장)
+
+class ProviderManager:
+    TOKEN_FIELD_MAPPING = {
+        # 기존 매핑...
+
+        # Gemini CLI 호환 매핑 추가
+        "gemini_cli": {
+            "input": "usage.promptTokens",
+            "output": "usage.completionTokens",
+            "total": "usage.totalTokens"
+        }
+    }
+
+    def normalize_for_gemini_cli(self, usage: dict) -> dict:
+        """DidimAI 토큰 사용량을 Gemini CLI 형식으로 변환"""
+        return {
+            "promptTokens": usage.get("input_tokens", 0),
+            "completionTokens": usage.get("output_tokens", 0),
+            "totalTokens": usage.get("total_tokens", 0),
+        }
+```
+
+## 4.7 에러 처리
+
+### 4.7.1 에러 코드 매핑
+
+```typescript
+// packages/core/src/providers/didim/errorMapping.ts
+
+import { LlmError, LlmErrorType } from '../errors';
+
+/**
+ * DidimAIStudio 에러 코드 → Gemini CLI 에러 타입 매핑
+ */
+export const ERROR_CODE_MAPPING: Record<string, LlmErrorType> = {
+  AUTH_FAILED: LlmErrorType.AUTHENTICATION,
+  RATE_LIMITED: LlmErrorType.RATE_LIMIT,
+  MODEL_OVERLOADED: LlmErrorType.MODEL_OVERLOADED,
+  CONTEXT_TOO_LONG: LlmErrorType.CONTEXT_LENGTH_EXCEEDED,
+  CONTENT_FILTERED: LlmErrorType.CONTENT_FILTER,
+  TIMEOUT: LlmErrorType.TIMEOUT,
+  NETWORK_ERROR: LlmErrorType.NETWORK,
+  INVALID_REQUEST: LlmErrorType.INVALID_REQUEST,
+};
+
+export function mapDidimErrorToLlmError(
+  errorCode: string,
+  message: string,
+): LlmError {
+  const errorType = ERROR_CODE_MAPPING[errorCode] || LlmErrorType.UNKNOWN;
+  return new LlmError(errorType, message, 'didim-aistudio');
+}
+```
+
+### 4.7.2 폴백 전략
+
+```typescript
+// packages/core/src/providers/didim/fallback.ts
+
+export interface FallbackConfig {
+  enabled: boolean;
+  fallbackProvider: string; // 'gemini' | 'claude' | 'openai'
+  maxRetries: number;
+  retryableErrors: LlmErrorType[];
+}
+
+export const DEFAULT_FALLBACK_CONFIG: FallbackConfig = {
+  enabled: true,
+  fallbackProvider: 'gemini',
+  maxRetries: 2,
+  retryableErrors: [
+    LlmErrorType.RATE_LIMIT,
+    LlmErrorType.MODEL_OVERLOADED,
+    LlmErrorType.TIMEOUT,
+    LlmErrorType.NETWORK,
+  ],
+};
+```
+
+## 4.8 테스트 전략
+
+### 4.8.1 단위 테스트
+
+```typescript
+// packages/core/src/providers/didim/converter.test.ts
+
+import { describe, it, expect } from 'vitest';
+import { DidimTypeConverter } from './converter';
+
+describe('DidimTypeConverter', () => {
+  const converter = new DidimTypeConverter();
+
+  describe('toLlmToDidimInput', () => {
+    it('should convert text message correctly', () => {
+      const request: LlmGenerateRequest = {
+        model: 'gemini-2.5-pro',
+        messages: [
+          {
+            role: 'user',
+            content: [{ type: 'text', text: 'Hello' }],
+          },
+        ],
+      };
+
+      const result = converter.toLlmToDidimInput(request, {
+        scenarioMyPageId: 1,
+        userId: 'user-1',
+        threadId: 'thread-1',
+        qaId: 'qa-1',
+      });
+
+      expect(result.message).toBe('Hello');
+      expect(result.scenario_my_page_id).toBe(1);
+    });
+
+    it('should extract attachments from image content', () => {
+      const request: LlmGenerateRequest = {
+        model: 'gemini-2.5-pro',
+        messages: [
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: 'What is this?' },
+              {
+                type: 'image',
+                source: {
+                  type: 'url',
+                  mediaType: 'image/png',
+                  data: 'https://example.com/image.png',
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = converter.toLlmToDidimInput(request, {
+        scenarioMyPageId: 1,
+        userId: 'user-1',
+        threadId: 'thread-1',
+        qaId: 'qa-1',
+      });
+
+      expect(result.attachments).toContain('https://example.com/image.png');
+    });
+  });
+
+  describe('fromDidimOutputToStreamEvent', () => {
+    it('should convert MESSAGE_PARTIAL to content_delta', () => {
+      const output: DidimSSEOutput = {
+        scenario_my_page_id: 1,
+        user_id: 'user-1',
+        thread_id: 'thread-1',
+        qa_id: 'qa-1',
+        status: 'MESSAGE_PARTIAL',
+        content: 'Hello',
+        delta: true,
+      };
+
+      const result = converter.fromDidimOutputToStreamEvent(output);
+
+      expect(result.type).toBe('content_delta');
+      expect(result.delta?.text).toBe('Hello');
+    });
+
+    it('should convert COMPLETE to message_end with usage', () => {
+      const output: DidimSSEOutput = {
+        scenario_my_page_id: 1,
+        user_id: 'user-1',
+        thread_id: 'thread-1',
+        qa_id: 'qa-1',
+        status: 'COMPLETE',
+        total_tokens: 150,
+      };
+
+      const result = converter.fromDidimOutputToStreamEvent(output);
+
+      expect(result.type).toBe('message_end');
+      expect(result.usage?.totalTokens).toBe(150);
+    });
+  });
+});
+```
+
+### 4.8.2 통합 테스트
+
+```typescript
+// packages/core/src/providers/didim/adapter.integration.test.ts
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { DidimAIStudioAdapter } from './adapter';
+
+describe('DidimAIStudioAdapter Integration', () => {
+  let adapter: DidimAIStudioAdapter;
+
+  beforeAll(() => {
+    // 테스트 환경 설정
+    adapter = new DidimAIStudioAdapter({
+      apiKey: process.env.DIDIM_AI_API_KEY || '',
+      baseUrl: process.env.DIDIM_AI_BASE_URL || 'http://localhost:8000',
+      scenarioMyPageId: 1,
+      userId: 'test-user',
+    });
+  });
+
+  it('should generate content via DidimAIStudio', async () => {
+    const request: LlmGenerateRequest = {
+      model: 'gpt-4',
+      messages: [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Say hello' }],
+        },
+      ],
+    };
+
+    const response = await adapter.generateContent(request);
+
+    expect(response.content).toBeDefined();
+    expect(response.content.length).toBeGreaterThan(0);
+  });
+
+  it('should stream content via DidimAIStudio', async () => {
+    const request: LlmGenerateRequest = {
+      model: 'gpt-4',
+      messages: [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Count from 1 to 5' }],
+        },
+      ],
+    };
+
+    const events: LlmStreamEvent[] = [];
+    const stream = await adapter.generateContentStream(request);
+
+    for await (const event of stream) {
+      events.push(event);
+    }
+
+    expect(events.length).toBeGreaterThan(0);
+    expect(events.some((e) => e.type === 'message_end')).toBe(true);
+  });
+});
+```
+
+## 4.9 구현 일정
+
+> **참고**: DidimAIStudio 연동은 Phase 3 (프로바이더 확장) 이후에 진행됩니다.
+> 전체 Multi-LLM 어댑터 리팩토링은 05-implementation-plan.md 참조
+
+### Phase 1: 기반 작업 (3일)
+
+| 작업                                              | 담당       | 일정  |
+| ------------------------------------------------- | ---------- | ----- |
+| DidimAIStudio API 분석 (scenario-gateway, agents) | gemini-cli | 0.5일 |
+| 공통 타입 정의 (TypeScript)                       | gemini-cli | 1일   |
+| 에러 매핑 정의                                    | gemini-cli | 0.5일 |
+| API-Key 발급 및 테스트 환경 구성                  | 공통       | 1일   |
+
+### Phase 2: 어댑터 구현 (5일)
+
+| 작업                               | 담당       | 일정  |
+| ---------------------------------- | ---------- | ----- |
+| DidimAIStudioAdapter 구현          | gemini-cli | 2일   |
+| DidimTypeConverter 구현 (SSE 파싱) | gemini-cli | 1.5일 |
+| SSE 스트리밍 테스트                | gemini-cli | 0.5일 |
+| 기존 API 호환성 검증               | 공통       | 1일   |
+
+### Phase 3: 테스트 및 통합 (4일)
+
+| 작업                                    | 담당       | 일정 |
+| --------------------------------------- | ---------- | ---- |
+| 단위 테스트 작성                        | gemini-cli | 1일  |
+| 통합 테스트 작성 (Docker 환경)          | 공통       | 1일  |
+| E2E 테스트 (scenario-gateway ↔ agents) | 공통       | 1일  |
+| 문서화 및 예제 작성                     | 공통       | 1일  |
+
+### 선택적 확장: Gemini CLI 전용 API (1주)
+
+| 작업                                   | 담당          | 일정 |
+| -------------------------------------- | ------------- | ---- |
+| `/api/v1/gemini-cli/*` 엔드포인트 추가 | DidimAIStudio | 2일  |
+| GeminiCLIService 구현                  | DidimAIStudio | 2일  |
+| 통합 테스트                            | 공통          | 1일  |
+
+### 총 예상 기간: 2주 (기본) ~ 3주 (전용 API 포함)
+
+## 4.10 향후 확장
+
+### 4.10.1 단기 확장 (1-2개월)
+
+1. **양방향 동기화**: 설정 변경 시 실시간 동기화
+2. **분산 트레이싱**: OpenTelemetry 기반 통합 트레이싱
+3. **공유 메모리**: 대화 히스토리 공유
+
+### 4.10.2 장기 확장 (3-6개월)
+
+1. **플러그인 시스템**: gemini-cli에서 DidimAI 에이전트 직접 호출
+2. **워크플로우 연동**: LangGraph 워크플로우를 CLI에서 실행
+3. **통합 대시보드**: 사용량, 비용, 성능 통합 모니터링
+
+---
+
+## 4.11 서버 측 문맥 관리 및 제약사항 (리뷰 피드백 C 반영)
+
+### 4.11.1 문맥 관리 아키텍처 차이
+
+Gemini CLI(기본 모드)와 DidimAIStudio 연동 모드는 대화 문맥(히스토리) 관리
+방식이 근본적으로 다릅니다:
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                     문맥 관리 방식 비교                                    │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  [기본 모드: 클라이언트 측 관리]                                          │
+│  ┌─────────────┐    전체 히스토리 전송    ┌──────────────┐               │
+│  │ Gemini CLI  │ ───────────────────────▶ │ LLM API      │               │
+│  │ (히스토리   │                          │ (Stateless)  │               │
+│  │  로컬 저장) │ ◀─────────────────────── │              │               │
+│  └─────────────┘    응답                  └──────────────┘               │
+│                                                                          │
+│  [Gateway 모드: 서버 측 관리]                                            │
+│  ┌─────────────┐   마지막 메시지만 전송   ┌──────────────┐               │
+│  │ Gemini CLI  │ ───────────────────────▶ │ DidimAI      │               │
+│  │ (로컬 사본) │   + thread_id 헤더       │ Studio       │               │
+│  │             │                          │ (thread에    │               │
+│  │             │ ◀─────────────────────── │  히스토리    │               │
+│  └─────────────┘    응답 + thread_id      │  서버 저장)  │               │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.11.2 알려진 제약사항
+
+> ⚠️ **중요**: 아래 제약사항들은 DidimAIStudio Gateway 모드 사용 시 적용됩니다.
+
+| 제약사항                 | 설명                                                            | 영향                                          |
+| ------------------------ | --------------------------------------------------------------- | --------------------------------------------- |
+| **단방향 동기화**        | CLI 로컬 히스토리 조작(삭제/수정)이 서버 thread에 반영되지 않음 | 로컬에서 대화 삭제해도 서버는 이전 문맥 유지  |
+| **히스토리 전송 불가**   | `extractLastUserMessage()`로 마지막 메시지만 전송               | 시스템 메시지, 이전 대화가 직접 전달되지 않음 |
+| **서버 의존적 문맥**     | Multi-turn 품질은 DidimAIStudio의 thread 관리에 의존            | 서버 측 thread 만료/삭제 시 문맥 손실 가능    |
+| **도구 컨텍스트 미전달** | `tools[]` 정보가 gateway API로 전달되지 않음                    | 시나리오에 사전 정의된 도구만 사용 가능       |
+
+### 4.11.3 UX 안내 메시지 설계 (권고사항 2 반영)
+
+DidimAIStudio 연동 시 사용자에게 서버 측 문맥 관리 특성을 인지시키기 위한 UX
+장치:
+
+```typescript
+// packages/cli/src/views/DidimModeIndicator.tsx
+
+const DIDIM_MODE_NOTICES = {
+  // 세션 시작 시 표시 (한 번만)
+  sessionStart: `
+    ℹ️  DidimAIStudio 모드로 연결되었습니다.
+    • 대화 히스토리는 서버에서 관리됩니다.
+    • 로컬에서 히스토리를 수정해도 서버에 반영되지 않습니다.
+  `,
+
+  // 새 thread 시작 시
+  newThread: (threadId: string) => `
+    🔗 새 대화 스레드가 시작되었습니다: ${threadId.substring(0, 8)}...
+  `,
+
+  // 기존 thread 연결 시
+  resumeThread: (threadId: string) => `
+    🔗 기존 대화를 이어갑니다: ${threadId.substring(0, 8)}...
+    (서버에 저장된 대화 문맥이 적용됩니다)
+  `,
+
+  // 로컬 히스토리 삭제 시도 시 경고
+  localDeleteWarning: `
+    ⚠️  로컬 히스토리만 삭제됩니다.
+    서버의 대화 기록은 유지되며, 다음 질문 시 이전 문맥이 적용될 수 있습니다.
+  `,
+};
+
+// 사용 예시
+function renderSessionStart(): React.ReactNode {
+  const { provider } = useProviderContext();
+
+  if (provider === 'didim') {
+    return (
+      <Box marginBottom={1}>
+        <Text color="cyan">{DIDIM_MODE_NOTICES.sessionStart}</Text>
+      </Box>
+    );
+  }
+  return null;
+}
+```
+
+### 4.11.4 향후 해결 방안 (Out of Scope)
+
+아래 항목들은 현재 설계 범위 외이며, 향후 확장으로 고려됩니다:
+
+1. **양방향 동기화 API**: CLI ↔ DidimAIStudio 간 히스토리 동기화 프로토콜
+2. **Thread 관리 CLI 명령어**: `gemini thread list`, `gemini thread delete <id>`
+3. **오프라인 모드 전환**: 서버 연결 불가 시 자동으로 기본 모드로 fallback