codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/services/chat_service.py

@@ -0,0 +1,898 @@
+"""
+채팅 서비스 구현
+
+IChatService의 Embedded 구현.
+"""
+
+import logging
+import os
+import re
+from datetime import datetime
+from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple
+
+from codebuff_core.interfaces import IChatService
+from codebuff_core.llm import LLMService
+from codebuff_core.llm.service import DEFAULT_MAX_OUTPUT_TOKENS
+from codebuff_core.managers import get_config_manager, get_session_manager
+from codebuff_core.managers.session_manager import ChatMessage
+from codebuff_core.models.chat import ChatRequest, ChatResponse
+from codebuff_core.services.pii_guardrail import mask_pii
+
+logger = logging.getLogger(__name__)
+
+
+def _chat_system_prompt() -> str:
+    """채팅 호출의 system — 도구 없는 Chat 과 같은 `prompts.chat_system_prompt` (이슈 #218).
+
+    요약·테이블 후보 질문처럼 채팅이 아닌 호출은 system 을 넘기지 않는다.
+    """
+    from codebuff_core.services.rag_chat_agent import build_chat_mode_system_prompt
+
+    return build_chat_mode_system_prompt("simple")
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# @<경로> Context Injection (이슈 #259 — codex CLI 처럼 `@` 는 파일 지정 하나)
+# ═══════════════════════════════════════════════════════════════════════════
+FILE_CONTEXT_TEMPLATE = """The following is the content of the file `{filepath}`:
+
+```
+{content}
+```"""
+
+# `@경로` · `@"공백 경로"` · 옛 `@file:경로` (손으로 친 옛 형식).
+# 작은따옴표는 경로 구분자로 쓰지 않는다 — `@'s value ... it's` 같은 영어 문장을 잡는다.
+_FILE_CMD_PATTERN = re.compile(
+    r"(?<!\S)@(?P<legacy>file:)?"
+    r"(?:\"(?P<dq>[^\"\n]+)\"|(?P<bare>[^\s\"'`\\]+(?:\\ [^\s\\]*)*))"
+)
+
+# 경로 뒤에 붙은 구두점·조사(`@a.py,` · `@a.py를`)만 떼어 본다. 영문·숫자는 떼지 않는다 —
+# `@property` 가 `prop` 파일로, `@a.pyc` 가 `a.py` 로 풀리면 안 된다.
+_TRAILING_TRIM = re.compile(r"[.,;:!?)\]}가-힣]{1,4}$")
+_MAX_FILE_CHARS = 100_000
+# 노트북은 JSON 전체를 파싱해야 셀을 합칠 수 있어 읽기 전에 크기로 막는다 (출력 이미지가 든 수백 MB 파일)
+_MAX_NOTEBOOK_BYTES = 20 * 1024 * 1024
+
+
+def _resolve_mention(arg: str, base_dir: str) -> str:
+    filepath = arg if os.path.isabs(arg) else os.path.join(base_dir, arg)
+    return os.path.normpath(filepath)
+
+
+def _inside_root(filepath: str, base_dir: str) -> bool:
+    """멘션은 기준 디렉터리 안의 파일만 읽는다 — `..`·절대경로·심볼릭 링크로 밖을 못 읽는다.
+
+    파서는 사람이 친 글만이 아니라 붙여 넣은 코드·노트북 본문도 훑는다. 그 안의
+    `@../../.aws/credentials` 가 LLM 으로 새면 안 된다 (read-file API 와 같은 경계).
+    """
+    root = os.path.realpath(base_dir)
+    return os.path.commonpath([root, os.path.realpath(filepath)]) == root
+
+
+def _read_mention_file(filepath: str) -> str:
+    if filepath.endswith(".ipynb") and os.path.getsize(filepath) > _MAX_NOTEBOOK_BYTES:
+        raise ValueError(f"notebook too large (> {_MAX_NOTEBOOK_BYTES} bytes)")
+    with open(filepath, "r", encoding="utf-8") as f:
+        if not filepath.endswith(".ipynb"):
+            # 전체를 읽고 자르지 않는다 — 수 GB 파일이 메모리에 통째로 올라온다
+            content = f.read(_MAX_FILE_CHARS + 1)
+            if len(content) > _MAX_FILE_CHARS:
+                content = content[:_MAX_FILE_CHARS] + "\n\n... [truncated]"
+            return content
+        content = f.read()
+    try:
+        import nbformat
+
+        nb = nbformat.reads(content, as_version=4)
+        content = "\n\n".join(
+            f"# Cell {i + 1} ({c.cell_type}):\n{c.source}"
+            for i, c in enumerate(nb.cells)
+        )
+    except Exception:
+        pass  # Use raw content if parsing fails
+    if len(content) > _MAX_FILE_CHARS:
+        content = (
+            content[:_MAX_FILE_CHARS]
+            + f"\n\n... [truncated, {len(content) - _MAX_FILE_CHARS} more characters]"
+        )
+    return content
+
+
+def _process_file_commands(
+    message: str, base_dir: str = "."
+) -> Tuple[str, str, List[str]]:
+    """Process `@<경로>` file mentions in a user message.
+
+    기준 디렉터리 안의 실제 파일로 풀리는 멘션만 내용을 싣고 `'경로'` 로 바꾼다. `@notebook`·`@property`·
+    이메일·없는 경로·디렉터리는 원문 그대로 두고 오류도 내지 않는다 — 코드에 흔한
+    데코레이터가 파일 조회 오류로 번지지 않게 한다. 파일이라고 **명시한** 옛 `@file:`
+    과 따옴표 경로만 없을 때 오류를 낸다.
+
+    Args:
+        message: User message potentially containing @<경로> mentions
+        base_dir: Base directory for resolving relative paths
+
+    Returns:
+        Tuple of (file_context, cleaned_message, errors)
+    """
+    context_parts: List[str] = []
+    errors: List[str] = []
+    pieces: List[str] = []
+    pos = 0
+
+    for match in _FILE_CMD_PATTERN.finditer(message):
+        explicit = bool(match.group("legacy")) or match.group("bare") is None
+        raw = match.group("dq") or match.group("bare") or ""
+        arg, suffix = raw.replace("\\ ", " "), ""
+        filepath = _resolve_mention(arg, base_dir)
+
+        trail = _TRAILING_TRIM.search(arg)
+        if match.group("bare") is not None and not os.path.isfile(filepath) and trail:
+            for n in range(1, min(len(trail.group()), len(arg) - 1) + 1):
+                candidate = _resolve_mention(arg[:-n], base_dir)
+                if os.path.isfile(candidate):
+                    arg, suffix, filepath = arg[:-n], arg[-n:], candidate
+                    break
+
+        if not _inside_root(filepath, base_dir):
+            if explicit:
+                errors.append(f"Path outside workspace: {arg}")
+            continue
+
+        if not os.path.isfile(filepath):
+            if explicit:
+                if os.path.isdir(filepath):
+                    errors.append(f"Cannot read directory: {filepath}")
+                else:
+                    errors.append(f"File not found: {filepath}")
+            continue
+
+        try:
+            content = _read_mention_file(filepath)
+        except UnicodeDecodeError:
+            errors.append(f"Cannot read file (encoding error): {filepath}")
+            continue
+        except PermissionError:
+            errors.append(f"Permission denied: {filepath}")
+            continue
+        except Exception as e:
+            errors.append(f"Error reading {filepath}: {e}")
+            continue
+
+        context_parts.append(
+            FILE_CONTEXT_TEMPLATE.format(filepath=filepath, content=content)
+        )
+        pieces.append(message[pos : match.start()])
+        pieces.append(f"'{arg}'{suffix}")
+        pos = match.end()
+        logger.info(f"Processed file mention: {match.group()}")
+
+    pieces.append(message[pos:])
+    combined_context = "\n\n".join(context_parts) if context_parts else ""
+    return combined_context, "".join(pieces), errors
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Summarization Prompt (Claude Code Benchmark)
+# ═══════════════════════════════════════════════════════════════════════════
+SUMMARIZATION_PROMPT = """다음 대화 내용을 요약하여 향후 컨텍스트 윈도우에서 작업을 효율적으로 재개할 수 있도록 해주세요.
+이 요약은 대화 히스토리를 대체하므로, 구조화되고 간결하며 실행 가능해야 합니다.
+
+요약에 반드시 포함할 내용:
+
+## 완료된 작업
+- 완료된 태스크와 주요 결과물
+- 생성/수정된 파일 목록
+
+## 현재 상태
+- 진행 중인 작업
+- 마지막으로 논의된 주제
+
+## 다음 단계
+- 명확한 후속 액션 항목
+- 보류 중인 결정 사항
+
+## 핵심 맥락
+- 사용자 선호사항 및 제약조건
+- 중요한 기술적 결정사항
+- 작업 재개에 필수적인 정보
+
+작성 지침:
+- 간결하되, 작업이 끊김 없이 계속될 수 있을 정도의 세부사항은 보존
+- 불필요한 인사말, 확인 메시지, 중복 내용은 제외
+- 코드 스니펫은 핵심적인 경우에만 포함
+- 한국어로 작성
+
+대화 내용:
+{conversation}
+
+요약:"""
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Auto-Compact Configuration (Aligned with Agent mode SummarizationMiddleware)
+# ═══════════════════════════════════════════════════════════════════════════
+AUTO_COMPACT_TOKEN_THRESHOLD = 30000  # Trigger when tokens exceed this threshold
+AUTO_COMPACT_KEEP_MESSAGES = 15  # Keep last N messages after compaction
+
+# Token estimation
+CHARS_PER_TOKEN = 3.5
+
+
+def _request_file_context(request: ChatRequest) -> Tuple[str, str, List[str]]:
+    """요청의 `@<경로>` 멘션을 푼다. 앱이 만든 프롬프트(`fileMentions=False`)는 그대로 둔다."""
+    if not request.fileMentions:
+        return "", request.message, []
+    return _process_file_commands(
+        request.message, base_dir=request.workspaceRoot or os.getcwd()
+    )
+
+
+def _estimate_tokens(text: str) -> int:
+    """Estimate token count from text length."""
+    return int(len(text) / CHARS_PER_TOKEN)
+
+
+def _estimate_session_tokens(messages) -> int:
+    """Estimate total tokens in session messages."""
+    total_chars = sum(len(m.content) for m in messages)
+    return int(total_chars / CHARS_PER_TOKEN)
+
+
+class EmbeddedChatService(IChatService):
+    """
+    채팅 서비스 구현.
+
+    인프로세스에서 직접 채팅 로직을 실행합니다.
+    """
+
+    def __init__(self):
+        """Embedded 채팅 서비스 초기화"""
+        self._config_manager = get_config_manager()
+        self._session_manager = get_session_manager()
+        # RAG agent checkpointer: ToolMessage(스킬 내용 등)를 turn 간 유지
+        self._rag_checkpointer = None  # lazy init
+        self._rag_initialized_threads: set = set()
+        # RAG agent 캐시: conversation별로 같은 graph 인스턴스 재사용
+        self._rag_agents: Dict[str, Any] = {}  # conv_id → RAGChatAgent
+        logger.info("EmbeddedChatService 초기화됨")
+
+    def _get_config(self) -> Dict[str, Any]:
+        """현재 LLM 설정 반환"""
+        return self._config_manager.get_config()
+
+    def _build_llm_config(self, llm_config) -> Dict[str, Any]:
+        """LLM 설정 — 서버가 해석한 값만 쓴다 (이슈 #113).
+
+        접속 설정은 centri > 시크릿 env > pod 파일이고, 브라우저가 보낸 `llmConfig` 의
+        접속 정보는 받지 않는다. 인자는 호출부 호환을 위해 남겼다.
+        """
+        return self._get_config()
+
+    def _get_or_create_conversation(self, conversation_id: Optional[str]) -> str:
+        """기존 대화 가져오기 또는 새로 생성"""
+        session = self._session_manager.get_or_create_session(conversation_id)
+        return session.id
+
+    def _build_context(
+        self, conversation_id: str, max_messages: int = 5
+    ) -> Optional[str]:
+        """이력에서 대화 컨텍스트 구성"""
+        return self._session_manager.build_context(conversation_id, max_messages)
+
+    def _store_messages(
+        self, conversation_id: str, user_message: str, assistant_response: str
+    ) -> None:
+        """대화 이력에 사용자 및 어시스턴트 메시지 저장"""
+        self._session_manager.store_messages(
+            conversation_id, user_message, assistant_response
+        )
+
+    async def _auto_compact_if_needed(
+        self, conversation_id: str, llm_config: Dict[str, Any]
+    ) -> Optional[str]:
+        """토큰 임계값 초과 시 자동 압축.
+
+        Agent 모드 SummarizationMiddleware와 동일 전략:
+        - 트리거: 토큰 수 > AUTO_COMPACT_TOKEN_THRESHOLD
+        - 유지: 최근 AUTO_COMPACT_KEEP_MESSAGES개 메시지
+        - 결과: [요약] + [최근 메시지]
+
+        Returns:
+            압축된 경우 요약 문자열, 아니면 None
+        """
+        session = self._session_manager.get_session(conversation_id)
+        if not session or not session.messages:
+            return None
+
+        estimated_tokens = _estimate_session_tokens(session.messages)
+
+        if estimated_tokens <= AUTO_COMPACT_TOKEN_THRESHOLD:
+            return None
+
+        if len(session.messages) <= AUTO_COMPACT_KEEP_MESSAGES:
+            return None
+
+        logger.info(
+            f"[Chat] Auto-compact triggered for {conversation_id}: "
+            f"~{estimated_tokens} tokens > {AUTO_COMPACT_TOKEN_THRESHOLD} threshold, "
+            f"{len(session.messages)} messages"
+        )
+
+        try:
+            messages_to_summarize = session.messages[:-AUTO_COMPACT_KEEP_MESSAGES]
+            recent_messages = session.messages[-AUTO_COMPACT_KEEP_MESSAGES:]
+
+            conversation_text = "\n".join(
+                [
+                    f"{'사용자' if m.role == 'user' else '어시스턴트'}: {m.content}"
+                    for m in messages_to_summarize
+                ]
+            )
+
+            llm_service = LLMService(llm_config)
+            prompt = SUMMARIZATION_PROMPT.format(conversation=conversation_text)
+            summary = await llm_service.generate_response(prompt)
+
+            summary_message = ChatMessage(
+                role="assistant",
+                content=f"[이전 대화 요약]\n\n{summary}",
+                timestamp=datetime.now().timestamp(),
+            )
+
+            original_count = len(session.messages)
+            session.messages = [summary_message] + list(recent_messages)
+            session.updated_at = datetime.now().timestamp()
+            self._session_manager._save_sessions()
+
+            compressed_count = len(session.messages)
+            logger.info(
+                f"[Chat] Auto-compacted {conversation_id}: "
+                f"{original_count} -> {compressed_count} messages"
+            )
+
+            return summary
+
+        except Exception as e:
+            logger.error(f"[Chat] Auto-compact failed: {e}", exc_info=True)
+            return None
+
+    async def send_message(self, request: ChatRequest) -> ChatResponse:
+        """채팅 메시지를 보내고 응답 받기"""
+        logger.info(f"[Embedded] 채팅 메시지: {request.message[:100]}...")
+
+        config = self._build_llm_config(request.llmConfig)
+
+        if not config or not config.get("provider"):
+            raise ValueError(
+                "LLM이 설정되지 않음. API 키가 포함된 llmConfig를 제공하세요."
+            )
+
+        # 대화 가져오기 또는 생성
+        conversation_id = self._get_or_create_conversation(request.conversationId)
+
+        # @<경로> 컨텍스트 처리 — 핸들러가 채운 워크스페이스 루트 기준 (이슈 #259)
+        file_context, cleaned_message, context_errors = _request_file_context(request)
+        if context_errors:
+            logger.warning(f"Context processing errors: {context_errors}")
+
+        # 이력에서 컨텍스트 구성
+        history_context = self._build_context(conversation_id)
+
+        # 파일 컨텍스트 + 이력 컨텍스트 결합
+        all_context_parts = []
+        if file_context:
+            all_context_parts.append(file_context)
+        if history_context:
+            all_context_parts.append(history_context)
+        combined_context = "\n\n".join(all_context_parts) if all_context_parts else None
+
+        # LLM 호출
+        llm_service = LLMService(config)
+        response = await llm_service.generate_response(
+            cleaned_message,
+            context=combined_context,
+            system_prompt=_chat_system_prompt(),
+        )
+
+        # 메시지 저장 (cleaned_message 사용)
+        self._store_messages(conversation_id, cleaned_message, response)
+
+        # 자동 압축 (토큰 임계값 초과 시)
+        await self._auto_compact_if_needed(conversation_id, config)
+
+        # 모델 정보 가져오기
+        provider = config.get("provider", "unknown")
+        model = config.get(provider, {}).get("model", "unknown")
+
+        return ChatResponse(
+            response=response,
+            conversationId=conversation_id,
+            model=f"{provider}/{model}",
+        )
+
+    async def compact(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        """Compact conversation history by summarizing older messages.
+
+        Strategy (Claude Code benchmark):
+        - Keep the last 3 messages intact
+        - Summarize all older messages using LLM
+        - Replace history with [summary] + [last 3 messages]
+        """
+        conversation_id = body.get("conversationId")
+        if not conversation_id:
+            return {
+                "success": False,
+                "message": "conversationId가 필요합니다.",
+                "originalMessages": 0,
+                "compressedMessages": 0,
+            }
+
+        session = self._session_manager.get_session(conversation_id)
+        if not session:
+            return {
+                "success": False,
+                "message": "세션을 찾을 수 없습니다.",
+                "originalMessages": 0,
+                "compressedMessages": 0,
+            }
+
+        original_count = len(session.messages)
+
+        # Already minimal - no compaction needed
+        if original_count <= 3:
+            return {
+                "success": True,
+                "message": "이미 최소 상태입니다. 압축이 필요하지 않습니다.",
+                "originalMessages": original_count,
+                "compressedMessages": original_count,
+            }
+
+        try:
+            # Split messages: older (to summarize) vs recent (to keep)
+            messages_to_summarize = session.messages[:-3]
+            recent_messages = session.messages[-3:]
+
+            # Build conversation text for summarization
+            conversation_text = "\n".join(
+                [
+                    f"{'사용자' if m.role == 'user' else '어시스턴트'}: {m.content}"
+                    for m in messages_to_summarize
+                ]
+            )
+
+            # Get LLM config from body or fallback to server config
+            llm_config = body.get("llmConfig") or self._get_config()
+            if isinstance(llm_config, dict) and "provider" not in llm_config:
+                llm_config = self._get_config()
+
+            # Generate summary using LLMService
+            llm_service = LLMService(llm_config)
+            prompt = SUMMARIZATION_PROMPT.format(conversation=conversation_text)
+            summary = await llm_service.generate_response(prompt)
+
+            # Create summary message
+            summary_message = ChatMessage(
+                role="assistant",
+                content=f"[이전 대화 요약]\n\n{summary}",
+                timestamp=datetime.now().timestamp(),
+            )
+
+            # Replace session messages: [summary] + [last 3]
+            session.messages = [summary_message] + list(recent_messages)
+            session.updated_at = datetime.now().timestamp()
+
+            # Persist changes
+            self._session_manager._save_sessions()
+
+            compressed_count = len(session.messages)
+            logger.info(
+                f"Compacted conversation {conversation_id}: "
+                f"{original_count} -> {compressed_count} messages"
+            )
+
+            return {
+                "success": True,
+                "message": f"대화가 압축되었습니다. ({original_count}개 → {compressed_count}개 메시지)",
+                "originalMessages": original_count,
+                "compressedMessages": compressed_count,
+                "summary": summary,
+            }
+
+        except Exception as e:
+            logger.error(f"Compact failed: {e}", exc_info=True)
+            return {
+                "success": False,
+                "message": f"압축 중 오류가 발생했습니다: {str(e)}",
+                "originalMessages": original_count,
+                "compressedMessages": original_count,
+            }
+
+    async def send_message_stream(
+        self, request: ChatRequest
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """채팅 메시지를 보내고 스트리밍 응답 받기"""
+        logger.info(f"[Embedded] 채팅 스트림: {request.message[:100]}...")
+
+        # AWS Secrets Manager 연결정보 로드 실패 시 여기서 사용자에게 알림
+        # (기동은 정상 진행되고, 실제 채팅 시도 시점에만 노출)
+        _secret_err = os.environ.get("CODEBUFF_SECRET_LOAD_ERROR")
+        if _secret_err:
+            yield {
+                "error": (
+                    "연결 설정을 불러오지 못했습니다 (AWS Secrets Manager). "
+                    "관리자에게 문의하세요. "
+                    f"[{_secret_err}]"
+                )
+            }
+            return
+
+        config = self._build_llm_config(request.llmConfig)
+
+        if not config or not config.get("provider"):
+            yield {
+                "error": "LLM이 설정되지 않음. API 키가 포함된 llmConfig를 제공하세요."
+            }
+            return
+
+        # 대화 가져오기 또는 생성
+        conversation_id = self._get_or_create_conversation(request.conversationId)
+
+        # /reset 명령: agent 캐시 + checkpointer state 초기화
+        if request.message.strip() == "/reset":
+            self._reset_rag_conversation(conversation_id)
+            yield {
+                "content": "대화가 초기화되었습니다.",
+                "done": True,
+                "conversationId": conversation_id,
+                "reset": True,
+            }
+            return
+
+        # @<경로> 컨텍스트 처리 — 핸들러가 채운 워크스페이스 루트 기준 (이슈 #259)
+        file_context, cleaned_message, context_errors = _request_file_context(request)
+
+        # 컨텍스트 에러를 경고로 전송
+        if context_errors:
+            yield {
+                "warning": "Context errors: " + "; ".join(context_errors),
+                "done": False,
+            }
+
+        # === PII Guardrail ===
+        # 사용자 메시지에서 PII 14종 검출 → 동일 길이 '*' 마스킹.
+        # 마스킹된 cleaned_message가 이후 모든 경로(RAG agent, 일반 LLM, 저장)로 흐름.
+        mask = mask_pii(cleaned_message)
+        if mask.has_pii:
+            logger.info(
+                "[PII] masked types=%s count=%d",
+                mask.detected_types,
+                len(mask.matches),
+            )
+            cleaned_message = mask.masked_text
+            yield {
+                "type": "input_masked",
+                "masked_text": mask.masked_text,
+                "detected_types": mask.detected_types,
+                "done": False,
+            }
+
+        # RAG agent 라우팅 — simple/knowledge 모두 RAG agent 경로 사용 (컨텍스트 공유)
+        # simple 모드: no_tools=True + prefix 주입으로 도구 호출 차단
+        # checkpointer가 대화 state를 관리하므로 history_context는 주입하지 않음
+        chat_mode = request.chatMode
+        if self._should_use_rag_agent():
+            async for chunk in self._stream_via_rag_agent(
+                config,
+                conversation_id,
+                cleaned_message,
+                file_context or None,
+                chat_mode=chat_mode,
+            ):
+                yield chunk
+            return
+
+        # 이력 컨텍스트 구성 (기존 LLM 경로에서만 사용)
+        history_context = self._build_context(conversation_id)
+
+        # 파일 컨텍스트 + 이력 컨텍스트 결합
+        all_context_parts = []
+        if file_context:
+            all_context_parts.append(file_context)
+        if history_context:
+            all_context_parts.append(history_context)
+        combined_context = "\n\n".join(all_context_parts) if all_context_parts else None
+
+        # LLM 응답 스트리밍 (기존 경로)
+        llm_service = LLMService(config)
+        full_response = ""
+
+        max_tokens = request.maxTokens or self._config_manager.get(
+            "maxOutputTokens", DEFAULT_MAX_OUTPUT_TOKENS
+        )
+
+        try:
+            async for chunk in llm_service.generate_response_stream(
+                cleaned_message,
+                context=combined_context,
+                max_tokens=max_tokens,
+                system_prompt=_chat_system_prompt(),
+            ):
+                full_response += chunk
+                yield {"content": chunk, "done": False}
+
+            # 스트리밍 완료 후 메시지 저장 (cleaned_message 사용)
+            self._store_messages(conversation_id, cleaned_message, full_response)
+
+            # 자동 압축 체크 (토큰 임계값 초과 시)
+            session = self._session_manager.get_session(conversation_id)
+            if session and session.messages:
+                estimated_tokens = _estimate_session_tokens(session.messages)
+                if (
+                    estimated_tokens > AUTO_COMPACT_TOKEN_THRESHOLD
+                    and len(session.messages) > AUTO_COMPACT_KEEP_MESSAGES
+                ):
+                    yield {
+                        "status": "대화 컨텍스트 요약 중...",
+                        "icon": "thinking",
+                        "done": False,
+                    }
+                    summary = await self._auto_compact_if_needed(
+                        conversation_id, config
+                    )
+                    if summary:
+                        yield {
+                            "status": "대화가 자동으로 압축되었습니다.",
+                            "icon": "check",
+                            "done": False,
+                        }
+
+            # 마지막 청크 전송
+            yield {"content": "", "done": True, "conversationId": conversation_id}
+
+        except Exception as e:
+            logger.error(f"스트림 채팅 실패: {e}", exc_info=True)
+            yield {"error": str(e)}
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # RAG Agent 라우팅
+    # ═══════════════════════════════════════════════════════════════════════
+
+    @staticmethod
+    def _should_use_rag_agent() -> bool:
+        """RAG가 가용한지 확인. 매니저가 미등록이면 초기화 시도."""
+        from codebuff_core.services.rag_collections import is_rag_available
+
+        if is_rag_available():
+            return True
+
+        # 서버 재시작 후 RAG Admin 페이지를 안 열었을 때를 위한 자동 초기화
+        try:
+            from jupyter_ext.handlers.rag_admin_handler import _ensure_manager
+
+            _ensure_manager()
+            return is_rag_available()
+        except Exception as e:
+            logger.warning("RAG 자동 초기화 실패 (기존 LLM 경로 사용): %s", e)
+            return False
+
+    def _reset_rag_conversation(self, conversation_id: str) -> None:
+        """대화 초기화: agent 캐시 + checkpointer state + initialized_threads 정리."""
+        # agent 캐시에서 해당 conversation 제거
+        self._rag_agents.pop(conversation_id, None)
+        # initialized_threads에서 제거 (다음 턴에서 first_turn으로 처리)
+        self._rag_initialized_threads.discard(conversation_id)
+        # checkpointer에서 해당 thread state 제거
+        if self._rag_checkpointer is not None:
+            try:
+                storage = getattr(self._rag_checkpointer, "storage", None)
+                if storage and isinstance(storage, dict):
+                    storage.pop(conversation_id, None)
+            except Exception:
+                pass
+        logger.info(f"[RAG-Chat] conversation reset: {conversation_id[:12]}...")
+
+    async def _generate_table_clarification(
+        self,
+        config: Dict[str, Any],
+        candidates: dict,
+        confirmed_tables: Optional[list] = None,
+    ) -> str:
+        """테이블 후보를 LLM에 전달하여 사용자에게 되묻는 자연스러운 질문 생성."""
+        try:
+            # 후보 정보를 간결하게 정리
+            candidate_info = []
+            for query, tables in candidates.items():
+                group = {"검색어": query, "후보": []}
+                for t in tables[:5]:
+                    group["후보"].append(
+                        {
+                            "테이블명": t.get("table_name", ""),
+                            "한글명": t.get("korean_name", ""),
+                            "설명": t.get("description", "")[:100],
+                            "score": t.get("score", 0),
+                        }
+                    )
+                candidate_info.append(group)
+
+            confirmed_info = []
+            if confirmed_tables:
+                for t in confirmed_tables:
+                    confirmed_info.append(
+                        {
+                            "테이블명": t.get("table_name", ""),
+                            "한글명": t.get("korean_name", ""),
+                        }
+                    )
+
+            import json as _json
+
+            prompt = (
+                "사용자가 테이블을 검색했는데 여러 후보가 나왔습니다. "
+                "사용자에게 어떤 테이블을 의미하는지 자연스럽게 되물어주세요.\n\n"
+                "규칙:\n"
+                "- 각 후보 테이블의 테이블명, 한글명, 설명을 간단히 소개하세요.\n"
+                "- 사용자가 쉽게 선택할 수 있도록 번호나 테이블명으로 안내하세요.\n"
+                "- 자동 확인된 테이블이 있으면 별도로 안내하세요.\n"
+                "- 마크다운 형식으로 작성하세요.\n\n"
+                f"[후보 테이블]\n{_json.dumps(candidate_info, ensure_ascii=False)}\n\n"
+            )
+            if confirmed_info:
+                prompt += (
+                    f"[자동 확인된 테이블]\n"
+                    f"{_json.dumps(confirmed_info, ensure_ascii=False)}\n\n"
+                )
+
+            llm_service = LLMService(config)
+            response = await llm_service.generate_response(prompt)
+            return response.strip()
+        except Exception as e:
+            logger.warning(f"테이블 후보 질문 생성 실패: {e}")
+            # fallback: 간단한 텍스트
+            lines = [
+                "검색 결과 여러 테이블이 발견되었습니다. 어떤 테이블을 의미하셨나요?\n"
+            ]
+            for query, tables in candidates.items():
+                lines.append(f"**{query}**")
+                for t in tables[:5]:
+                    tname = t.get("table_name", "")
+                    kname = t.get("korean_name", "")
+                    lines.append(f"- `{tname}` ({kname})")
+                lines.append("")
+            if confirmed_tables:
+                lines.append("자동 확인된 테이블:")
+                for t in confirmed_tables:
+                    lines.append(
+                        f"- `{t.get('table_name', '')}` ({t.get('korean_name', '')})"
+                    )
+            lines.append("\n원하시는 테이블명을 알려주세요.")
+            return "\n".join(lines)
+
+    def _build_history_messages(
+        self, conversation_id: str, limit: int = 10
+    ) -> Optional[List[Dict[str, str]]]:
+        """SessionManager 이력을 RAGChatAgent용 메시지 리스트로 변환."""
+        session = self._session_manager.get_session(conversation_id)
+        if not session or not session.messages:
+            return None
+        recent = session.messages[-limit:]
+        return [{"role": m.role, "content": m.content} for m in recent]
+
+    def _get_rag_checkpointer(self):
+        """RAG agent용 MemorySaver를 lazy 초기화."""
+        if self._rag_checkpointer is None:
+            from langgraph.checkpoint.memory import MemorySaver
+
+            self._rag_checkpointer = MemorySaver()
+        return self._rag_checkpointer
+
+    async def _stream_via_rag_agent(
+        self,
+        config: Dict[str, Any],
+        conversation_id: str,
+        cleaned_message: str,
+        combined_context: Optional[str],
+        chat_mode: Optional[str] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """RAGChatAgent를 통해 스트리밍 응답.
+
+        MemorySaver checkpointer로 turn 간 LangGraph state 유지.
+        첫 turn에만 SessionManager 이력을 전달 (서버 재시작 후 연속성).
+        이후 turn에서는 checkpointer가 ToolMessage 포함 전체 state 유지.
+        """
+        from codebuff_core.services.rag_chat_agent import (
+            RAGChatAgent,
+        )
+
+        try:
+            checkpointer = self._get_rag_checkpointer()
+            is_first_turn = conversation_id not in self._rag_initialized_threads
+            is_simple = chat_mode == "simple"
+
+            logger.info(
+                f"[RAG-Chat] conv={conversation_id[:12]}... "
+                f"first_turn={is_first_turn} mode={chat_mode} "
+                f"initialized_threads={len(self._rag_initialized_threads)}"
+            )
+
+            # agent graph 캐시: 같은 conversation에서는 같은 graph 재사용
+            # (graph namespace가 달라지면 checkpointer에서 이전 state를 못 찾음)
+            # chat_mode를 키에 포함하지 않음 — 사용자가 모드를 전환해도 대화 연속성 유지
+            agent = self._rag_agents.get(conversation_id)
+            if agent is None:
+                agent = RAGChatAgent(
+                    config,
+                    checkpointer=checkpointer,
+                    table_score_threshold=0.7,
+                    table_confirm_mode="chat",
+                )
+                # 캐시 크기 제한 (가장 오래된 것 제거)
+                if len(self._rag_agents) > 50:
+                    oldest = next(iter(self._rag_agents))
+                    del self._rag_agents[oldest]
+                self._rag_agents[conversation_id] = agent
+
+            effective_message = cleaned_message
+
+            # 첫 turn: SessionManager 이력 전달 (서버 재시작 후 연속성)
+            # 이후: checkpointer가 state 유지하므로 history 불필요
+            history = (
+                self._build_history_messages(conversation_id) if is_first_turn else None
+            )
+
+            # chat 모드(simple): simple 프롬프트를 phase로 직접 주입 — codex 와 같은 빌더
+            # (centri `prompts.chat_system_prompt` 반영, 이슈 #178)
+            # RAG enable 모드(knowledge): None → agent가 _build_system_prompt() 사용
+            _phase_prompt = None
+            if is_simple:
+                from codebuff_core.services.rag_chat_agent import (
+                    build_chat_mode_system_prompt,
+                )
+
+                _phase_prompt = build_chat_mode_system_prompt("simple")
+
+            full_response = ""
+            async for chunk in agent.stream_response(
+                effective_message,
+                history,
+                combined_context,
+                thread_id=conversation_id,
+                phase_system_prompt=_phase_prompt,
+                block_tools=is_simple,
+            ):
+                if "content" in chunk:
+                    full_response += chunk.get("content", "")
+                yield chunk
+
+            self._rag_initialized_threads.add(conversation_id)
+
+            # 텍스트만 SessionManager에 저장 (서버 재시작 시 복원용)
+            self._store_messages(conversation_id, cleaned_message, full_response)
+
+            # 완료 청크
+            yield {"content": "", "done": True, "conversationId": conversation_id}
+
+        except Exception as e:
+            logger.error(f"RAG agent 스트림 실패: {e}", exc_info=True)
+            # RAG agent 실패 시 기존 LLM 경로로 폴백
+            logger.info("RAG agent 실패, 기존 LLM 스트리밍으로 폴백")
+            llm_service = LLMService(config)
+            full_response = ""
+            try:
+                async for chunk in llm_service.generate_response_stream(
+                    cleaned_message,
+                    context=combined_context,
+                    system_prompt=_chat_system_prompt(),
+                ):
+                    full_response += chunk
+                    yield {"content": chunk, "done": False}
+
+                self._store_messages(conversation_id, cleaned_message, full_response)
+                yield {
+                    "content": "",
+                    "done": True,
+                    "conversationId": conversation_id,
+                }
+            except Exception as fallback_err:
+                logger.error(f"폴백 스트림도 실패: {fallback_err}", exc_info=True)
+                yield {"error": str(fallback_err)}