ltcai 8.9.0 → 9.0.0

package/latticeai/api/chat.py

@@ -14,7 +14,7 @@ import subprocess
 import tempfile
 import threading
 from pathlib import Path
-from typing import AsyncIterator, Dict, List, Optional
+from typing import Any, AsyncIterator, Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse, StreamingResponse
@@ -28,6 +28,25 @@ from lattice_brain.runtime.hooks import dispatch_tool
 from latticeai.services.app_context import AppContext
 from latticeai.services.tool_dispatch import build_agent_runtime, collect_created_files
 from tools import AGENT_ROOT, ToolError, ensure_agent_root, execute_tool, knowledge_save, network_status
+# Pure chat helpers (language/intent detection, file-action parsing, recent-context
+# assembly) live in chat_helpers; re-imported here so ``from latticeai.api.chat
+# import <helper>`` keeps resolving. See __all__ below.
+from latticeai.api.chat_helpers import (
+    _LANG_HINT,
+    build_recent_chat_context,
+    detect_language,
+    file_action_target,
+    format_network_status,
+    inline_file_action_content,
+    is_clear_command,
+    is_current_url_request,
+    is_file_action_request,
+    is_network_status_request,
+    pair_user_history,
+    single_text_stream,
+    strip_generated_file_content,
+    workspace_scope_from_request,
+)
 
 class ChatRequest(BaseModel):
     message: str
@@ -72,195 +91,26 @@ class AgentEvalRequest(BaseModel):
     skill: str
     case_id: Optional[str] = None
 
-def pair_user_history(history: List[Dict], user_email: str) -> List[Dict]:
-    """Restrict history to one user's exchange.
-
-    Keeps the user's own messages plus assistant replies that directly follow
-    them. A bare role=="assistant" pass would leak every other user's replies
-    into this user's prompt context.
-    """
-    paired: List[Dict] = []
-    include_next_assistant = False
-    for item in history:
-        if item.get("role") == "assistant":
-            if include_next_assistant:
-                paired.append(item)
-                include_next_assistant = False
-        elif item.get("user_email") == user_email:
-            paired.append(item)
-            include_next_assistant = True
-        else:
-            include_next_assistant = False
-    return paired
-
-
-def detect_language(text: str) -> str:
-    """Detect language: 'ko' (Korean) or 'en' (English)."""
-    total = max(len(text), 1)
-    ko = sum(1 for c in text if '가' <= c <= '힣')
-    if ko / total > 0.05:
-        return "ko"
-    return "en"
-
-_LANG_HINT = {
-    "ko": "Respond in Korean (한국어로 답변하세요).",
-    "en": "Respond in English.",
-}
-
-def is_network_status_request(text: str) -> bool:
-    """사용자가 현재 IP/네트워크 정보를 물었는지 감지합니다."""
-    t = (text or "").lower()
-    has_ip = bool(re.search(r"((?<![a-z0-9])ip(?![a-z0-9])|아이피|ip\s*주소|아이피\s*주소|ipconfig|ifconfig|네트워크)", t))
-    asks_current = any(word in t for word in ["내", "현재", "지금", "local", "로컬", "주소", "address", "뭐", "알려", "확인", "상태"])
-    return has_ip and asks_current
-
-def is_current_url_request(text: str) -> bool:
-    t = (text or "").lower()
-    has_url = any(word in t for word in ["url", "주소", "링크", "address"])
-    asks_current = any(word in t for word in ["현재", "지금", "여기", "접속", "페이지", "브라우저", "알려", "뭐"])
-    return has_url and asks_current
-
-def is_clear_command(text: str) -> bool:
-    return (text or "").strip().lower() in {"/clear", "/clear_all"}
-
-# Path segments intentionally exclude spaces: allowing spaces let the target
-# match swallow preceding words (e.g. "create a text file report.txt" resolved
-# to the whole phrase as the path). Chat file targets are single tokens.
-_FILE_TARGET_RE = re.compile(
-    r"(?<![\w.-])(?:[~./\\]?[\w.@()+-]+[\\/])*[\w.@()+-]+"
-    r"\.(?:py|js|jsx|ts|tsx|md|markdown|txt|json|yaml|yml|toml|html|css|csv|xml|pdf|docx|xlsx|pptx|sh|sql)",
-    re.IGNORECASE,
-)
-
 
-def is_file_action_request(text: str) -> bool:
-    """Return True for chat requests that should execute file tools, not prose.
-
-    The Brain chat composer posts to ``/chat``. Without this gate, explicit
-    side-effect requests such as "create hello.md" are handled as plain model
-    generation, which commonly produces a code block instead of a real file.
-    Keep the gate narrow so normal Q&A and "how do I create a file?" stay in
-    ordinary chat.
-    """
-    raw = (text or "").strip()
-    if not raw:
-        return False
-    lower = raw.lower()
-
-    if any(phrase in lower for phrase in (
-        "how to ", "how do i ", "방법", "어떻게", "예시", "sample", "example",
-    )) and not any(phrase in lower for phrase in (
-        "actually create", "real file", "실제로", "파일로", "저장해", "만들어",
-    )):
-        return False
-
-    has_target = bool(_FILE_TARGET_RE.search(raw))
-    has_file_word = any(word in lower for word in (
-        "file", "파일", "문서", "artifact", "아티팩트", "save as", "저장",
-    ))
-    has_action = any(word in lower for word in (
-        "create", "make", "write", "save", "generate", "edit", "update",
-        "만들", "생성", "작성", "저장", "수정", "써줘", "만들어줘",
-    ))
-
-    if not has_action:
-        return False
-    if has_target and has_action:
-        return True
-    return has_file_word and has_action
-
-
-def file_action_target(text: str) -> Optional[str]:
-    """Extract the first explicit workspace file target from a request."""
-    match = _FILE_TARGET_RE.search(text or "")
-    if not match:
-        return None
-    return match.group(0).strip().strip("`'\".,:;)]}")
-
-
-def inline_file_action_content(text: str) -> Optional[str]:
-    """Extract short user-provided content for deterministic file writes."""
-    raw = (text or "").strip()
-    # Each pattern requires an explicit binder so ambiguous words like "text"
-    # ("create a text file report.txt") or a bare "with" ("report.md with a
-    # summary of X") do not get captured as literal file content.
-    patterns = [
-        r"(?:내용|본문)\s*(?:은|는|이에요|입니다)\s*(.+)$",
-        r"(?:내용|본문|content|body|text)\s*[:=]\s*(.+)$",
-        r"(?:content|body)\s+(?:is|as)\s+(.+)$",
-        r"(?:with the content|with content|containing)\s+(.+)$",
-    ]
-    for pattern in patterns:
-        match = re.search(pattern, raw, flags=re.IGNORECASE | re.DOTALL)
-        if match:
-            content = match.group(1).strip()
-            return content.strip("`'\"")
-    return None
-
-
-def strip_generated_file_content(text: str) -> str:
-    """Remove common chat wrappers when a model is asked for file content only."""
-    content = (text or "").strip()
-    fenced = re.search(r"```(?:[\w.+-]+)?\s*(.*?)\s*```", content, flags=re.DOTALL)
-    if fenced:
-        content = fenced.group(1).strip()
-    return content
-
-
-def format_network_status(info: Dict) -> str:
-    lines = [
-        f"내부 IP: {info.get('local_ip') or '확인 안 됨'}",
-        f"외부 IP: {info.get('public_ip') or '확인 안 됨'}",
-        f"호스트명: {info.get('hostname') or '확인 안 됨'}",
-    ]
-    local_ips = info.get("local_ips") or {}
-    if local_ips:
-        lines.extend(["", "인터페이스:"])
-        lines.extend(f"- {name}: {ip}" for name, ip in local_ips.items())
-    note = info.get("note")
-    if note:
-        lines.extend(["", note])
-    return "\n".join(lines)
-
-def workspace_scope_from_request(request: Request) -> Optional[str]:
-    header = request.headers.get("X-Workspace-Id")
-    if header and header.strip():
-        return header.strip()
-    query = request.query_params.get("workspace_id")
-    return query.strip() if query and query.strip() else None
-
-async def single_text_stream(text: str, model: str = "system") -> AsyncIterator[str]:
-    yield f"data: {json.dumps({'chunk': text, 'model': model}, ensure_ascii=False)}\n\n"
-    yield "data: [DONE]\n\n"
-
-
-def build_recent_chat_context(
-    *,
-    get_history,
-    limit: int = 10,
-    include_image_missing_replies: bool = True,
-    user_email: Optional[str] = None,
-    conversation_id: Optional[str] = None,
-) -> str:
-    history = get_history()
-    if conversation_id:
-        history = [item for item in history if item.get("conversation_id") == conversation_id]
-    if user_email:
-        history = pair_user_history(history, user_email)
-    history = history[-limit:]
-    lines = []
-    for item in history:
-        role = item.get("role", "user")
-        content = item.get("content", "")
-        if not include_image_missing_replies and role == "assistant":
-            if "이미지" in content and any(word in content for word in ["업로드", "제공", "올려"]):
-                continue
-        source = item.get("source")
-        label = role
-        if source:
-            label = f"{role} ({source})"
-        lines.append(f"{label}: {content}")
-    return "\n".join(lines)
+# The chat helpers imported at the top of the module are re-exported so
+# ``from latticeai.api.chat import <helper>`` (tests, app_factory) keeps resolving
+# after the split; __all__ marks them as intentional re-exports.
+__all__ = [
+    "create_chat_router",
+    "build_recent_chat_context",
+    "pair_user_history",
+    "detect_language",
+    "file_action_target",
+    "inline_file_action_content",
+    "is_file_action_request",
+    "is_network_status_request",
+    "is_current_url_request",
+    "is_clear_command",
+    "format_network_status",
+    "strip_generated_file_content",
+    "workspace_scope_from_request",
+    "single_text_stream",
+]
 
 
 def create_chat_router(context: AppContext) -> APIRouter:
@@ -298,6 +148,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
     _doc_gen_sessions: dict = {}
     _pending_agents: dict[str, tuple] = {}
     _pending_agents_lock = threading.Lock()
+    _background_tasks: set[asyncio.Task] = set()
 
     on_chat_message = context.on_chat_message
 
@@ -315,6 +166,232 @@ def create_chat_router(context: AppContext) -> APIRouter:
         except Exception as exc:
             logging.warning("chat message bridge failed: %s", exc)
 
+    def schedule_background_task(coro) -> None:
+        task = asyncio.create_task(coro)
+        _background_tasks.add(task)
+
+        def _finish(done: asyncio.Task) -> None:
+            _background_tasks.discard(done)
+            try:
+                done.result()
+            except asyncio.CancelledError:
+                pass
+            except Exception as exc:
+                logging.warning("background chat task failed: %s", exc)
+
+        task.add_done_callback(_finish)
+
+    async def save_history_entry(role: str, content: str, history_meta: Dict, history_user: Dict) -> None:
+        await asyncio.to_thread(save_to_history, role, content, **history_meta, **history_user)
+
+    async def persist_chat_exchange(
+        req: ChatRequest,
+        answer: str,
+        *,
+        history_meta: Dict,
+        history_user: Dict,
+        user_message: Optional[str] = None,
+    ) -> None:
+        message = user_message if user_message is not None else req.message
+        await save_history_entry("user", message, history_meta, history_user)
+        await save_history_entry("assistant", answer, history_meta, history_user)
+        notify_chat_message("user", req.message, req.source)
+        notify_chat_message("assistant", answer, req.source)
+
+    def no_model_response() -> JSONResponse:
+        detail = "No model loaded. Call /models/load first."
+        if CONFIG.is_public:
+            detail = f"No public model loaded. Set OPENAI_API_KEY and LATTICEAI_PUBLIC_MODEL={PUBLIC_MODEL}, or call /models/load with an OpenAI-compatible model."
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "no_model_loaded",
+                "detail": detail,
+                "message": detail,
+                "action": "load_model",
+            },
+        )
+
+    def single_answer_response(req: ChatRequest, answer: str, *, model: str) -> JSONResponse | StreamingResponse:
+        if req.stream:
+            return StreamingResponse(
+                single_text_stream(answer),
+                media_type="text/event-stream",
+                headers={"X-Model": model},
+            )
+        return JSONResponse(content={"response": answer})
+
+    def agent_payload_stream(answer: str, payload: Dict[str, Any]) -> AsyncIterator[str]:
+        async def _stream() -> AsyncIterator[str]:
+            yield f"data: {json.dumps({'chunk': answer, 'model': router.current_model_id, 'agent': payload}, ensure_ascii=False)}\n\n"
+            yield f"data: {json.dumps({'chunk': '', 'model': router.current_model_id, 'agent': payload}, ensure_ascii=False)}\n\n"
+            yield "data: [DONE]\n\n"
+
+        return _stream()
+
+    async def handle_network_status_intent(
+        req: ChatRequest,
+        *,
+        history_meta: Dict,
+        history_user: Dict,
+    ) -> JSONResponse | StreamingResponse:
+        history_message = f"{req.message}\n[Image attached]" if req.image_data else req.message
+        try:
+            answer = format_network_status(network_status())
+        except ToolError as exc:
+            answer = f"네트워크 정보를 확인하지 못했습니다: {exc}"
+        await persist_chat_exchange(req, answer, history_meta=history_meta, history_user=history_user, user_message=history_message)
+        return single_answer_response(req, answer, model="network_status")
+
+    async def handle_clear_intent(
+        req: ChatRequest,
+        *,
+        effective_email: Optional[str],
+    ) -> JSONResponse | StreamingResponse:
+        command = req.message.strip().lower()
+        clear_scope = "all" if command == "/clear_all" else "conversation"
+        if ENABLE_GRAPH and KNOWLEDGE_GRAPH:
+            try:
+                KNOWLEDGE_GRAPH.ingest_event(
+                    "ClearEvent",
+                    f"{command} requested",
+                    user_email=effective_email,
+                    user_nickname=req.user_nickname,
+                    source=req.source or "web",
+                    conversation_id=req.conversation_id,
+                    metadata={"command": command, "scope": clear_scope},
+                )
+            except Exception as e:
+                logging.warning("knowledge graph clear event ingest failed: %s", e)
+        if command == "/clear_all":
+            result = clear_history(0, **history_scope_for_user(effective_email))
+            answer = f"채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
+        elif req.conversation_id:
+            result = clear_conversation(req.conversation_id, **history_scope_for_user(effective_email))
+            answer = f"현재 대화방 채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
+        else:
+            result = clear_history(0, **history_scope_for_user(effective_email))
+            answer = f"채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
+        append_audit_event(
+            "clear_command",
+            user_email=effective_email,
+            user_nickname=req.user_nickname,
+            source=req.source or "web",
+            conversation_id=req.conversation_id,
+            command=command,
+            scope=clear_scope,
+            removed=result.get("removed", 0),
+            kept=result.get("kept", 0),
+        )
+        notify_chat_message("user", req.message, req.source)
+        notify_chat_message("assistant", answer, req.source)
+        return single_answer_response(req, answer, model="history")
+
+    async def handle_current_url_intent(
+        req: ChatRequest,
+        *,
+        history_meta: Dict,
+        history_user: Dict,
+    ) -> JSONResponse | StreamingResponse:
+        answer = f"현재 페이지 URL: {req.client_url}"
+        await persist_chat_exchange(req, answer, history_meta=history_meta, history_user=history_user)
+        return single_answer_response(req, answer, model="client_url")
+
+    async def handle_direct_file_action(req: ChatRequest) -> Optional[JSONResponse | StreamingResponse]:
+        target_path = file_action_target(req.message)
+        if not target_path:
+            return None
+        content = inline_file_action_content(req.message)
+        if content is None and not router.current_model_id:
+            return no_model_response()
+        if content is None and router.current_model_id:
+            if req.model and req.model != router.current_model_id:
+                if req.model not in router.loaded_model_ids:
+                    raise HTTPException(status_code=404, detail=f"Model '{req.model}' not loaded.")
+                router.switch_model(req.model)
+            generation_context = (
+                "Create the exact content for the requested file. "
+                "Return only the file bytes as plain text. "
+                "Do not wrap the answer in Markdown fences, commentary, or explanations.\n\n"
+                f"Target path: {target_path}\n"
+                f"User request: {req.message}"
+            )
+            raw_content = await router.generate_as(
+                router.current_model_id,
+                message="Return only the requested file content.",
+                context=generation_context,
+                max_tokens=req.max_tokens,
+                temperature=req.temperature,
+            )
+            content = strip_generated_file_content(str(raw_content))
+        if content is None:
+            raise HTTPException(status_code=400, detail="File content could not be generated.")
+        try:
+            result = execute_tool("write_file", {"path": target_path, "content": content})
+        except ToolError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        answer = f"{result.get('path') or target_path} 파일을 만들었습니다."
+        created_files = [{
+            "path": result.get("path") or target_path,
+            "filename": Path(result.get("path") or target_path).name,
+            "bytes": result.get("bytes", 0),
+            "action": "write_file",
+        }]
+        notify_chat_message("user", req.message, req.source)
+        notify_chat_message("assistant", answer, req.source)
+        payload = {
+            "status": "ok",
+            "response": answer,
+            "workspace": str(AGENT_ROOT),
+            "steps": [{
+                "state": AgentState.EXECUTING.value,
+                "action": "write_file",
+                "args": {"path": target_path},
+                "result": result,
+            }],
+            "state_history": [AgentState.EXECUTING.value, AgentState.DONE.value],
+            "final_state": AgentState.DONE.value,
+            "created_files": created_files,
+            "routed_to_agent": True,
+            "action_route": "direct_write_file",
+        }
+        if req.stream:
+            return StreamingResponse(
+                agent_payload_stream(answer, payload),
+                media_type="text/event-stream",
+                headers={"X-Model": router.current_model_id or "tool", "X-Routed-To": "agent"},
+            )
+        return JSONResponse(content=payload)
+
+    async def route_file_action_to_agent(
+        req: ChatRequest,
+        request: Request,
+        *,
+        effective_email: Optional[str],
+    ) -> JSONResponse | StreamingResponse:
+        agent_req = AgentRequest(
+            message=req.message,
+            conversation_id=req.conversation_id,
+            source=req.source or "web",
+            max_steps=25,
+            temperature=min(req.temperature, 0.2),
+            user_email=effective_email,
+            user_nickname=req.user_nickname,
+            workspace_id=workspace_scope_from_request(request),
+        )
+        result = await agent(agent_req, request)
+        answer = str(result.get("response") or "파일 작업을 처리했습니다.")
+        notify_chat_message("user", req.message, req.source)
+        notify_chat_message("assistant", answer, req.source)
+        result["routed_to_agent"] = True
+        if req.stream:
+            return StreamingResponse(
+                agent_payload_stream(answer, result),
+                media_type="text/event-stream",
+                headers={"X-Model": router.current_model_id, "X-Routed-To": "agent"},
+            )
+        return JSONResponse(content=result)
+
     def history_scope_for_user(user_email: Optional[str]) -> Dict:
         require_auth = bool(getattr(CONFIG, "require_auth", False))
         scoped_user = user_email if require_auth else None
@@ -415,9 +492,11 @@ def create_chat_router(context: AppContext) -> APIRouter:
         current_user = require_user(request)
         enforce_rate_limit(current_user, "chat")
         img_len = len(req.image_data) if req.image_data else 0
-        print(
-            f"🧪 /chat request: stream={req.stream} image_data_len={img_len} "
-            f"message_len={len(req.message or '')}"
+        logging.debug(
+            "/chat request: stream=%s image_data_len=%s message_len=%s",
+            req.stream,
+            img_len,
+            len(req.message or ""),
         )
         effective_email = req.user_email or current_user or None
         history_user = get_history_user(effective_email, req.user_nickname)
@@ -428,162 +507,21 @@ def create_chat_router(context: AppContext) -> APIRouter:
         }
 
         if is_network_status_request(req.message):
-            history_message = f"{req.message}\n[Image attached]" if req.image_data else req.message
-            save_to_history("user", history_message, **history_meta, **history_user)
-            try:
-                answer = format_network_status(network_status())
-            except ToolError as exc:
-                answer = f"네트워크 정보를 확인하지 못했습니다: {exc}"
-            save_to_history("assistant", answer, **history_meta, **history_user)
-            notify_chat_message("user", req.message, req.source)
-            notify_chat_message("assistant", answer, req.source)
-            if req.stream:
-                return StreamingResponse(
-                    single_text_stream(answer),
-                    media_type="text/event-stream",
-                    headers={"X-Model": "network_status"},
-                )
-            return JSONResponse(content={"response": answer})
+            return await handle_network_status_intent(req, history_meta=history_meta, history_user=history_user)
 
         if is_clear_command(req.message):
-            command = req.message.strip().lower()
-            clear_scope = "all" if command == "/clear_all" else "conversation"
-            if ENABLE_GRAPH and KNOWLEDGE_GRAPH:
-                try:
-                    KNOWLEDGE_GRAPH.ingest_event(
-                        "ClearEvent",
-                        f"{command} requested",
-                        user_email=effective_email,
-                        user_nickname=req.user_nickname,
-                        source=req.source or "web",
-                        conversation_id=req.conversation_id,
-                        metadata={"command": command, "scope": clear_scope},
-                    )
-                except Exception as e:
-                    logging.warning("knowledge graph clear event ingest failed: %s", e)
-            if command == "/clear_all":
-                result = clear_history(0, **history_scope_for_user(effective_email))
-                answer = f"채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
-            else:
-                if req.conversation_id:
-                    result = clear_conversation(req.conversation_id, **history_scope_for_user(effective_email))
-                    answer = f"현재 대화방 채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
-                else:
-                    result = clear_history(0, **history_scope_for_user(effective_email))
-                    answer = f"채팅창을 정리했습니다. 화면에서 제거 {result.get('removed', 0)}개. 감사 로그와 지식 그래프/RAG 데이터는 유지됩니다."
-            append_audit_event(
-                "clear_command",
-                user_email=effective_email,
-                user_nickname=req.user_nickname,
-                source=req.source or "web",
-                conversation_id=req.conversation_id,
-                command=command,
-                scope=clear_scope,
-                removed=result.get("removed", 0),
-                kept=result.get("kept", 0),
-            )
-            if req.stream:
-                return StreamingResponse(
-                    single_text_stream(answer),
-                    media_type="text/event-stream",
-                    headers={"X-Model": "history"},
-                )
-            return JSONResponse(content={"response": answer})
+            return await handle_clear_intent(req, effective_email=effective_email)
 
         if is_current_url_request(req.message) and req.client_url:
-            answer = f"현재 페이지 URL: {req.client_url}"
-            save_to_history("user", req.message, **history_meta, **history_user)
-            save_to_history("assistant", answer, **history_meta, **history_user)
-            notify_chat_message("user", req.message, req.source)
-            notify_chat_message("assistant", answer, req.source)
-            if req.stream:
-                return StreamingResponse(
-                    single_text_stream(answer),
-                    media_type="text/event-stream",
-                    headers={"X-Model": "client_url"},
-                )
-            return JSONResponse(content={"response": answer})
+            return await handle_current_url_intent(req, history_meta=history_meta, history_user=history_user)
 
         if is_file_action_request(req.message):
-            target_path = file_action_target(req.message)
-            if target_path:
-                content = inline_file_action_content(req.message)
-                if content is None and router.current_model_id:
-                    if req.model and req.model != router.current_model_id:
-                        if req.model not in router.loaded_model_ids:
-                            raise HTTPException(status_code=404, detail=f"Model '{req.model}' not loaded.")
-                        router.switch_model(req.model)
-                    generation_context = (
-                        "Create the exact content for the requested file. "
-                        "Return only the file bytes as plain text. "
-                        "Do not wrap the answer in Markdown fences, commentary, or explanations.\n\n"
-                        f"Target path: {target_path}\n"
-                        f"User request: {req.message}"
-                    )
-                    raw_content = await router.generate_as(
-                        router.current_model_id,
-                        message="Return only the requested file content.",
-                        context=generation_context,
-                        max_tokens=req.max_tokens,
-                        temperature=req.temperature,
-                    )
-                    content = strip_generated_file_content(str(raw_content))
-                if content is None:
-                    content = ""
-                try:
-                    result = execute_tool("write_file", {"path": target_path, "content": content})
-                except ToolError as exc:
-                    raise HTTPException(status_code=400, detail=str(exc)) from exc
-                answer = f"{result.get('path') or target_path} 파일을 만들었습니다."
-                created_files = [{
-                    "path": result.get("path") or target_path,
-                    "filename": Path(result.get("path") or target_path).name,
-                    "bytes": result.get("bytes", 0),
-                    "action": "write_file",
-                }]
-                notify_chat_message("user", req.message, req.source)
-                notify_chat_message("assistant", answer, req.source)
-                payload = {
-                    "status": "ok",
-                    "response": answer,
-                    "workspace": str(AGENT_ROOT),
-                    "steps": [{
-                        "state": AgentState.EXECUTING.value,
-                        "action": "write_file",
-                        "args": {"path": target_path},
-                        "result": result,
-                    }],
-                    "state_history": [AgentState.EXECUTING.value, AgentState.DONE.value],
-                    "final_state": AgentState.DONE.value,
-                    "created_files": created_files,
-                    "routed_to_agent": True,
-                    "action_route": "direct_write_file",
-                }
-                if req.stream:
-                    async def _stream_file_result():
-                        yield f"data: {json.dumps({'chunk': answer, 'model': router.current_model_id, 'agent': payload}, ensure_ascii=False)}\n\n"
-                        yield f"data: {json.dumps({'chunk': '', 'model': router.current_model_id, 'agent': payload}, ensure_ascii=False)}\n\n"
-                        yield "data: [DONE]\n\n"
-                    return StreamingResponse(
-                        _stream_file_result(),
-                        media_type="text/event-stream",
-                        headers={"X-Model": router.current_model_id or "tool", "X-Routed-To": "agent"},
-                    )
-                return JSONResponse(content=payload)
+            direct_response = await handle_direct_file_action(req)
+            if direct_response is not None:
+                return direct_response
 
         if not router.current_model_id:
-            detail = "No model loaded. Call /models/load first."
-            if CONFIG.is_public:
-                detail = f"No public model loaded. Set OPENAI_API_KEY and LATTICEAI_PUBLIC_MODEL={PUBLIC_MODEL}, or call /models/load with an OpenAI-compatible model."
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": "no_model_loaded",
-                    "detail": detail,
-                    "message": detail,
-                    "action": "load_model",
-                },
-            )
+            return no_model_response()
 
         if req.model and req.model != router.current_model_id:
             if req.model not in router.loaded_model_ids:
@@ -591,32 +529,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
             router.switch_model(req.model)
 
         if is_file_action_request(req.message):
-            agent_req = AgentRequest(
-                message=req.message,
-                conversation_id=req.conversation_id,
-                source=req.source or "web",
-                max_steps=25,
-                temperature=min(req.temperature, 0.2),
-                user_email=effective_email,
-                user_nickname=req.user_nickname,
-                workspace_id=workspace_scope_from_request(request),
-            )
-            result = await agent(agent_req, request)
-            answer = str(result.get("response") or "파일 작업을 처리했습니다.")
-            notify_chat_message("user", req.message, req.source)
-            notify_chat_message("assistant", answer, req.source)
-            result["routed_to_agent"] = True
-            if req.stream:
-                async def _stream_agent_result():
-                    yield f"data: {json.dumps({'chunk': answer, 'model': router.current_model_id, 'agent': result}, ensure_ascii=False)}\n\n"
-                    yield f"data: {json.dumps({'chunk': '', 'model': router.current_model_id, 'agent': result}, ensure_ascii=False)}\n\n"
-                    yield "data: [DONE]\n\n"
-                return StreamingResponse(
-                    _stream_agent_result(),
-                    media_type="text/event-stream",
-                    headers={"X-Model": router.current_model_id, "X-Routed-To": "agent"},
-                )
-            return JSONResponse(content=result)
+            return await route_file_action_to_agent(req, request, effective_email=effective_email)
 
         lang = detect_language(req.message)
         context = f"[LANGUAGE: {_LANG_HINT[lang]}]\n" + (req.context or "")
@@ -651,7 +564,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 graph_md = doc_gen_context_result.get("context_markdown", "")
                 if graph_md:
                     context += f"\n\n[KNOWLEDGE GRAPH — Document Generation Context]\n{graph_md}"
-                    print("📝 Document generation context retrieved from knowledge graph.")
+                    logging.debug("Document generation context retrieved from knowledge graph.")
         except Exception as e:
             logging.warning("Knowledge graph reinforcement skipped: %s", e)
 
@@ -691,7 +604,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
             trace_seed["context_assembly"] = context_trace
 
         history_message = f"{req.message}\n[Image attached]" if req.image_data else req.message
-        save_to_history("user", history_message, **history_meta, **history_user)
+        await asyncio.to_thread(save_to_history, "user", history_message, **history_meta, **history_user)
         notify_chat_message("user", req.message, req.source)
 
         if is_doc_gen and ENABLE_GRAPH and KNOWLEDGE_GRAPH:
@@ -708,19 +621,27 @@ def create_chat_router(context: AppContext) -> APIRouter:
             if req.stream:
                 async def _stream_doc_gen():
                     collected = []
-                    async for chunk in router.stream_generate_document(
-                        req.message, system_prompt,
-                        max_tokens=req.max_tokens or 8192,
-                        temperature=req.temperature or 0.3,
-                    ):
-                        collected.append(chunk)
-                        yield f"data: {json.dumps({'text': chunk}, ensure_ascii=False)}\n\n"
+                    stream_error = None
+                    try:
+                        async for chunk in router.stream_generate_document(
+                            req.message, system_prompt,
+                            max_tokens=req.max_tokens or 8192,
+                            temperature=req.temperature or 0.3,
+                        ):
+                            collected.append(chunk)
+                            yield f"data: {json.dumps({'text': chunk}, ensure_ascii=False)}\n\n"
+                    except Exception as exc:
+                        stream_error = str(exc)
+                        logging.warning("document stream failed: %s", exc)
+                        yield f"data: {json.dumps({'error': stream_error}, ensure_ascii=False)}\n\n"
                     full_text = "".join(collected)
                     if footnote:
                         yield f"data: {json.dumps({'text': footnote}, ensure_ascii=False)}\n\n"
                         full_text += footnote
+                    if stream_error:
+                        full_text = f"{full_text}\n\n[stream_error] {stream_error}" if full_text else f"[stream_error] {stream_error}"
                     session.update(graph_md, full_text, req.conversation_id)
-                    save_to_history("assistant", full_text, **history_meta, **history_user)
+                    await asyncio.to_thread(save_to_history, "assistant", full_text, **history_meta, **history_user)
                     trace_record = CHAT_SERVICE.record_trace(
                         question=req.message,
                         response=full_text,
@@ -745,7 +666,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 if footnote:
                     result += footnote
                 session.update(graph_md, result, req.conversation_id)
-                save_to_history("assistant", str(result), **history_meta, **history_user)
+                await asyncio.to_thread(save_to_history, "assistant", str(result), **history_meta, **history_user)
                 trace_record = CHAT_SERVICE.record_trace(
                     question=req.message,
                     response=str(result),
@@ -788,7 +709,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
 
             result = await router.generate(req.message, full_context, req.max_tokens, req.temperature, req.image_data)
 
-            save_to_history("assistant", str(result), **history_meta, **history_user)
+            await asyncio.to_thread(save_to_history, "assistant", str(result), **history_meta, **history_user)
             trace_record = CHAT_SERVICE.record_trace(
                 question=req.message,
                 response=str(result),
@@ -883,33 +804,45 @@ def create_chat_router(context: AppContext) -> APIRouter:
         history_meta: Optional[Dict] = None,
     ) -> AsyncIterator[str]:
         full_response = ""
-        async for chunk in router.stream_generate(req.message, context, req.max_tokens, req.temperature, image_data):
-            clean_chunk = chunk
-            if hasattr(chunk, "text"):
-                clean_chunk = chunk.text
-            elif isinstance(chunk, str) and "text='" in chunk:
-                try:
-                    clean_chunk = chunk.split("text='")[1].split("', token=")[0].replace('\\n', '\n').replace('\\\\n', '\n')
-                except Exception:
-                    pass
-
-            full_response += str(clean_chunk)
-            yield f"data: {json.dumps({'chunk': clean_chunk, 'model': router.current_model_id}, ensure_ascii=False)}\n\n"
+        stream_error: Optional[str] = None
+        try:
+            async for chunk in router.stream_generate(req.message, context, req.max_tokens, req.temperature, image_data):
+                clean_chunk = chunk.text if hasattr(chunk, "text") else chunk
+                full_response += str(clean_chunk)
+                yield f"data: {json.dumps({'chunk': clean_chunk, 'model': router.current_model_id}, ensure_ascii=False)}\n\n"
+        except Exception as exc:
+            stream_error = str(exc)
+            logging.warning("chat stream failed: %s", exc)
+            yield f"data: {json.dumps({'error': stream_error, 'model': router.current_model_id}, ensure_ascii=False)}\n\n"
         history_user = get_history_user(effective_email or req.user_email, req.user_nickname)
-        save_to_history("assistant", full_response, **(history_meta or {}), **history_user)
-        trace_record = CHAT_SERVICE.record_trace(
-            question=req.message,
-            response=full_response,
-            conversation_id=req.conversation_id,
-            user_email=effective_email or req.user_email,
-            trace=trace_seed or CHAT_SERVICE.build_graph_trace(
-                req.message,
-                KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None,
-                context,
-            ),
-        )
-        notify_chat_message("assistant", full_response, req.source)
-        yield f"data: {json.dumps({'chunk': '', 'model': router.current_model_id, 'trace_id': trace_record['id'], 'trace': trace_record}, ensure_ascii=False)}\n\n"
+        persisted_response = full_response
+        if stream_error and not persisted_response:
+            persisted_response = f"[stream_error] {stream_error}"
+        elif stream_error:
+            persisted_response = f"{persisted_response}\n\n[stream_error] {stream_error}"
+        trace_record = None
+        try:
+            await asyncio.to_thread(save_to_history, "assistant", persisted_response, **(history_meta or {}), **history_user)
+            trace_record = CHAT_SERVICE.record_trace(
+                question=req.message,
+                response=persisted_response,
+                conversation_id=req.conversation_id,
+                user_email=effective_email or req.user_email,
+                trace=trace_seed or CHAT_SERVICE.build_graph_trace(
+                    req.message,
+                    KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None,
+                    context,
+                ),
+            )
+            notify_chat_message("assistant", persisted_response, req.source)
+        except Exception as exc:
+            logging.warning("chat stream persistence failed: %s", exc)
+        trailer = {"chunk": "", "model": router.current_model_id}
+        if trace_record:
+            trailer.update({"trace_id": trace_record["id"], "trace": trace_record})
+        if stream_error:
+            trailer["error"] = stream_error
+        yield f"data: {json.dumps(trailer, ensure_ascii=False)}\n\n"
         yield "data: [DONE]\n\n"
 
     @api_router.post("/agent/eval")
@@ -1018,11 +951,11 @@ def create_chat_router(context: AppContext) -> APIRouter:
     ) -> dict:
         """HTTP glue: drive the runtime to a terminal state, persist, shape the response."""
         await _AGENT_RUNTIME.run_to_completion(ctx, req, lang_hint, current_user, max_steps, max_retry)
-        asyncio.create_task(_AGENT_RUNTIME.memory_update(ctx, req, current_user))
+        schedule_background_task(_AGENT_RUNTIME.memory_update(ctx, req, current_user))
 
         message = ctx.final_message or "작업을 완료했습니다."
-        save_to_history("user", req.message, source=req.source or "web", conversation_id=req.conversation_id, workspace_id=req.workspace_id)
-        save_to_history("assistant", message, source=req.source or "web", conversation_id=req.conversation_id, workspace_id=req.workspace_id)
+        await asyncio.to_thread(save_to_history, "user", req.message, source=req.source or "web", conversation_id=req.conversation_id, workspace_id=req.workspace_id)
+        await asyncio.to_thread(save_to_history, "assistant", message, source=req.source or "web", conversation_id=req.conversation_id, workspace_id=req.workspace_id)
         try:
             WORKSPACE_OS.record_agent_run(
                 agent_id="agent:executor",