codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/agent_factory.py

@@ -0,0 +1,2270 @@
+"""AgentFactory - Jupyter 환경을 위한 DeepAgents 래퍼.
+
+Jupyter 노트북 작업을 위해 구성된 DeepAgents 인스턴스를 생성하는 팩토리 모듈.
+DeepAgents 라이브러리를 래핑하고 Jupyter 전용 도구를 주입함.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+from codebuff_core.directory_policy import EXCLUDED_RELATIVE_DIRS
+from codebuff_core.directory_policy import SEARCH_EXCLUDED_DIRS as _SKIP_DIRS
+from codebuff_core.platform_rules import is_bdp_platform, platform_rules_block
+from langchain.agents.middleware import (
+    InterruptOnConfig,
+    ModelRetryMiddleware,
+)
+from langchain.chat_models import init_chat_model
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, ToolCall
+from langchain_core.tools import BaseTool
+from langgraph.checkpoint.memory import MemorySaver
+
+from codebuff_core.managers.config_manager import prompt_value
+
+from ..log_paths import get_debug_log_path
+from ..tools.context import NotebookContextManager
+from . import custom_skills
+from .autofix_middleware import AutoFixMiddleware
+from .file_diffs import FileDiffTracker
+from .middleware import DSMemoryMiddleware, MemoryStore
+from .middleware_prompts import DS_HITL_DESCRIPTION_PREFIX
+from .prompts import get_system_prompt
+from .todo_prompts import DS_TODO_TOOL_DESCRIPTION
+
+# Direct file-based debug logging (bypasses Python logging config)
+_DEBUG_LOG = get_debug_log_path()
+
+
+def _planner_system_prompt() -> str:
+    """multi 모드 메인 에이전트 `prompts.planner` (이슈 #218 — 코드 상수 없음)."""
+    return prompt_value("planner")
+
+
+def _patch_todo_middleware() -> None:
+    """TodoListMiddleware 기본값을 DS 특화 규칙(`prompts.todo_rules`)과 도구 설명으로 바꾼다."""
+    from langchain.agents.middleware import TodoListMiddleware as _TodoMW
+
+    _TodoMW.__init__.__kwdefaults__["system_prompt"] = prompt_value("todo_rules")
+    _TodoMW.__init__.__kwdefaults__["tool_description"] = DS_TODO_TOOL_DESCRIPTION
+
+
+def _dbg(msg: str) -> None:
+    """Write debug message directly to file, bypassing logging framework."""
+    try:
+        import datetime
+
+        ts = datetime.datetime.now().strftime("%H:%M:%S.%f")[:-3]
+        with open(_DEBUG_LOG, "a") as f:
+            f.write(f"[{ts}] {msg}\n")
+    except OSError:
+        pass
+
+
+logger = logging.getLogger(__name__)
+if not logger.handlers and not logger.parent.handlers:
+    logger.setLevel(logging.INFO)
+
+# max_tokens 잘림 시 자동 이어쓰기 최대 횟수
+_MAX_CONTINUATIONS = 3
+
+# ---------------------------------------------------------------------------
+# rg 없는 환경에서 grep Python fallback 안전화
+# ---------------------------------------------------------------------------
+
+
+_PYTHON_SEARCH_TIMEOUT = 10  # seconds
+# deepagents _DEFAULT_GLOB_TIMEOUT 과 같은 값 — private 이라 import 하지 않는다
+_GLOB_TIMEOUT = 5  # seconds
+_MAX_SEARCH_RESULTS = 10_000
+
+
+def _iter_pruned_files(root: Path, deadline: float):
+    """_SKIP_DIRS 를 순회 단계에서 쳐내며 root 아래 파일을 yield 한다.
+
+    rglob("*") 뒤에 사후 필터를 거는 것은 소용없다 — 제외 대상이 워크스페이스
+    항목의 98.8%(336,036 중 331,986)라 비용이 순회 자체에 있다. os.walk 의
+    dirnames[:] 가지치기만이 그 순회를 막는다.
+
+    os.walk 는 기본이 followlinks=False 라 rglob 의 심볼릭 처리와 같다(실측 확인).
+    """
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            d
+            for d in dirnames
+            if d not in _SKIP_DIRS
+            and (Path(dirpath) / d).relative_to(root).parts
+            not in EXCLUDED_RELATIVE_DIRS
+        ]
+        if time.monotonic() > deadline:
+            return
+        base = Path(dirpath)
+        for name in filenames:
+            if time.monotonic() > deadline:
+                return
+            yield base / name
+
+
+class _InvalidGlobPattern(ValueError):
+    """glob 패턴 자체가 거부된 경우. 설치된 판의 예외를 이것으로 모은다."""
+
+
+@dataclass(frozen=True)
+class _DeepagentsCaps:
+    """설치된 deepagents 판의 glob/grep 계약.
+
+    pyproject 제약이 `deepagents>=0.1.0` 이고 실제로 두 판이 쓰이고 있는데
+    (uv.lock 은 0.6.8, 주 저장소 .venv 는 0.7.13) **두 계약이 호환되지 않는다**:
+
+    | | 0.6.8 | 0.7.13 |
+    |---|---|---|
+    | `_python_search` 반환 | `(results, error)` | `(results, truncated, error)` |
+    | `_python_search` 키워드 | `timeout` | `max_count`, `timeout` |
+    | `GlobResult` 필드 | `error`, `matches` | `+truncated`, `+truncation_reason` |
+    | glob 패턴 의미 | `rglob(pattern)` | `compile_grep_include_glob` |
+
+    한쪽에 맞춰 쓰면 다른 쪽에서 TypeError 로 죽는다. 버전 문자열이 아니라
+    **심볼의 존재**로 판별한다 — 그래야 중간 판에서도 맞는다.
+    """
+
+    search_returns_truncated: bool
+    glob_has_truncation: bool
+    _compile_include_glob: Callable[[str], Callable[[str], bool]] | None
+    _invalid_pattern_exc: type[Exception]
+
+    def compile_pattern(self, pattern: str, virtual_mode: bool):
+        """패턴을 rel_path 매처로 컴파일한다. 거부되면 _InvalidGlobPattern."""
+        if self._compile_include_glob is not None:
+            # 0.7.13+: `..` 거부와 선행 `/` 앵커까지 공용 매처가 담당한다.
+            try:
+                return self._compile_include_glob(pattern)
+            except self._invalid_pattern_exc as e:
+                raise _InvalidGlobPattern(str(e)) from e
+
+        # 0.6.8: 부모가 `search_path.rglob(pattern)` 을 쓴다. 그 의미를 그대로
+        # 재현한다 — rglob(p) == glob("**/" + p) 이고, wcmatch 의
+        # GLOBSTAR|BRACE|DOTGLOB 조합이 이와 일치하는 것을 7개 패턴으로 실측했다
+        # (dotfile 포함 여부까지). 부모의 선행 `/` 처리와 `..` 거부도 옮긴다.
+        import wcmatch.glob as wcglob
+
+        if pattern.startswith("/"):
+            pattern = pattern.lstrip("/")
+        if virtual_mode and ".." in Path(pattern).parts:
+            msg = "Path traversal not allowed in glob pattern"
+            raise _InvalidGlobPattern(msg)
+
+        flags = wcglob.GLOBSTAR | wcglob.BRACE | wcglob.DOTGLOB
+        full = "**/" + pattern
+
+        def _match(rel_path: str) -> bool:
+            return wcglob.globmatch(rel_path, full, flags=flags)
+
+        return _match
+
+
+_DEEPAGENTS_CAPS: _DeepagentsCaps | None = None
+
+
+def _deepagents_caps() -> _DeepagentsCaps:
+    """설치된 deepagents 판의 계약을 한 번만 읽어 캐시한다."""
+    global _DEEPAGENTS_CAPS  # noqa: PLW0603
+    if _DEEPAGENTS_CAPS is not None:
+        return _DEEPAGENTS_CAPS
+
+    import dataclasses
+    import inspect
+
+    from deepagents.backends.filesystem import FilesystemBackend
+    from deepagents.backends.protocol import GlobResult
+
+    sig = inspect.signature(FilesystemBackend._python_search)  # noqa: SLF001
+    glob_fields = {f.name for f in dataclasses.fields(GlobResult)}
+
+    try:
+        from deepagents.backends.utils import (
+            InvalidGlobPatternError,
+            compile_grep_include_glob,
+        )
+    except ImportError:
+        compile_grep_include_glob = None
+        InvalidGlobPatternError = ValueError
+
+    _DEEPAGENTS_CAPS = _DeepagentsCaps(
+        search_returns_truncated="max_count" in sig.parameters,
+        glob_has_truncation="truncated" in glob_fields,
+        _compile_include_glob=compile_grep_include_glob,
+        _invalid_pattern_exc=InvalidGlobPatternError,
+    )
+    return _DEEPAGENTS_CAPS
+
+
+def _create_safe_backend(root_dir, virtual_mode=True):
+    """Create a SafeFilesystemBackend instance (lazy import of deepagents)."""
+    from deepagents.backends.local_shell import LocalShellBackend
+
+    caps = _deepagents_caps()
+
+    class SafeFilesystemBackend(LocalShellBackend):
+        """LocalShellBackend with _SKIP_DIRS pruning and a deadline on glob/grep."""
+
+        def _bounded_search(  # noqa: PLR0913
+            self,
+            pattern,
+            base_full,
+            include_glob,
+            *,
+            max_count=None,
+            timeout=None,
+        ):
+            import re
+
+            import wcmatch.glob as wcglob
+
+            limit = (
+                _MAX_SEARCH_RESULTS
+                if max_count is None
+                else max(0, min(max_count, _MAX_SEARCH_RESULTS))
+            )
+            budget = (
+                _PYTHON_SEARCH_TIMEOUT
+                if timeout is None
+                else min(timeout, _PYTHON_SEARCH_TIMEOUT)
+            )
+            deadline = time.monotonic() + budget
+            results = {}
+            count = 0
+            try:
+                regex = re.compile(pattern)
+            except re.error as e:
+                return {}, False, f"Invalid search pattern {pattern!r}: {e}"
+            candidates = (
+                (base_full,)
+                if base_full.is_file()
+                else _iter_pruned_files(base_full, deadline)
+            )
+            for fp in candidates:
+                if time.monotonic() >= deadline:
+                    return results, True, "Search truncated: time budget exhausted"
+                if include_glob and not wcglob.globmatch(
+                    fp.name, include_glob, flags=wcglob.BRACE
+                ):
+                    continue
+                try:
+                    # Keep symlink targets within the requested scope and workspace.
+                    fp.resolve().relative_to(base_full.resolve())
+                    if self.virtual_mode:
+                        fp.resolve().relative_to(self.cwd)
+                    if not fp.is_file() or fp.stat().st_size > self.max_file_size_bytes:
+                        continue
+                    out_path = (
+                        self._to_virtual_path(fp) if self.virtual_mode else str(fp)
+                    )
+                    with fp.open(encoding="utf-8") as source:
+                        for line_num, line in enumerate(source, 1):
+                            if time.monotonic() >= deadline:
+                                return (
+                                    results,
+                                    True,
+                                    "Search truncated: time budget exhausted",
+                                )
+                            if regex.search(line):
+                                if count >= limit:
+                                    return (
+                                        results,
+                                        True,
+                                        "Search truncated: result limit reached",
+                                    )
+                                results.setdefault(out_path, []).append(
+                                    (line_num, line.rstrip("\n"))
+                                )
+                                count += 1
+                except (UnicodeDecodeError, OSError, RuntimeError, ValueError):
+                    continue
+            truncated = time.monotonic() >= deadline
+            return (
+                results,
+                truncated,
+                "Search truncated: time budget exhausted" if truncated else None,
+            )
+
+        def _ripgrep_bounded(self, pattern, base_full, include_glob, rg):
+            import selectors
+            import subprocess
+
+            limit = _MAX_SEARCH_RESULTS
+            deadline = time.monotonic() + _PYTHON_SEARCH_TIMEOUT
+            cmd = [
+                rg,
+                "--json",
+                "--hidden",
+                "--no-ignore",
+                "-F",
+                "--max-count",
+                str(limit + 1),
+                "--max-filesize",
+                str(self.max_file_size_bytes),
+            ]
+            if include_glob:
+                cmd += ["--glob", include_glob]
+            is_dir = base_full.is_dir()
+            if is_dir:
+                for name in sorted(_SKIP_DIRS):
+                    cmd += ["--glob", f"!**/{name}/**"]
+                for parts in sorted(EXCLUDED_RELATIVE_DIRS):
+                    cmd += ["--glob", "!/" + "/".join(parts) + "/**"]
+            cmd += ["--", pattern, "." if is_dir else str(base_full)]
+            results = {}
+            count = 0
+            buffer = b""
+            try:
+                process = subprocess.Popen(
+                    cmd,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.DEVNULL,
+                    cwd=base_full if is_dir else None,
+                )
+            except OSError:
+                return None  # executable disappeared after which(); use the Python path
+            try:
+                with selectors.DefaultSelector() as selector:
+                    selector.register(process.stdout, selectors.EVENT_READ)
+                    while True:
+                        remaining = deadline - time.monotonic()
+                        if remaining <= 0 or not selector.select(remaining):
+                            return (
+                                results,
+                                True,
+                                "Search truncated: time budget exhausted",
+                            )
+                        chunk = os.read(process.stdout.fileno(), 65536)
+                        if not chunk:
+                            break
+                        buffer += chunk
+                        while b"\n" in buffer:
+                            raw, buffer = buffer.split(b"\n", 1)
+                            if time.monotonic() >= deadline:
+                                return (
+                                    results,
+                                    True,
+                                    "Search truncated: time budget exhausted",
+                                )
+                            try:
+                                frame = json.loads(raw)
+                                if frame.get("type") != "match":
+                                    continue
+                                data = frame["data"]
+                                raw_path = Path(data["path"]["text"])
+                                fp = base_full / raw_path if is_dir else raw_path
+                                fp.resolve().relative_to(base_full.resolve())
+                                if self.virtual_mode:
+                                    fp.resolve().relative_to(self.cwd)
+                                    out_path = self._to_virtual_path(fp)
+                                else:
+                                    out_path = str(fp)
+                                if count >= limit:
+                                    return (
+                                        results,
+                                        True,
+                                        "Search truncated: result limit reached",
+                                    )
+                                results.setdefault(out_path, []).append(
+                                    (
+                                        data["line_number"],
+                                        data["lines"].get("text", "").rstrip("\n"),
+                                    )
+                                )
+                                count += 1
+                            except (KeyError, OSError, RuntimeError, ValueError):
+                                continue
+                try:
+                    code = process.wait(timeout=max(0.001, deadline - time.monotonic()))
+                except subprocess.TimeoutExpired:
+                    return results, True, "Search truncated: time budget exhausted"
+                return (
+                    results,
+                    False,
+                    None if code in (0, 1) else f"ripgrep failed (exit {code})",
+                )
+            finally:
+                if process.poll() is None:
+                    process.terminate()
+                    try:
+                        process.wait(timeout=1)
+                    except subprocess.TimeoutExpired:
+                        process.kill()
+                        process.wait()
+                process.stdout.close()
+
+        def _python_search(
+            self, pattern, base_full, include_glob, *, max_count=None, timeout=None
+        ):
+            results, truncated, error = self._bounded_search(
+                pattern, base_full, include_glob, max_count=max_count, timeout=timeout
+            )
+            if caps.search_returns_truncated:
+                return results, truncated, error
+            return results, error
+
+        def grep(self, pattern, path=None, glob=None):
+            import re
+            import shutil
+
+            from deepagents.backends.protocol import GrepResult
+
+            try:
+                base = self._resolve_path(path or ".")
+                if not base.exists():
+                    return GrepResult(matches=[])
+            except (OSError, RuntimeError, ValueError) as e:
+                return GrepResult(matches=[], error=str(e))
+            rg = shutil.which("rg")
+            searched = self._ripgrep_bounded(pattern, base, glob, rg) if rg else None
+            if searched is None:
+                searched = self._bounded_search(re.escape(pattern), base, glob)
+            results, truncated, error = searched
+            matches = [
+                {"path": name, "line": number, "text": text}
+                for name, lines in results.items()
+                for number, text in lines
+            ]
+            # The supported 0.6 API exposes partial-result information through error.
+            # Newer result types additionally expose a dedicated truncated field.
+            from dataclasses import fields
+
+            extra = (
+                {"truncated": truncated}
+                if "truncated" in {f.name for f in fields(GrepResult)}
+                else {}
+            )
+            if truncated:
+                error = f"{error}; {len(matches)} partial matches retained. Narrow the path or pattern to retrieve complete results."
+            return GrepResult(matches=matches, error=error, **extra)
+
+        def glob(self, pattern, path=None):  # noqa: C901, PLR0912
+            """FilesystemBackend.glob 에 _SKIP_DIRS 가지치기를 넣은 판.
+
+            순회 소스만 `_iter_pruned_files` 로 바꾸고 나머지 계약(패턴 의미·
+            virtual_mode 경로 변환·정렬·GlobResult 필드)은 설치된 판의 것을
+            그대로 따른다 — 패턴 매처는 `_deepagents_caps()` 가 준다.
+
+            탈출구: 제외 디렉토리를 명시적으로 겨냥하려면 `path` 로 그 안을
+            가리킨다. os.walk 는 루트 자신을 가지치기하지 않으므로
+            `glob("*.py", path="/extensions/jupyter/node_modules")` 는 동작한다.
+            """
+            from datetime import datetime
+
+            from deepagents.backends.protocol import GlobResult
+
+            try:
+                matches_pattern = caps.compile_pattern(pattern, self.virtual_mode)
+            except _InvalidGlobPattern as e:
+                return GlobResult(error=str(e), matches=None)
+
+            display_path = path if path is not None else "<default>"
+            try:
+                search_path = (
+                    self.cwd
+                    if path is None or path == "/"
+                    else self._resolve_path(path)
+                )
+                if not search_path.exists() or not search_path.is_dir():
+                    return GlobResult(matches=[])
+            except (OSError, RuntimeError) as e:
+                return GlobResult(
+                    error=f"Error globbing path '{display_path}': {e}",
+                    matches=[],
+                )
+
+            deadline = time.monotonic() + _GLOB_TIMEOUT
+            results: list[dict] = []
+            hit_cap = False
+            try:
+                for matched_path in _iter_pruned_files(search_path, deadline):
+                    try:
+                        rel_path = matched_path.relative_to(search_path).as_posix()
+                    except ValueError:
+                        continue
+                    if not matches_pattern(rel_path):
+                        continue
+                    try:
+                        if not matched_path.is_file():
+                            continue
+                    except (PermissionError, OSError, RuntimeError):
+                        continue
+                    if len(results) >= _MAX_SEARCH_RESULTS:
+                        hit_cap = True
+                        break
+                    if self.virtual_mode:
+                        try:
+                            matched_path.resolve().relative_to(self.cwd)
+                            out_path = self._to_virtual_path(matched_path)
+                        except (OSError, RuntimeError, ValueError):
+                            continue
+                    else:
+                        out_path = str(matched_path)
+                    try:
+                        st = matched_path.stat()
+                        results.append(
+                            {
+                                "path": out_path,
+                                "is_dir": False,
+                                "size": int(st.st_size),
+                                "modified_at": datetime.fromtimestamp(  # noqa: DTZ006
+                                    st.st_mtime,
+                                ).isoformat(),
+                            },
+                        )
+                    except OSError:
+                        results.append({"path": out_path, "is_dir": False})
+            except (OSError, RuntimeError, ValueError) as e:
+                results.sort(key=lambda x: x.get("path", ""))
+                return GlobResult(
+                    error=f"Glob of '{display_path}' aborted partway: {e}",
+                    matches=results,
+                )
+
+            results.sort(key=lambda x: x.get("path", ""))
+            truncated = hit_cap or time.monotonic() >= deadline
+            reason = "result_limit" if hit_cap else "budget"
+            if not caps.glob_has_truncation:
+                return GlobResult(
+                    matches=results,
+                    error=f"Glob truncated: {reason}; no file list returned by the tool. Narrow the path or pattern."
+                    if truncated
+                    else None,
+                )
+            return GlobResult(
+                matches=results,
+                truncated=truncated,
+                truncation_reason=reason if truncated else None,
+            )
+
+    return SafeFilesystemBackend(root_dir=root_dir, virtual_mode=virtual_mode)
+
+
+# ---------------------------------------------------------------------------
+# HITL Helper Functions
+# ---------------------------------------------------------------------------
+
+
+def _inject_content_from_state(tool_call: ToolCall, state: Any) -> None:
+    """HITL 인터럽트 전에 서브에이전트 코드/description을 tool_call args에 주입.
+
+    ContentInjectionMiddleware.before_model이 추출한 [CODE]/[SQL] 블록은
+    after_model에서 주입되지만, HITL이 먼저 실행되므로 args가 비어있음.
+    이 함수를 ds_tool_description 콜백에서 호출하여 HITL 인터럽트 시점에
+    tool_call args를 in-place로 수정함.
+    """
+    from .content_injection import _extract_code_block, _extract_description
+
+    name = tool_call["name"]
+    args = tool_call.get("args", {})
+
+    if name == "jupyter_cell":
+        messages = state.get("messages", [])
+        # 역순 탐색: jupyter_cell 실행 결과가 [CODE] 블록보다 먼저 나오면
+        # 해당 [CODE]는 이미 소비됨(stale) → description 주입 안함
+        for msg in reversed(messages):
+            if not (hasattr(msg, "type") and msg.type == "tool"):
+                continue
+            content = getattr(msg, "content", "")
+            if not isinstance(content, str):
+                continue
+            # jupyter_cell 실행 결과가 [CODE]보다 먼저 → stale
+            if '"tool": "jupyter_cell"' in content:
+                _dbg("SKIP_INJECT: found jupyter_cell result before [CODE] → stale")
+                break
+            if "[CODE]" not in content:
+                continue
+            # fresh [CODE] 블록 발견
+            code = _extract_code_block(content, lang="python")
+            if code:
+                if not args.get("code"):
+                    tool_call["args"]["code"] = code
+                if not args.get("description"):
+                    desc = _extract_description(content)
+                    if desc:
+                        tool_call["args"]["description"] = desc
+                        _dbg(
+                            f"INJECT_DESCRIPTION: len={len(desc)} "
+                            f"preview={desc[:100]!r}",
+                        )
+                    else:
+                        _dbg(
+                            "INJECT_DESCRIPTION: _extract_description returned None. "
+                            f"content_preview={content[:200]!r}",
+                        )
+                break
+
+    elif name == "file_write" and not args.get("content"):
+        messages = state.get("messages", [])
+        for msg in reversed(messages):
+            if not (hasattr(msg, "type") and msg.type == "tool"):
+                continue
+            content = getattr(msg, "content", "")
+            if not isinstance(content, str) or "[CODE]" not in content:
+                continue
+            code = _extract_code_block(content, lang="python")
+            if code:
+                tool_call["args"]["content"] = code
+                break
+
+
+def ds_tool_description(
+    tool_call: ToolCall,
+    state: Any,
+    runtime: Any,
+) -> str:
+    """HITL 승인 요청 시 사용자 친화적 도구 설명 생성."""
+    # 서브에이전트 코드/description 주입 (multi-agent 모드용)
+    _inject_content_from_state(tool_call, state)
+
+    name = tool_call["name"]
+    args = tool_call.get("args", {})
+
+    if name == "jupyter_cell":
+        code = args.get("code", "")
+        lines = code.split("\n") if code else []
+        if len(lines) > 5:
+            preview = "\n".join(lines[:5])
+            return (
+                f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+                f"**Jupyter Cell Execution** ({len(lines)} lines):\n"
+                f"```python\n{preview}\n# ... {len(lines) - 5} more lines\n```"
+            )
+        return (
+            f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+            f"**Jupyter Cell Execution:**\n```python\n{code}\n```"
+        )
+
+    if name == "file_write":
+        path = args.get("path", "unknown")
+        content = args.get("content", "")
+        size = len(content)
+        return (
+            f"{DS_HITL_DESCRIPTION_PREFIX}\n\n**File Write:** `{path}` ({size} bytes)"
+        )
+
+    return (
+        f"{DS_HITL_DESCRIPTION_PREFIX}\n\n"
+        f"**Tool:** {name}\n"
+        f"**Args:** {json.dumps(args, ensure_ascii=False, indent=2)}"
+    )
+
+
+_TOOL_NAME_MAP = {
+    "jupyter_cell": "jupyter_cell_tool",
+    "jupyter_markdown": "jupyter_markdown_tool",
+    "file_write": "write_file_tool",
+    "read_file": "read_file_tool",
+    "notebook_info": "notebook_info_tool",
+    "diagnostics": "diagnostics_tool",
+    "references": "references_tool",
+    "ask_user_tool": "ask_user_tool",
+    "final_summary_tool": "final_summary_tool",
+    "security_scan": "security_scan_tool",
+}
+
+
+def _get_tool_status_message(tool_name: str, tool_args: dict) -> dict:
+    """도구별 한국어 상태 메시지 생성 (chat-mode-enhancement 호환)."""
+    name = (tool_name or "").strip().lower()
+    if name in ("jupyter_cell", "jupyter_cell_tool"):
+        return {"status": "코드 실행 중...", "icon": "code", "label": "코드 실행"}
+    if name in ("jupyter_markdown", "markdown_tool"):
+        return {
+            "status": "마크다운 추가 중...",
+            "icon": "markdown",
+            "label": "마크다운",
+        }
+    if name in ("file_write", "write_file_tool"):
+        return {
+            "status": f"파일 작성: {tool_args.get('path', '')}",
+            "icon": "file",
+            "label": "파일 작성",
+        }
+    if name in ("write_todos",):
+        return {"status": "작업 계획 수립 중...", "icon": "todo", "label": "작업 계획"}
+    if name in ("glob", "search_files", "search_files_tool"):
+        pattern = tool_args.get("pattern", "")
+        return {
+            "status": f"파일 검색: '{pattern}'",
+            "icon": "search",
+            "label": "파일 검색",
+        }
+    if name in ("search_notebook_cells", "search_notebook_cells_tool"):
+        pattern = tool_args.get("pattern", "")
+        nb_path = tool_args.get("notebook_path", "")
+        return {
+            "status": f"노트북 검색: '{pattern}' in {nb_path}",
+            "icon": "search",
+            "label": "노트북 검색",
+        }
+    if name in ("list_workspace", "list_workspace_tool"):
+        path = tool_args.get("path", ".")
+        return {
+            "status": f"Workspace 검색: {path}",
+            "icon": "folder",
+            "label": "폴더 탐색",
+        }
+    if name in ("read_file", "read_file_tool"):
+        path = tool_args.get("path", "")
+        return {"status": f"파일 읽기: {path}", "icon": "file", "label": "파일 읽기"}
+    if name in ("final_summary", "final_summary_tool"):
+        return {"status": "작업 마무리중...", "icon": "summary", "label": "마무리"}
+    if name in ("ask_user", "ask_user_tool"):
+        return {
+            "status": "사용자 입력 대기 중...",
+            "icon": "pause",
+            "label": "사용자 입력",
+        }
+    if name in ("task",):
+        agent_type = tool_args.get("subagent_type", tool_args.get("agent_name", ""))
+        desc = tool_args.get("description", "")[:50]
+        return {
+            "status": f"서브에이전트 호출: {agent_type} - {desc}",
+            "icon": "agent",
+            "label": "서브에이전트",
+        }
+    if name in ("security_scan", "security_scan_tool"):
+        scan_type = tool_args.get("scan_type", "all")
+        return {
+            "status": f"보안 스캔 실행 중: {scan_type}",
+            "icon": "shield",
+            "label": "보안 스캔",
+        }
+    return {"status": f"Tool 실행: {tool_name}", "icon": "tool", "label": tool_name}
+
+
+def _repair_summary_json_content(content: str) -> str:
+    """gpt-oss 등에서 깨진 summary JSON 복구."""
+    if '"summary"' not in content or '"next_items"' not in content:
+        return content
+    try:
+        json.loads(content)
+        return content  # 이미 유효
+    except json.JSONDecodeError:
+        try:
+            from json_repair import repair_json
+
+            return repair_json(content)
+        except Exception:
+            return content
+
+
+def _transform_interrupt_to_frontend(hitl_request: dict, thread_id: str) -> dict:
+    """HITLRequest → 프론트엔드 포맷 변환."""
+    action_requests = hitl_request.get("action_requests", [])
+    action_count = len(action_requests)
+    if not action_requests:
+        return {
+            "thread_id": thread_id,
+            "action": "unknown",
+            "args": {},
+            "description": "",
+            "actionCount": 0,
+        }
+    ar = action_requests[0]
+    backend_name = ar.get("name", "unknown")
+    return {
+        "thread_id": thread_id,
+        "action": _TOOL_NAME_MAP.get(backend_name, backend_name + "_tool"),
+        "args": ar.get("args", {}),
+        "description": ar.get("description", ""),
+        "actionCount": action_count,
+    }
+
+
+def ds_error_formatter(exc: Exception) -> str:
+    """사용자 친화적 에러 메시지 포맷."""
+    _dbg(f"MODEL_ERROR: type={type(exc).__name__} msg={str(exc)[:500]}")
+    exc_type = type(exc).__name__
+
+    if "rate" in exc_type.lower() or "rate" in str(exc).lower():
+        return (
+            f"API rate limit reached ({exc_type}). "
+            "The request will be retried automatically. "
+            "If this persists, try again in a few moments."
+        )
+
+    if "auth" in exc_type.lower() or "key" in str(exc).lower():
+        return f"Authentication error ({exc_type}). Please check your API key configuration."
+
+    if "timeout" in exc_type.lower():
+        return f"Request timed out ({exc_type}). The model may be overloaded."
+
+    return f"Model call failed ({exc_type}): {exc}"
+
+
+# ---------------------------------------------------------------------------
+# AgentConfig / AgentEvent
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AgentConfig:
+    """에이전트 생성을 위한 설정."""
+
+    provider: str
+    model: str
+    api_key: str
+    base_url: str = ""
+    temperature: float = 0.0
+    max_tokens: int = 8192
+    max_iterations: int = 20
+    mode: str = "default"
+    agent_mode: str = "multi"  # "single" | "multi" | "<name>_direct"
+
+
+@dataclass
+class AgentEvent:
+    """에이전트 실행 중 발생하는 이벤트."""
+
+    type: str
+    data: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """딕셔너리로 변환."""
+        return {"type": self.type, **self.data}
+
+
+def _inject_resource_context_for_codegen(prompt: str, workspace_root: str) -> str:
+    """코드 생성 프롬프트의 {{RESOURCE_CONTEXT}}를 실제 리소스 정보로 치환."""
+    try:
+        from ..resource_usage import (
+            classify_resource_tiers,
+            generate_tier_guidance,
+            get_integrated_resources,
+        )
+
+        data = get_integrated_resources(workspace_root=workspace_root)
+        tiers = classify_resource_tiers(data)
+        guidance = generate_tier_guidance(tiers, mode="codegen")
+        return prompt.replace("{{RESOURCE_CONTEXT}}", guidance)
+    except Exception:
+        return prompt.replace("{{RESOURCE_CONTEXT}}", "")
+
+
+PYTHON_QUALITY_SKILL = "python_code_quality"
+# 옛 python_expert 기본값의 절 제목 — 저장값에 이것이 있으면 원칙이 이미 들어 있다
+_PYTHON_QUALITY_TITLE = "# 코드 생성 품질 원칙"
+
+
+def python_quality_section(prompt: str, workspace_root: Optional[str]) -> str:
+    """python_expert 에 붙일 품질 원칙 — 정본은 스킬 `python_code_quality` 한 벌이다 (이슈 #228).
+
+    모든 호출에 적용되던 규칙이라 모델이 스킬을 부르기를 기다리지 않고 조립 때 붙인다.
+    같은 이름의 포털 스킬이 있으면 그 본문이 이긴다. `prompt` 에 원칙이 이미 있으면
+    (옛 기본값을 저장한 조직) 두 벌이 되지 않게 붙이지 않는다.
+    """
+    if _PYTHON_QUALITY_TITLE in prompt:
+        return ""
+    skills = custom_skills.with_builtin(
+        custom_skills.discover(workspace_root) if workspace_root else []
+    )
+    body = custom_skills.load_body(PYTHON_QUALITY_SKILL, skills)
+    if body.startswith("Error: "):
+        return ""
+    # 스킬 목록에도 같은 이름이 뜨므로 한 번 더 읽는 왕복을 막는다
+    return (
+        f"\n\n(아래는 스킬 `{PYTHON_QUALITY_SKILL}` 본문이다 — 이미 붙어 있으니"
+        " load_skill_tool 로 다시 읽지 않는다)\n\n" + body
+    )
+
+
+# ---------------------------------------------------------------------------
+# AgentFactory
+# ---------------------------------------------------------------------------
+
+#: 실행 전 사용자 승인을 받는 도구 — HITL interrupt 대상. centri 도구 보고의
+#: `approval` 도 이것을 읽는다(이슈 #248). multi 모드의 `ask_user_tool` 은 따로 더한다
+HITL_TOOL_NAMES = ("file_write", "jupyter_cell")
+
+
+class AgentFactory:
+    """Jupyter 도구가 포함된 LangChain Agent 인스턴스를 생성하는 팩토리.
+
+    LangChain Agent 라이브러리를 래핑하여 Jupyter 노트북 작업에 맞게
+    구성된 에이전트를 생성함. 다음을 처리:
+    - 프로바이더 설정 기반 LLM 초기화
+    - Jupyter 전용 도구 주입 (jupyter_cell, jupyter_markdown)
+    - 파일, 셸 도구 주입
+    - 미들웨어 스택 구성 (중복 없이 필요한 것만)
+    - 실시간 진행 상황 업데이트를 위한 이벤트 스트리밍
+    - HITL (Human-in-the-loop) 그래프 인터럽트 통합
+    """
+
+    def __init__(
+        self,
+        notebook_context: NotebookContextManager,
+        workspace_root: str | None = None,
+        on_event: Callable[[AgentEvent], Any] | None = None,
+        memory_store: MemoryStore | None = None,
+    ):
+        """에이전트 팩토리 초기화.
+
+        Args:
+            notebook_context: 노트북 상태 관리자
+            workspace_root: 파일/셸/검색 작업의 루트 디렉토리
+            on_event: 에이전트 이벤트 콜백 (진행 상황, 도구 호출 등)
+            memory_store: DS 세션 메모리 저장소 (미지정 시 새로 생성)
+
+        """
+        self._notebook_context = notebook_context
+        self._workspace_root = workspace_root or "."
+        self._on_event = on_event
+        self._memory_store = memory_store or MemoryStore()
+
+    _AGENTS_MD_MAX_CHARS = 10_000
+
+    def _read_agents_md(self) -> str | None:
+        """워크스페이스 루트의 AGENTS.md 를 읽어 반환 (대소문자 무시, 이슈 #139)."""
+        ws = Path(self._workspace_root)
+        agents_md_path = None
+        try:
+            for f in ws.iterdir():
+                if f.is_file() and f.name.lower() == "agents.md":
+                    agents_md_path = f
+                    break
+        except OSError:
+            return None
+        if agents_md_path is None:
+            return None
+        try:
+            content = agents_md_path.read_text(encoding="utf-8").strip()
+            if content:
+                if len(content) > self._AGENTS_MD_MAX_CHARS:
+                    _dbg(
+                        f"{agents_md_path.name} truncated: {len(content)}"
+                        f" → {self._AGENTS_MD_MAX_CHARS} chars",
+                    )
+                    content = content[: self._AGENTS_MD_MAX_CHARS]
+                else:
+                    _dbg(f"{agents_md_path.name} loaded ({len(content)} chars)")
+                return content
+        except Exception as e:
+            _dbg(f"Failed to read {agents_md_path.name}: {e}")
+        return None
+
+    def _instruction_suffix(self, include_custom_skills: bool = True) -> str:
+        """시스템 프롬프트 뒤에 붙일 것 — 사내 플랫폼 규칙, AGENTS.md, 커스텀 스킬 목록.
+
+        사내가 아니고 커스텀 스킬이 없으면 규칙·목록이 빈 문자열이라 로컬 프롬프트는
+        전과 같다 (이슈 #120, #134). 스킬 미들웨어 섹션을 이미 실은 프롬프트(direct 모드)는
+        `include_custom_skills=False` 로 목록이 두 번 실리지 않게 한다.
+        """
+        suffix = ""
+        platform_rules = platform_rules_block()
+        if platform_rules:
+            suffix += "\n\n---\n\n" + platform_rules
+        agents_md = self._read_agents_md()
+        if agents_md:
+            suffix += "\n\n---\n\n# Project Instructions (AGENTS.md)\n\n" + agents_md
+        if include_custom_skills:
+            skills_section = custom_skills.prompt_section(
+                custom_skills.discover(self._workspace_root), "load_skill_tool"
+            )
+            if skills_section:
+                suffix += "\n\n---\n\n" + skills_section
+        return suffix
+
+    def _builtin_skill_suffix(self) -> str:
+        """메인 에이전트에 싣는 내장 스킬 목록 — 커스텀이 재정의한 것은 뺀다 (이슈 #220).
+
+        키워드로 붙던 DS 템플릿(`DSSkillsMiddleware`)이 내장 스킬이 되어, 메인 에이전트는
+        이 목록을 보고 `load_skill_tool` 로 읽는다. 커스텀 목록은 `_instruction_suffix` 가 싣는다.
+        """
+        section = custom_skills.builtin_section(
+            custom_skills.discover(self._workspace_root), "load_skill_tool"
+        )
+        return "\n\n---\n\n" + section if section else ""
+
+    def _skill_tools(self) -> list:
+        """메인 에이전트의 `load_skill_tool` — 내장 스킬이 있으므로 항상 준다 (이슈 #134, #220)."""
+        from .skill_middleware import get_skill_middleware
+
+        return get_skill_middleware(self._workspace_root).get_tools()
+
+    def _create_subagents(self) -> list:
+        """멀티에이전트 모드용 서브에이전트 목록 생성.
+
+        Returns:
+            SubAgent TypedDict 목록 (python_expert, researcher, athena_query,
+            airflow_expert, emr_expert, lambda_expert, spring_expert, bq_agent)
+
+        """
+        from deepagents import SubAgent
+
+        from .langchain_tools import (
+            create_diagnostics_tool,
+            create_references_tool,
+        )
+        from .skill_middleware import get_skill_middleware
+
+        # 서브에이전트 프롬프트는 `prompts.<이름>` 이다 — 관리자 값, 없으면 스냅샷 (이슈 #218)
+
+        # 서브에이전트 공통 도구 (read_file, execute는 DeepAgents FilesystemMiddleware가 자동 제공)
+        read_tools = [
+            create_diagnostics_tool(self._workspace_root),
+            create_references_tool(self._workspace_root),
+        ]
+
+        # python_expert: 코드 생성 + skills
+        skill_mw = get_skill_middleware(self._workspace_root)
+        base_py_prompt = prompt_value("python_expert")
+        # 코드를 쓰는 서브에이전트는 AGENTS.md 를 못 받으므로 플랫폼 규칙을 직접 붙인다 (이슈 #120)
+        platform_rules = platform_rules_block()
+        platform_section = "\n\n" + platform_rules if platform_rules else ""
+        py_dev_prompt = (
+            base_py_prompt
+            + python_quality_section(base_py_prompt, self._workspace_root)
+            + "\n\n"
+            + skill_mw.get_prompt_section()
+            + platform_section
+        )
+        if "{{RESOURCE_CONTEXT}}" in py_dev_prompt:
+            py_dev_prompt = _inject_resource_context_for_codegen(
+                py_dev_prompt,
+                self._workspace_root,
+            )
+        py_dev_tools = read_tools + skill_mw.get_tools()
+
+        researcher_prompt = prompt_value("researcher")
+
+        # 도메인 전문가 프롬프트 (skill section 포함)
+        skill_section = skill_mw.get_prompt_section()
+        skill_tools = read_tools + skill_mw.get_tools()
+
+        athena_prompt = (
+            prompt_value("athena_query") + "\n\n" + skill_section + platform_section
+        )
+        airflow_prompt = prompt_value("airflow_expert") + "\n\n" + skill_section
+        emr_prompt = (
+            prompt_value("emr_expert") + "\n\n" + skill_section + platform_section
+        )
+        lambda_prompt = (
+            prompt_value("lambda_expert") + "\n\n" + skill_section + platform_section
+        )
+        spring_prompt = prompt_value("spring_expert") + "\n\n" + skill_section
+        bq_prompt = prompt_value("bq_agent") + "\n\n" + skill_section
+
+        return [
+            SubAgent(
+                name="python_expert",
+                description="Python 코드 생성 전문가. 데이터 분석, 시각화, 파일 처리 등 Python 코드를 생성합니다.",
+                system_prompt=py_dev_prompt,
+                tools=py_dev_tools,
+            ),
+            SubAgent(
+                name="researcher",
+                description="정보 검색 전문가. 파일 탐색, 코드 분석, 워크스페이스 구조 파악을 수행합니다.",
+                system_prompt=researcher_prompt,
+                tools=read_tools,
+            ),
+            SubAgent(
+                name="athena_query",
+                description="AWS Athena SQL 전문가. 쿼리 생성, 성능 튜닝, EXPLAIN 분석, CloudWatch 로그 분석을 수행합니다.",
+                system_prompt=athena_prompt,
+                tools=skill_tools,
+            ),
+            SubAgent(
+                name="airflow_expert",
+                description="Airflow 전문가 (MWAA/Composer). DAG 개발, 성능 튜닝, 에러 분석, 로그 해석, task dependency 시각화(Mermaid)를 수행합니다.",
+                system_prompt=airflow_prompt,
+                tools=skill_tools,
+            ),
+            SubAgent(
+                name="emr_expert",
+                description="EMR PySpark 전문가. PySpark 코드 생성, Spark 성능 튜닝, YARN/Spark UI 로그 분석을 수행합니다.",
+                system_prompt=emr_prompt,
+                tools=skill_tools,
+            ),
+            SubAgent(
+                name="lambda_expert",
+                description="AWS Lambda 전문가. handler 생성, Cold Start 최적화, CloudWatch 로그 분석을 수행합니다.",
+                system_prompt=lambda_prompt,
+                tools=skill_tools,
+            ),
+            SubAgent(
+                name="spring_expert",
+                description="Java & Spring Boot 전문가. 코드 생성, JVM/Spring 성능 튜닝, GC/Thread Dump 분석을 수행합니다.",
+                system_prompt=spring_prompt,
+                tools=skill_tools,
+            ),
+            SubAgent(
+                name="bq_agent",
+                description="GCP BigQuery 분석 전문가. 쿼리 요약, 실행계획 시각화(Mermaid), 900-slot 쿼리 튜닝, 비용 분석, Oracle→BQ SQL 변환을 수행합니다.",
+                system_prompt=bq_prompt,
+                tools=skill_tools,
+            ),
+        ]
+
+    def _create_model(self, config: AgentConfig) -> BaseChatModel:
+        """설정에서 LangChain 채팅 모델 생성.
+
+        Args:
+            config: 프로바이더와 API 키가 포함된 에이전트 설정
+
+        Returns:
+            구성된 BaseChatModel 인스턴스
+
+        """
+        kwargs: dict[str, Any] = {
+            "api_key": config.api_key,
+            "temperature": config.temperature,
+            "max_tokens": config.max_tokens,
+            # tool 호출 시 병렬 tool_call 비활성화. tools 없는 호출에도 같은 model
+            # 객체가 쓰이지만 parallel_tool_calls는 tools 미지정 요청에서도 에러
+            # 없이 무시됨(tool_choice와 달리 안전). vllm(openai-compatible)만
+            # 지원하는 factory라 전역 적용 가능.
+            "model_kwargs": {"parallel_tool_calls": False},
+            # 스트리밍에도 토큰 사용량을 받는다(`stream_options.include_usage`). 없으면
+            # astream 경로의 AIMessage.usage_metadata 가 비어 토큰이 전부 NULL 이다 (#98).
+            # 엔드포인트가 이 필드를 거부하면 채팅이 400 으로 깨진다 — 반입 체크리스트
+            # (docs/로깅RDS/적재-계약.md) 에서 운영 vLLM 으로 먼저 확인한다.
+            "stream_usage": True,
+        }
+        if config.base_url:
+            kwargs["base_url"] = config.base_url
+        if "gpt-oss" in config.model.lower():
+            # gpt-oss 토크나이저 고유 stop token — 다른 모델엔 적용하지 않음.
+            kwargs["extra_body"] = {"stop_token_ids": [200002, 199999, 200012]}
+
+        model_string = f"{config.provider}:{config.model}"
+        _dbg(
+            f"CREATE_MODEL: model_string={model_string} "
+            f"base_url={config.base_url} "
+            f"api_key_len={len(config.api_key) if config.api_key else 0} "
+            f"api_key_prefix={config.api_key[:8] if config.api_key else 'EMPTY'}",
+        )
+        return init_chat_model(model_string, **kwargs)
+
+    def _create_all_tools(self) -> list[BaseTool]:
+        """Jupyter, 파일, 셸 도구를 포함한 모든 LangChain 도구 생성.
+
+        Note: file_list과 search_code는 FilesystemFileSearchMiddleware가 대체
+            (glob_search, grep_search 도구 자동 제공).
+
+        Returns:
+            모든 LangChain BaseTool 인스턴스 목록
+
+        """
+        from .ast_tools import (
+            create_analyze_dependencies_tool,
+            create_analyze_file_structure_tool,
+            create_search_symbol_definition_tool,
+        )
+        from .langchain_tools import (
+            create_diagnostics_tool,
+            create_file_find_tool,
+            create_file_write_tool,
+            create_jupyter_cell_tool,
+            create_jupyter_markdown_tool,
+            create_notebook_info_tool,
+            create_rag_search_tool,
+            create_references_tool,
+            create_security_scan_tool,
+        )
+
+        tools = [
+            # Jupyter 도구
+            create_jupyter_cell_tool(self._notebook_context),
+            create_jupyter_markdown_tool(self._notebook_context),
+            create_notebook_info_tool(self._notebook_context),
+            # 파일 도구 (read_file은 DeepAgents FilesystemMiddleware가 제공)
+            create_file_write_tool(self._workspace_root),  # ruff 자동 포맷 유지
+            # LSP 도구 (grep 기반 폴백) - search_code는 grep_search가 대체
+            create_diagnostics_tool(self._workspace_root),
+            create_references_tool(self._workspace_root),
+            # 보안 스캔 도구
+            create_security_scan_tool(self._workspace_root),
+            # AST 기반 코드 분석 도구
+            create_analyze_file_structure_tool(self._workspace_root),
+            create_search_symbol_definition_tool(self._workspace_root),
+            create_analyze_dependencies_tool(self._workspace_root),
+            # Fuzzy 파일 검색 도구
+            create_file_find_tool(self._workspace_root),
+        ]
+
+        # RAG 검색 도구 (qdrant-client 미설치 시 무시)
+        try:
+            tools.append(create_rag_search_tool())
+        except Exception:
+            pass
+
+        return tools
+
+    def _create_middleware(
+        self,
+        model: BaseChatModel,
+        session_id: str = "",
+    ) -> list[Any]:
+        """미들웨어 스택 생성.
+
+        미들웨어 순서 (중요 - 첫 번째가 가장 안쪽):
+        1. PatchToolCallsMiddleware: dangling tool call 패치
+        2. ModelRetryMiddleware: 모델 호출 재시도
+        3. AutoFixMiddleware: 코드 자동 수정 + 에러 복구
+        4. LimitToolCallsMiddleware: tool_calls 1개 제한
+        5. SummarizationMiddleware: 컨텍스트 압축
+        6. ContinuationControlMiddleware: non-HITL 도구 후 LLM 가이드
+        7. DSMemoryMiddleware: 메모리 주입
+        8. TodoListMiddleware: 작업 계획
+        9. FilesystemFileSearchMiddleware: 파일 검색 도구
+        10. HumanInTheLoopMiddleware: 승인 게이트 (가장 바깥)
+        11. ObservabilityMiddleware: 전체 타이밍 JSONL 로깅 (가장 바깥)
+
+        Args:
+            model: 요약에 사용할 LLM
+            session_id: 세션 ID (Observability 로깅용)
+
+        Returns:
+            미들웨어 인스턴스 목록
+
+        """
+        from .code_history_middleware import CodeHistoryMiddleware
+        from .continuation_middleware import (
+            ContinuationControlMiddleware,
+            LimitToolCallsMiddleware,
+            TodoActiveMiddleware,
+        )
+        from .guardrail_middleware import (
+            InputGuardrailMiddleware,
+            OutputGuardrailMiddleware,
+            PiiMaskMiddleware,
+            PlatformGuardMiddleware,
+        )
+        from .mermaid_middleware import MermaidFixMiddleware
+        from .observability import ObservabilityMiddleware, default_user_identity
+
+        # 1. AutoFix: 코드 자동 수정 + 에러 복구
+        autofix_middleware = AutoFixMiddleware(
+            notebook_context=self._notebook_context,
+            max_retries=2,
+            session_id=session_id,
+        )
+
+        # 2. ModelRetry: API 실패 시 자동 재시도
+        retry_middleware = ModelRetryMiddleware(
+            max_retries=3,
+            backoff_factor=1.5,
+            initial_delay=0.3,
+            max_delay=30.0,
+            on_failure=ds_error_formatter,
+        )
+
+        # Note: create_deep_agent already provides these middlewares internally:
+        #   - PatchToolCallsMiddleware
+        #   - SummarizationMiddleware
+        #   - TodoListMiddleware
+        #   - FilesystemMiddleware
+        #   - HumanInTheLoopMiddleware (via interrupt_on param)
+        # Only pass custom middlewares that are NOT provided by create_deep_agent.
+
+        # 3. LimitToolCalls: tool_calls 1개 제한 + kwargs 정리
+        limit_tool_calls = LimitToolCallsMiddleware()
+
+        # 4. TodoActive: wrap_tool_call로 todo_active/last_tool_name state flag 관리
+        todo_active = TodoActiveMiddleware()
+
+        # 5. ContinuationControl: state flag 기반 continuation 가이드
+        continuation_control = ContinuationControlMiddleware()
+
+        # 6. CodeHistory: 서브에이전트에 코드 실행 이력 주입
+        code_history = CodeHistoryMiddleware()
+
+        # DSMemory: 세션 메모리 주입/추출
+        memory_middleware = DSMemoryMiddleware(
+            memory_store=self._memory_store,
+            max_memories_per_call=10,
+            auto_extract=False,
+        )
+
+        # Observability: 전체 파이프라인 타이밍 + 구조화된 JSONL 로깅
+        observability = ObservabilityMiddleware(
+            session_id=session_id,
+            user_identity=default_user_identity(),
+        )
+
+        # Guardrails: 입력/출력 안전 검사
+        from codebuff_core.managers.config_manager import get_config_manager
+
+        guardrail_cfg = get_config_manager().get("guardrails", {})
+
+        middleware_list = [
+            retry_middleware,
+            autofix_middleware,
+            limit_tool_calls,
+        ]
+        # Output Guardrail: limit_tool_calls 뒤, todo_active 앞
+        if guardrail_cfg.get("enableOutput", True):
+            middleware_list.append(
+                OutputGuardrailMiddleware(
+                    max_code_length=guardrail_cfg.get("maxCodeLength", 10_000),
+                ),
+            )
+
+        # Mermaid Fix: guardrail 뒤 (차단된 응답엔 수정 불필요)
+        middleware_list.append(MermaidFixMiddleware())
+
+        middleware_list.extend(
+            [
+                todo_active,
+                continuation_control,
+                code_history,
+                memory_middleware,
+            ],
+        )
+
+        # Input Guardrail: memory_middleware 뒤 (가장 바깥 커스텀)
+        if guardrail_cfg.get("enableInput", True):
+            middleware_list.append(
+                InputGuardrailMiddleware(
+                    max_input_length=guardrail_cfg.get("maxInputLength", 50_000),
+                ),
+            )
+
+        middleware_list.append(observability)
+        # 개인정보 마스킹: 모델 호출을 감싸는 것 중 가장 안쪽 — 바깥이 더한 메시지까지 가린다.
+        # codex 경로와 같은 규칙이다 (이슈 #155). 끄는 설정은 두지 않는다 — codex 에도 없다.
+        middleware_list.append(PiiMaskMiddleware())
+        # 사내 BDP: boto3 직접 사용을 돌려보낸다 (이슈 #120). 가장 안쪽에 둬야 막힌 호출도
+        # 관측(tool_call 행)과 todo 상태 미들웨어를 지나간다 — codex 쪽 계측과 맞춘다.
+        if is_bdp_platform():
+            middleware_list.append(PlatformGuardMiddleware())
+
+        return middleware_list
+
+    def create_agent(
+        self,
+        config: AgentConfig,
+        additional_tools: Sequence[BaseTool] | None = None,
+        checkpointer=None,
+        thread_id: str | None = None,
+    ) -> AgentRunner:
+        """Jupyter용으로 구성된 LangChain Agent 인스턴스 생성.
+
+        Args:
+            config: 에이전트 설정
+            additional_tools: 추가할 선택적 도구들
+
+        Returns:
+            실행 준비된 AgentRunner 인스턴스
+
+        """
+        # LLM 생성
+        model = self._create_model(config)
+
+        # 모든 도구 생성 (Jupyter + 파일 + 셸)
+        all_tools = self._create_all_tools()
+
+        # 추가 도구가 있으면 결합
+        if additional_tools:
+            all_tools.extend(additional_tools)
+
+        # 미들웨어 스택 생성
+        middleware = self._create_middleware(model, session_id=thread_id or "")
+
+        # TodoListMiddleware 기본값을 DS 특화 프롬프트로 교체.
+        from langchain.agents.middleware import TodoListMiddleware as _TodoMW
+
+        _patch_todo_middleware()
+        _dbg(
+            f"TodoListMiddleware patched: system_prompt_len="
+            f"{len(_TodoMW.__init__.__kwdefaults__.get('system_prompt', ''))}",
+        )
+        _dbg(
+            f"TodoListMiddleware patched: tool_desc starts with="
+            f"{_TodoMW.__init__.__kwdefaults__.get('tool_description', '')[:50]}",
+        )
+
+        # HITL interrupt 설정
+        interrupt_on = {
+            name: InterruptOnConfig(
+                allowed_decisions=["approve", "edit", "reject"],
+                description=ds_tool_description,
+            )
+            for name in HITL_TOOL_NAMES
+        }
+
+        # 멀티에이전트 모드 분기
+        subagents = None
+        if config.agent_mode.endswith("_direct"):
+            # 서브에이전트 직접 실행 모드: Planner 바이패스
+            from .skill_middleware import get_skill_middleware
+
+            # 직접 실행 모드 → 서브에이전트 프롬프트 키 (이슈 #218)
+            _DIRECT_PROMPT_KEY = {
+                "bq_agent_direct": "bq_agent",
+                "athena_query_direct": "athena_query",
+                "airflow_expert_direct": "airflow_expert",
+                "emr_expert_direct": "emr_expert",
+                "lambda_expert_direct": "lambda_expert",
+                "spring_expert_direct": "spring_expert",
+            }
+
+            custom_key = _DIRECT_PROMPT_KEY[config.agent_mode]
+
+            skill_mw = get_skill_middleware(self._workspace_root)
+            skill_tools = skill_mw.get_tools()
+            skill_section = skill_mw.get_prompt_section()
+
+            # jupyter_markdown 도구 추가 (노트북에 직접 출력)
+            from .langchain_tools import create_jupyter_markdown_tool
+
+            all_tools.extend(skill_tools)
+            all_tools.append(create_jupyter_markdown_tool(self._notebook_context))
+
+            system_prompt = prompt_value(custom_key) + "\n\n" + skill_section
+            _dbg(
+                f"DIRECT_MODE({config.agent_mode}): tools={len(all_tools)} "
+                f"prompt_key={custom_key}",
+            )
+        elif config.agent_mode == "multi":
+            from ..tools.user_tools import ask_user_tool, final_summary_tool
+
+            all_tools.extend([ask_user_tool, final_summary_tool])
+            subagents = self._create_subagents()
+
+            # ask_user_tool HITL 설정
+            interrupt_on["ask_user_tool"] = InterruptOnConfig(
+                allowed_decisions=["approve", "edit", "reject"],
+                description=ds_tool_description,
+            )
+
+            # 관리자 값 → 스냅샷 (`prompts.planner`, 이슈 #218)
+            system_prompt = _planner_system_prompt()
+            _dbg(
+                f"MULTI_AGENT: subagents={[s['name'] for s in subagents]} "
+                f"tools_count={len(all_tools)}",
+            )
+        else:
+            system_prompt = get_system_prompt(config.mode)
+
+        # 사내 플랫폼 규칙·AGENTS.md·스킬 목록을 붙인다 (이슈 #120, #134, #220).
+        # direct 모드는 스킬 미들웨어가 목록과 도구를 이미 실었다.
+        direct_mode = config.agent_mode.endswith("_direct")
+        if not direct_mode:
+            all_tools.extend(self._skill_tools())
+        system_prompt += self._instruction_suffix(include_custom_skills=not direct_mode)
+        if not direct_mode:
+            system_prompt += self._builtin_skill_suffix()
+
+        # multi 모드: ContentInjectionMiddleware 추가
+        if config.agent_mode == "multi":
+            from .content_injection import ContentInjectionMiddleware
+
+            middleware.insert(0, ContentInjectionMiddleware())
+
+        # DeepAgents 그래프 생성 (checkpointer 포함 - HITL 인터럽트/리줌에 필수)
+        backend = _create_safe_backend(root_dir=self._workspace_root, virtual_mode=True)
+
+        # DeepAgents 그래프 생성 (checkpointer 포함 - HITL 인터럽트/리줌에 필수)
+        # Note: 서브에이전트의 write_todos 사용은 시스템 프롬프트에서 금지
+        from deepagents import create_deep_agent
+
+        # execute 도구 제거: FilesystemMiddleware가 자동 생성하는 execute를 필터링
+        from deepagents.middleware.filesystem import FilesystemMiddleware
+
+        _orig_fs_init = FilesystemMiddleware.__init__
+
+        def _fs_init_no_execute(self_mw, **kwargs):
+            _orig_fs_init(self_mw, **kwargs)
+            self_mw.tools = [t for t in self_mw.tools if t.name != "execute"]
+
+        FilesystemMiddleware.__init__ = _fs_init_no_execute
+
+        # 서브에이전트는 오케스트레이터의 미들웨어를 물려받지 않는다 — 각자 계측을
+        # 붙여야 호출이 model_call·turn 토큰에 들어간다. single·direct 모드에도
+        # task 도구로 부르는 general-purpose 가 있으므로 모드와 무관하게 건다 (이슈 #98).
+        subagents = _observe_subagents(subagents or [], thread_id or "")
+        subagents = _guard_subagents(subagents)
+        subagents = _mask_subagents(subagents)
+
+        agent = create_deep_agent(
+            model=model,
+            tools=all_tools,
+            system_prompt=system_prompt,
+            middleware=middleware,
+            subagents=subagents,
+            backend=backend,
+            checkpointer=checkpointer or MemorySaver(),
+            interrupt_on=interrupt_on,
+        ).with_config({"recursion_limit": 1000})
+
+        return AgentRunner(
+            agent=agent,
+            config=config,
+            on_event=self._on_event,
+            thread_id=thread_id,
+            workspace_root=self._workspace_root,
+        )
+
+
+def _observe_subagents(subagents: list, session_id: str) -> list:
+    """서브에이전트마다 자기 이름의 관측 미들웨어를 붙인다 (이슈 #98).
+
+    deepagents 가 자동으로 붙이는 general-purpose 는 미들웨어를 받을 자리가 없다.
+    같은 이름의 명시 스펙은 기본값을 대신하므로(도구·모델은 부모 것을 물려받는다)
+    계측을 붙이려고 기본 스펙 그대로 선언한다.
+    """
+    from deepagents import SubAgent
+    from deepagents.middleware.subagents import GENERAL_PURPOSE_SUBAGENT
+
+    from .observability import ObservabilityMiddleware, default_user_identity
+
+    specs = list(subagents)
+    if not any(s["name"] == GENERAL_PURPOSE_SUBAGENT["name"] for s in specs):
+        # 기본 경로처럼 맨 앞에 둔다 — task 도구 설명의 나열 순서가 위임 선택에 닿는다
+        specs.insert(0, SubAgent(**GENERAL_PURPOSE_SUBAGENT))
+    identity = default_user_identity()
+    for spec in specs:
+        spec["middleware"] = [
+            *spec.get("middleware", []),
+            ObservabilityMiddleware(
+                session_id=session_id,
+                user_identity=identity,
+                agent_name=spec["name"],
+            ),
+        ]
+    return specs
+
+
+def _guard_subagents(specs: list) -> list:
+    """사내면 서브에이전트에도 boto3 가드를 가장 안쪽에 붙인다 — 오케스트레이터 것을 물려받지 않는다 (이슈 #120)."""
+    if not is_bdp_platform():
+        return specs
+    from .guardrail_middleware import PlatformGuardMiddleware
+
+    for spec in specs:
+        spec["middleware"] = [*spec.get("middleware", []), PlatformGuardMiddleware()]
+    return specs
+
+
+def _mask_subagents(specs: list) -> list:
+    """서브에이전트에도 개인정보 마스킹을 붙인다 — 오케스트레이터 것을 물려받지 않는다 (이슈 #155).
+
+    task 도구로 넘기는 설명과 서브에이전트의 도구 결과도 모델로 간다.
+    """
+    from .guardrail_middleware import PiiMaskMiddleware
+
+    for spec in specs:
+        spec["middleware"] = [*spec.get("middleware", []), PiiMaskMiddleware()]
+    return specs
+
+
+# ---------------------------------------------------------------------------
+# AgentRunner
+# ---------------------------------------------------------------------------
+
+
+class AgentRunner:
+    """이벤트 스트리밍이 포함된 LangChain Agent 실행기.
+
+    컴파일된 LangChain Agent 그래프를 래핑하고 다음을 제공:
+    - 이벤트 스트리밍이 포함된 비동기 실행
+    - 반복 추적 및 제한
+    - HITL 그래프 인터럽트 처리
+    - 에러 처리
+    """
+
+    def __init__(
+        self,
+        agent: Any,  # LangChain의 CompiledStateGraph
+        config: AgentConfig,
+        on_event: Callable[[AgentEvent], Any] | None = None,
+        thread_id: str | None = None,
+        workspace_root: str = "",
+    ):
+        """실행기 초기화.
+
+        Args:
+            agent: 컴파일된 LangChain Agent 그래프
+            config: 에이전트 설정
+            on_event: 에이전트 이벤트 콜백
+            thread_id: 클라이언트에서 전달받은 스레드 ID (미지정 시 자동 생성)
+            workspace_root: 승인 없는 파일 쓰기의 diff 를 잴 루트 (이슈 #147)
+
+        """
+        self._agent = agent
+        self._config = config
+        self._on_event = on_event
+        self._iteration = 0
+        self._tool_count = 0
+        self._is_cancelled = False
+        # write_file/edit_file 의 before 를 run_id 별로 쥔다 — resume 루프도 같이 쓴다 (#147)
+        self.file_diffs = FileDiffTracker(workspace_root)
+        # 진행 중이거나 HITL 로 멈춘 턴의 계측 — 핸들러가 넣고 뺀다 (#98)
+        self.turn_meter = None
+        self.parked_at = (
+            None  # HITL 대기로 멈춘 시각 — client 유휴 회수가 본다 (이슈 #98)
+        )
+        self._thread_id: str = thread_id or str(__import__("uuid").uuid4())
+        # Content dedup
+        self._emitted_content_hashes: set = set()
+        # Auto-terminate
+        self._last_todos_data: list = []
+        self._all_todos_completed: bool = False
+        # Subagent tracking: task 도구 실행 중 서브에이전트 LLM 응답 필터링
+        self._inside_subagent: bool = False
+        # Streaming turn metrics
+        self._turn_start_time: float = 0.0
+        self._turn_token_estimate: int = 0
+        # Truncation auto-continuation
+        self._truncation_count: int = 0
+        self._truncated_this_turn: bool = False
+
+    @property
+    def agent(self) -> Any:
+        """컴파일된 에이전트 그래프 접근."""
+        return self._agent
+
+    @property
+    def thread_id(self) -> str:
+        """현재 실행 스레드 ID."""
+        return self._thread_id
+
+    @property
+    def iteration(self) -> int:
+        """현재 반복 횟수."""
+        return self._iteration
+
+    @property
+    def emitted_content_hashes(self) -> set:
+        """Emitted content hashes for dedup."""
+        return self._emitted_content_hashes
+
+    async def _emit_event(self, event_type: str, data: dict[str, Any]) -> None:
+        """콜백으로 이벤트 발생."""
+        event = AgentEvent(type=event_type, data=data)
+        if self._on_event:
+            result = self._on_event(event)
+            if asyncio.iscoroutine(result):
+                await result
+
+    async def run(self, prompt: str) -> str:
+        """주어진 프롬프트로 에이전트 실행.
+
+        HITL 인터럽트 발생 시 hitl_request 이벤트를 emit하고,
+        외부에서 resume()을 호출할 때까지 대기.
+
+        Args:
+            prompt: 사용자 요청
+
+        Returns:
+            에이전트의 최종 응답
+
+        Raises:
+            asyncio.CancelledError: 실행이 취소된 경우
+            Exception: 실행 에러 발생 시
+
+        """
+        await self._emit_event("start", {"prompt": prompt})
+        _dbg(f"=== AGENT RUN START === prompt={prompt[:100]}")
+        _dbg(f"  agent_type={type(self._agent).__name__} model={self._config.model}")
+        _dbg(f"  agent_mode={self._config.agent_mode}")
+
+        try:
+            # 초기 메시지 생성
+            messages = [HumanMessage(content=prompt)]
+
+            # 실행 이벤트 스트리밍
+            final_response = ""
+
+            config = {
+                "configurable": {"thread_id": self._thread_id},
+                "recursion_limit": 1000,
+            }
+
+            _astream_input: dict | None = {"messages": messages}
+            _run_astream = True
+            _astream_loop_count = 0
+            _MAX_ASTREAM_LOOPS = (
+                _MAX_CONTINUATIONS + 1
+            )  # 정상 1회 + continuation 최대 N회
+
+            while _run_astream:
+                _astream_loop_count += 1
+                if _astream_loop_count > _MAX_ASTREAM_LOOPS:
+                    _dbg(
+                        f"ASTREAM_LOOP_HARD_LIMIT: {_astream_loop_count} iterations, breaking",
+                    )
+                    break
+                _run_astream = (
+                    False  # 기본적으로 1회만 실행; truncation 시 True로 재설정
+                )
+                self._truncated_this_turn = False
+                async for event in self._agent.astream_events(
+                    _astream_input,
+                    config=config,
+                    version="v2",
+                ):
+                    if self._is_cancelled:
+                        raise asyncio.CancelledError()
+
+                    event_kind = event.get("event", "")
+                    # DEBUG: 모든 이벤트 종류 로깅
+                    if event_kind not in ("on_chat_model_stream",):
+                        _dbg(
+                            f"ASTREAM_EVENT: kind={event_kind} name={event.get('name', '')} "
+                            f"tags={event.get('tags', [])} run_id={str(event.get('run_id', ''))[:8]}",
+                        )
+
+                    # 반복 추적 (각 LLM 호출이 하나의 반복)
+                    if event_kind == "on_chat_model_start":
+                        # 서브에이전트 내부 LLM은 무시
+                        if self._inside_subagent:
+                            continue
+                        self._iteration += 1
+                        self._turn_start_time = time.monotonic()
+                        self._turn_token_estimate = 0
+                        # 턴별 콘텐츠 버퍼링
+                        # on_chat_model_end에서 최종 AIMessage의 tool_calls 유무로 판정:
+                        #   tool_calls 있음 → content는 reasoning → 버림
+                        #   tool_calls 없음 → content는 최종 응답 → emit
+                        self._stream_buffer: list[str] = []
+                        await self._emit_event(
+                            "progress",
+                            {
+                                "message": "LLM 응답 대기 중",
+                                "icon": "thinking",
+                                "turn": self._iteration,
+                                "step": self._tool_count,
+                            },
+                        )
+
+                        # 반복 제한 확인
+                        if self._iteration > self._config.max_iterations:
+                            raise Exception("Maximum iterations reached")
+
+                    # 도구 호출 추적
+                    elif event_kind == "on_tool_start":
+                        tool_name = event.get("name", "unknown")
+                        tool_input = event.get("data", {}).get("input", {})
+                        if not isinstance(tool_input, dict):
+                            tool_input = {}
+                        # 서브에이전트 진입/이탈 추적
+                        if tool_name == "task":
+                            self._inside_subagent = True
+                        self._tool_count += 1
+                        _dbg(
+                            f"TOOL_START: name={tool_name} input_keys={list(tool_input.keys())}",
+                        )
+                        logger.info(
+                            "Tool START: %s, input=%s",
+                            tool_name,
+                            str(tool_input)[:200],
+                        )
+
+                        # 도구별 한국어 상태 메시지 emit
+                        status_msg = _get_tool_status_message(tool_name, tool_input)
+                        await self._emit_event(
+                            "progress",
+                            {
+                                "message": status_msg["status"],
+                                "icon": status_msg.get("icon"),
+                                "turn": self._iteration,
+                                "step": self._tool_count,
+                                "tool_label": status_msg.get("label", tool_name),
+                            },
+                        )
+
+                        await self._emit_event(
+                            "tool_call",
+                            {
+                                "id": event.get("run_id", ""),
+                                "name": tool_name,
+                                "arguments": tool_input,
+                            },
+                        )
+                        self.file_diffs.start(
+                            event.get("run_id", ""), tool_name, tool_input
+                        )
+
+                        # write_todos → 즉시 todos 이벤트 emit (실시간 UI 업데이트)
+                        if tool_name == "write_todos" and isinstance(tool_input, dict):
+                            todos_data = tool_input.get("todos", [])
+                            _dbg(f"WRITE_TODOS detected: {len(todos_data)} items")
+                            if todos_data:
+                                await self._emit_event("todos", {"todos": todos_data})
+                            # Auto-terminate: capture todos data
+                            self._last_todos_data = todos_data
+
+                    # 도구 결과 추적
+                    elif event_kind == "on_tool_end":
+                        tool_name = event.get("name", "unknown")
+                        tool_output = event.get("data", {}).get("output", "")
+                        # 서브에이전트 이탈 추적
+                        if tool_name == "task":
+                            self._inside_subagent = False
+                            # task 도구 반환값 디버그 로깅 — Command에서 실제 ToolMessage 추출
+                            task_content = ""
+                            try:
+                                if hasattr(tool_output, "update"):
+                                    # Command 객체 → update.messages[-1].content
+                                    _msgs = tool_output.update.get("messages", [])
+                                    if _msgs:
+                                        task_content = getattr(
+                                            _msgs[-1],
+                                            "content",
+                                            str(_msgs[-1]),
+                                        )
+                                elif isinstance(tool_output, str):
+                                    task_content = tool_output
+                                else:
+                                    task_content = (
+                                        str(tool_output) if tool_output else "EMPTY"
+                                    )
+                            except Exception as _e:
+                                task_content = f"EXTRACT_ERROR: {_e}"
+                            _dbg(
+                                f"TASK_RESULT: type={type(tool_output).__name__} "
+                                f"content_len={len(task_content)} "
+                                f"has_CODE={'[CODE]' in task_content} "
+                                f"has_DESC={'[DESCRIPTION]' in task_content} "
+                                f"content_preview={task_content[:500]!r}",
+                            )
+
+                        # 에러 여부 파싱
+                        tool_success = True
+                        try:
+                            parsed = (
+                                json.loads(tool_output)
+                                if isinstance(tool_output, str)
+                                else {}
+                            )
+                            if isinstance(parsed, dict):
+                                exec_result = parsed.get("execution_result")
+                                if (
+                                    isinstance(exec_result, dict)
+                                    and exec_result.get("success") is False
+                                ) or parsed.get("success") is False:
+                                    tool_success = False
+                        except (json.JSONDecodeError, TypeError, ValueError):
+                            pass
+
+                        await self._emit_event(
+                            "tool_result",
+                            {
+                                "id": event.get("run_id", ""),
+                                "name": tool_name,
+                                "result": {
+                                    "success": tool_success,
+                                    "data": tool_output,
+                                },
+                            },
+                        )
+
+                        # Auto-terminate: write_todos 완료 체크
+                        if tool_name == "write_todos" and self._last_todos_data:
+                            all_completed = all(
+                                t.get("status") == "completed"
+                                for t in self._last_todos_data
+                                if isinstance(t, dict)
+                            )
+                            if all_completed and self._last_todos_data:
+                                self._all_todos_completed = True
+                                _dbg("ALL_TODOS_COMPLETED: auto-terminate armed")
+
+                        file_diff = self.file_diffs.end(event.get("run_id", ""))
+                        if file_diff:
+                            await self._emit_event("file_diff", file_diff)
+
+                    elif event_kind == "on_tool_error":
+                        self.file_diffs.discard(event.get("run_id", ""))
+
+                    # LLM 턴 종료 - 최종 AIMessage의 tool_calls로 판정
+                    elif event_kind == "on_chat_model_end":
+                        # 서브에이전트 내부 LLM 출력도 로깅 (내용 확인용)
+                        if self._inside_subagent:
+                            _sub_out = event.get("data", {}).get("output", None)
+                            if _sub_out and hasattr(_sub_out, "message"):
+                                _sub_out = _sub_out.message
+                            _sub_content = (
+                                getattr(_sub_out, "content", "") if _sub_out else ""
+                            )
+                            _sub_tc = (
+                                getattr(_sub_out, "tool_calls", []) if _sub_out else []
+                            )
+                            _dbg(
+                                f"SUBAGENT_LLM_END: content_len={len(_sub_content) if isinstance(_sub_content, str) else 'list'} "
+                                f"has_tool_calls={bool(_sub_tc)} "
+                                f"has_CODE={'[CODE]' in _sub_content if isinstance(_sub_content, str) else 'N/A'} "
+                                f"content_preview={repr(_sub_content[:300]) if isinstance(_sub_content, str) else repr(str(_sub_content)[:300])}",
+                            )
+                            continue
+                        output_msg = event.get("data", {}).get("output", None)
+                        # output이 ChatGeneration인 경우 .message에서 추출
+                        if output_msg and hasattr(output_msg, "message"):
+                            output_msg = output_msg.message
+                        has_tool_calls = bool(
+                            output_msg
+                            and hasattr(output_msg, "tool_calls")
+                            and output_msg.tool_calls,
+                        )
+                        turn_elapsed_ms = (
+                            time.monotonic() - self._turn_start_time
+                        ) * 1000
+                        _dbg(
+                            f"LLM_TURN_END: has_tool_calls={has_tool_calls} "
+                            f"buffer_len={len(self._stream_buffer)} "
+                            f"output_msg_type={type(output_msg).__name__ if output_msg else 'None'} "
+                            f"content_preview={repr(''.join(self._stream_buffer)[:200]) if self._stream_buffer else 'empty'}",
+                        )
+                        _dbg(
+                            f"LLM_TURN_METRICS: turn={self._iteration} "
+                            f"elapsed_ms={turn_elapsed_ms:.0f} "
+                            f"est_tokens={self._turn_token_estimate}",
+                        )
+                        # finish_reason 추출 (truncation 감지용)
+                        _finish_reason = None
+                        if output_msg and hasattr(output_msg, "response_metadata"):
+                            _meta = output_msg.response_metadata or {}
+                            _finish_reason = _meta.get("finish_reason") or _meta.get(
+                                "stop_reason",
+                            )
+                        self._truncated_this_turn = False
+
+                        if output_msg:
+                            _dbg(
+                                f"  output_msg attrs: content={repr(getattr(output_msg, 'content', 'N/A'))[:100]} "
+                                f"tool_calls={getattr(output_msg, 'tool_calls', 'N/A')} "
+                                f"finish_reason={_finish_reason}",
+                            )
+
+                        # Summarization 감지
+                        if output_msg and hasattr(output_msg, "additional_kwargs"):
+                            if (output_msg.additional_kwargs or {}).get(
+                                "lc_source",
+                            ) == "summarization":
+                                await self._emit_event(
+                                    "progress",
+                                    {
+                                        "message": "대화가 자동으로 압축되었습니다.",
+                                        "icon": "check",
+                                    },
+                                )
+
+                        if has_tool_calls and output_msg:
+                            logger.info(
+                                "Tool calls: %s",
+                                [
+                                    tc.get("name", "?")
+                                    for tc in getattr(output_msg, "tool_calls", [])
+                                ],
+                            )
+                            # Tool calling 응답의 content 제거:
+                            # 일부 LLM(vLLM/오픈소스)은 tool_calls와 함께 reasoning content를
+                            # 포함하는데, 이 content가 checkpointer에 저장되면 context window를
+                            # 불필요하게 소모함. AIMessage.content를 비워서 방지.
+                            if getattr(output_msg, "content", ""):
+                                old_len = (
+                                    len(output_msg.content)
+                                    if isinstance(output_msg.content, str)
+                                    else len(str(output_msg.content))
+                                )
+                                _dbg(
+                                    f"STRIP_TOOL_CONTENT: removing {old_len} chars from tool-calling AIMessage",
+                                )
+                                try:
+                                    output_msg.content = ""
+                                except (AttributeError, TypeError):
+                                    pass  # immutable인 경우 무시
+                            # Premature summary 필터링: tool_calls 있으면서 summary 패턴도 있으면 스킵
+                            if self._stream_buffer:
+                                buf_check = "".join(self._stream_buffer)
+                                if (
+                                    '"summary"' in buf_check
+                                    and '"next_items"' in buf_check
+                                ):
+                                    non_todo_tools = [
+                                        tc
+                                        for tc in output_msg.tool_calls
+                                        if tc.get("name") not in ("write_todos",)
+                                    ]
+                                    if non_todo_tools:
+                                        _dbg(
+                                            "FILTERED: premature summary with active tool calls",
+                                        )
+                                        self._stream_buffer = []
+
+                        if self._stream_buffer and not has_tool_calls:
+                            # tool_calls 없는 턴 → 최종 응답
+                            buf = "".join(self._stream_buffer)
+                            # assistantfinal 마커가 있으면 그 이후만 추출
+                            if "assistantfinal" in buf:
+                                buf = buf[
+                                    buf.index("assistantfinal")
+                                    + len("assistantfinal") :
+                                ]
+                            # JSON tool response 필터링
+                            if buf:
+                                stripped = buf.strip()
+                                is_json_tool = (
+                                    stripped.startswith('{"tool":')
+                                    or stripped.startswith('{"status":')
+                                    or '"pending_execution"' in stripped
+                                )
+                                if is_json_tool:
+                                    _dbg("FILTERED: JSON tool response")
+                                    buf = ""
+                            # Summary JSON repair + content hash dedup
+                            if buf:
+                                buf = _repair_summary_json_content(buf)
+                                content_hash = hash(buf)
+                                if content_hash not in self._emitted_content_hashes:
+                                    self._emitted_content_hashes.add(content_hash)
+                                    final_response += buf
+                                    await self._emit_event("stream", {"content": buf})
+                                else:
+                                    _dbg(
+                                        f"DEDUP: skipped duplicate content (hash={content_hash})",
+                                    )
+                            # Truncation 감지: finish_reason이 length/max_tokens이면
+                            # done 이벤트를 보내지 않고 continuation을 위해 플래그 설정
+                            if (
+                                _finish_reason in ("length", "max_tokens")
+                                and not self._inside_subagent
+                                and self._truncation_count < _MAX_CONTINUATIONS
+                            ):
+                                self._truncation_count += 1
+                                self._truncated_this_turn = True
+                                _dbg(
+                                    f"TRUNCATION_DETECTED: count={self._truncation_count}, "
+                                    f"finish_reason={_finish_reason}",
+                                )
+                                self._stream_buffer = []
+                                continue  # done/auto-terminate 스킵
+                            # Auto-terminate: summary 감지 후 자동 종료
+                            if self._all_todos_completed and buf:
+                                if '"summary"' in buf and '"next_items"' in buf:
+                                    _dbg(
+                                        "AUTO_TERMINATE: all todos completed + summary detected",
+                                    )
+                                    await self._emit_event("debug_clear", {})
+                                    await self._emit_event(
+                                        "done",
+                                        {"reason": "all_todos_completed"},
+                                    )
+                                    return final_response
+                        elif (
+                            not self._stream_buffer
+                            and not has_tool_calls
+                            and output_msg
+                        ):
+                            # List content 핸들링 (multimodal)
+                            raw_content = getattr(output_msg, "content", "")
+                            if isinstance(raw_content, list):
+                                text_parts = []
+                                for part in raw_content:
+                                    if isinstance(part, str):
+                                        text_parts.append(part)
+                                    elif (
+                                        isinstance(part, dict)
+                                        and part.get("type") == "text"
+                                    ):
+                                        text_parts.append(part.get("text", ""))
+                                buf = "".join(text_parts)
+                            else:
+                                buf = raw_content or ""
+                            if buf:
+                                # 미들웨어(예: ModelRetryMiddleware)가 스트리밍 없이
+                                # 생성한 AIMessage (에러 메시지 등)를 사용자에게 표시
+                                _dbg(f"NON_STREAMED_MSG: {buf[:200]!r}")
+                                content_hash = hash(buf)
+                                if content_hash not in self._emitted_content_hashes:
+                                    self._emitted_content_hashes.add(content_hash)
+                                    final_response += buf
+                                    await self._emit_event("stream", {"content": buf})
+                                else:
+                                    _dbg("DEDUP: skipped duplicate non-streamed msg")
+                        # tool_calls 있는 턴의 content는 reasoning → 버림
+                        self._stream_buffer = []
+
+                    # 콘텐츠 버퍼링 (턴 종료 시 판정)
+                    elif event_kind == "on_chat_model_stream":
+                        # 서브에이전트 내부 LLM 스트리밍은 무시
+                        if self._inside_subagent:
+                            continue
+                        chunk = event.get("data", {}).get("chunk", None)
+                        if chunk and hasattr(chunk, "content") and chunk.content:
+                            self._stream_buffer.append(chunk.content)
+                            self._turn_token_estimate += len(chunk.content) // 4
+                            # Log first chunk of each buffer to verify streaming
+                            if len(self._stream_buffer) == 1:
+                                _dbg(f"STREAM_FIRST_CHUNK: {chunk.content[:100]!r}")
+
+                # async for 종료 후: truncation이 감지되었으면 continuation 주입
+                if self._truncated_this_turn:
+                    if self._truncation_count >= _MAX_CONTINUATIONS:
+                        _dbg(
+                            f"CONTINUATION_LIMIT_REACHED: {self._truncation_count}/{_MAX_CONTINUATIONS}",
+                        )
+                        break
+                    _dbg(
+                        f"CONTINUATION_INJECTING: count={self._truncation_count}/{_MAX_CONTINUATIONS}",
+                    )
+                    await self._emit_event(
+                        "progress",
+                        {
+                            "message": f"응답이 잘려 이어서 생성 중... ({self._truncation_count}/{_MAX_CONTINUATIONS})",
+                            "icon": "spinner",
+                        },
+                    )
+                    # 새 입력으로 astream_events를 재호출하여 START→model 경로를 타게 함.
+                    # aupdate_state + astream_events(None)은 라우팅이 마지막 AIMessage의
+                    # tool_calls를 검사하여 END로 보내므로 LLM이 재호출되지 않음.
+                    _astream_input = {
+                        "messages": [
+                            HumanMessage(
+                                content=(
+                                    "[SYSTEM] 응답이 max_tokens 한도에 도달하여 잘렸습니다. "
+                                    "이전 내용에 이어서 계속 작성하세요. "
+                                    "이전 내용을 반복하지 말고, 잘린 지점부터 이어서 작성하세요."
+                                ),
+                            ),
+                        ],
+                    }
+                    _run_astream = True  # while 루프 재실행
+                    _dbg(f"CONTINUATION_INJECTED: count={self._truncation_count}")
+                    continue  # while 루프의 다음 iteration으로
+
+            # GraphInterrupt 감지: astream_events()는 GraphInterrupt를
+            # raise하지 않으므로, 루프 종료 후 state를 확인하여
+            # 인터럽트 여부를 판정함.
+            _dbg(
+                f"=== ASTREAM LOOP DONE === iterations={self._iteration} final_response_len={len(final_response)}",
+            )
+            state = await self._agent.aget_state(config)
+            _dbg(
+                f"  state.values keys={list(state.values.keys()) if hasattr(state, 'values') else 'N/A'}",
+            )
+            _dbg(
+                f"  state.tasks count={len(state.tasks) if hasattr(state, 'tasks') else 'N/A'}",
+            )
+
+            # 최종 todos state emit (일관성 보장)
+            state_values = state.values if hasattr(state, "values") else {}
+            final_todos = state_values.get("todos", [])
+            if final_todos:
+                serializable = [
+                    {
+                        "content": t["content"] if isinstance(t, dict) else t.content,
+                        "status": t["status"] if isinstance(t, dict) else t.status,
+                    }
+                    for t in final_todos
+                ]
+                await self._emit_event("todos", {"todos": serializable})
+
+            if state.tasks:
+                for task in state.tasks:
+                    if task.interrupts:
+                        hitl_request = task.interrupts[0].value
+                        hitl_event = _transform_interrupt_to_frontend(
+                            hitl_request,
+                            self._thread_id,
+                        )
+                        _dbg(
+                            f"HITL_INTERRUPT: action={hitl_event.get('action')} "
+                            f"args_keys={list(hitl_event.get('args', {}).keys())} "
+                            f"thread_id={hitl_event.get('thread_id')} "
+                            f"actionCount={hitl_event.get('actionCount')}",
+                        )
+                        # HITL interrupt 시 dedup 상태 저장
+                        self._saved_emitted_hashes = self._emitted_content_hashes.copy()
+                        await self._emit_event(
+                            "progress",
+                            {"message": "사용자 승인 대기 중", "icon": "pause"},
+                        )
+                        await self._emit_event("hitl_request", hitl_event)
+                        _dbg("HITL_INTERRUPT: hitl_request event emitted")
+                        return final_response  # "complete" 안 보내고 조기 리턴
+
+            # 인터럽트 없으면 정상 완료
+            await self._emit_event("debug_clear", {})
+
+            # 빈 응답 복구: ModelRetryMiddleware가 에러를 AIMessage로 래핑하여
+            # astream_events에서 스트리밍되지 않은 경우, graph state에서 복원
+            if not final_response and self._iteration > 0:
+                try:
+                    last_messages = state_values.get("messages", [])
+                    if last_messages:
+                        last_msg = last_messages[-1]
+                        last_content = getattr(last_msg, "content", "")
+                        if isinstance(last_content, str) and last_content:
+                            _dbg(
+                                f"EMPTY_RESPONSE_RECOVERY: content={last_content[:200]!r}",
+                            )
+                            final_response = last_content
+                            await self._emit_event("stream", {"content": last_content})
+                except Exception as e:
+                    _dbg(f"EMPTY_RESPONSE_RECOVERY_ERROR: {e}")
+
+            await self._emit_event(
+                "complete",
+                {
+                    "response": final_response,
+                    "iterations": self._iteration,
+                },
+            )
+
+            return final_response
+
+        except asyncio.CancelledError:
+            logger.info("Agent execution cancelled")
+            await self._emit_event(
+                "cancelled",
+                {"message": "작업이 사용자에 의해 중단되었습니다."},
+            )
+            raise
+
+        except Exception as e:
+            logger.error(f"Agent execution error: {e}")
+            await self._emit_event("error", {"error": str(e)})
+            raise
+
+    def cancel(self) -> None:
+        """실행 중인 에이전트 취소."""
+        self._is_cancelled = True
+
+
+def config_from_dict(data: dict[str, Any]) -> AgentConfig:
+    """딕셔너리(프론트엔드 형식)에서 AgentConfig 생성.
+
+    vllm (OpenAI-compatible) provider만 지원.
+
+    Args:
+        data: 프론트엔드의 LLM 설정이 포함된 딕셔너리
+
+    Returns:
+        AgentConfig 인스턴스
+
+    """
+    vllm_config = data.get("vllm", {})
+    api_key = vllm_config.get("apiKey", "")
+    model = vllm_config.get("model", "")
+    base_url = vllm_config.get("endpoint", "").rstrip("/")
+    # OpenAI-compatible endpoints require /v1 suffix
+    if base_url and not base_url.endswith("/v1"):
+        base_url = f"{base_url}/v1"
+
+    return AgentConfig(
+        provider="openai",
+        model=model,
+        api_key=api_key,
+        base_url=base_url,
+        # temperature 는 사용자 설정이 아니다 — AgentConfig 기본값 0.0 고정 (이슈 #171)
+        max_tokens=data.get("maxTokens", 8192),
+        max_iterations=data.get("maxIterations", 20),
+        mode=data.get("mode", "default"),
+        agent_mode=data.get("agentMode", "multi"),
+    )