@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/web_ui_controller.py

@@ -0,0 +1,189 @@
+"""Router web UI projection and GET application controller."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+
+RuntimeConfig = dict[str, Any]
+ProviderConfig = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class WebUiConstants:
+    version: str
+    activity_path: Path
+    context_usage_path: Path
+    default_timeout_ms: int
+
+
+@dataclass(frozen=True, slots=True)
+class WebUiProjectionPorts:
+    current_alias: Callable[[RuntimeConfig], str]
+    read_json: Callable[[Path], dict[str, Any]]
+    rate_limit_usage: Callable[
+        [str, ProviderConfig],
+        tuple[int, int | None],
+    ]
+    positive_int: Callable[[Any], int | None]
+    idle_timeout_ms: Callable[[int], int]
+    context_limit: Callable[[str, ProviderConfig], int | None]
+
+
+@dataclass(frozen=True, slots=True)
+class WebUiDisplayPorts:
+    render_home: Callable[..., str]
+    render_chat: Callable[..., str]
+    provider_mode: Callable[[str, ProviderConfig], str]
+    api_key_status: Callable[[str, ProviderConfig], str]
+
+
+@dataclass(frozen=True, slots=True)
+class WebUiHttpPorts:
+    load_config: Callable[[], RuntimeConfig]
+    current_provider: Callable[
+        [RuntimeConfig],
+        tuple[str, ProviderConfig],
+    ]
+    write_text: Callable[..., None]
+
+
+@dataclass(frozen=True, slots=True)
+class WebUiController:
+    constants: WebUiConstants
+    projection: WebUiProjectionPorts
+    display: WebUiDisplayPorts
+    http: WebUiHttpPorts
+
+    def render_router_home(
+        self,
+        config: RuntimeConfig,
+        provider: str,
+        provider_config: ProviderConfig,
+    ) -> str:
+        upstream = self.projection.read_json(
+            self.constants.activity_path
+        )
+        context = self.projection.read_json(
+            self.constants.context_usage_path
+        )
+        used, rpm_limit = self.projection.rate_limit_usage(
+            provider,
+            provider_config,
+        )
+        rpm_text = self._rpm_text(provider_config, used, rpm_limit)
+        timeout_ms = (
+            self.projection.positive_int(
+                provider_config.get("request_timeout_ms")
+            )
+            or self.constants.default_timeout_ms
+        )
+        idle_ms = (
+            self.projection.positive_int(
+                provider_config.get("stream_idle_timeout_ms")
+            )
+            or self.projection.idle_timeout_ms(timeout_ms)
+        )
+        context_limit = self.projection.context_limit(
+            provider,
+            provider_config,
+        )
+        context_text = self._context_text(context, context_limit)
+        upstream_text = " · ".join(
+            value
+            for value in (
+                str(upstream.get("event") or "idle"),
+                str(upstream.get("provider") or provider),
+                str(
+                    upstream.get("model")
+                    or provider_config.get("current_model")
+                    or ""
+                ),
+            )
+            if value
+        )
+        return self.display.render_home(
+            version=self.constants.version,
+            provider=provider,
+            model=self.projection.current_alias(config),
+            context_text=context_text,
+            timeout_ms=timeout_ms,
+            idle_ms=idle_ms,
+            rpm_text=rpm_text,
+            upstream_text=upstream_text,
+        )
+
+    def render_web_chat(
+        self,
+        config: RuntimeConfig,
+        provider: str,
+        provider_config: ProviderConfig,
+    ) -> str:
+        timeout_ms = (
+            self.projection.positive_int(
+                provider_config.get("request_timeout_ms")
+            )
+            or self.constants.default_timeout_ms
+        )
+        return self.display.render_chat(
+            model=self.projection.current_alias(config),
+            provider=provider,
+            mode=self.display.provider_mode(provider, provider_config),
+            api_status=self.display.api_key_status(
+                provider,
+                provider_config,
+            ),
+            timeout_ms=timeout_ms,
+        )
+
+    def handle_get(self, handler: Any, path: str) -> bool:
+        if path not in {"/ca/web/chat", "/ca/web/chat/"}:
+            return False
+        config = self.http.load_config()
+        provider, provider_config = self.http.current_provider(config)
+        self.http.write_text(
+            handler,
+            self.render_web_chat(
+                config,
+                provider,
+                provider_config,
+            ),
+            content_type="text/html; charset=utf-8",
+        )
+        return True
+
+    @staticmethod
+    def _rpm_text(
+        provider_config: ProviderConfig,
+        used: int,
+        limit: int | None,
+    ) -> str:
+        if not bool(provider_config.get("rate_limit_status", False)):
+            return "off"
+        if limit == 0:
+            return f"{used}/min unmanaged"
+        return f"{used}/{limit}" if limit else "unknown"
+
+    def _context_text(
+        self,
+        context: dict[str, Any],
+        limit: int | None,
+    ) -> str:
+        tokens = self.projection.positive_int(context.get("tokens"))
+        percent = context.get("percent")
+        if isinstance(percent, (int, float)):
+            return f"{tokens or 0:,}/{limit or 0:,} tok ({percent}%)"
+        if limit:
+            return f"{tokens or 0:,}/{limit:,} tok"
+        return "unknown"
+
+
+__all__ = [
+    "WebUiConstants",
+    "WebUiController",
+    "WebUiDisplayPorts",
+    "WebUiHttpPorts",
+    "WebUiProjectionPorts",
+]

package/ciel_runtime_support/windows_console_input.py

@@ -0,0 +1,137 @@
+"""Windows console input queue adapter."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Iterable
+
+
+def _windows_console_utf16_units(chars: Iterable[str]) -> list[str]:
+    """Expand non-BMP code points into WCHAR-sized UTF-16 surrogate units."""
+    units: list[str] = []
+    for char in chars:
+        codepoint = ord(char)
+        if codepoint > 0xFFFF:
+            codepoint -= 0x10000
+            units.extend((chr(0xD800 + (codepoint >> 10)), chr(0xDC00 + (codepoint & 0x3FF))))
+        else:
+            units.append(char)
+    return units
+
+
+class WindowsConsoleInputWriter:
+    """Inject keystrokes into the active Windows console input queue."""
+
+    def __init__(self, input_handle: Callable[[], Any], mouse_filter_factory: Callable[[], Any]) -> None:
+        self.handle = input_handle()
+        if self.handle is None:
+            raise RuntimeError("Windows console input handle is not available")
+        self._mouse_filter = mouse_filter_factory()
+        self._queue_baseline: int | None = None
+
+    def wait_until_input_consumed(self, timeout_seconds: float = 2.0) -> bool:
+        """Wait until the most recently written console-input batch leaves the queue."""
+        if self._queue_baseline is None:
+            return True
+        import ctypes
+        from ctypes import wintypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel32.GetNumberOfConsoleInputEvents.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+        kernel32.GetNumberOfConsoleInputEvents.restype = wintypes.BOOL
+        deadline = time.monotonic() + max(0.0, timeout_seconds)
+        while True:
+            pending = wintypes.DWORD(0)
+            if not kernel32.GetNumberOfConsoleInputEvents(self.handle, ctypes.byref(pending)):
+                return False
+            if int(pending.value) <= self._queue_baseline:
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.01)
+
+    def write(self, data: bytes) -> None:
+        if not data:
+            return
+        data = self._mouse_filter.feed(data)
+        if not data:
+            return
+        text = data.decode("utf-8", errors="replace")
+        chars: list[str] = []
+        index = 0
+        while index < len(text):
+            char = text[index]
+            if char == "\r" and index + 1 < len(text) and text[index + 1] == "\n":
+                chars.append("\r")
+                index += 2
+                continue
+            chars.append("\r" if char == "\n" else char)
+            index += 1
+        self._write_chars(chars)
+
+    def _write_chars(self, chars: list[str]) -> None:
+        import ctypes
+        from ctypes import wintypes
+
+        if not chars:
+            return
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        user32 = ctypes.WinDLL("user32", use_last_error=True)
+
+        class KEY_EVENT_RECORD(ctypes.Structure):
+            _fields_ = [
+                ("bKeyDown", wintypes.BOOL),
+                ("wRepeatCount", wintypes.WORD),
+                ("wVirtualKeyCode", wintypes.WORD),
+                ("wVirtualScanCode", wintypes.WORD),
+                ("uChar", wintypes.WCHAR),
+                ("dwControlKeyState", wintypes.DWORD),
+            ]
+
+        class EVENT_UNION(ctypes.Union):
+            _fields_ = [("KeyEvent", KEY_EVENT_RECORD)]
+
+        class INPUT_RECORD(ctypes.Structure):
+            _fields_ = [("EventType", wintypes.WORD), ("Event", EVENT_UNION)]
+
+        user32.MapVirtualKeyW.argtypes = [wintypes.UINT, wintypes.UINT]
+        user32.MapVirtualKeyW.restype = wintypes.UINT
+        kernel32.WriteConsoleInputW.argtypes = [
+            wintypes.HANDLE,
+            ctypes.POINTER(INPUT_RECORD),
+            wintypes.DWORD,
+            ctypes.POINTER(wintypes.DWORD),
+        ]
+        kernel32.WriteConsoleInputW.restype = wintypes.BOOL
+        kernel32.GetNumberOfConsoleInputEvents.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+        kernel32.GetNumberOfConsoleInputEvents.restype = wintypes.BOOL
+        key_event = 0x0001
+        left_ctrl_pressed = 0x0008
+        map_vk_to_vsc = 0
+        vk_map = {"\r": 0x0D, "\x1b": 0x1B, "\x08": 0x08, "\t": 0x09, "\x15": 0x55}
+        records: list[Any] = []
+        for char in _windows_console_utf16_units(chars):
+            virtual_key = vk_map.get(char)
+            if virtual_key is None and len(char) == 1 and "A" <= char.upper() <= "Z":
+                virtual_key = ord(char.upper())
+            elif virtual_key is None:
+                virtual_key = 0
+            control = left_ctrl_pressed if char == "\x15" else 0
+            scan_code = int(user32.MapVirtualKeyW(int(virtual_key), map_vk_to_vsc)) if virtual_key else 0
+            for key_down in (True, False):
+                record = INPUT_RECORD()
+                record.EventType = key_event
+                record.Event.KeyEvent = KEY_EVENT_RECORD(
+                    bool(key_down), 1, int(virtual_key), scan_code, char, control
+                )
+                records.append(record)
+        array_type = INPUT_RECORD * len(records)
+        written = wintypes.DWORD(0)
+        pending_before = wintypes.DWORD(0)
+        if kernel32.GetNumberOfConsoleInputEvents(self.handle, ctypes.byref(pending_before)):
+            self._queue_baseline = int(pending_before.value)
+        else:
+            self._queue_baseline = None
+        ok = kernel32.WriteConsoleInputW(self.handle, array_type(*records), len(records), ctypes.byref(written))
+        if not ok or int(written.value) != len(records):
+            raise OSError(f"WriteConsoleInputW failed: written={int(written.value)} expected={len(records)}")

package/ciel_runtime_support/windows_console_mode.py

@@ -0,0 +1,112 @@
+"""Windows Console mode adapter and mouse-input lifecycle guard."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class WindowsConsoleModePorts:
+    input_handle: Callable[[], Any]
+    parse_bool: Callable[..., bool]
+    environment: Mapping[str, str]
+
+
+@dataclass(frozen=True, slots=True)
+class WindowsConsoleModeService:
+    ports: WindowsConsoleModePorts
+
+    def input_supported(self) -> bool:
+        return self.current() is not None
+
+    def mouse_filter_enabled(self) -> bool:
+        return self.ports.parse_bool(
+            self.ports.environment.get(
+                "CIEL_RUNTIME_WINDOWS_CONSOLE_MOUSE_FILTER"
+            ),
+            True,
+        )
+
+    def current(self) -> int | None:
+        handle = self.ports.input_handle()
+        if handle is None:
+            return None
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            mode = wintypes.DWORD(0)
+            kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            kernel32.GetConsoleMode.argtypes = [
+                wintypes.HANDLE,
+                ctypes.POINTER(wintypes.DWORD),
+            ]
+            kernel32.GetConsoleMode.restype = wintypes.BOOL
+            if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                return None
+            return int(mode.value)
+        except Exception:
+            return None
+
+    def set(self, mode: int) -> bool:
+        handle = self.ports.input_handle()
+        if handle is None:
+            return False
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            kernel32.SetConsoleMode.argtypes = [
+                wintypes.HANDLE,
+                wintypes.DWORD,
+            ]
+            kernel32.SetConsoleMode.restype = wintypes.BOOL
+            return bool(
+                kernel32.SetConsoleMode(handle, wintypes.DWORD(int(mode)))
+            )
+        except Exception:
+            return False
+
+
+class WindowsConsoleMouseInputGuard:
+    ENABLE_MOUSE_INPUT = 0x0010
+
+    def __init__(
+        self,
+        *,
+        platform_name: str,
+        filter_enabled: Callable[[], bool],
+        current_mode: Callable[[], int | None],
+        set_mode: Callable[[int], bool],
+        log: Callable[[str, str], None],
+    ) -> None:
+        self._platform_name = platform_name
+        self._filter_enabled = filter_enabled
+        self._current_mode = current_mode
+        self._set_mode = set_mode
+        self._log = log
+        self.original_mode: int | None = None
+
+    def apply(self) -> None:
+        if self._platform_name != "nt" or not self._filter_enabled():
+            return
+        current = self._current_mode()
+        if current is None:
+            return
+        if self.original_mode is None:
+            self.original_mode = current
+        filtered = current & ~self.ENABLE_MOUSE_INPUT
+        if filtered != current and self._set_mode(filtered):
+            self._log(
+                "INFO",
+                "windows_console_mouse_input_disabled "
+                f"mode={current:#x}->{filtered:#x}",
+            )
+
+    def restore(self) -> None:
+        if self._platform_name != "nt" or self.original_mode is None:
+            return
+        self._set_mode(self.original_mode)

package/docs/Architecture.md

@@ -14,6 +14,11 @@
 | **Protocol Adapter** | 요청/응답 Wire 형식 변환 | — |
 | **Tool Dialect** | 런타임별 툴 이름 및 수정 | — |
 | **Runtime Router** | 런타임별 HTTP 경로와 라우터 기능 소유 | 다른 런타임의 경로 직접 처리 금지 |
+| **Channel Injection** | 런타임 입력 정책과 터미널 전송 조정 | SSE/MCP 수집, cursor 저장, subprocess 생명주기 금지 |
+| **Credential Source** | API key, inbound OAuth, 향후 계정 저장소의 인증 해석 | provider wire 변환 및 retry 금지 |
+| **Prompt Strategy** | protocol별 system context 배치와 원본 불변성 보장 | provider 이름 분기 금지 |
+| **Fallback Policy** | 실패 원인별 provider/model 후보 계획 | HTTP 실행 및 credential 접근 금지 |
+| **Usage Sink** | provider 중립 token usage event 저장·집계 | prompt/credential 저장 금지 |
 
 ---
 
@@ -111,6 +116,13 @@ class RateLimitState:
 - `default_base_url()` → `str`
 - `list_models(config: ProviderConfig)` → `list[ModelInfo]`
 - `build_headers(config, api_key)` → `dict[str, str]`
+- `capabilities(config)` → upstream protocol 및 tools/thinking/local 특성
+- `supported_protocols(config, model)` → 모델별 지원 protocol 집합
+- `select_protocol(operation, config, model)` → 요청 목적별 upstream protocol 선택
+- `request_policy(config)` → chat/models/model-info endpoint와 timeout 기본값
+- `resolve_endpoint(operation, config)` → provider-owned endpoint 선택
+- `model_paths(config)` → provider별 모델 discovery fallback 순서
+- `model_catalog_policy(config)` → configured/Anthropic/OpenAI/Ollama/LM Studio/NVIDIA/Fireworks catalog 전략 선택
 
 ### `ToolDialect` (ABC)
 런타임별 툴 이름 정규화 인터페이스.
@@ -136,6 +148,21 @@ class RateLimitState:
 
 `tests/test_runtime_routers.py`가 Claude/Codex 라우터가 공통 기능을 모두 제공하는지와 경로 소유권이 섞이지 않는지 확인한다.
 
+## Channel Injection 구조
+
+`ciel_runtime_support/channel_injection.py`는 외부 메시지를 대화 입력으로 제출하는 마지막 단계만 담당한다.
+
+| 구성요소 | 패턴 | 책임 |
+|----------|------|------|
+| `InputTransport` | Port / Adapter | PTY 또는 Windows Console 입력 전송 계약 |
+| `CallableInputTransport` | Adapter | 기존 descriptor/writer를 전송 계약에 연결 |
+| `RuntimeInjectionPolicy` | Strategy value | clear, paste, Enter, 지연, 재시도 등 런타임 의미 |
+| `PromptInjection` | Command | 변경 불가능한 한 번의 주입 요청 |
+| `ChannelPromptInjector` | Application Service | 정책과 transport를 조정하며 제출 순서를 보장 |
+
+의존성 방향은 `channel source -> delivery coordinator -> prompt injector -> input transport`이다.
+`ChannelPromptInjector`는 SSE, MCP, cursor, transcript 또는 subprocess를 참조하지 않는다. 플랫폼별 transport도 메시지 의미를 해석하지 않는다. 이 경계를 통해 Claude, Codex, AGY 정책과 Windows/PTY 구현을 독립적으로 테스트하고 교체한다.
+
 ---
 
 ## LaunchMode 흐름
@@ -152,3 +179,30 @@ class RateLimitState:
 - [[Providers]] — 제공자 목록
 - [[Router]] — HTTP 라우터
 - [[Configuration]] — 설정 시스템
+
+## 운영 경로 적용
+
+아키텍처 계약은 테스트용 모델에 머무르지 않고 운영 경로의 composition root에서 실제로 적용된다.
+
+- `ciel_runtime_support/provider_adapters.py`는 전용 Adapter와 선언형 hosted-provider factory를 하나의 Descriptor Registry에 등록한다. 표준 OpenAI Chat 제공자는 `providers/catalog.py`, Anthropic Messages 호환 제공자는 `providers/anthropic_catalog.py`, 동적 cloud endpoint는 `providers/cloud.py`가 소유한다. `HttpBearerProviderAdapter`는 공통 인증 기반일 뿐 Provider 선택 단위가 아니다.
+- `provider_descriptor.py`는 provider 이름·표시명·별칭·구체 Adapter 타입의 단일 등록 원천이다. 단순 provider는 descriptor 데이터만 추가하고, 복잡한 protocol/OAuth 동작은 계속 전용 Adapter에 둔다.
+- `prompt_injection.py`는 Anthropic Messages, OpenAI Chat/Responses, Ollama Chat, Google Generative의 system prompt 배치를 Strategy로 분리한다. Anthropic의 첫 identity/cache block 순서는 변경하지 않는다.
+- `credentials.py`는 API key와 inbound OAuth header를 Chain of Responsibility로 해석한다. allowlist 밖의 cookie/secret header는 전달하지 않으며 OAuth token 발급·갱신은 향후 별도 infrastructure adapter가 구현한다.
+- `routing_fallback.py`는 rate limit, unavailable, timeout, model error별 immutable 후보 계획만 담당한다. 기존 `upstream_retry.py`와 API-key cooldown이 transport 실행을 계속 소유하므로 정책과 재시도 효과가 섞이지 않는다.
+- `usage_events.py`는 token usage를 prompt나 key 없이 JSONL로 기록하는 Port/Adapter다. UI 또는 특정 database에 결합하지 않아 analytics backend를 교체할 수 있다.
+- wire profile, thinking passback 및 tool-choice 정책은 Provider 이름 조건문 대신 구체 Adapter의 protocol/capability 메서드를 사용한다. Kimi·Fireworks의 dual protocol과 OpenCode의 모델별 endpoint도 Adapter가 선택한다.
+- 모델 조회 Application Service는 Provider 이름을 분기하지 않고 Adapter의 `ProviderModelCatalogPolicy`와 `model_paths()`를 사용한다. 새 Provider는 기존 catalog 전략을 조합하면 모델 서비스 수정 없이 등록할 수 있다.
+- `provider_policy.py`도 Provider 이름을 분기하지 않는다. 모델별 protocol, request option, tool-choice 및 thinking 보존은 구체 Adapter 메서드로 선택한다.
+- `ciel_runtime_support/runtime_adapters.py`의 `CliRuntimeAdapter`가 Claude, Codex, AGY의 정규화된 `LaunchSpec`을 `RuntimeCommand`로 변환한다.
+- `ciel_runtime_support/protocols/openai_responses.py`는 설정이나 네트워크에 의존하지 않고 OpenAI Responses와 Anthropic Messages 사이를 변환한다.
+- `ciel_runtime_support/registry.py`는 provider, runtime, protocol, tool dialect 구현을 조건문 대신 이름 기반 factory로 선택한다.
+- `ciel_runtime_support/tool_dialects.py`는 Claude 도구 이름과 MCP 서버 이름 변형을 `ToolDialect` 구현으로 정규화한다.
+- `ciel_runtime_support/provider_limits.py`, `provider_models.py`, `provider_policy.py`는 키 순환·rate limit·모델 카탈로그·wire 정규화를 Provider 계층에 둔다.
+- `ciel_runtime_support/runtime_launch.py`는 네 런타임의 프로세스 및 라우터·채널 수명주기를 조정하고, `runtime_adapters.py`가 최종 CLI 문법을 소유한다.
+- `ciel_runtime_support/streaming_anthropic.py`는 Anthropic/Ollama/OpenAI 스트림 변환을 명시적 dependency object로 실행한다.
+- `ciel_runtime_support/config_repository.py`, `cli_dispatch.py`, `prelaunch.py`, `web_ui.py`는 각각 Repository, Application Service, UI Controller, Presentation 경계를 형성한다.
+- `ciel_runtime_support/tool_schema.py`는 도구 schema registry와 입력 보정을, `tool_dialects.py`는 런타임별 이름 dialect를 분리해 담당한다.
+
+`ciel_runtime.py`는 기존 공개 함수 호환성을 유지하는 composition root다. 각 래퍼는 호출 시점의 의존성을 typed service object로 조립해 하위 모듈에 위임하므로 테스트 patch 호환성을 유지하면서 숨은 전역 service locator를 만들지 않는다. 지원 모듈은 composition root를 역참조하지 않으며, 이 의존성 방향은 아키텍처 계약 테스트가 검증한다.
+
+외부 gateway 프로젝트에서 검증된 data-driven provider registry, multi-account fallback 개념, protocol별 prompt injection, usage analytics는 위 경계로 흡수한다. 반면 client fingerprint 위장, subscription token 추출, 기본 활성 lossy prompt compression처럼 보안·호환성 위험이 큰 기법은 architecture capability로 취급하지 않는다.

package/docs/Configuration.md

@@ -23,10 +23,12 @@
 | `router.log` | 라우터 로그 |
 | `log-level` | 로그 레벨 파일 |
 | `router.pid` | 라우터 프로세스 PID |
+| `router-external-token` | 외부 디버그 접근용 Bearer 토큰 (`0600`) |
 | `router-activity.json` | 라우터 활동 상태 |
 | `rate-limit-state.json` | 레이트 리밋 상태 |
 | `requests.jsonl` | 요청 덤프 (디버그용, 최대 5MB) |
 | `responses.jsonl` | 응답 덤프 (디버그용, 최대 5MB) |
+| `usage-events.jsonl` | provider/model별 token usage event (10MB에서 1세대 회전) |
 | `router-sse-trace.jsonl` | SSE 트레이스 (최대 2MB) |
 | `model-list-cache.json` | 모델 목록 캐시 (TTL: 300초) |
 | `model-registry.json` | 모델 레지스트리 |
@@ -78,10 +80,12 @@
 | `CIEL_RUNTIME_CONFIG_DIR` | 설정 디렉터리 재정의 |
 | `CIEL_RUNTIME_ROUTER_PORT` | 라우터 포트 재정의 |
 | `CIEL_RUNTIME_ROUTER_CLIENT_HOST` | 라우터 클라이언트 바인드 호스트 |
+| `CIEL_RUNTIME_ROUTER_EXTERNAL_TOKEN` | 외부 디버그 접근용 Bearer 토큰 재정의 |
 | `CIEL_RUNTIME_UPSTREAM_USER_AGENT` | 업스트림 User-Agent (기본: `claude-cli`) |
 | `CIEL_RUNTIME_EVENT_LOG` | 이벤트 로그 활성화 (기본: `true`) |
 | `CIEL_RUNTIME_EVENT_LEVEL` | 이벤트 로그 레벨 (기본: `info`) |
 | `CIEL_RUNTIME_EVENT_BUFFER` | 이벤트 버퍼 크기 (기본: `1000`) |
+| `CIEL_RUNTIME_USAGE_LOG` | token usage JSONL 기록 활성화 (기본: `true`) |
 | `CIEL_RUNTIME_THINKING_PASSBACK_MAX` | Thinking 패스백 최대 토큰 (기본: `4096`) |
 | `CIEL_RUNTIME_PYTHON` | 사용할 Python 실행 파일 경로 |
 | `CIEL_RUNTIME_SKIP_POSTINSTALL_STOP` | npm 설치 후 stop 건너뜀 |
@@ -121,6 +125,19 @@ ciel-runtimectl log-level DEBUG
 파일 `log-level`에 레벨 문자열을 저장하거나,  
 `config.json`의 `"log_level"` 키로도 설정 가능.
 
+## 외부 라우터 접근
+
+라우터는 기본적으로 `127.0.0.1`에만 바인딩된다. 외부 디버그 접근을 활성화하면
+`router-external-token` 파일에 제한된 권한으로 토큰을 생성한다. 외부 클라이언트는
+모든 요청에 다음 헤더를 보내야 한다.
+
+```http
+Authorization: Bearer <token>
+```
+
+`CIEL_RUNTIME_ROUTER_EXTERNAL_TOKEN` 환경 변수로 파일 토큰을 재정의할 수 있다.
+루프백 요청은 기존 로컬 CLI 호환성을 위해 토큰 없이 허용된다.
+
 ---
 
 ## 언어 설정