codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/managers/config_manager.py

@@ -0,0 +1,690 @@
+"""
+Configuration Manager - Handle extension settings persistence
+
+Singleton manager for configuration persistence across sessions.
+Includes both admin (LLM/server) and user (workspace/preferences) settings.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from codebuff_core.legacy_paths import resolve
+from codebuff_core.managers import remote_config
+
+
+def _is_masked_api_key(value: str) -> bool:
+    """Check if a value looks like a masked API key (e.g., 'sk-o...b459').
+
+    Masked keys are produced by _mask_api_key(): key[:4] + '...' + key[-4:]
+    resulting in 11-char strings, or '***' for short keys.
+    Real API keys are typically 30+ chars and don't contain '...'.
+    """
+    if not isinstance(value, str) or not value:
+        return False
+    if value == "***":
+        return True
+    return "..." in value and len(value) < 20
+
+
+def _strip_masked_keys(incoming: dict, existing: dict) -> dict:
+    """Replace masked API key values in incoming config with existing real values.
+
+    When the frontend sends back masked keys (e.g., 'sk-o...b459'), this function
+    restores the real values from the existing config to prevent data corruption.
+    """
+    import copy
+
+    cleaned = copy.deepcopy(incoming)
+    for key, value in list(cleaned.items()):
+        if isinstance(value, dict):
+            existing_section = existing.get(key, {})
+            if isinstance(existing_section, dict):
+                # Restore real apiKey if incoming is masked
+                # (rag.vllmApiKey 처럼 `...ApiKey` 로 끝나는 키도 가려서 나간다 — 이슈 #113)
+                for field in [
+                    f for f in value if f == "apiKey" or f.endswith("ApiKey")
+                ]:
+                    if not _is_masked_api_key(value[field]):
+                        continue
+                    if field in existing_section and not _is_masked_api_key(
+                        existing_section[field]
+                    ):
+                        value[field] = existing_section[field]
+                    else:
+                        del value[field]
+                # Restore real keys in keys array (e.g., keys[].key)
+                if "keys" in value and isinstance(value["keys"], list):
+                    existing_keys = existing_section.get("keys", [])
+                    existing_keys_by_id = {
+                        k.get("id"): k
+                        for k in existing_keys
+                        if isinstance(k, dict) and "id" in k
+                    }
+                    for item in value["keys"]:
+                        if (
+                            isinstance(item, dict)
+                            and "key" in item
+                            and _is_masked_api_key(item["key"])
+                        ):
+                            existing_item = existing_keys_by_id.get(item.get("id"))
+                            if (
+                                existing_item
+                                and "key" in existing_item
+                                and not _is_masked_api_key(existing_item["key"])
+                            ):
+                                item["key"] = existing_item["key"]
+        elif key == "apiKey" and _is_masked_api_key(value):
+            if key in existing and not _is_masked_api_key(existing[key]):
+                cleaned[key] = existing[key]
+            else:
+                del cleaned[key]
+    return cleaned
+
+
+# codex 권한 모드의 허용값 (이슈 #88). 에이전트 엔진 선택은 이슈 #138 에서 지웠다 —
+# 어느 엔진으로 보낼지는 패널의 모드 드롭다운이 정한다.
+CODEX_PERMISSION_MODES = ("ask", "bypass")
+# 아무것도 안 고른 사용자의 권한 모드 — ask 였다가 이슈 #180 에서 bypass 로 바꿨다.
+# 사용자가 ask 를 골라 저장했으면 그 값이 이긴다. centri 사본은
+# `schemas/config/codebuff_config_defaults.json`(scripts/dump_config_defaults.py)로 따라간다.
+DEFAULT_CODEX_PERMISSION_MODE = "bypass"
+
+# 추론 엔진 — centri 전역 설정 `features.inference_engine` (이슈 #155).
+# Chat(사내 검색 포함, #183)·Agent·노트북 자동생성·EDA Agent 가 이 값 하나를 따른다.
+# langchain 이면 Agent 는 deepagents, 나머지는 RAGChatAgent 로 돈다.
+INFERENCE_ENGINES = remote_config.INFERENCE_ENGINES
+DEFAULT_INFERENCE_ENGINE = "codex"
+
+# agent 모드 게이트 — centri 조직 키 `features.agent_enabled` (이슈 #179).
+# 값이 없으면 켜짐이다 (이슈 #236) — Agent 는 기본으로 보이고, centri 가 명시적으로
+# false 를 보낼 때만 닫힌다(조직 끄기 스위치).
+DEFAULT_AGENT_ENABLED = True
+
+
+def _coerce_choice(value: Any, choices: tuple, default: str) -> str:
+    """열거형 설정을 읽을 때 허용값 밖이면 기본값으로 떨어뜨린다."""
+    return value if value in choices else default
+
+
+class ConfigManager:
+    """Manage configuration persistence"""
+
+    _instance = None
+    _config_file = None
+
+    def __init__(self):
+        try:
+            # 1순위: 환경변수
+            jupyter_config_dir = os.environ.get("JUPYTER_CONFIG_DIR")
+
+            # 2순위: 홈 디렉토리 ~/.jupyter
+            if not jupyter_config_dir:
+                # expanduser가 실패할 경우를 대비
+                try:
+                    jupyter_config_dir = os.path.expanduser("~/.jupyter")
+                except Exception:
+                    jupyter_config_dir = None
+
+            # 경로가 유효한지 체크하고, 없으면 생성 시도
+            if jupyter_config_dir:
+                config_path = Path(jupyter_config_dir)
+                try:
+                    config_path.mkdir(parents=True, exist_ok=True)
+                    self._config_file = resolve(
+                        config_path / "codebuff_config.json",
+                        config_path / "hdsp_agent_config.json",
+                    )
+                except Exception as e:
+                    print(f"Warning: Cannot write to {jupyter_config_dir}: {e}")
+                    self._config_file = None
+
+            # 3순위 (비상용): 쓰기 실패했거나 경로가 없으면 /tmp 사용
+            if not self._config_file:
+                tmp_dir = Path(tempfile.gettempdir()) / "jupyter_codebuff"
+                tmp_dir.mkdir(parents=True, exist_ok=True)
+                self._config_file = tmp_dir / "codebuff_config.json"
+                print(f"Using temporary config path: {self._config_file}")
+
+        except Exception as e:
+            # 최악의 경우: 메모리에서만 동작하도록 가짜 경로 설정 (서버 다운 방지)
+            print(f"Critical Error in ConfigManager init: {e}")
+            self._config_file = Path("/tmp/codebuff_config_fallback.json")
+
+        self._config = self._load_config()
+
+    @classmethod
+    def get_instance(cls):
+        """Get singleton instance"""
+        if cls._instance is None:
+            cls._instance = ConfigManager()
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls):
+        """Reset singleton instance (for testing)"""
+        cls._instance = None
+
+    def _load_config(self) -> Dict[str, Any]:
+        """Load configuration from file"""
+        if not self._config_file.exists():
+            return self._default_config()
+
+        try:
+            with open(self._config_file, "r") as f:
+                loaded = json.load(f)
+                # Merge with defaults to ensure all keys exist
+                defaults = self._default_config()
+                defaults.update(loaded)
+                # 옛 프롬프트 키 이름은 새 이름으로 읽는다 (이슈 #218). 파일은 다시 쓰지 않는다
+                defaults["prompts"] = remote_config.migrate_renamed_prompts(
+                    defaults.get("prompts")
+                )
+                self._migrate_legacy_providers(defaults)
+                self._sanitize_masked_keys(defaults)
+                return defaults
+        except (json.JSONDecodeError, IOError) as e:
+            print(f"Error loading config: {e}")
+            return self._default_config()
+
+    def _migrate_legacy_providers(self, config: Dict[str, Any]):
+        """Auto-migrate gemini/openai provider to vllm."""
+        changed = False
+        if config.get("provider") in ("gemini", "openai"):
+            config["provider"] = "vllm"
+            changed = True
+        for key in ("gemini", "openai"):
+            if key in config:
+                del config[key]
+                changed = True
+        summ = config.get("summarization")
+        if isinstance(summ, dict) and summ.get("provider") in ("gemini", "openai"):
+            summ["provider"] = "vllm"
+            changed = True
+        if changed:
+            self._persist(config)
+
+    def _sanitize_masked_keys(self, config: Dict[str, Any]):
+        """마스킹된 API 키를 빈 문자열로 교체하고 파일에 반영."""
+        changed = False
+        for section_key in ("vllm", "summarization", "embedding"):
+            section = config.get(section_key)
+            if isinstance(section, dict):
+                api_key = section.get("apiKey", "")
+                if _is_masked_api_key(api_key):
+                    section["apiKey"] = ""
+                    changed = True
+        if changed:
+            print(
+                "[ConfigManager] WARNING: 마스킹된 API 키가 감지되어 제거되었습니다. "
+                "설정에서 API 키를 다시 입력하세요."
+            )
+            self._persist(config)
+
+    def _persist(self, config: Dict[str, Any]):
+        """Write config dict to file."""
+        try:
+            self._config_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self._config_file, "w") as f:
+                json.dump(config, f, indent=2)
+        except IOError as e:
+            print(f"Warning: Failed to persist migrated config: {e}")
+
+    def _default_config(self) -> Dict[str, Any]:
+        """Get default configuration (merged admin + user schema)"""
+        return {
+            # LLM Provider Settings
+            "provider": "vllm",
+            "vllm": {
+                "endpoint": "https://openrouter.ai/api/v1",
+                "apiKey": "",
+                "model": "openai/gpt-oss-120b",
+            },
+            # Summarization LLM
+            "summarization": {
+                "enabled": False,
+                "provider": "vllm",
+                "model": None,
+                "endpoint": "",
+                "apiKey": "",
+            },
+            # Embedding
+            "embedding": {
+                "provider": "openai",
+                "model": "text-embedding-3-small",
+                "apiKey": "",
+                "endpoint": "",
+            },
+            # RAG
+            "rag": {
+                "enabled": True,
+                "knowledgeBasePath": None,
+                "qdrantMode": "local",
+                "qdrantUrl": "http://localhost:6333",
+                "qdrantPath": None,
+                "collectionName": "hdsp_docs",
+                "embeddingBackend": "vllm",
+                "vllmEndpoint": "http://localhost:8000",
+                "vllmModel": "qwen3-embedding-8b",
+                "vllmDimension": 4096,
+                "vllmApiKey": "",
+            },
+            # Server Settings
+            "idleTimeout": 3600,
+            "maxOutputTokens": 4096,
+            # Prompts (None = use defaults)
+            # 키 목록의 정본은 remote_config.PROMPT_KEYS (이슈 #113)
+            "prompts": {k: None for k in remote_config.PROMPT_KEYS},
+            # Guardrails
+            "guardrails": {
+                "enableInput": True,
+                "enableOutput": True,
+                "maxInputLength": 50000,
+                "maxCodeLength": 10000,
+            },
+            # Logging
+            "rawLlmLogging": False,
+            # User Settings
+            "workspaceRoot": "",
+            "autoApprove": False,
+            "codexPermissionMode": DEFAULT_CODEX_PERMISSION_MODE,
+            "codex": {
+                "endpoint": "",
+                "apiKey": "",
+            },
+        }
+
+    def get_config(self) -> Dict[str, Any]:
+        """Get current configuration"""
+        # Reload config from file to ensure we have the latest
+        self._config = self._load_config()
+        return self._effective(self._config)
+
+    def _effective(self, base: Dict[str, Any]) -> Dict[str, Any]:
+        """pod 파일 층(`base`)에 centri 중앙 설정을 얹은 사본 (이슈 #113).
+
+        `self._config` 는 파일 층 그대로 둔다 — 저장할 때 서버 값이 파일로 새지 않게.
+        URL 이 없거나 한 번도 받지 못했으면 오늘과 같다(pod 파일). 한 번이라도 받았으면
+        조직 키는 서버 > 코드 기본값이다(파일 무시). 켜는 스위치가 시크릿 키가 아니라
+        centri 수신부의 첫 200 이라서, 수신부가 없는 동안 pod 파일 값이 사라지지 않는다.
+        """
+        cfg = copy.deepcopy(base)
+        user_set = cfg.pop("_userSet", None)
+        snap = remote_config.get_client().snapshot()
+        _apply_connection(cfg, snap)
+        if snap is None:
+            return cfg
+        defaults = self._default_config()
+        for path in remote_config.ORG_SCHEMA:
+            if path in snap:
+                _set_path(cfg, path, snap[path])
+            else:
+                found, value = _get_path(defaults, path)
+                if found:
+                    _set_path(cfg, path, value)
+                else:
+                    _del_path(cfg, path)
+        chosen = set(user_set) if isinstance(user_set, list) else set()
+        for key in remote_config.USER_KEYS:
+            # 개인설정(centri 사용자 행) > pod 파일에서 고른 값 > 조직 기본값
+            for path in (f"user.{key}", f"userDefaults.{key}"):
+                if path not in snap:
+                    continue
+                if path.startswith("userDefaults.") and key in chosen:
+                    break
+                cfg[key] = snap[path]
+                break
+        return cfg
+
+    def save_config(self, config: Dict[str, Any]):
+        """Save configuration to file - no validation"""
+        # Strip masked API keys to prevent overwriting real keys
+        config = _strip_masked_keys(config, self._config)
+        config = self._keep_file_org_values(config)
+        # Merge with existing config
+        self._config.update(config)
+
+        # Ensure config directory exists
+        self._config_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write to file
+        try:
+            with open(self._config_file, "w") as f:
+                json.dump(self._config, f, indent=2)
+        except IOError as e:
+            raise RuntimeError(f"Failed to save config: {e}")
+
+    def _keep_file_org_values(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """서버·env 가 정하는 키는 파일 값으로 되돌려 저장한다 (이슈 #113).
+
+        `get_config()` 사본을 통째로 저장하는 경로(RAG 관리자 등)가 서버 값을 파일에
+        쓰면, URL 을 지우고 재기동해도 옛 값으로 돌아가지 못한다. 사용자 기본값도
+        같다 — 사용자가 고른 값은 `update_user_config` 가 따로 쓴다. 접속 설정은 URL 이
+        없어도 env 가 얹히므로 늘 되돌린다 — 안 그러면 시크릿 API 키가 파일에 남는다.
+        """
+        if config is self._config:
+            return config
+        config = copy.deepcopy(config)
+        paths = list(remote_config.CONNECTION_ENV) + list(remote_config.API_KEY_ENV)
+        if remote_config.get_client().enabled:
+            paths += list(remote_config.ORG_SCHEMA) + list(remote_config.USER_KEYS)
+        for path in paths:
+            top = path.split(".", 1)[0]
+            if top not in config:
+                continue
+            found, value = _get_path(self._config, path)
+            if found:
+                _set_path(config, path, copy.deepcopy(value))
+            else:
+                _del_path(config, path)
+                if config.get(top) == {} and top not in self._config:
+                    del config[top]
+        return config
+
+    def get(self, key: str, default=None):
+        """Get specific config value"""
+        return self._effective(self._config).get(key, default)
+
+    def set(self, key: str, value: Any):
+        """Set specific config value"""
+        self._config[key] = value
+        self.save_config(self._config)
+
+    def update_config(self, updates: Dict[str, Any]):
+        """Update configuration with partial updates (deep merge for nested dicts)"""
+        # Strip masked API keys to prevent overwriting real keys
+        updates = _strip_masked_keys(updates, self._config)
+        for key, value in updates.items():
+            if (
+                key in self._config
+                and isinstance(self._config[key], dict)
+                and isinstance(value, dict)
+            ):
+                self._config[key].update(value)
+            else:
+                self._config[key] = value
+        self.save_config(self._config)
+
+    def get_codex_settings(self) -> Dict[str, str]:
+        """codex 접속 설정 — 주소는 centri > env > 설정 파일, 키는 env > 설정 파일 (이슈 #88·#113).
+
+        endpoint 가 빈 문자열이면 codex 엔진을 쓸 수 없는 상태다.
+        """
+        codex = self.get_config().get("codex")
+        if not isinstance(codex, dict):
+            return {"endpoint": "", "apiKey": ""}
+        return {
+            "endpoint": codex.get("endpoint", "") or "",
+            "apiKey": codex.get("apiKey", "") or "",
+        }
+
+    def get_inference_engine(self) -> str:
+        """전역 추론 엔진 — 값이 없거나 허용값 밖이면 codex (이슈 #155)."""
+        features = self.get_config().get("features")
+        value = features.get("inference_engine") if isinstance(features, dict) else None
+        return _coerce_choice(value, INFERENCE_ENGINES, DEFAULT_INFERENCE_ENGINE)
+
+    def get_agent_enabled(self) -> bool:
+        """agent 모드 실효값 — centri > (못 받았으면) pod 파일 > 기본값 (이슈 #179)."""
+        features = self.get_config().get("features")
+        value = features.get("agent_enabled") if isinstance(features, dict) else None
+        return value if isinstance(value, bool) else DEFAULT_AGENT_ENABLED
+
+    def get_user_config(self) -> Dict[str, Any]:
+        """Get user configuration (workspace, autoApprove, codex 권한). temperature 는 0.0 고정 (이슈 #171)."""
+        config = self.get_config()
+        return {
+            "workspaceRoot": config.get("workspaceRoot", ""),
+            "autoApprove": config.get("autoApprove", False),
+            "codexPermissionMode": _coerce_choice(
+                config.get("codexPermissionMode"),
+                CODEX_PERMISSION_MODES,
+                DEFAULT_CODEX_PERMISSION_MODE,
+            ),
+        }
+
+    def update_user_config(self, updates: Dict[str, Any]):
+        """Update user configuration (only allowed fields)."""
+        allowed_fields = {
+            "workspaceRoot",
+            "autoApprove",
+            "codexPermissionMode",
+        }
+        # 열거형 필드는 값까지 본다 — 화이트리스트만 보면 오타가 그대로 저장돼
+        # 읽는 쪽이 매번 폴백을 해야 한다 (이슈 #88).
+        enum_fields = {
+            "codexPermissionMode": CODEX_PERMISSION_MODES,
+        }
+        filtered_updates = {
+            k: v
+            for k, v in updates.items()
+            if k in allowed_fields and (k not in enum_fields or v in enum_fields[k])
+        }
+        if not filtered_updates:
+            return
+        client = remote_config.get_client()
+        if client.can_save_user:
+            self._save_user_remote(client, filtered_updates)
+            return
+        self._track_user_choices(filtered_updates)
+        self.update_config(filtered_updates)
+
+    def _save_user_remote(self, client, updates: Dict[str, Any]):
+        """개인설정을 centri 사용자 행에 쓴다 (이슈 #113). 실패는 예외로 올린다.
+
+        조직 기본값과 같은 값은 행을 지운다 — 패널은 모든 칸을 보내므로, 그대로 두면 한 번
+        저장한 사용자는 조직 기본값이 바뀌어도 영영 못 받는다. 저장한 키는 pod 파일의
+        `_userSet` 에서 뺀다: 서버 행을 지웠을 때 파일의 옛 선택이 되살아나지 않게.
+        """
+        values = remote_config.sanitize_user(updates)
+        baseline = self._org_user_defaults()
+        set_values = {k: v for k, v in values.items() if v != baseline.get(k)}
+        unset = [k for k in values if k not in set_values]
+        client.save_user(set_values, unset)
+        # 저장한 키는 pod 파일 값도 코드 기본값으로 되돌린다. 조직 기본값과 같은 값을 골라
+        # 서버 행을 지웠는데 스냅샷에 `userDefaults.<키>` 가 없으면, 파일의 옛 값이 다시 보인다.
+        defaults = self._default_config()
+        changed = False
+        for key in values:
+            if key in defaults and self._config.get(key) != defaults[key]:
+                self._config[key] = defaults[key]
+                changed = True
+            elif key not in defaults and key in self._config:
+                del self._config[key]
+                changed = True
+        chosen = self._config.get("_userSet")
+        if isinstance(chosen, list) and set(chosen) & set(values):
+            self._config["_userSet"] = sorted(set(chosen) - set(values))
+            changed = True
+        if changed:
+            self.save_config(self._config)
+
+    def describe_sources(self) -> List[Dict[str, Any]]:
+        """설정 화면 "센트리에서 받은 설정" 의 행 — 허용 목록 키의 실효값과 출처 (이슈 #183).
+
+        출처는 `portal`(centri) · `env` · `file`(pod 파일) · `default`(코드 기본값) 중 하나이고
+        `_effective` 의 우선순위를 그대로 따른다. API 키 경로는 허용 목록에 없다.
+        프롬프트는 본문 대신 글자 수를 싣고, 정한 것만 싣는다 — 안 정한 것은 스냅샷 기본값
+        (`codebuff_config_defaults.json`)이다 (이슈 #218).
+        프롬프트 행에는 그 키를 읽는 엔진·자리(`appliesTo`)를 붙인다 (이슈 #208).
+        """
+        base = self._load_config()
+        snap = remote_config.get_client().snapshot()
+        effective = self._effective(base)
+        defaults = self._default_config()
+        rows: List[Dict[str, Any]] = []
+        for path in list(remote_config.CONNECTION_ENV) + list(remote_config.ORG_SCHEMA):
+            connection = path in remote_config.CONNECTION_ENV
+            if snap is not None and path in snap:
+                source = "portal"
+            elif connection and _connection_env(path) is not None:
+                source = "env"
+            elif (snap is None or connection) and _in_file(base, defaults, path):
+                source = "file"
+            else:
+                source = "default"
+            _, value = _get_path(effective, path)
+            if path in _FEATURE_EFFECTIVE:
+                # 안 정한 기능 키는 부르는 쪽이 기본값을 채운다 — 표도 그 값을 보인다
+                value = _FEATURE_EFFECTIVE[path](self)
+            if path.startswith("prompts."):
+                if not isinstance(value, str) or not value.strip():
+                    continue
+                # 옛 프론트가 파일에 남긴 로딩 문구는 값이 아니다 (configured_prompt 와 같은 판정)
+                if value == "(프롬프트를 불러오는 중...)":
+                    continue
+                value = len(value)
+                engines, where = remote_config.PROMPT_KEY_SCOPES[
+                    path[len("prompts.") :]
+                ]
+                rows.append(
+                    {
+                        "key": path,
+                        "value": value,
+                        "source": source,
+                        # 이 키를 읽는 엔진·자리 — 화면이 현재 엔진과 대조한다 (이슈 #208)
+                        "appliesTo": {"engines": list(engines), "where": where},
+                    }
+                )
+                continue
+            rows.append({"key": path, "value": value, "source": source})
+        return rows
+
+    def _org_user_defaults(self) -> Dict[str, Any]:
+        """개인설정 칸마다 사용자가 아무것도 안 골랐을 때 보이는 값."""
+        snap = remote_config.get_client().snapshot() or {}
+        defaults = self._default_config()
+        return {
+            key: snap.get(f"userDefaults.{key}", defaults.get(key))
+            for key in remote_config.USER_KEYS
+        }
+
+    def _track_user_choices(self, updates: Dict[str, Any]):
+        """조직 기본값과 다른 값을 고른 키만 `_userSet` 에 남긴다 (이슈 #113).
+
+        패널은 필드를 한꺼번에 저장하므로 "저장했다" 가 곧 "골랐다" 가 아니다. 손대지
+        않은 값까지 고정하면 조직 기본값이 바뀌어도 그 사용자에게는 영영 안 닿는다.
+        """
+        snap = remote_config.get_client().snapshot() or {}
+        defaults = self._default_config()
+        chosen = self._config.get("_userSet")
+        chosen = set(chosen) if isinstance(chosen, list) else set()
+        for key in remote_config.USER_DEFAULT_KEYS:
+            if key not in updates:
+                continue
+            baseline = snap.get(f"userDefaults.{key}", defaults.get(key))
+            if updates[key] == baseline:
+                chosen.discard(key)
+            else:
+                chosen.add(key)
+        self._config["_userSet"] = sorted(chosen)
+
+
+def _apply_connection(cfg: Dict[str, Any], snap: Optional[Dict[str, Any]]):
+    """접속 설정을 얹는다 — 주소·모델은 centri > env > pod 파일, API 키는 env > pod 파일.
+
+    API 키는 centri 로도 관리 화면으로도 오지 않는다. 시크릿 env 가 유일한 운영 경로다.
+    """
+    for path in remote_config.CONNECTION_ENV:
+        if snap is not None and path in snap:
+            _set_path(cfg, path, snap[path])
+            continue
+        value = _connection_env(path)
+        if value is not None:
+            _set_path(cfg, path, value)
+    for path, env in remote_config.API_KEY_ENV.items():
+        raw = os.environ.get(env, "")
+        if raw:
+            _set_path(cfg, path, raw)
+
+
+def _connection_env(path: str) -> Any:
+    """접속 키의 env 값 — 비었거나 규격 밖(차원이 숫자가 아님)이면 None."""
+    raw = os.environ.get(remote_config.CONNECTION_ENV[path], "").strip()
+    if not raw:
+        return None
+    if path == "rag.vllmDimension":
+        return int(raw) if raw.isdigit() else None
+    return raw
+
+
+def _in_file(base: Dict[str, Any], defaults: Dict[str, Any], path: str) -> bool:
+    """파일이 이 키를 기본값과 다르게 정했는가. 파일에 없는 키는 파일 출처가 아니다."""
+    found, value = _get_path(base, path)
+    return found and (found, value) != _get_path(defaults, path)
+
+
+# 기본값이 `_default_config()` 가 아니라 게터에 있는 기능 키 (이슈 #183)
+_FEATURE_EFFECTIVE = {
+    "features.eda_enabled": lambda cm: _feature(cm, "eda_enabled") is not False,
+    "features.bdp_qa_enabled": lambda cm: _feature(cm, "bdp_qa_enabled") is not False,
+    "features.agent_enabled": lambda cm: cm.get_agent_enabled(),
+    "features.inference_engine": lambda cm: cm.get_inference_engine(),
+}
+
+
+def _feature(cm: "ConfigManager", key: str) -> Any:
+    features = cm.get_config().get("features")
+    return features.get(key) if isinstance(features, dict) else None
+
+
+def _get_path(cfg: Dict[str, Any], path: str):
+    node: Any = cfg
+    for part in path.split("."):
+        if not isinstance(node, dict) or part not in node:
+            return False, None
+        node = node[part]
+    return True, node
+
+
+def _set_path(cfg: Dict[str, Any], path: str, value: Any):
+    *parents, leaf = path.split(".")
+    node = cfg
+    for part in parents:
+        if not isinstance(node.get(part), dict):
+            node[part] = {}
+        node = node[part]
+    node[leaf] = value
+
+
+def _del_path(cfg: Dict[str, Any], path: str):
+    *parents, leaf = path.split(".")
+    node: Any = cfg
+    for part in parents:
+        node = node.get(part) if isinstance(node, dict) else None
+    if isinstance(node, dict):
+        node.pop(leaf, None)
+
+
+def get_config_manager() -> ConfigManager:
+    """Get the singleton ConfigManager instance"""
+    return ConfigManager.get_instance()
+
+
+def configured_prompt(key: str) -> str:
+    """관리자가 정한 `prompts.<key>` (centri > pod 파일). 없으면 빈 문자열 (이슈 #178).
+
+    빈 문자열이면 부르는 쪽이 스냅샷 기본값을 쓴다(`prompt_value`). 프롬프트 조립을 설정 오류로 막지 않는다.
+    """
+    try:
+        value = get_config_manager().get_config().get("prompts", {}).get(key)
+    except Exception:
+        return ""
+    if not isinstance(value, str) or not value.strip():
+        return ""
+    # 옛 프론트가 파일에 남긴 로딩 문구는 값이 아니다 (agent_factory 와 같은 판정)
+    return "" if value == "(프롬프트를 불러오는 중...)" else value
+
+
+def prompt_value(key: str) -> str:
+    """`prompts.<key>` 의 실효값 — 관리자 값(centri > pod 파일), 없으면 스냅샷 기본값 (이슈 #218).
+
+    코드 상수 폴백은 없다. 기본값의 정본은 centri 이고 codebuff 는 그것을 옮긴
+    `codebuff_config_defaults.json` 만 들고 있다.
+    """
+    return configured_prompt(key) or remote_config.snapshot_prompt(key)