codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/managers/remote_skills.py

@@ -0,0 +1,539 @@
+"""centri 커스텀 스킬 동기화 (이슈 #134).
+
+스킬의 정본은 centri RDS(`codebuff.custom_skill`)이고, centri 포털에서 편집한다. pod 는
+agent server 의 `GET /api/v1/codebuff/skills` 로 받아 동기화 디렉터리
+`<codebuff 홈>/skills/<scope>/<name>/SKILL.md` 로 내려쓴다. 에이전트는 그 파일을 로컬
+스킬과 같은 규칙으로 읽는다(`jupyter_ext/agent/custom_skills.py`). 계약은
+`docs/스킬RDS/계약.md` 가 정본이다.
+
+- `CODEBUFF_SKILLS_URL` 이 없으면 완전한 no-op 이다. 공유 키가 있는 pod 는 시크릿
+  부트스트랩이 클러스터 주소로 채운다.
+- 기동 때 한 번, 그 뒤 300초마다 받는다. 기동은 기다리지 않는다 — 스킬은 설정과 달리
+  기동 시점에 한 번만 읽는 값이 없고, 다음 에이전트 생성부터 쓰이면 된다.
+- 200 을 받으면 받은 목록이 곧 디렉터리의 상태다. 빠진 스킬은 지운다 — 단 `SYNC_SCOPES`
+  네 디렉터리 바로 아래의 스킬 디렉터리만 지운다. 사람이 만든 스킬 디렉터리와 섞지 않는다.
+- 받기 실패(연결·타임아웃·4xx/5xx·비JSON·`schema_version` 불일치)는 파일을 그대로 둔다.
+  마지막으로 받은 스킬이 계속 쓰인다. 쓰는 도중의 디스크 오류는 그 회차를 멈춘다 — 쓰기를
+  지우기보다 먼저 하므로 옛 스킬이 남는 쪽이고, 다음 회차가 다시 맞춘다.
+- 항목 단위로 검증한다. 남의 `scope_key`·규격 밖 이름·빈 설명·상한 넘는 본문은 그 항목만
+  버린다.
+- 어떤 경우에도 예외를 밖으로 내지 않는다.
+
+로컬 스킬 보고 (이슈 #182): 같은 스레드가 주기마다 pod 가 찾은 로컬 스킬 목록을
+`POST <CODEBUFF_SKILLS_URL>/local` 로 보낸다. 지난 성공 보고와 같으면 보내지 않는다.
+본문의 `host` 는 `socket.gethostname()`(k8s 에서는 pod 이름)이다 (이슈 #204).
+centri 수신부가 아직 없을 수 있어(404) 실패는 debug 로그와 `status()["report"]` 로만
+남기고, 다음 주기에 다시 보낸다.
+
+도구 정의 보고 (이슈 #248): 같은 본문 최상위 `tools[]` 에 에이전트가 모델에 넘기는 도구
+정의(엔진별 이름·설명·입력 스키마·승인 여부)를 싣는다. centri(lks21c/centri#1846)는 규격
+밖 항목을 그 항목만 버리므로, 여기서 먼저 계약에 맞춘다(`clean_tools`). 목록을 만들지
+못하면 `tools` 키를 뺀다 — 빈 배열은 "도구 0개" 로 읽힌다.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import socket
+import threading
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+from codebuff_core.legacy_paths import resolve_home
+
+logger = logging.getLogger(__name__)
+
+SCHEMA_VERSION = 1
+REFRESH_INTERVAL_SEC = 300.0
+# 본문이 수십 KB 라 설정(3초)보다 길게 준다. 기동을 기다리게 하지 않으므로 길어도 무해하다
+TIMEOUT_SEC = 10.0
+URL_ENV = "CODEBUFF_SKILLS_URL"
+# 설정 동기화와 같은 공유 키·사용자 토큰 (remote_config 와 같은 값)
+TOKEN_ENV = "CODEX_SERVER_API_KEY"
+USER_TOKEN_ENV = "KEYCLOAK_ID_TOKEN"
+USER_TOKEN_HEADER = "X-Codebuff-User-Token"
+#: 로컬 스킬 보고 경로 — `CODEBUFF_SKILLS_URL` 뒤에 붙인다 (이슈 #182)
+REPORT_SUFFIX = "/local"
+
+SKILL_FILE = "SKILL.md"
+#: 디렉터리 이름이 되는 값이라 경로 문자를 막는다. 로컬 파서와 DDL 주석이 이 값을 따른다
+NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+# YAML 이 읽지 못하는 문자 — 설명에 남으면 로컬 파서가 그 파일을 통째로 버린다
+_YAML_UNPRINTABLE = re.compile(
+    "[^\x09\x0a\x0d\x20-\x7e\x85\xa0-\ud7ff\ue000-\ufffd\U00010000-\U0010ffff]"
+)
+#: codex `read_file` 의 상한과 같다. 넘는 본문은 받지 않는다
+BODY_MAX_CHARS = 64_000
+DESCRIPTION_MAX_CHARS = 1_024
+#: 동기화 디렉터리 안의 하위 디렉터리 — 순서가 우선순위다(구체적인 쪽이 앞)
+SYNC_SCOPES = ("user", "project", "team", "global")
+#: 응답 항목에서 pod 가 읽는 필드. DDL 이 모두 담아야 한다
+ENTRY_FIELDS = ("name", "scope", "scope_key", "description", "body", "enabled")
+
+# 도구 정의 보고의 centri 계약 (이슈 #248, centri `codebuff_builtin_tools.py`)
+TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+TOOL_ENGINES = ("codex", "langchain")
+TOOL_VERSION_RE = re.compile(r"^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$")
+#: 넘으면 centri 가 스키마를 비운다 — 보내기 전에 비워 본문을 줄인다
+TOOL_SCHEMA_MAX_CHARS = 16_000
+TOOL_MAX_ITEMS = 100
+
+_KST = timezone(timedelta(hours=9))
+
+
+def clean_tools(entries: Sequence[Any]) -> List[Dict[str, Any]]:
+    """도구 정의 목록을 centri 계약에 맞춘다. 맞출 수 없는 항목은 버린다.
+
+    이름·엔진·버전이 규격 밖이거나 같은 엔진에 같은 이름이 또 있으면 버린다. 설명은 1024자에서
+    자르고, 직렬화한 스키마가 16000자를 넘으면 비운다. 승인은 `True` 일 때만 참이다.
+    """
+    out: List[Dict[str, Any]] = []
+    seen = set()
+    for e in entries:
+        if len(out) >= TOOL_MAX_ITEMS:
+            break
+        if not isinstance(e, dict):
+            continue
+        name, engine = e.get("name"), e.get("engine")
+        if not isinstance(name, str) or not TOOL_NAME_RE.match(name):
+            continue
+        if engine not in TOOL_ENGINES or (engine, name) in seen:
+            continue
+        version = e.get("codebuff_version")
+        if not isinstance(version, str) or not TOOL_VERSION_RE.match(version):
+            continue
+        schema = e.get("input_schema")
+        if isinstance(schema, dict):
+            text = json.dumps(schema, ensure_ascii=False)
+        elif isinstance(schema, str):
+            text = schema
+        else:
+            schema, text = "", ""
+        if len(text) > TOOL_SCHEMA_MAX_CHARS:
+            schema = ""
+        description = e.get("description")
+        seen.add((engine, name))
+        out.append(
+            {
+                "name": name,
+                "engine": engine,
+                "codebuff_version": version,
+                "description": (description if isinstance(description, str) else "")[
+                    :DESCRIPTION_MAX_CHARS
+                ],
+                "input_schema": schema,
+                "approval": e.get("approval") is True,
+            }
+        )
+    return out
+
+
+def _render(name: str, description: str, body: str) -> str:
+    """SKILL.md 한 벌. 설명은 YAML 큰따옴표 문자열로 쓴다.
+
+    JSON 문자열은 YAML 큰따옴표 문자열로도 읽히고 한 줄이라, 설명 속 `---` 가 frontmatter
+    경계(`---` 만 있는 줄)로 읽힐 일이 없다.
+    """
+    quoted = json.dumps(description, ensure_ascii=False)
+    # 이름도 따옴표로 감싼다 — 맨 이름 `no`·`0x1f` 는 YAML 이 불리언·숫자로 읽는다
+    return f"---\nname: {json.dumps(name)}\ndescription: {quoted}\n---\n\n{body}\n"
+
+
+def _clean_description(text: str) -> str:
+    return " ".join(_YAML_UNPRINTABLE.sub("", text).split())[:DESCRIPTION_MAX_CHARS]
+
+
+class RemoteSkillsClient:
+    """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_ids: Sequence[str] = (),
+        user_token: str = "",
+        root: Optional[Path] = None,
+        local_source: Optional[Callable[[], List[dict]]] = None,
+        tools_source: Optional[Callable[[], List[dict]]] = None,
+    ) -> None:
+        self._url = (url or "").strip()
+        self._token = token or ""
+        self._team = team or ""
+        self._project = project or ""
+        # 사번이 어느 변수로 오는지 확정하지 못했다(이슈 #101). 첫 값을 보내고, 받을 때는
+        # 후보 중 하나와 맞으면 이 사용자의 것으로 본다
+        self._user_ids = tuple(u for u in user_ids if u)
+        self._user_token = user_token or ""
+        self._transport = transport
+        self._interval = refresh_interval
+        self._timeout = timeout
+        self._root = root
+        self._lock = threading.Lock()
+        # 디스크 쓰기는 한 번에 하나 — 임시 파일 이름이 pid 라 겹치면 서로의 것을 옮긴다
+        self._apply_lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._count = 0
+        self._dropped = 0
+        self._updated_at: Optional[str] = None
+        self._last_ok_at: Optional[str] = None
+        self._last_error: Optional[str] = None
+        self._attempted = False
+        # 로컬 스킬 보고 — 목록을 만드는 함수는 jupyter_ext 가 준다(워크스페이스를 안다)
+        self._local_source = local_source
+        # 도구 정의 보고 (이슈 #248) — 도구를 만드는 쪽(jupyter_ext)이 목록을 준다
+        self._tools_source = tools_source
+        self._report_sent: Optional[str] = None
+        self._report_count = 0
+        self._report_ok_at: Optional[str] = None
+        self._report_error: Optional[str] = None
+        self._report_attempted = False
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self._url)
+
+    @property
+    def started(self) -> bool:
+        return self._thread is not None
+
+    @property
+    def root(self) -> Path:
+        return self._root if self._root is not None else resolve_home("skills")
+
+    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-skills", daemon=True
+        )
+        self._thread.start()
+
+    @property
+    def report_url(self) -> str:
+        return self._url.rstrip("/") + REPORT_SUFFIX
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self.refresh_now()
+            self.report_now()
+            self._stop.wait(self._interval)
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def refresh_now(self) -> bool:
+        """한 번 받아 디렉터리에 반영한다. 성공 여부를 돌려준다. 예외를 내지 않는다."""
+        if not self.enabled:
+            return False
+        try:
+            entries, updated_at = self._fetch()
+            wanted, dropped = self._accept(entries)
+            with self._apply_lock:
+                self._apply(wanted)
+            with self._lock:
+                self._count = len(wanted)
+                self._dropped = dropped
+                self._updated_at = updated_at
+                self._last_ok_at = datetime.now(_KST).isoformat(timespec="seconds")
+                self._last_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._attempted = True
+            logger.warning("custom skills 받기 실패 — 마지막 파일 유지: %s", e)
+            return False
+
+    def report_now(self) -> bool:
+        """로컬 스킬 목록을 centri 에 보낸다. 바뀌지 않았으면 보내지 않는다. 예외를 내지 않는다.
+
+        수신부 미배포(404)가 정상 상태일 수 있어 실패는 WARNING 이 아니라 debug 로 남긴다.
+        """
+        if not self.enabled or self._local_source is None:
+            return False
+        try:
+            skills = list(self._local_source())
+            payload: Dict[str, Any] = {
+                "schema_version": SCHEMA_VERSION,
+                "team": self._team,
+                "project": self._project,
+                "user": self._user_ids[0] if self._user_ids else "",
+                # 같은 사람·팀·프로젝트의 기계 둘을 centri 가 가를 수 있게 (#204)
+                "host": socket.gethostname(),
+                "skills": skills,
+            }
+            tools = self._report_tools()
+            if tools is not None:
+                payload["tools"] = tools
+            digest = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+            with self._lock:
+                if digest == self._report_sent:
+                    return True
+            payload["reported_at"] = datetime.now(_KST).isoformat(timespec="seconds")
+            self._post_report(payload)
+            with self._lock:
+                self._report_sent = digest
+                self._report_count = len(skills)
+                self._report_ok_at = payload["reported_at"]
+                self._report_error = None
+                self._report_attempted = True
+            return True
+        except Exception as e:  # noqa: BLE001 — 보고 실패가 pod 를 흔들면 안 된다
+            with self._lock:
+                self._report_error = f"{type(e).__name__}: {e}"[:300]
+                self._report_attempted = True
+            logger.debug("로컬 스킬 보고 실패 — 다음 주기에 다시 보낸다: %s", e)
+            return False
+
+    def _report_tools(self) -> Optional[List[Dict[str, Any]]]:
+        """보고할 도구 정의. 소스가 없거나 실패하면 None — 스킬 보고는 계속 간다."""
+        if self._tools_source is None:
+            return None
+        try:
+            return clean_tools(list(self._tools_source()))
+        except Exception as e:  # noqa: BLE001 — 도구 목록 실패가 스킬 보고를 막지 않는다
+            logger.debug("도구 정의 목록 실패 — 이번 보고에서 뺀다: %s", e)
+            return None
+
+    def _post_report(self, payload: Dict[str, Any]) -> None:
+        import httpx
+
+        with httpx.Client(
+            transport=self._transport, timeout=httpx.Timeout(self._timeout)
+        ) as client:
+            resp = client.post(self.report_url, headers=self._headers(), json=payload)
+        resp.raise_for_status()
+
+    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) -> Tuple[list, Optional[str]]:
+        import httpx
+
+        params = {
+            "team": self._team,
+            "project": self._project,
+            "user": self._user_ids[0] if self._user_ids else "",
+        }
+        with httpx.Client(
+            transport=self._transport, timeout=httpx.Timeout(self._timeout)
+        ) as client:
+            resp = client.get(self._url, headers=self._headers(), params=params)
+        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}")
+        skills = body.get("skills")
+        # 빠진 `skills` 를 빈 목록으로 받으면 받은 스킬이 전부 지워진다
+        if not isinstance(skills, list):
+            raise ValueError("skills 가 JSON 배열이 아님")
+        updated_at = body.get("updated_at")
+        return skills, updated_at if isinstance(updated_at, str) else None
+
+    def _owns(self, scope: str, key: str) -> bool:
+        if scope == "global":
+            return key == ""
+        if scope == "team":
+            return bool(self._team) and key == self._team
+        if scope == "project":
+            return bool(self._project) and key == self._project
+        return key in self._user_ids
+
+    def _accept(self, entries: list) -> Tuple[Dict[Tuple[str, str], str], int]:
+        """받을 스킬 `{(scope, name): 파일 내용}` 과 버린 항목 수."""
+        wanted: Dict[Tuple[str, str], str] = {}
+        dropped = 0
+        for e in entries:
+            reason = self._reject_reason(e)
+            if reason is None and (e["scope"], e["name"]) in wanted:
+                reason = "같은 scope 에 같은 이름이 또 있음"
+            if reason is not None:
+                dropped += 1
+                label = e.get("name") if isinstance(e, dict) else type(e).__name__
+                logger.warning("custom skill 항목을 버림 (%s): %r", reason, label)
+                continue
+            wanted[(e["scope"], e["name"])] = _render(
+                e["name"], _clean_description(e["description"]), e["body"].strip()
+            )
+        return wanted, dropped
+
+    def _reject_reason(self, e: Any) -> Optional[str]:
+        if not isinstance(e, dict):
+            return "객체가 아님"
+        # TINYINT 가 0·"0" 으로 직렬화돼도 꺼진 것으로 본다
+        if e.get("enabled", True) in (False, 0, "0", "false", None):
+            return "꺼짐"
+        name, scope = e.get("name"), e.get("scope")
+        # fullmatch — `$` 는 끝 개행 앞에서도 맞아 `sql\n` 이 디렉터리 이름이 된다
+        if not isinstance(name, str) or not NAME_RE.fullmatch(name):
+            return "이름이 규격 밖"
+        if scope not in SYNC_SCOPES:
+            return "scope 가 규격 밖"
+        if not self._owns(scope, e.get("scope_key") or ""):
+            return "이 pod 의 scope_key 가 아님"
+        desc, body = e.get("description"), e.get("body")
+        if not isinstance(desc, str) or not _clean_description(desc):
+            return "설명이 없음"
+        if not isinstance(body, str):
+            return "본문이 문자열이 아님"
+        if len(body) > BODY_MAX_CHARS:
+            return f"본문이 {BODY_MAX_CHARS}자를 넘음"
+        return None
+
+    def _apply(self, wanted: Dict[Tuple[str, str], str]) -> None:
+        """쓰기를 먼저 하고 지우기를 나중에 한다 — 중간에 실패하면 옛 스킬이 남는 쪽이다."""
+        root = self.root
+        for (scope, name), text in wanted.items():
+            skill_dir = root / scope / name
+            # 심볼릭 링크는 따라가지 않는다 — 링크만 떼고 가리키는 곳은 남긴다.
+            # 같은 이름의 일반 파일도 떼야 디렉터리를 만들 수 있다
+            if skill_dir.is_symlink() or skill_dir.is_file():
+                skill_dir.unlink()
+            path = skill_dir / SKILL_FILE
+            if path.is_symlink():
+                path.unlink()
+            try:
+                if path.read_text(encoding="utf-8") == text:
+                    continue
+            except (OSError, UnicodeDecodeError):
+                pass
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_name(f".{SKILL_FILE}.{os.getpid()}.tmp")
+            try:
+                tmp.write_text(text, encoding="utf-8")
+                os.replace(tmp, path)
+            finally:
+                if tmp.exists():
+                    tmp.unlink()
+        for scope in SYNC_SCOPES:
+            scope_dir = root / scope
+            scope_dir.mkdir(parents=True, exist_ok=True)
+            for child in scope_dir.iterdir():
+                if (scope, child.name) in wanted:
+                    continue
+                if child.is_symlink() or not child.is_dir():
+                    child.unlink()
+                else:
+                    shutil.rmtree(child)
+
+    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,
+                "skills": self._count,
+                "dropped": self._dropped,
+                "updatedAt": self._updated_at,
+                "lastOkAt": self._last_ok_at,
+                "lastError": self._last_error,
+                "report": self._report_status(),
+            }
+
+    def _report_status(self) -> Dict[str, Any]:
+        """로컬 스킬 보고 상태. `_lock` 을 잡은 채로 부른다."""
+        if not self.enabled or self._local_source is None:
+            state = "disabled"
+        elif not self._report_attempted:
+            state = "pending"
+        elif self._report_error is not None:
+            state = "error"
+        else:
+            state = "ok"
+        return {
+            "state": state,
+            "skills": self._report_count,
+            "lastOkAt": self._report_ok_at,
+            "lastError": self._report_error,
+        }
+
+
+_client: Optional[RemoteSkillsClient] = None
+_client_lock = threading.Lock()
+
+
+def get_client() -> RemoteSkillsClient:
+    """현재 클라이언트. 기동 전이면 꺼진 클라이언트다 — identity 는 기동이 넘긴다."""
+    global _client
+    with _client_lock:
+        if _client is None:
+            _client = RemoteSkillsClient()
+        return _client
+
+
+def _client_from_env(
+    team: str,
+    project: str,
+    user_ids: Sequence[str],
+    local_source: Optional[Callable[[], List[dict]]] = None,
+    tools_source: Optional[Callable[[], List[dict]]] = None,
+) -> RemoteSkillsClient:
+    return RemoteSkillsClient(
+        url=os.environ.get(URL_ENV, ""),
+        token=os.environ.get(TOKEN_ENV, ""),
+        team=team,
+        project=project,
+        user_ids=user_ids,
+        user_token=os.environ.get(USER_TOKEN_ENV, ""),
+        local_source=local_source,
+        tools_source=tools_source,
+    )
+
+
+def start_from_env(
+    team: str,
+    project: str,
+    user_ids: Sequence[str],
+    local_source: Optional[Callable[[], List[dict]]] = None,
+    tools_source: Optional[Callable[[], List[dict]]] = None,
+) -> RemoteSkillsClient:
+    """서버 기동 시 시크릿 주입 뒤에 부른다. 첫 받기를 기다리지 않는다.
+
+    팀·프로젝트·사용자는 인자로만 받는다 — 팀은 JWT 클레임 폴백이 있어 env 를 직접
+    읽으면 빠진다(`jupyter_ext.team_access.resolve_team`). `local_source` 는 centri 에
+    보고할 로컬 스킬 목록을, `tools_source` 는 도구 정의 목록을 돌려주는 함수다(이슈 #182·#248).
+    """
+    global _client
+    with _client_lock:
+        if _client is None or not _client.started:
+            _client = _client_from_env(
+                team=team,
+                project=project,
+                user_ids=user_ids,
+                local_source=local_source,
+                tools_source=tools_source,
+            )
+            _client.start()
+        return _client
+
+
+def set_client(client: Optional[RemoteSkillsClient]) -> None:
+    """테스트용 — 클라이언트를 갈아 끼운다. None 이면 다음 조회 때 꺼진 클라이언트를 만든다."""
+    global _client
+    with _client_lock:
+        _client = client