codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/analytics_ingest.py

@@ -0,0 +1,599 @@
+"""코드버프 로그 RDS 적재 송신부 (이슈 #30).
+
+지금 로그는 pod 로컬 JSONL 파일로만 쌓인다. 이 모듈은 **파일 쓰기는 그대로 두고**
+같은 이벤트를 cd1-agent 수집 API 로 한 벌 더 보낸다. 파일이 내구 사본으로 남으므로
+전송이 실패해도 데이터를 잃지 않는다.
+
+세 가지가 이 모듈의 계약이다.
+
+1. **호출자를 절대 막지 않는다.** `enqueue`/`flush` 는 어떤 경우에도 예외를 밖으로
+   내지 않고, 큐가 차면 버린다. 로깅 실패가 사용자 작업을 막으면 안 된다 —
+   기존 `analytics_handler` 의 `except: pass` 성질을 그대로 잇는다.
+2. **`CODEBUFF_INGEST_URL` 이 비면 완전한 no-op 이다.** 큐에 쌓지도 않는다. 그래서
+   수집 API·시크릿·네트워크가 준비되기 전에도 이 코드를 안전하게 머지할 수 있다.
+3. **`context` 는 원문 그대로 보낸다** (이슈 #30 판단, 2026-09-03). 화이트리스트로
+   지우지 않는다. 대신 행 크기 상한 하나만 코드가 진다 — `MAX_CONTEXT_BYTES` 를
+   넘으면 **행을 버리지 않고 잘라서** `context_truncated` 로 표시한다.
+   ⚠️ 원문에는 사용자 프롬프트와 셀 소스코드가 들어 있다. 접근 통제(GRANT)와
+      보존기간(TTL)은 DB 쪽에서 정해야 하는 몫이다 (이슈 #30 `## 미해결`).
+
+재시도는 하지 않는다. 대신 `event_id` 에 UNIQUE 를 걸어(`schemas/rds/codebuff_mysql.sql`)
+수집 API 가 나중에 재시도를 넣더라도 중복이 쌓이지 않게 해 뒀다.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import os
+import queue
+import threading
+import time
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from .team_access import resolve_team
+
+logger = logging.getLogger(__name__)
+
+#: 사내 표준 시간대. 컨테이너 TZ 에 기대지 않고 오프셋을 명시한다 — 기존
+#: `analytics_handler` 의 `datetime.now()` 는 naive 라 컨테이너가 UTC 면 9시간 밀린다.
+KST = timezone(timedelta(hours=9))
+
+#: `context` JSON 한 건의 상한. 원문 적재를 택했으므로 상한이 없으면 페이로드가
+#: 무한정 커진다 (선례 `telemetry_ingest.py` 는 본문 4MB 를 넘기면 요청 전체를 버린다).
+MAX_CONTEXT_BYTES = 64 * 1024
+
+QUEUE_MAXSIZE = 5000
+
+#: 절단 폴백에서 "작다" 의 기준. 집계가 쓰는 필드(cell_index, cell_attribution,
+#: agent_code_ratio_pct)는 전부 이보다 훨씬 작다.
+_SMALL_VALUE_BYTES = 512
+FLUSH_BATCH = 200
+#: 요청 1건의 바이트 상한 (이슈 #98). 행 수만으로 자르면 최악 200행 × 64KB = 12.8MB 가
+#: 나가는데, 수신 선례(`telemetry_ingest.py`)의 본문 상한은 4MB 이고 413 이면 배치 전체를
+#: 버린다. 헤더·키 여유를 두고 3MB 로 자른다.
+MAX_BATCH_BYTES = 3 * 1024 * 1024
+FLUSH_INTERVAL_SEC = 30.0
+HTTP_TIMEOUT_SEC = 5.0
+
+#: 세션 종료 경로의 예산. 이 경로는 **async 호출자 안에서 동기로** 돌기 때문에
+#: (`idle_monitor._monitor_loop`, `IdleShutdownHandler.post` 둘 다 `async def`)
+#: 이벤트루프를 잡는다. 그래서 요청 1건의 타임아웃이 아니라 **전체 예산**을 건다 —
+#: 요청마다 2초씩 무한정 쓰는 일이 없도록 배치 루프가 이 예산을 보고 멈춘다.
+SESSION_END_BUDGET_SEC = 2.0
+SESSION_END_REQUEST_TIMEOUT_SEC = 1.0
+SCHEMA_VERSION = 1
+#: codebuff↔centri 통신의 공유 키 — codex 게이트웨이와 같은 `codex_api_key` 를 Bearer 로 보낸다.
+#: 수신기 전용 토큰은 두지 않는다 (이슈 #113, 2026-09-25 사용자 결정).
+TOKEN_ENV = "CODEX_SERVER_API_KEY"
+
+TABLE_UX_EVENT = "ux_event_hst"
+TABLE_AGENT_CALL = "agent_call_hst"
+TABLE_SESSION_END = "session_end_hst"
+_TABLES = (TABLE_UX_EVENT, TABLE_AGENT_CALL, TABLE_SESSION_END)
+
+_UX_EVENT_TYPES = ("impression", "click", "error")
+_AGENT_EVENT_KINDS = ("model_call", "tool_call", "error_classification", "turn")
+
+_ENV_TEAM = resolve_team()
+_ENV_PROJECT = os.environ.get("HDSP_PRJ_ID", "")
+_ENV_USER = os.environ.get("JUPYTERHUB_USER", "") or os.environ.get("HDSP_BDP_ID", "")
+
+
+# ---------------------------------------------------------------------------
+# 값 정규화
+# ---------------------------------------------------------------------------
+def _as_float(value: Any) -> Optional[float]:
+    try:
+        if value is None or isinstance(value, bool):
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_int(value: Any) -> Optional[int]:
+    try:
+        if value is None or isinstance(value, bool):
+            return None
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_flag(value: Any) -> Optional[int]:
+    if value is None:
+        return None
+    return 1 if value else 0
+
+
+def _as_text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return value if isinstance(value, str) else str(value)
+
+
+def _as_clipped(value: Any, limit: int) -> Optional[str]:
+    """칼럼 폭까지 자른다. 넘겨 보내면 INSERT IGNORE 가 경고만 남기고 조용히 자른다."""
+    text = _as_text(value)
+    return None if text is None else text[:limit]
+
+
+def _blob_len(obj: Any) -> int:
+    return len(json.dumps(obj, ensure_ascii=False, default=str).encode("utf-8"))
+
+
+def _normalize_context(raw: Any) -> "tuple[dict, int]":
+    """`context` 를 원문 그대로 두되 타입 드리프트만 흡수하고 상한을 건다.
+
+    반환: (context, context_truncated)
+    """
+    if not isinstance(raw, dict):
+        return {}, 0
+
+    ctx = dict(raw)
+
+    # 실측 드리프트: 같은 키가 int(43건)/float(26건) 으로 섞여 들어온다.
+    # JSON 타입이 섞이면 조회 쪽에서 캐스팅이 갈라지므로 여기서 하나로 만든다.
+    if "agent_code_ratio_pct" in ctx:
+        ctx["agent_code_ratio_pct"] = _as_float(ctx["agent_code_ratio_pct"])
+
+    if _blob_len(ctx) <= MAX_CONTEXT_BYTES:
+        return ctx, 0
+
+    # 긴 문자열부터 반씩 줄인다. 집계가 쓰는 필드는 짧아서 마지막까지 남는다.
+    for _ in range(64):
+        if _blob_len(ctx) <= MAX_CONTEXT_BYTES:
+            return ctx, 1
+        longest_key = None
+        longest_len = 0
+        for key, value in ctx.items():
+            if isinstance(value, str) and len(value) > longest_len:
+                longest_key, longest_len = key, len(value)
+        if longest_key is None:
+            break
+        ctx[longest_key] = (
+            ctx[longest_key][: longest_len // 2] if longest_len > 16 else ""
+        )
+
+    if _blob_len(ctx) > MAX_CONTEXT_BYTES:
+        # 문자열 halving 으로 못 줄인 경우(중첩 구조·키가 아주 많은 경우).
+        # 통째로 버리면 A5 가 쓰는 cell_attribution 같은 **작은 집계 필드까지** 사라진다.
+        # 그래서 작은 값만 남기고 큰 값을 버린다.
+        kept = {
+            key: value
+            for key, value in ctx.items()
+            if _blob_len(value) <= _SMALL_VALUE_BYTES
+        }
+        kept["_truncated"] = True
+        ctx = kept if _blob_len(kept) <= MAX_CONTEXT_BYTES else {"_truncated": True}
+    return ctx, 1
+
+
+def _identity_of(event: dict, identity: Optional[dict]) -> "dict[str, str]":
+    src = identity or {}
+    return {
+        "team": event.get("team") or src.get("team") or _ENV_TEAM,
+        "project": event.get("project") or src.get("project") or _ENV_PROJECT,
+        "user_id": event.get("user_id") or src.get("user_id") or _ENV_USER,
+    }
+
+
+def _from_epoch_ms(value: Any) -> Optional[datetime]:
+    """브라우저 `Date.now()` (epoch ms) → KST. 유일하게 모호하지 않은 시각원이다."""
+    ms = _as_int(value)
+    if ms is None or ms <= 0:
+        return None
+    try:
+        return datetime.fromtimestamp(ms / 1000.0, KST)
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+def _from_naive_text(value: Any) -> Optional[datetime]:
+    """파일에 적힌 naive 시각 문자열 → KST 로 간주.
+
+    ⚠️ 원본이 `datetime.now()` (naive) 라 pod 컨테이너 TZ 가 UTC 면 실제로는 UTC 다.
+    그 판정은 이슈 #30 `## 미해결` [측정] 이 추적한다. 여기서는 KST 로 간주하되,
+    epoch ms 가 있으면 그쪽을 먼저 쓴다.
+    """
+    text = _as_text(value)
+    if not text:
+        return None
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S"):
+        try:
+            return datetime.strptime(text, fmt).replace(tzinfo=KST)
+        except ValueError:
+            continue
+    return None
+
+
+def _stamp(*candidates: Any) -> "tuple[str, str]":
+    """이벤트 자신의 시각을 우선 쓰고, 없을 때만 현재 시각으로 떨어진다.
+
+    빌드 시각을 찍으면 라이브 적재는 맞지만 **파일을 나중에 배치로 백필할 때
+    전부 오늘 날짜가 된다.** 파일이 내구 사본이라는 이 설계의 전제가 깨지므로
+    이벤트가 들고 온 시각을 먼저 본다.
+    """
+    moment = next((c for c in candidates if isinstance(c, datetime)), None)
+    if moment is None:
+        moment = datetime.now(KST)
+    return moment.strftime("%Y-%m-%d %H:%M:%S"), moment.strftime("%Y-%m-%d")
+
+
+# ---------------------------------------------------------------------------
+# 행 빌더 — 순수 함수. 실패하면 예외 대신 None 을 돌려준다
+# ---------------------------------------------------------------------------
+def build_ux_event_row(
+    event: Any,
+    identity: Optional[dict] = None,
+    now: Optional[datetime] = None,
+) -> Optional[dict]:
+    """analytics 이벤트(impression/click/error) → `ux_event_hst` 행."""
+    try:
+        if not isinstance(event, dict):
+            return None
+        event_type = event.get("event_type")
+        if event_type not in _UX_EVENT_TYPES:
+            return None
+        # 레거시 키 `event_name` 을 현행 `feature` 로 접는다 (실측 2건).
+        feature = event.get("feature") or event.get("event_name")
+        if not feature:
+            return None
+
+        context, truncated = _normalize_context(event.get("context"))
+        event_at, event_dt = _stamp(
+            now,
+            _from_epoch_ms(event.get("timestamp")),
+            _from_naive_text(event.get("datetime")),
+        )
+        return {
+            "event_id": _as_text(event.get("event_id")) or str(uuid.uuid4()),
+            "session_id": _as_text(event.get("session_id")),
+            "event_type": event_type,
+            "feature": _as_text(feature),
+            "event_at": event_at,
+            "event_dt": event_dt,
+            "client_ts": _as_int(event.get("timestamp")),
+            "extension_version": _as_text(event.get("extension_version")),
+            "cpu_cores": _as_float(event.get("cpu_cores")),
+            "memory_total_gb": _as_float(event.get("memory_total_gb")),
+            "gpu_name": _as_text(event.get("gpu_name")),
+            "gpu_memory_total_mb": _as_int(event.get("gpu_memory_total_mb")),
+            "context": context,
+            "context_truncated": truncated,
+            **_identity_of(event, identity),
+        }
+    except Exception:
+        logger.debug("build_ux_event_row failed", exc_info=True)
+        return None
+
+
+def build_agent_call_row(
+    event: Any,
+    identity: Optional[dict] = None,
+    now: Optional[datetime] = None,
+) -> Optional[dict]:
+    """구조화 이벤트(model_call/tool_call/error_classification/turn) → `agent_call_hst` 행."""
+    try:
+        if not isinstance(event, dict):
+            return None
+        kind = event.get("event")
+        if kind not in _AGENT_EVENT_KINDS:
+            return None
+
+        called_at, called_dt = _stamp(now, _from_naive_text(event.get("ts")))
+        return {
+            "event_id": str(uuid.uuid4()),
+            "event_kind": kind,
+            "agent_backend": _as_text(event.get("agent_backend")),
+            "called_at": called_at,
+            "called_dt": called_dt,
+            "session_id": _as_text(event.get("session_id")),
+            "ux_session_id": _as_text(event.get("ux_session_id")),
+            "call_num": _as_int(event.get("call_num")),
+            "elapsed_ms": _as_float(event.get("elapsed_ms")),
+            "status": _as_text(event.get("status")),
+            "tool_name": _as_text(event.get("tool_name")),
+            "error_message": _as_text(event.get("error")),
+            "input_msg_count": _as_int(event.get("input_msg_count")),
+            "output_tool_calls": _as_int(event.get("output_tool_calls")),
+            "model_name": _as_clipped(event.get("model_name"), 64),
+            "agent_name": _as_clipped(event.get("agent_name"), 64),
+            "input_tokens": _as_int(event.get("input_tokens")),
+            "output_tokens": _as_int(event.get("output_tokens")),
+            "cached_tokens": _as_int(event.get("cached_tokens")),
+            "finish_reason": _as_clipped(event.get("finish_reason"), 32),
+            "error_type": _as_text(event.get("error_type")),
+            "decision": _as_text(event.get("decision")),
+            "root_cause": _as_text(event.get("root_cause")),
+            "used_llm": _as_flag(event.get("used_llm")),
+            "confidence": _as_float(event.get("confidence")),
+            **_identity_of(event, identity),
+        }
+    except Exception:
+        logger.debug("build_agent_call_row failed", exc_info=True)
+        return None
+
+
+def build_session_end_row(
+    event: Any,
+    identity: Optional[dict] = None,
+    now: Optional[datetime] = None,
+) -> Optional[dict]:
+    """idle_shutdown 이벤트 → `session_end_hst` 행.
+
+    이 이벤트는 pod 가 죽기 직전에 한 번 나온다. 필드가 비어 있어도 "세션이 끝났다" 는
+    사실 자체가 정보이므로 **행을 만들어 낸다** (다른 둘과 달리 None 을 돌려주지 않는다).
+    """
+    try:
+        if not isinstance(event, dict):
+            event = {}
+        ended_at, ended_dt = _stamp(now, _from_naive_text(event.get("ts")))
+        return {
+            "event_id": str(uuid.uuid4()),
+            "ended_at": ended_at,
+            "ended_dt": ended_dt,
+            "idle_seconds": _as_float(event.get("idle_seconds")),
+            "timeout_setting": _as_int(event.get("timeout_setting")),
+            "trigger_source": _as_text(event.get("trigger_source")),
+            **_identity_of(event, identity),
+        }
+    except Exception:
+        logger.debug("build_session_end_row failed", exc_info=True)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# 전송 클라이언트
+# ---------------------------------------------------------------------------
+class IngestClient:
+    """유계 큐 + 데몬 스레드 1개로 수집 API 에 배치 전송한다.
+
+    스레드가 하나인 것은 의도다 — async 핸들러(`analytics_handler`)와 sync writer
+    (`observability`, `log_paths`) 세 경로가 같은 큐를 쓰므로 전송 코드가 한 벌로 남는다.
+    """
+
+    def __init__(
+        self,
+        url: str = "",
+        token: str = "",
+        queue_maxsize: int = QUEUE_MAXSIZE,
+        transport: Any = None,
+        start_worker: bool = True,
+        flush_interval: float = FLUSH_INTERVAL_SEC,
+        batch: int = FLUSH_BATCH,
+    ) -> None:
+        self._url = (url or "").strip()
+        self._token = token or ""
+        self._queue: "queue.Queue[tuple]" = queue.Queue(maxsize=queue_maxsize)
+        self._transport = transport
+        self._batch = batch
+        self._flush_interval = flush_interval
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        # 이벤트루프 스레드·데몬·to_thread 워커가 동시에 올릴 수 있다.
+        self._counter_lock = threading.Lock()
+        # 바이트 상한에 걸려 다음 배치로 넘긴 행. 큐 앞에 되돌릴 수 없어서 따로 든다.
+        # drain 은 데몬과 세션 종료 경로가 동시에 부를 수 있어 잠근다.
+        self._carry: Optional[tuple] = None
+        self._drain_lock = threading.Lock()
+        self.dropped = 0
+        # 설정 화면의 "사용 로그 수신" 줄 (이슈 #183). 실패는 여전히 삼키고 기록만 한다
+        self._last_ok_at: Optional[str] = None
+        self._last_error: Optional[str] = None
+        if start_worker and self.enabled:
+            self._thread = threading.Thread(
+                target=self._run, name="codebuff-ingest", daemon=True
+            )
+            self._thread.start()
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self._url)
+
+    @property
+    def queued(self) -> int:
+        return self._queue.qsize() + (1 if self._carry is not None else 0)
+
+    def status(self) -> "dict[str, Any]":
+        """송신 상태 — `disabled`·`pending`(아직 안 보냄)·`ok`·`error`. 마지막 전송이 정한다."""
+        with self._counter_lock:
+            if not self.enabled:
+                state = "disabled"
+            elif self._last_error is not None:
+                state = "error"
+            elif self._last_ok_at is not None:
+                state = "ok"
+            else:
+                state = "pending"
+            return {
+                "state": state,
+                "queued": self.queued,
+                "dropped": self.dropped,
+                "lastOkAt": self._last_ok_at,
+                "lastError": self._last_error,
+            }
+
+    def _record(self, error: Optional[str]) -> None:
+        with self._counter_lock:
+            if error is None:
+                self._last_ok_at = datetime.now(KST).isoformat(timespec="seconds")
+            self._last_error = error
+
+    def enqueue(self, table: str, row: Optional[dict]) -> None:
+        """행 하나를 큐에 넣는다. **어떤 경우에도 예외를 내지 않는다.**"""
+        try:
+            if not self.enabled or row is None or table not in _TABLES:
+                return
+            try:
+                self._queue.put_nowait((table, row))
+            except queue.Full:
+                # 버리는 것이 맞다. 여기서 블로킹하면 사용자 요청이 멈춘다.
+                with self._counter_lock:
+                    self.dropped += 1
+        except Exception:
+            logger.debug("ingest enqueue failed", exc_info=True)
+
+    def drain_payload(self, limit: Optional[int] = None) -> dict:
+        """큐에서 최대 `limit` 행, `MAX_BATCH_BYTES` 이하를 꺼내 페이로드로 묶는다.
+
+        상한을 넘기는 행은 버리지 않고 다음 배치의 첫 행으로 넘긴다. 행 1개가 상한보다
+        크더라도 그 행 혼자 한 배치로 나간다 (`MAX_CONTEXT_BYTES` 가 행 크기를 막는다).
+        """
+        rows: "dict[str, list]" = {}
+        cap = limit or self._batch
+        with self._drain_lock:
+            used = 0
+            for _ in range(cap):
+                if self._carry is not None:
+                    item, self._carry = self._carry, None
+                else:
+                    try:
+                        item = self._queue.get_nowait()
+                    except queue.Empty:
+                        break
+                size = _blob_len(item[1])
+                if rows and used + size > MAX_BATCH_BYTES:
+                    self._carry = item
+                    break
+                used += size
+                rows.setdefault(item[0], []).append(item[1])
+        return {"schema_version": SCHEMA_VERSION, "rows": rows}
+
+    def flush(
+        self,
+        timeout: float = HTTP_TIMEOUT_SEC,
+        budget: Optional[float] = None,
+    ) -> None:
+        """큐를 비운다. 전송 실패도 조용히 버린다 — 재시도하지 않는다.
+
+        `timeout` 은 **요청 1건**의 상한이고 `budget` 은 이 호출 **전체**의 상한이다.
+        둘을 나눈 이유: 큐에 5,000행이 있으면 배치가 25개까지 나오므로 요청 상한만으로는
+        전체가 25배로 늘어난다. 호출자를 막는 경로(세션 종료)는 반드시 `budget` 을 준다.
+        """
+        try:
+            if not self.enabled:
+                return
+            deadline = None if budget is None else time.monotonic() + budget
+            while True:
+                if deadline is not None and time.monotonic() >= deadline:
+                    return
+                payload = self.drain_payload()
+                if not payload["rows"]:
+                    return
+                self._send(payload, timeout)
+        except Exception:
+            logger.debug("ingest flush failed", exc_info=True)
+
+    def close(self, timeout: float = 2.0) -> None:
+        self._stop.set()
+        thread = self._thread
+        if thread is not None:
+            thread.join(timeout=timeout)
+        self.flush(timeout=timeout)
+
+    # -- 내부 ---------------------------------------------------------------
+    def _run(self) -> None:
+        while not self._stop.wait(self._flush_interval):
+            self.flush()
+
+    def _send(self, payload: dict, timeout: float) -> None:
+        try:
+            import httpx
+
+            body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._token}",
+            }
+            # 단일 실수(float)는 connect/read/write/pool 각각에 적용된다. 전체 상한은
+            # flush(budget=...) 가 본다.
+            limit = httpx.Timeout(timeout)
+            with httpx.Client(transport=self._transport, timeout=limit) as client:
+                response = client.post(self._url, content=body, headers=headers)
+            if response.status_code >= 400:
+                self._record(f"HTTP {response.status_code}")
+                logger.debug(
+                    "ingest rejected: status=%s rows=%s",
+                    response.status_code,
+                    {k: len(v) for k, v in payload["rows"].items()},
+                )
+            else:
+                self._record(None)
+        except Exception as e:
+            self._record(f"{type(e).__name__}: {e}"[:300])
+            logger.debug("ingest send failed", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# 프로세스 단일 클라이언트 + 훅이 부르는 얇은 헬퍼
+# ---------------------------------------------------------------------------
+_CLIENT: Optional[IngestClient] = None
+_CLIENT_LOCK = threading.Lock()
+
+
+def get_client() -> IngestClient:
+    global _CLIENT
+    if _CLIENT is None:
+        with _CLIENT_LOCK:
+            if _CLIENT is None:
+                _CLIENT = IngestClient(
+                    url=os.environ.get("CODEBUFF_INGEST_URL", ""),
+                    token=os.environ.get(TOKEN_ENV, ""),
+                )
+                # 정상 종료(SIGTERM 이 아닌) 경로에서 큐 잔량을 흘려보낸다.
+                # 이게 없으면 close() 를 아무도 부르지 않아 죽은 코드가 된다.
+                atexit.register(_close_client_at_exit)
+    return _CLIENT
+
+
+def _close_client_at_exit() -> None:
+    client = _CLIENT
+    if client is not None:
+        try:
+            client.close()
+        except Exception:
+            pass
+
+
+def enqueue_ux_event(event: Any, identity: Optional[dict] = None) -> None:
+    try:
+        get_client().enqueue(TABLE_UX_EVENT, build_ux_event_row(event, identity))
+    except Exception:
+        logger.debug("enqueue_ux_event failed", exc_info=True)
+
+
+def enqueue_agent_call(event: Any, identity: Optional[dict] = None) -> None:
+    try:
+        get_client().enqueue(TABLE_AGENT_CALL, build_agent_call_row(event, identity))
+    except Exception:
+        logger.debug("enqueue_agent_call failed", exc_info=True)
+
+
+def enqueue_session_end(event: Any, identity: Optional[dict] = None) -> None:
+    """세션 종료는 pod 가 곧 죽으므로 넣고 바로 동기 플러시한다.
+
+    ⚠️ 호출자(`log_paths.write_idle_shutdown_log`)가 `async def` 안에서 불리므로 이
+    함수는 **이벤트루프를 잡는다.** 그래서 전체 예산(`SESSION_END_BUDGET_SEC`)을 걸어
+    상한을 실제로 만든다 — 예산이 없으면 배치 수만큼 곱해진다.
+    """
+    try:
+        client = get_client()
+        row = build_session_end_row(event, identity)
+        before = client.dropped
+        client.enqueue(TABLE_SESSION_END, row)
+        if client.dropped > before:
+            # 큐가 차 있었다. 이 경로가 존재하는 이유인 행이 제일 먼저 버려지면 안 된다.
+            client.flush(
+                timeout=SESSION_END_REQUEST_TIMEOUT_SEC, budget=SESSION_END_BUDGET_SEC
+            )
+            client.enqueue(TABLE_SESSION_END, row)
+        client.flush(
+            timeout=SESSION_END_REQUEST_TIMEOUT_SEC, budget=SESSION_END_BUDGET_SEC
+        )
+    except Exception:
+        logger.debug("enqueue_session_end failed", exc_info=True)

jupyter_ext/etc/jupyter/jupyter_server_config.d/codebuff_agent.json

@@ -0,0 +1,7 @@
+{
+  "ServerApp": {
+    "jpserver_extensions": {
+      "jupyter_ext": true
+    }
+  }
+}

jupyter_ext/handlers/__init__.py

@@ -0,0 +1,8 @@
+"""Handlers for Codebuff."""
+
+try:
+    from .websocket import AgentWebSocketHandler
+except ImportError:
+    AgentWebSocketHandler = None  # type: ignore[assignment,misc]
+
+__all__ = ["AgentWebSocketHandler"]