codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/managers/remote_config.py

@@ -0,0 +1,673 @@
+"""centri 중앙 설정 동기화 (이슈 #113).
+
+설정의 정본은 centri RDS(`codebuff.config_value`)이고, pod 는 agent server 의
+`GET /api/v1/codebuff/config` 로 받아 쓴다. 계약은 `docs/설정RDS/계약.md` 가 정본이다.
+
+- 조직 설정(프롬프트·가드레일·LLM·임베딩·codex 주소 등)은 centri 포털에서 전역 < 팀 <
+  프로젝트 < 사용자 단위로 정하고, centri 가 이 pod 의 팀·프로젝트·사용자에 맞게 해석해
+  내려준다(사용자 층은 이슈 #181).
+- 개인설정은 codebuff 설정 패널에서 고치고, 저장은 centri 의 사용자 행(팀·프로젝트·사용자)
+  이다(`save_user`). 사용자는 centri 가 `KEYCLOAK_ID_TOKEN` 으로 판정한다 — pod 가 보낸
+  사용자 이름을 믿지 않는다. API 키는 어디에도 싣지 않는다(시크릿 env 전용).
+
+- `CODEBUFF_CONFIG_URL` 이 없으면 완전한 no-op 이다 — 오늘과 같다.
+- 데몬 스레드 1개가 주기적으로 받아 **스냅샷**만 교체한다. `ConfigManager` 는 스냅샷을
+  읽을 뿐이라 요청 경로에서 네트워크 I/O 가 없다 — centri 장애가 모든 요청의 타임아웃이
+  되지 않게 하려는 것이다.
+- 실패(연결·타임아웃·4xx/5xx·비JSON·`schema_version` 불일치)는 마지막 성공 스냅샷을
+  유지한다. 성공 이력이 없으면 스냅샷이 없고, pod 파일 값을 그대로 쓴다 — 켜는 스위치는
+  시크릿 키가 아니라 centri 의 첫 200 이다.
+- 인증은 codebuff↔centri 공유 키(`CODEX_SERVER_API_KEY`) 하나를 Bearer 로 보낸다.
+- 검증은 필드 단위다. 타입·범위·허용 목록을 벗어난 필드만 버리고 나머지는 적용한다.
+- 어떤 경우에도 예외를 밖으로 내지 않는다.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from datetime import datetime, timedelta, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence, Tuple
+
+logger = logging.getLogger(__name__)
+
+SCHEMA_VERSION = 1
+REFRESH_INTERVAL_SEC = 60.0
+# 갱신 주기를 줄이는 env — centri 연동 스모크용 (이슈 #237). 1초 밑·숫자 아님은 기본값이다
+REFRESH_ENV = "CODEBUFF_CONFIG_REFRESH_SEC"
+TIMEOUT_SEC = 3.0
+URL_ENV = "CODEBUFF_CONFIG_URL"
+# codebuff↔centri 통신은 공유 키 하나로 인증한다 — codex 게이트웨이와 같은 `codex_api_key`
+# (시크릿 `WDD/WDP-BDP-SCM-CODEBUFF`). centri 도 같은 시크릿에서 읽어 대조한다.
+TOKEN_ENV = "CODEX_SERVER_API_KEY"
+# 사용자 판정용 — centri 가 서명을 검증하고 `preferred_username` 을 사용자로 쓴다.
+USER_TOKEN_ENV = "KEYCLOAK_ID_TOKEN"
+USER_TOKEN_HEADER = "X-Codebuff-User-Token"
+
+# 추론 엔진 — 조직 키 `features.inference_engine` 의 허용값 (이슈 #155).
+# config_manager 가 이 모듈을 import 하므로 순환을 피하려고 여기 둔다.
+INFERENCE_ENGINES = ("codex", "langchain")
+
+_BOTH = INFERENCE_ENGINES
+_LANGCHAIN = ("langchain",)
+_CODEX = ("codex",)
+
+# 프롬프트 키의 정본 — 키마다 (그 키를 읽는 엔진, 어디에 들어가나) (이슈 #208, #218).
+# 기본 설정(`_default_config().prompts`)·서버 허용 목록·설정 화면의 "적용" 표시가 이것에서
+# 나온다. 어느 엔진·자리에서도 안 읽는 키는 여기 둘 수 없다 — 그것이 폐기 기준이다.
+# 키는 기능 단위다: 두 엔진이 같은 기능을 쓰면 같은 키를 읽는다. codex 전용 키는 codex 만의
+# 층(스레드 base·Agent 지시문)뿐이고, langchain 전용 키는 기본 엔진(codex)에서 효과가 없다.
+# 키와 내장 스킬을 가르는 기준 (이슈 #228): 스킬은 두 엔진 모두 요청할 때 읽힌다. 그래서 엔진
+# 고유 규칙·파싱 표식·`{{RESOURCE_CONTEXT}}` 같은 자리표시자·매 턴 규칙·스킬 라우팅 안내는 키에
+# 남기고, 분야에서만 필요하고 엔진 이름 없이 쓸 수 있는 지식은 스킬로 옮긴다. 옮긴 곳은 아래
+# 설명(설정 화면 "적용:")에 스킬 이름으로 적는다.
+PROMPT_KEY_SCOPES: Dict[str, Tuple[Tuple[str, ...], str]] = {
+    "chat_system_prompt": (_BOTH, "채팅 시스템 (사내 자료 검색 끔) — 시스템 프롬프트"),
+    "chat_rag_prompt": (
+        _BOTH,
+        "채팅 시스템 (사내 자료 검색 켬) — 검색 결과 뒤 근거 지시",
+    ),
+    "planner": (_LANGCHAIN, "Agent — 메인 에이전트"),
+    "python_expert": (
+        _LANGCHAIN,
+        "Agent — python_expert 서브에이전트 (품질 원칙은 스킬 python_code_quality)",
+    ),
+    "researcher": (_LANGCHAIN, "Agent — researcher 서브에이전트"),
+    "athena_query": (_LANGCHAIN, "Agent — athena_query 서브에이전트"),
+    "athena_query_prompt": (_BOTH, "Athena 쿼리 패널 — 쿼리 생성(1단계)"),
+    "airflow_expert": (
+        _LANGCHAIN,
+        "Agent — airflow_expert 서브에이전트 (작성 가이드는 스킬 airflow_dag_development)",
+    ),
+    "emr_expert": (_LANGCHAIN, "Agent — emr_expert 서브에이전트"),
+    "lambda_expert": (_LANGCHAIN, "Agent — lambda_expert 서브에이전트"),
+    "spring_expert": (_LANGCHAIN, "Agent — spring_expert 서브에이전트"),
+    "bq_agent": (
+        _LANGCHAIN,
+        "Agent — bq_agent 서브에이전트 (응답 구조는 스킬 bigquery·bigquery_oracle)",
+    ),
+    # 이슈 #178: codex Agent 밖 base 지시문, 사내 플랫폼 규칙(두 엔진 공용)
+    "codex_base_instructions": (_CODEX, "채팅 시스템 — codex 스레드 base 지시문"),
+    "bdp_platform_rules": (_BOTH, "사내 플랫폼 규칙 — 사내 환경에서만 붙는다"),
+    # 이슈 #208: BDP Q&A 본문, 셀 버튼·코드리뷰 템플릿(프론트가 호출마다 받아 쓴다)
+    "chat_qa_system_prompt": (
+        _BOTH,
+        "채팅 시스템 (사내 자료 검색 켬) — 시스템 프롬프트",
+    ),
+    "cell_explain_prompt": (_BOTH, "셀 버튼 설명"),
+    "cell_fix_prompt": (_BOTH, "셀 버튼 수정 — 에러가 있을 때"),
+    "cell_improve_prompt": (_BOTH, "셀 버튼 수정 — 에러가 없을 때(개선 제안)"),
+    "cell_question_prompt": (_BOTH, "셀 버튼 질문"),
+    "review_rules_prompt": (_BOTH, "코드리뷰 — 공통 규칙 (codex `/review` 도)"),
+    "review_security_prompt": (_BOTH, "코드리뷰 — 보안 관점 (codex `/review` 도)"),
+    "review_performance_prompt": (_BOTH, "코드리뷰 — 성능 관점 (codex `/review` 도)"),
+    "review_quality_prompt": (_BOTH, "코드리뷰 — 코드 품질 관점 (codex `/review` 도)"),
+    "review_summary_prompt": (_BOTH, "코드리뷰 — 요약"),
+    # 이슈 #218: 코드 상수였던 프롬프트
+    "answer_format_rules": (_BOTH, "채팅 시스템 — 응답 서식 규칙"),
+    "todo_rules": (_BOTH, "Agent — 할 일 목록(write_todos) 규칙"),
+    "notebook_generation_prompt": (
+        _BOTH,
+        "노트북 생성(/create-notebook) (품질 원칙은 스킬 python_code_quality)",
+    ),
+    "athena_explain_fix_prompt": (_BOTH, "Athena 쿼리 패널 — EXPLAIN 오류 수정(2단계)"),
+    "athena_plan_tuning_prompt": (_BOTH, "Athena 쿼리 패널 — 쿼리 플랜 튜닝(3단계)"),
+    "athena_response_contract": (_BOTH, "Athena 쿼리 패널 — 검색 결과 뒤 응답 형식"),
+    "guide_ingest_markdown_prompt": (_BOTH, "가이드 적재 — 마크다운 구조화"),
+    "guide_chunk_summary_prompt": (_BOTH, "가이드 적재 — 청크 요약"),
+    "codex_agent_instructions": (_CODEX, "Agent — codex developer 지시문"),
+    "codex_agent_base_instructions": (_CODEX, "Agent — codex 스레드 base 지시문"),
+}
+PROMPT_KEYS = tuple(PROMPT_KEY_SCOPES)
+PROMPT_MAX_CHARS = 10_000
+
+# 바꾼 값이 언제 반영되나 (이슈 #218). centri 값은 폴링(60초)으로 들어오고, 그 뒤 이 시점에
+# 읽힌다. 회신 표(`scripts/prompt_key_table.py`)가 이것에서 나오고, 키 집합이
+# `PROMPT_KEYS` 와 같은지는 `backend/tests/test_prompt_keys_218.py` 가 잰다.
+_NEXT_REQUEST = "다음 요청"
+_NEW_SESSION = "새 세션(codex) · 다음 요청(langchain)"
+PROMPT_KEY_APPLY: Dict[str, str] = {
+    "chat_system_prompt": _NEW_SESSION,
+    "chat_rag_prompt": _NEXT_REQUEST,
+    "planner": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "python_expert": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "researcher": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "athena_query": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "athena_query_prompt": _NEXT_REQUEST,
+    "airflow_expert": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "emr_expert": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "lambda_expert": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "spring_expert": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "bq_agent": "다음 요청 (Agent 캐시가 프롬프트를 키로 쓴다)",
+    "codex_base_instructions": "새 스레드·재개 (codex)",
+    "bdp_platform_rules": _NEW_SESSION,
+    "chat_qa_system_prompt": "새 세션(codex) · 새 대화(langchain)",
+    "cell_explain_prompt": "다음 호출 (프론트가 설정을 다시 받은 뒤)",
+    "cell_fix_prompt": "다음 호출 (프론트가 설정을 다시 받은 뒤)",
+    "cell_improve_prompt": "다음 호출 (프론트가 설정을 다시 받은 뒤)",
+    "cell_question_prompt": "다음 호출 (프론트가 설정을 다시 받은 뒤)",
+    "review_rules_prompt": "다음 호출 (셀 리뷰는 프론트가 설정을 다시 받은 뒤, `/review` 는 바로)",
+    "review_security_prompt": "다음 호출 (셀 리뷰는 프론트가 설정을 다시 받은 뒤, `/review` 는 바로)",
+    "review_performance_prompt": "다음 호출 (셀 리뷰는 프론트가 설정을 다시 받은 뒤, `/review` 는 바로)",
+    "review_quality_prompt": "다음 호출 (셀 리뷰는 프론트가 설정을 다시 받은 뒤, `/review` 는 바로)",
+    "review_summary_prompt": "다음 호출 (프론트가 설정을 다시 받은 뒤)",
+    "answer_format_rules": "새 세션(codex) · 다음 요청(langchain, 사내 자료 검색 끔) · 새 대화(langchain, 사내 자료 검색 켬)",
+    "todo_rules": "새 세션(codex) · 다음 요청(langchain)",
+    "notebook_generation_prompt": _NEXT_REQUEST,
+    "athena_explain_fix_prompt": _NEXT_REQUEST,
+    "athena_plan_tuning_prompt": _NEXT_REQUEST,
+    "athena_response_contract": _NEXT_REQUEST,
+    "guide_ingest_markdown_prompt": "다음 적재 작업",
+    "guide_chunk_summary_prompt": "다음 적재 작업",
+    "codex_agent_instructions": "새 세션 (codex)",
+    "codex_agent_base_instructions": "새 스레드·재개 (codex)",
+}
+
+# 옛 이름 → 새 이름 (이슈 #218). centri 가 옛 이름으로 보내거나 pod 파일에 옛 이름이 남아
+# 있으면 새 이름이 비었을 때만 옮긴다 — 새 이름이 있으면 새 이름이 이긴다. 파일은 다시 쓰지 않는다.
+RENAMED_PROMPT_KEYS: Dict[str, str] = {
+    "athena_tuning_prompt": "athena_query_prompt",
+    "python_developer": "python_expert",
+    "mwaa_expert": "airflow_expert",
+}
+
+
+def migrate_renamed_prompts(prompts: Any) -> Any:
+    """`RENAMED_PROMPT_KEYS` 의 옛 이름 값을 새 이름으로 옮긴 사본. dict 가 아니면 그대로."""
+    if not isinstance(prompts, dict):
+        return prompts
+    out = dict(prompts)
+    for old, new in RENAMED_PROMPT_KEYS.items():
+        value = out.pop(old, None)
+        current = out.get(new)
+        if (
+            isinstance(value, str)
+            and value.strip()
+            and not (isinstance(current, str) and current.strip())
+        ):
+            out[new] = value
+    return out
+
+
+# 기본값 원문을 코드 상수로 두지 않는다 (이슈 #208, #218). 정본은 centri 기본값이고, codebuff 의
+# 폴백은 그것을 옮긴 스냅샷 `schemas/config/codebuff_config_defaults.json` 하나뿐이다.
+# 문구를 고치려면 스냅샷을 고친다 — `scripts/dump_config_defaults.py` 는 키를 스냅샷에서
+# 그대로 옮기고, 프론트 폴백(`frontend/utils/featurePromptDefaults.json`)도 거기서 만든다.
+SNAPSHOT_PROMPT_KEYS = PROMPT_KEYS
+# 패키지 안의 이 파일은 스냅샷을 가리키는 심볼릭 링크다 — wheel 에는 내용이 실린다.
+SNAPSHOT_FILE = Path(__file__).resolve().parents[1] / "codebuff_config_defaults.json"
+
+
+@lru_cache(maxsize=1)
+def _snapshot_prompts() -> Dict[str, str]:
+    with open(SNAPSHOT_FILE, encoding="utf-8") as f:
+        return json.load(f)["values"]["prompts"]
+
+
+def snapshot_prompt(key: str) -> str:
+    """스냅샷의 `prompts.<key>` 기본값.
+
+    파일이나 키가 없으면 예외를 그대로 낸다 — 배포물이 깨진 것이라 빈 프롬프트로 조용히
+    도는 것보다 낫다. `backend/tests/test_feature_prompt_defaults.py` 가 있음을 지킨다.
+    """
+    if key not in SNAPSHOT_PROMPT_KEYS:
+        raise KeyError(f"스냅샷이 정본인 프롬프트 키가 아니다: {key}")
+    return _snapshot_prompts()[key]
+
+
+# 사용자가 고르는 값 — 서버는 조직 기본값만 준다. 사용자가 고른 값이 이긴다.
+# `agentEngine` 은 이슈 #138, `temperature` 는 이슈 #171(0.0 고정)에서 폐기했다.
+# 서버가 보내도 모르는 키로 무시한다.
+USER_DEFAULT_KEYS = ("codexPermissionMode", "autoApprove")
+# 개인설정 패널이 저장하는 키 — centri 사용자 행(`user.<키>`)으로 간다.
+USER_KEYS = USER_DEFAULT_KEYS + ("workspaceRoot",)
+
+# 접속 설정 — 서버 > 시크릿 env > pod 파일 > 코드 기본값. 받은 적이 있어도 pod 파일을
+# 버리지 않는다: 로컬 개발 서버는 centri·시크릿 없이 파일로 LLM 에 붙는다.
+# 값은 해당 env 이름이다. API 키는 이 표에 없다 — 키는 env(없으면 pod 파일)만 쓴다.
+CONNECTION_ENV = {
+    "vllm.endpoint": "VLLM_ENDPOINT",
+    "vllm.model": "VLLM_MODEL",
+    "rag.vllmEndpoint": "EMBEDDING_ENDPOINT",
+    "rag.vllmModel": "EMBEDDING_MODEL",
+    "rag.vllmDimension": "EMBEDDING_DIMENSION",
+    "codex.endpoint": "CODEX_SERVER_URL",
+}
+API_KEY_ENV = {
+    "vllm.apiKey": "VLLM_API_KEY",
+    "rag.vllmApiKey": "EMBEDDING_API_KEY",
+    "codex.apiKey": "CODEX_SERVER_API_KEY",
+}
+
+_KST = timezone(timedelta(hours=9))
+_INVALID = object()
+
+
+def _is_int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _bool(value: Any) -> Any:
+    return value if isinstance(value, bool) else _INVALID
+
+
+def _int_range(lo: int, hi: int) -> Callable[[Any], Any]:
+    return lambda v: v if _is_int(v) and lo <= v <= hi else _INVALID
+
+
+def _text(max_chars: int) -> Callable[[Any], Any]:
+    return lambda v: (
+        v if isinstance(v, str) and v.strip() and len(v) <= max_chars else _INVALID
+    )
+
+
+def _choice(choices: tuple) -> Callable[[Any], Any]:
+    return lambda v: v if v in choices else _INVALID
+
+
+def _url(schemes: tuple) -> Callable[[Any], Any]:
+    return lambda v: (
+        v.strip()
+        if isinstance(v, str) and len(v) <= 500 and v.strip().startswith(schemes)
+        else _INVALID
+    )
+
+
+def _connection_schema() -> Dict[str, Callable[[Any], Any]]:
+    http = ("http://", "https://")
+    return {
+        "vllm.endpoint": _url(http),
+        "vllm.model": _text(200),
+        "rag.vllmEndpoint": _url(http),
+        "rag.vllmModel": _text(200),
+        "rag.vllmDimension": _int_range(1, 65_536),
+        "codex.endpoint": _url(("ws://", "wss://")),
+    }
+
+
+def _org_schema() -> Dict[str, Callable[[Any], Any]]:
+    schema: Dict[str, Callable[[Any], Any]] = {
+        f"prompts.{k}": _text(PROMPT_MAX_CHARS) for k in PROMPT_KEYS
+    }
+    schema.update(
+        {
+            "guardrails.enableInput": _bool,
+            "guardrails.enableOutput": _bool,
+            "guardrails.maxInputLength": _int_range(1, 1_000_000),
+            "guardrails.maxCodeLength": _int_range(1, 1_000_000),
+            "idleTimeout": _int_range(60, 86_400),
+            "maxOutputTokens": _int_range(1, 131_072),
+            "rawLlmLogging": _bool,
+            "features.eda_enabled": _bool,
+            "features.bdp_qa_enabled": _bool,
+            # agent 모드 게이트 — env 관리자 판정 대신 이 키를 본다 (이슈 #179)
+            "features.agent_enabled": _bool,
+            "features.inference_engine": _choice(INFERENCE_ENGINES),
+            "rag.enabled": _bool,
+            "rag.collectionName": _text(100),
+        }
+    )
+    return schema
+
+
+def _user_schema() -> Dict[str, Callable[[Any], Any]]:
+    from codebuff_core.managers.config_manager import CODEX_PERMISSION_MODES
+
+    return {
+        "codexPermissionMode": _choice(CODEX_PERMISSION_MODES),
+        "autoApprove": _bool,
+    }
+
+
+def _user_value_schema() -> Dict[str, Callable[[Any], Any]]:
+    """사용자 행 — 조직 기본값 키에 작업 폴더가 더해진다."""
+    schema = _user_schema()
+    schema["workspaceRoot"] = lambda v: (
+        v if isinstance(v, str) and len(v) <= 1000 else _INVALID
+    )
+    return schema
+
+
+# 조직 키 — 한 번이라도 받았으면 pod 파일 값을 쓰지 않는다 (서버 > 코드 기본값).
+ORG_SCHEMA = _org_schema()
+CONNECTION_SCHEMA = _connection_schema()
+
+
+def _flatten(values: Dict[str, Any], prefix: str = "") -> Dict[str, Any]:
+    flat: Dict[str, Any] = {}
+    for key, value in values.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, dict):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = value
+    return flat
+
+
+def _check(
+    values: Dict[str, Any], schema: Dict[str, Callable[[Any], Any]], prefix: str
+):
+    clean: Dict[str, Any] = {}
+    for path, raw in values.items():
+        check = schema.get(path)
+        if check is None:
+            logger.debug("remote config: 모르는 키 무시 %s%s", prefix, path)
+            continue
+        value = check(raw)
+        if value is _INVALID:
+            logger.warning("remote config: 규격 밖 값 무시 %s%s", prefix, path)
+            continue
+        clean[f"{prefix}{path}"] = value
+    return clean
+
+
+def sanitize(values: Any, user: Any = None) -> Dict[str, Any]:
+    """서버 응답을 검증해 통과한 필드만 `{점 경로: 값}` 으로 돌려준다.
+
+    `values` 는 조직 값(팀·프로젝트까지 해석된 것), `user` 는 이 사용자가 저장한 개인설정이다.
+    개인설정은 `user.<키>` 경로로 담긴다.
+    """
+    clean: Dict[str, Any] = {}
+    if isinstance(values, dict):
+        if "prompts" in values:
+            values = {**values, "prompts": migrate_renamed_prompts(values["prompts"])}
+        schema = dict(ORG_SCHEMA)
+        schema.update(CONNECTION_SCHEMA)
+        schema.update({f"userDefaults.{k}": v for k, v in _user_schema().items()})
+        clean.update(_check(_flatten(values), schema, ""))
+    if isinstance(user, dict):
+        clean.update(_check(user, _user_value_schema(), "user."))
+    return clean
+
+
+def sanitize_user(values: Dict[str, Any]) -> Dict[str, Any]:
+    """centri 로 보낼 개인설정 — 허용 키·규격 안의 값만 남긴다."""
+    return {
+        k[len("user.") :]: v
+        for k, v in _check(values, _user_value_schema(), "user.").items()
+    }
+
+
+class RemoteConfigClient:
+    """centri 에서 설정을 받아 스냅샷으로 들고 있는다."""
+
+    def __init__(
+        self,
+        url: str = "",
+        token: str = "",
+        transport: Any = None,
+        refresh_interval: float = REFRESH_INTERVAL_SEC,
+        timeout: float = TIMEOUT_SEC,
+        team: str = "",
+        project: str = "",
+        user_token: str = "",
+        user: str = "",
+    ) -> None:
+        self._url = (url or "").strip()
+        self._token = token or ""
+        # centri 가 조직 값을 전역 < 팀 < 프로젝트로 해석하는 데 쓴다 (이슈 #113)
+        self._scope = {"team": team or "", "project": project or ""}
+        self._user_token = user_token or ""
+        # GET 에만 싣는 로그 대조용 사번 (이슈 #181). 사용자 층은 centri 가 토큰으로 고른다
+        self._user = user or ""
+        self._transport = transport
+        self._interval = refresh_interval
+        self._timeout = timeout
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        # 첫 시도(성공·실패 무관)가 끝나면 선다 — 기동이 이것을 상한 있게 기다린다
+        self._first_attempt = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._snapshot: Optional[Dict[str, Any]] = None
+        self._updated_at: Optional[str] = None
+        self._last_ok_at: Optional[str] = None
+        self._last_error: Optional[str] = None
+        # 공유 키 인증이 막힌 사유 — 키를 통과한 뒤의 실패(500·스키마)는 None 이다 (이슈 #233)
+        self._connection_error: Optional[str] = None
+        self._attempted = False
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self._url)
+
+    @property
+    def started(self) -> bool:
+        return self._thread is not None
+
+    def start(self) -> None:
+        if not self.enabled or self._thread is not None:
+            return
+        self._thread = threading.Thread(
+            target=self._run, name="codebuff-remote-config", daemon=True
+        )
+        self._thread.start()
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self.refresh_now()
+            self._first_attempt.set()
+            self._stop.wait(self._interval)
+
+    def wait_first_attempt(self, timeout: float) -> bool:
+        """스레드의 첫 시도가 끝날 때까지 최대 `timeout` 초 기다린다. 끝났으면 True."""
+        return self._first_attempt.wait(timeout)
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def refresh_now(self) -> bool:
+        """한 번 받아 스냅샷을 교체한다. 성공 여부를 돌려준다. 예외를 내지 않는다."""
+        if not self.enabled:
+            return False
+        try:
+            values, user, updated_at = self._fetch()
+            clean = sanitize(values, user)
+            with self._lock:
+                self._snapshot = clean
+                self._updated_at = updated_at
+                self._last_ok_at = datetime.now(_KST).isoformat(timespec="seconds")
+                self._last_error = None
+                self._connection_error = None
+                self._attempted = True
+            return True
+        except Exception as e:  # noqa: BLE001 — 어떤 실패도 기본값으로 떨어뜨린다
+            with self._lock:
+                self._last_error = f"{type(e).__name__}: {e}"[:300]
+                self._connection_error = _connection_error(e)
+                self._attempted = True
+            logger.warning("remote config 받기 실패 — 마지막 값 유지: %s", e)
+            return False
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Authorization": f"Bearer {self._token}"} if self._token else {}
+        if self._user_token:
+            headers[USER_TOKEN_HEADER] = self._user_token
+        return headers
+
+    def _fetch(self):
+        import httpx
+
+        with httpx.Client(
+            transport=self._transport, timeout=httpx.Timeout(self._timeout)
+        ) as client:
+            resp = client.get(
+                self._url,
+                headers=self._headers(),
+                params={**self._scope, "user": self._user},
+            )
+        resp.raise_for_status()
+        body = resp.json()
+        if not isinstance(body, dict):
+            raise ValueError("응답이 JSON 객체가 아님")
+        version = body.get("schema_version")
+        if version != SCHEMA_VERSION:
+            raise ValueError(f"schema_version 불일치: {version!r}")
+        values = body.get("values")
+        # 빠진 `values` 를 "적용 키 0개" 로 받으면 모든 pod 가 조용히 기본값으로 돌아간다
+        if not isinstance(values, dict):
+            raise ValueError("values 가 JSON 객체가 아님")
+        updated_at = body.get("updated_at")
+        # `user` 는 사용자 토큰이 없거나 저장한 개인설정이 없으면 빠질 수 있다
+        user = body.get("user")
+        return (
+            values,
+            user if isinstance(user, dict) else {},
+            updated_at if isinstance(updated_at, str) else None,
+        )
+
+    @property
+    def can_save_user(self) -> bool:
+        """개인설정을 centri 에 저장할 수 있는가 — 한 번 받았고 사용자 토큰이 있을 때."""
+        return bool(self._user_token) and self.snapshot() is not None
+
+    def save_user(self, set_values: Dict[str, Any], unset: list) -> None:
+        """개인설정을 centri 사용자 행에 쓴다. 실패하면 예외를 낸다 — 저장 실패를 숨기지 않는다.
+
+        사용자는 centri 가 `X-Codebuff-User-Token` 으로 판정한다. 성공하면 스냅샷을 다시 받는다.
+        """
+        import httpx
+
+        body = {**self._scope, "set": set_values, "unset": list(unset)}
+        with httpx.Client(
+            transport=self._transport, timeout=httpx.Timeout(self._timeout)
+        ) as client:
+            resp = client.put(f"{self._url}/user", headers=self._headers(), json=body)
+        resp.raise_for_status()
+        self.refresh_now()
+
+    def snapshot(self) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            return dict(self._snapshot) if self._snapshot is not None else None
+
+    def connection(self) -> Dict[str, Any]:
+        """센트리 연결 한 줄 — 공유 키로 한 인증이 통했는가 (이슈 #233).
+
+        설정 수신이 그 인증 확인을 겸한다. 키를 통과한 뒤의 실패는 연결이 아니라 설정 수신의
+        오류라 `status()` 에만 남는다.
+        """
+        with self._lock:
+            if not self.enabled:
+                return {"state": "error", "reason": "no_url"}
+            if not self._attempted:
+                return {"state": "pending", "reason": None}
+            if self._connection_error is not None:
+                return {"state": "error", "reason": self._connection_error}
+            return {"state": "ok", "reason": None}
+
+    def status(self) -> Dict[str, Any]:
+        with self._lock:
+            if not self.enabled:
+                state = "disabled"
+            elif not self._attempted:
+                state = "pending"
+            elif self._last_error is not None:
+                state = "error"
+            else:
+                state = "ok"
+            return {
+                "state": state,
+                "schemaVersion": SCHEMA_VERSION,
+                # 조직 키만 센다 — 개인설정 행(`user.*`)까지 세면 "적용 키" 가 부풀어 보인다
+                "serverKeys": sum(
+                    1 for k in (self._snapshot or {}) if not k.startswith("user.")
+                ),
+                "updatedAt": self._updated_at,
+                "lastOkAt": self._last_ok_at,
+                "lastError": self._last_error,
+                # centri 가 층을 고르는 신원 — 팀이 비면 team·project 층 값이 안 닿는다 (이슈 #237).
+                # 토큰은 값이 아니라 있는지만 싣는다
+                "scope": {
+                    "team": self._scope["team"],
+                    "project": self._scope["project"],
+                    "userToken": bool(self._user_token),
+                },
+            }
+
+
+def _connection_error(e: Exception) -> Optional[str]:
+    """받기 실패를 연결 사유로 가른다. 키를 통과한 뒤의 실패면 None."""
+    import httpx
+
+    if isinstance(e, httpx.HTTPStatusError):
+        code = e.response.status_code
+        if code in (401, 403):
+            return "key_mismatch"
+        # centri 에 공유 키가 설정되지 않았을 때의 응답
+        if code == 503:
+            return "no_key"
+        return None
+    if isinstance(e, httpx.TransportError):
+        return "unreachable"
+    return None
+
+
+_client: Optional[RemoteConfigClient] = None
+_client_lock = threading.Lock()
+
+
+def get_client() -> RemoteConfigClient:
+    """현재 클라이언트. 아직 없으면 env 로 만든다 (스레드는 띄우지 않는다)."""
+    global _client
+    with _client_lock:
+        if _client is None:
+            _client = _client_from_env()
+        return _client
+
+
+def _client_from_env(
+    team: Optional[str] = None, user_ids: Sequence[str] = ()
+) -> RemoteConfigClient:
+    # 팀·프로젝트는 앞뒤 공백을 뗀다 — centri 포털은 공백을 떼고 층 행을 저장하므로(`_layer`)
+    # " 팀A" 로 물으면 그 팀·프로젝트·사용자 층이 아무것도 안 닿는다 (이슈 #237)
+    return RemoteConfigClient(
+        url=os.environ.get(URL_ENV, ""),
+        token=os.environ.get(TOKEN_ENV, ""),
+        team=(os.environ.get("HDSP_USER_TEAM", "") if team is None else team).strip(),
+        project=os.environ.get("HDSP_PRJ_ID", "").strip(),
+        user_token=os.environ.get(USER_TOKEN_ENV, ""),
+        user=next((u for u in user_ids if u), ""),
+        refresh_interval=_refresh_from_env(),
+    )
+
+
+def _refresh_from_env() -> float:
+    try:
+        value = float(os.environ.get(REFRESH_ENV, ""))
+    except ValueError:
+        return REFRESH_INTERVAL_SEC
+    # 너무 큰 값(inf·1e20)은 `Event.wait` 의 OverflowError 로 갱신 스레드를 죽인다. NaN 은 비교가 거짓이다
+    return value if 1 <= value <= 86400 else REFRESH_INTERVAL_SEC
+
+
+def start_from_env(
+    team: Optional[str] = None, user_ids: Sequence[str] = ()
+) -> RemoteConfigClient:
+    """서버 기동 시 시크릿 주입 뒤에 부른다. env 로 클라이언트를 다시 만들고 띄운다.
+
+    첫 시도를 최대 `TIMEOUT_SEC` 만큼 기다렸다 돌아온다. `ServerIdleMonitor` 가 생성 시
+    `idleTimeout` 을 한 번만 읽으므로, 기다리지 않으면 그 기동 내내 centri 값이 빠진다.
+    `team` 을 주면 env `HDSP_USER_TEAM` 대신 쓴다(JWT 팀 클레임 폴백은 jupyter_ext 가 안다).
+    `user_ids` 는 사번 후보(`team_access.user_ids()`)이고 첫 값을 `user` 로 싣는다.
+    요청 대신 스레드를 기다리는 것은 httpx 타임아웃이 DNS 조회를 덮지 않아서다 — 상한이
+    없으면 DNS 가 매달리는 동안 확장 로드 전체가 멈춘다.
+    """
+    global _client
+    with _client_lock:
+        if _client is None or not _client.started:
+            _client = _client_from_env(team, user_ids)
+            _client.start()
+        client = _client
+    if client.enabled:
+        client.wait_first_attempt(TIMEOUT_SEC)
+    return client
+
+
+def set_client(client: Optional[RemoteConfigClient]) -> None:
+    """테스트용 — 클라이언트를 갈아 끼운다. None 이면 다음 조회 때 env 로 다시 만든다."""
+    global _client
+    with _client_lock:
+        _client = client