coderouter-cli 1.8.5__tar.gz → 1.9.0__tar.gz

{coderouter_cli-1.8.5 → coderouter_cli-1.9.0}/CHANGELOG.md

@@ -6,6 +6,660 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v1.9.0] — 2026-04-29 (Umbrella tag — Cache observability + Adaptive routing + Cost-aware + Long-run reliability)
+
+**Theme: 「観測 → 理解 → 行動 → 信頼性」を 1 minor で揃える、observability pillar の成熟。** v1.9.0 は 6 sub-release (v1.9-A〜E) を通じて、CodeRouter を「動いてはいるが何が起きているか分からない」状態から、「**何にいくら使った / どこで遅くなった / 何で詰まった**」が運用ログ 1 行で分かる状態に押し上げる。具体的には:
+
+- **観測 (v1.9-A)** — Anthropic prompt cache の hit/miss を全リクエストで `cache-observed` ログに記録、`/dashboard` から hit_rate / saved tokens が見える
+- **透過 (v1.9-B)** — openai_compat 経路でも cache_control / thinking 等の Anthropic 拡張を可能な限り保持、不可能な場合は `capability-degraded` で明示
+- **動的最適化 (v1.9-C)** — profile に `adaptive: true` を付けると、normally-fast な provider が一時的に遅くなったとき自動で後ろに送り、user-felt latency を保護
+- **コスト把握 (v1.9-D)** — providers.yaml の `cost:` で USD pricing を宣言、cache savings は別計算 (LiteLLM 等の競合品が落としている粒度) で dashboard に出る
+- **信頼性ガード (v1.9-E phase 1, L3)** — 同じツールを同じ引数で連続呼び出しする「stuck loop」を検出、profile-level policy (`warn` / `inject` / `break`) で対処
+
+最後の v1.9.0 GA では v1.9.0a6 以降の実機検証で発見された **L3 `break` action の ingress 取りこぼし** (`ToolLoopBreakError` が catch されず 500 が返っていた) を 400 + 構造化 detail に修正、両 ingress 経路 (非 streaming HTTPException / streaming SSE error event) で揃えました。
+
+- Tests: 828 → **830** (+2: break action 非 streaming 400 / streaming SSE error event)
+- Runtime deps: 5 → 5 (29 sub-release 連続据え置き)
+- Backward compat: 完全互換、profile / providers.yaml / API 全部変化なし
+- v1.9.0a1〜a6 をまとめての GA、各 sub-release の詳細は本ファイル下部の alpha entry を参照
+
+### Changes since v1.9.0a6 — E-4 break action の ingress 修正
+
+#### `coderouter/guards/tool_loop.py`
+
+- `ToolLoopBreakError.__init__` に `threshold: int` / `window: int` をキーワード必須で追加。ingress 側で 400 detail を組むときに config を再 lookup せずに済むよう、検出パラメータを exception 自体に carry させる
+- docstring に「Anthropic ingress が catch して 400 + 構造化 detail に変換する」を明記 (a3 で約束していたが実装が伴っていなかった)
+
+#### `coderouter/routing/fallback.py`
+
+- `_apply_tool_loop_guard` の `raise ToolLoopBreakError(...)` で `threshold=profile.tool_loop_threshold, window=profile.tool_loop_window` を渡すよう更新
+
+#### `coderouter/ingress/anthropic_routes.py`
+
+- `ToolLoopBreakError` を import
+- 非 streaming `messages()` に `except ToolLoopBreakError → HTTPException(status_code=400, detail=_tool_loop_break_detail(exc))` を追加。`detail` は flat dict:
+
+  ```json
+  {
+    "error": "tool_loop_detected",
+    "message": "tool loop detected on profile='test-loop-break': tool 'Read' repeated 3 times consecutively.",
+    "profile": "test-loop-break",
+    "tool_name": "Read",
+    "repeat_count": 3,
+    "threshold": 3,
+    "window": 5
+  }
+  ```
+
+  クライアントは `detail.error == "tool_loop_detected"` で branch 可能、`message` は `str(exc)` と同一でログ grep フレンドリー
+- streaming `_anthropic_sse_iterator` に `except ToolLoopBreakError` ブランチを追加、Anthropic 標準 envelope (`error.type == "invalid_request_error"`) + `error.tool_loop` ネストで構造化フィールドを露出。HTTP は 200 のまま (StreamingResponse はヘッダ確定後で 4xx に切り替えられない、midstream-error と同じ事情)
+- helper 2 つ: `_tool_loop_break_extension(exc)` (両形式で共有する detection payload) / `_tool_loop_break_detail(exc)` (非 streaming flat dict 構築)
+- `args_canonical` は両形式から意図的に除外 (tool input にはユーザデータが含まれうるため、400 detail / SSE error event に流出させない)
+
+#### Tests
+
+- **`tests/test_ingress_anthropic.py`** + 2:
+  - `_LoopBreakingEngine` クラス + `client_and_loop_breaking_engine` fixture を追加
+  - `test_break_action_non_streaming_returns_400_with_structured_detail` — 400 + `detail.error="tool_loop_detected"` + 5 detection field + `args_canonical` 不在を検証
+  - `test_break_action_streaming_emits_invalid_request_error_event` — 200 + 単発 SSE error event + Anthropic 標準 envelope + `error.tool_loop` ネスト + `args_canonical` 不在を検証
+
+### v1.9 series summary
+
+| sub | release | feature |
+|---|---|---|
+| a1 | v1.9-A | Cache Observability — `cache-observed` log + dashboard panel |
+| a2 | v1.9-B | Cross-backend cache passthrough + capability gate + doctor cache probe |
+| a3 | v1.9-E phase 1 | L3 Tool-loop detection guard (warn / inject / break) |
+| a4 | v1.9-C | Adaptive Routing — health-based dynamic chain priority |
+| a5 | v1.9-D | Cost-aware Dashboard — Anthropic prompt-cache aware |
+| a6 | v1.9-A streaming patch | `_emit_cache_observed` を `stream_anthropic` に追加 (実装漏れ修正) |
+| **GA** | **v1.9-E phase 1 patch** | **`break` action の ingress 400 取りこぼし修正** (本 entry) |
+
+### Real-machine verification (2026-04-29, LM Studio + ollama)
+
+```
+E-2 (warn):    tool-loop-detected ... action: "warn"   → 200 OK + provider 応答
+E-3 (inject):  tool-loop-detected ... action: "inject" → system に hint 追加 + 200 OK
+                                                         + cache_read_input_tokens: 453 (prefix キャッシュ命中)
+E-4 (break, non-stream): 400 + {"detail":{"error":"tool_loop_detected","profile":"test-loop-break",
+                                           "tool_name":"Read","repeat_count":3,...}}
+E-4 (break, stream):     200 + event: error
+                               data: {"type":"error","error":{"type":"invalid_request_error",
+                                      "tool_loop":{"profile":"test-loop-break","repeat_count":3,...}}}
+
+C  (adaptive, 静止):  全 provider 同速 → static order 維持、`adaptive-routing-applied` 出ない
+C  (adaptive, 発火):  サイズ差 chain (lmstudio 27B-dense 474ms / ollama qwen-coder-1.5b 134ms / openrouter-free n/a)
+                      → global_median 304ms × 1.5 = 456ms、lmstudio 474ms ≥ 456ms → demote +1
+                      → effective_order: [ollama-qwen-coder-1_5b, openrouter-free, lmstudio-...]
+                      → 試験 4 回目から ollama-qwen-coder-1_5b 行きに切り替わって着地、
+                         debounce 30s で oscillation も観察されず
+```
+
+E-2/E-3 は a3 で観察済み、E-4 (両形式) と C 発火パスは GA 直前に実機で初観察。verification.md には MoE モデルの罠 (Qwen3.6-35B-A3B は active 3.8B で速い) と rolling-window タイミング制約の注意を後追いで加筆予定 (本リリースには含まず)。
+
+### Migration
+
+不要。**v1.8.x / v1.9.0a* からの自然なアップグレード**:
+
+- `coderouter` コマンド名 / Python import 名 / providers.yaml の format / env 変数 / ingress URL すべて完全に同じ
+- `tool_loop_action` を未指定または `warn` / `inject` で運用していた profile は挙動完全変化なし
+- `tool_loop_action: break` を既に使っていた profile のみ status code が 5xx → 4xx に変化 (a3〜a6 では実装バグで 500 Internal Server Error が返っていた、1.9.0 で docstring が約束する 400 + 構造化 detail に修正)。実運用で `break` を本番投入していたケースは想定されにくく、検証用途であれば修正後の方が期待挙動
+
+### Out of scope (v1.10 以降)
+
+v1.9 series は意図的に閉じる:
+
+- **v1.9-B2** — `message_delta` event の usage 集約で、streaming 経路でも実 token 数 / cache_read / cache_creation を取得 (現状は `outcome=unknown` 固定)
+- **v1.9-E phase 2** — L2 Memory pressure (LM Studio / ollama backend OOM 検知) / L5 Backend health (continuous probe + chain reorder)
+- **v1.10-?** — plan.md §13 系 (multi-tenant routing, etc.) — 別 minor
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/guards/tool_loop.py
+M  coderouter/ingress/anthropic_routes.py
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+M  tests/test_ingress_anthropic.py
+```
+
+---
+
+## [v1.9.0a6] — 2026-04-28 (v1.9-A streaming パスの cache-observed emit 漏れ patch)
+
+**Theme: 実機検証で発見した v1.9-A の小さな実装ギャップを潰す。** v1.9-A の CHANGELOG / `CacheOutcome` docstring で「streaming レスポンスは `outcome=unknown` で記録される」と約束していたが、`stream_anthropic` 経路に `_emit_cache_observed` の呼び出しが実装漏れしていた (非 streaming `generate_anthropic` のみ実装済み)。実機で `curl -N stream:true` を投げても JSONL に `cache-observed` event が現れない事で発覚。doc で約束していた動作に実装を揃える。
+
+- Tests: 826 → **828** (+2: streaming 成功時 emit / streaming 失敗時 emit せず)
+- Runtime deps: 5 → 5 (28 sub-release 連続据え置き)
+- Backward compat: 完全互換、profile / API 全部変更なし
+- Pre-release: `1.9.0a6`
+
+### Changes
+
+#### `coderouter/routing/fallback.py` `stream_anthropic` に cache-observed emit を追加
+
+- `_apply_tool_loop_guard` 直後に `request_had_cache_control = anthropic_request_has_cache_control(request)` を変数化 (v0.5-B の inline call と新規 emit 用 caller の二重評価を回避)
+- successful stream の最後 (`async for ev in event_iter` 完走後、`return` の直前) に `log_cache_observed(...)` を呼ぶ
+  - `outcome="unknown"` (v1.9-B が `message_delta` 集約するまで streaming は usage 取得しない約束)
+  - `streaming=True`
+  - tokens は all 0 (engine は streaming 経路の usage を集約していない、cost も 0)
+- 非 streaming `generate_anthropic` の挙動には影響なし
+
+#### Tests
+
+- **`tests/test_fallback_cache_observed.py`** + 2:
+  - `test_cache_observed_fires_on_streaming_with_unknown_outcome` — 成功 streaming で `outcome=unknown` / `streaming=True` / `request_had_cache_control=True` が記録される
+  - `test_cache_observed_streaming_does_not_fire_on_provider_failure` — provider 失敗時は emit しない (非 streaming と同じ contract)
+- 上記のため `_CacheAnthropicAdapter.stream_anthropic` を `NotImplementedError` raise から「3 events (start / delta / stop) を yield する minimal stream」に拡張
+
+### Why
+
+v1.9-A 検証中に「stream:true の curl を投げても `cache-observed` log が JSONL に出ない」を発見 (`docs/inside/verification.md` の A-3 検証パス)。v1.9-A の `CacheOutcome` docstring を読み直すと「streaming responses always pair with `outcome=unknown` until v1.9-B aggregates `message_delta`」と書いてあったが、実装が `generate_anthropic` のみで `stream_anthropic` には emit を入れ忘れていた。
+
+これは **doc-implementation gap**: dashboard / metrics dashboard 利用者から見ると「streaming で動いているはずなのに observation が記録されない」という不整合になる。v1.9.0a6 は約束と実装を揃える小 patch。
+
+副次的効果として A-3 (`hit_rate=null when only `unknown` observations`) の実機検証もこの patch で初めて可能になった。
+
+### Migration
+
+`pyproject.toml version 1.9.0a5 → 1.9.0a6`、`coderouter --version` は 1.9.0a6 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。Streaming 経路のレスポンス内容も変化なし — log line が 1 件追加されるだけ。
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+M  tests/test_fallback_cache_observed.py
+```
+
+### Out of scope (v1.9-B 送り)
+
+- `message_delta` event aggregation で streaming 時にも実 token 数 / cache_read / cache_creation を取得する → outcome を unknown 固定でなく実値で出せるようにする
+
+---
+
+## [v1.9.0a5] — 2026-04-28 (v1.9-D: Cost-aware Dashboard — Anthropic prompt-cache aware)
+
+**Theme: 「いくら使ってる」を可視化、cache savings を別枠で。** v1.9-A で観測、v1.9-B で透過保証、v1.9-D で **金額に翻訳**。Anthropic の prompt-cache 価格モデル (cache_read 90% 割引、cache_creation 25% 増し) を最初から正確に実装、LiteLLM 競合品が **cache savings を別計算しない** 弱点を構造的にカバー。
+
+`docs/inside/future.md` §5.5 の v1.9-D 範囲を実装。
+
+- Tests: 811 → **826** (+15: pure compute_cost 8 / collector dispatch 4 / Prometheus exposition 3)
+- Runtime deps: 5 → 5 (27 sub-release 連続据え置き)
+- Backward compat: 完全互換、`providers.yaml` の `cost:` フィールドは optional (unset = 0 contribution)
+- Pre-release: `1.9.0a5`
+
+### Changes
+
+#### `coderouter/cost.py` 新規 (~150 LOC)
+
+- `CostBreakdown` dataclass — per-attempt cost components (input/output/cache_read/cache_creation USD + total + savings)
+- `compute_cost_for_attempt(cost_config, *, input_tokens, ..., cache_creation)` 純関数:
+  - 4 token bucket をそれぞれの rate で計算
+  - cache_read tokens を `input_rate × cache_read_discount` で割引
+  - cache_creation tokens を `input_rate × cache_creation_premium` で premium
+  - savings = `cache_read tokens × input_rate × (1 - cache_read_discount)` (cache_creation は premium なので savings には入らない)
+  - 負の token / None config / partial config に対する defensive 処理
+
+#### Schema: `CostConfig` 新設
+
+- **`coderouter/config/schemas.py`**: `CostConfig` BaseModel に `input_tokens_per_million` / `output_tokens_per_million` / `cache_read_discount=0.10` / `cache_creation_premium=1.25` を declare
+- `ProviderConfig.cost: CostConfig | None = None` 追加 — opt-in、unset の provider (local 等) は dashboard に 0 contribution
+
+#### Engine integration
+
+- **`coderouter/routing/fallback.py`**: `_emit_cache_observed` を拡張、`provider_config: ProviderConfig | None = None` パラメータを受けて `compute_cost_for_attempt()` で per-attempt USD cost + savings を計算、log payload に折り込む
+- `generate_anthropic` の call site で `adapter.config` を渡す
+
+#### Logging schema 拡張
+
+- **`coderouter/logging.py`** `CacheObservedPayload` に `cost_usd: float` / `cost_savings_usd: float` フィールド追加 (default 0.0、pre-v1.9-D caller は zero contribution で互換)
+- `log_cache_observed` helper の signature にも optional kwargs 追加
+
+#### MetricsCollector: per-provider cost aggregation
+
+- **`coderouter/metrics/collector.py`**: `cache-observed` event の dispatch で cost を集計
+  - `_cost_total_usd: dict[str, float]` (per-provider)
+  - `_cost_savings_usd: dict[str, float]` (per-provider)
+  - `_cost_total_usd_aggregate: float` / `_cost_savings_usd_aggregate: float` (process-wide)
+- `snapshot()` 拡張:
+  - `counters.cost_total_usd` / `cost_savings_usd` (per-provider dict)
+  - `counters.cost_total_usd_aggregate` / `cost_savings_usd_aggregate` (process-wide)
+  - 各 provider row に `cost: {total_usd, savings_usd}` panel
+- `reset()` で v1.9-D state も clear
+- 防御的: malformed cost values (str/None) → 0.0 default、handler は raise しない
+
+#### Prometheus exposition
+
+- **`coderouter/metrics/prometheus.py`**: 新 helper `_counter_float()` (float-valued counter、`.10g` formatter で trailing zero trim) + 2 つの新 metric:
+  - `coderouter_cost_total_usd_total{provider}` — cumulative USD billed
+  - `coderouter_cost_savings_usd_total{provider}` — cumulative cache savings USD
+
+#### Tests (+15)
+
+- **`tests/test_metrics_cost.py`** 新規:
+  - `compute_cost_for_attempt`: None config / no cache / cache read discount / cache creation premium / combined / negative tokens defensive / partial config (7)
+  - Collector dispatch: per-provider aggregation / zero cost no entry / per-row cost panel / reset / malformed values (5)
+  - Prometheus: HELP+TYPE / per-provider labels / `_total` suffix (3)
+
+### Why
+
+`docs/inside/future.md` §5.5 で確立した「LiteLLM ですら未対応の cache savings 計算を最初から正確に実装」の具体実装。Anthropic 価格モデルを 4 token bucket × 4 multiplier で正確に表現、operator が「ローカル LLM 併用でいくら浮いたか」「Anthropic prompt cache でいくら節約できたか」を 1 画面で見える状態を実現。
+
+**競合状況**:
+- LiteLLM の cost tracker は `cache_read_input_tokens` を full input rate で billing (= overstate)、savings 別計算なし
+- claude-code-router は cost tracking 自体なし
+- v1.9-D は **Claude Code 系 OSS で唯一、cache-aware cost dashboard を持つ**
+
+### Migration
+
+`pyproject.toml version 1.9.0a4 → 1.9.0a5`、`coderouter --version` は 1.9.0a5 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。
+
+明示的に有効化する operator は paid provider に `cost:` ブロックを追加:
+
+```yaml
+providers:
+  - name: anthropic-direct
+    kind: anthropic
+    base_url: https://api.anthropic.com
+    model: claude-sonnet-4-8
+    api_key_env: ANTHROPIC_API_KEY
+    paid: true
+    cost:                              # v1.9-D 新フィールド
+      input_tokens_per_million: 3.00
+      output_tokens_per_million: 15.00
+      cache_read_discount: 0.10        # default、省略可
+      cache_creation_premium: 1.25     # default、省略可
+```
+
+`coderouter serve` 起動後、`/metrics.json` の `counters.cost_total_usd` / `cost_savings_usd` で per-provider cost を取得可能。Prometheus scrape は `coderouter_cost_total_usd_total{provider="anthropic-direct"}` で取れる。
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/config/schemas.py
+M  coderouter/logging.py
+M  coderouter/metrics/collector.py
+M  coderouter/metrics/prometheus.py
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+A  coderouter/cost.py
+A  tests/test_metrics_cost.py
+```
+
+### Out of scope (次回以降)
+
+- **`/dashboard` HTML cost panel**: snapshot schema は揃ったが UI 描画は v1.9-D2 で
+- **`coderouter stats --cost` TUI**: 5 行サマリ CLI コマンドは v1.9-D2 で
+- **期間別累積 (1 day / 1 week / 1 month)**: 現在 process-lifetime のみ。期間集計は SQLite persistence と組み合わせて v1.10 候補
+- **OpenAI-shaped engine paths のコスト集計**: Anthropic 非 streaming 経路のみ。OpenAI ingress + streaming 対応は v1.9-C2 と同じ follow-up
+
+---
+
+## [v1.9.0a4] — 2026-04-28 (v1.9-C: Adaptive Routing — health-based dynamic chain priority)
+
+**Theme: 「平常時の最適化」を chain に持ち込む。** 静的に declare した `providers` 順序を、live observed の median latency / error rate に基づいて自動再優先化。L5 (v1.9-E phase 3 予定) は二値 (HEALTHY/UNHEALTHY) で crash 対応するのに対し、C は連続値 gradient で **平常時の遅さ** を吸収する。両方とも同じ observation stream から動くが、適用ロジックが直交。
+
+`docs/inside/future.md` §5.4 の v1.9-C 範囲を MVP 実装。**Anthropic 非 streaming パスのみ** 対応 (v1.9-C2 で OpenAI-shaped + streaming follow-up 予定)。
+
+- Tests: 795 → **811** (+16: stats 4 / no-demote 3 / latency demote 2 / error-rate demote 2 / debounce 2 / engine integration 2 / constants pin 1)
+- Runtime deps: 5 → 5 (26 sub-release 連続据え置き)
+- Backward compat: 完全互換、既存 profile は default の `adaptive: false` で従来挙動を維持
+- Pre-release: `1.9.0a4`、`pip install --pre coderouter-cli` で取得可能
+
+### Changes
+
+#### `coderouter/routing/adaptive.py` 新規 (~360 LOC)
+
+- `AdaptiveAdjuster` クラス — per-process singleton (engine が 1 つ保持)
+  - `record_attempt(provider, *, latency_ms, success, now=None)` — observation 記録、append on each engine attempt
+  - `stats_for(provider, *, now=None) -> ProviderStats` — rolling-window から median latency + error rate 計算
+  - `compute_effective_order(adapters, *, now=None) -> list[BaseAdapter]` — 静的 chain → 動的順序、debounce 適用
+- `_ProviderObservation` / `_AdjusterState` / `ProviderStats` データクラス
+- `_apply_debounce` 内部メソッド — `last_committed_rank` 比較で debounce window 内の rank 変更を pinning (両方向、demote→promote と promote→demote 両方)
+- 定数:
+  - `ROLLING_WINDOW_S = 60.0`
+  - `LATENCY_DEMOTE_FACTOR = 1.5` (median × 1.5 を超えたら -1 段)
+  - `ERROR_RATE_DEMOTE_THRESHOLD = 0.10` (10% 失敗で -2 段)
+  - `DEBOUNCE_S = 30.0`
+  - `MIN_SAMPLES_FOR_LATENCY = 3` / `MIN_SAMPLES_FOR_ERROR_RATE = 5`
+
+#### Engine integration (`coderouter/routing/fallback.py`)
+
+- `FallbackEngine.__init__` で `_adaptive_adjuster: AdaptiveAdjuster` を eager 構築。`@property` の `_adaptive` で lazy-fallback も用意 (legacy test `__new__` bypass パターンに対する resilience)
+- `_resolve_anthropic_chain`: profile が `adaptive: true` のときに `_adaptive.compute_effective_order(base)` で chain を再優先化、その後 thinking-capable bucket logic に渡す
+- `_profile_is_adaptive(profile_name)` ヘルパ — chain resolver と recording 側で同じ profile lookup を共有
+- `generate_anthropic` の adapter 呼び出しを `time.monotonic()` で wrap、success/failure 両方で `record_attempt(...)` 呼び出し。auth-flavored failures (401/403) は latency_ms=None で記録 (短絡応答なので latency 信号として無意味)
+
+#### Logging
+
+- 新 event `adaptive-routing-applied` (info-level) — 静的 chain と effective chain order が異なるときのみ fire。payload に static_order / effective_order / per-provider stats を含む
+
+#### Config schema
+
+- `FallbackChain.adaptive: bool = False` 追加。既存 yaml はそのまま動く (default false)
+
+#### Tests
+
+- **`tests/test_routing_adaptive.py`** 新規 (+16 tests):
+  - **Stats**: unseen / median は success のみ / window roll-off / error rate zero on empty (4)
+  - **No demote**: empty chain / no obs / all fast (3)
+  - **Latency demote**: 1.5× threshold / min samples gate (2)
+  - **Error rate demote**: 10% threshold / min samples gate (2)
+  - **Debounce**: pin within window / release after window (2)
+  - **Engine integration**: static profile not invoking adjuster / adaptive profile invoking adjuster (2)
+  - **Constants pin**: ROLLING_WINDOW_S / LATENCY_DEMOTE_FACTOR / ERROR_RATE_DEMOTE_THRESHOLD / DEBOUNCE_S / MIN_SAMPLES_* (1)
+
+### Why
+
+`docs/inside/future.md` §5.4 で確立した「task-based (auto_router、v1.6-A) + health-based (v1.9-C) の両軸対応」のうち health-based を実装。auto_router は request shape (intent) で profile を選ぶが、profile の chain 内 priority は static のまま。v1.9-C で chain 内 priority が live observed health に追従するようになり、両軸が初めて補完関係を成す。
+
+**競合状況**: claude-code-router は task-based 単独、LiteLLM は session-cost-based、何れも latency-aware adaptive routing を持たない。CodeRouter は v1.9-C で **task-based + health-based 両軸** を持つ唯一の Claude Code 系 OSS という位置づけ。
+
+### Migration
+
+`pyproject.toml version 1.9.0a3 → 1.9.0a4`、`coderouter --version` は 1.9.0a4 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。新フィールド `adaptive: false` がデフォルトなので、既存 profile はゼロ変更で従来動作を維持。
+
+明示的に有効化する operator は profile に追加:
+
+```yaml
+profiles:
+  - name: coding
+    providers:
+      - lmstudio-qwen3-5-9b
+      - ollama-gemma4-26b
+      - openrouter-free
+    adaptive: true   # 平常時の latency / error rate に基づく動的優先度
+```
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/config/schemas.py
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+A  coderouter/routing/adaptive.py
+A  tests/test_routing_adaptive.py
+```
+
+### Out of scope (次回以降の v1.9-C2)
+
+- **OpenAI-shaped engine paths**: `generate` / `stream` (非 Anthropic ingress) からの `record_attempt` 呼び出し。MVP では Anthropic 非 streaming のみカバー
+- **Anthropic streaming**: `stream_anthropic` の latency 計測 (mid-stream success の境界をどこに置くか設計余地あり)
+- **Dashboard panel**: `/dashboard` に effective chain order の可視化 (「static order vs current effective order」の差分強調表示)
+- **MetricsCollector への adaptive 集計**: 現在は `adaptive-routing-applied` log のみ。将来 dashboard panel 用に reorder 回数 / 直近 reorder timestamp などを集計
+- **L5 (v1.9-E phase 3)**: binary HEALTHY/UNHEALTHY backend swap。本実装の continuous gradient と棲み分け、両方とも同じ observation stream を消費する設計
+
+---
+
+## [v1.9.0a3] — 2026-04-28 (v1.9-E phase 1: L3 Tool-loop detection guard)
+
+**Theme: Long-run reliability の最初の guard。** `docs/inside/future.md` §5.3 の v1.9-E は L2/L3/L5 の 3 系統障害を扱う 1-2 週間のまとまった作業。1 commit で全部やると重いので **L3 (Tool loop detection) → L2 (Memory pressure) → L5 (Backend health)** の 3 段階で alpha pre-release を切る。
+
+L3 は最も isolated で HTTP 系の依存なし、~300 LOC、self-contained。「Claude Code を 8 時間連続で local LLM に向けて使っても止まらない」を訴求するための最初の具体実装。
+
+- Tests: 779 → **795** (+16: pure detect 8 / inject mutation 3 / engine helper 5)
+- Runtime deps: 5 → 5 (25 sub-release 連続据え置き)
+- Backward compat: 完全互換、`providers.yaml` 編集不要 (新フィールドはすべて default 値あり)
+- Pre-release: `1.9.0a3`、`pip install --pre coderouter-cli` で取得可能
+
+### Changes
+
+#### `coderouter/guards/` 新パッケージ + L3 detector
+
+- **`coderouter/guards/__init__.py`** 新規 — Long-run guards のパッケージドッジ。L2 / L5 が今後追加される予定地。
+- **`coderouter/guards/tool_loop.py`** 新規 (~250 LOC):
+  - `detect_tool_loop(request, *, window, threshold) -> ToolLoopDetection | None` 純関数。直近 `window` 件の assistant `tool_use` ブロックの**末尾連続**で同一 `(name, args)` が `threshold` 回以上発生していると検知
+  - `ToolUseRecord` / `ToolLoopDetection` データクラス
+  - `inject_loop_break_hint(request, *, hint)` — system フィールドに hint を append (str / None / list-of-blocks の 3 形を吸収)
+  - `ToolLoopBreakError` (CodeRouterError 派生) — `break` action 用 exception
+  - `DEFAULT_LOOP_INJECT_HINT` 定数 — 「You appear to be calling the same tool with the same arguments repeatedly...」
+  - **canonical-form JSON 比較** (`json.dumps(args, sort_keys=True)`) で `{"a":1,"b":2}` と `{"b":2,"a":1}` を同一視
+  - **trailing-run only** 検出 — 過去に脱出済みの streak は無視 (現在状態のみが actionable)
+
+#### Engine integration
+
+- **`coderouter/routing/fallback.py`**: `_apply_tool_loop_guard(request, config)` ヘルパ追加。`generate_anthropic` / `stream_anthropic` の chain dispatch 直前で呼ばれる。Action 別の挙動:
+  - `warn`: log のみ、request はそのまま
+  - `inject`: log + `inject_loop_break_hint` で system 注入された新 request を返す
+  - `break`: log + `raise ToolLoopBreakError`
+- profile lookup 失敗時は silent no-op (chain resolution が別経路で error を出すので二重診断にならない)
+
+#### Config schema
+
+- **`coderouter/config/schemas.py`** `FallbackChain` 拡張:
+  - `tool_loop_window: int = 5` (range 2-50)
+  - `tool_loop_threshold: int = 3` (range 2-50)
+  - `tool_loop_action: Literal["warn", "inject", "break"] = "warn"`
+- 既存 profile はすべて default で warn-only として動作 → 既存 deployment はゼロ変更
+
+#### Logging
+
+- **`coderouter/logging.py`**: `tool-loop-detected` warn-level log shape を新設
+  - `ToolLoopDetectedPayload` TypedDict (profile / tool_name / repeat_count / threshold / window / action)
+  - `log_tool_loop_detected()` helper — 単一の chokepoint
+- 3 つの action すべてが同じ log line を fire するので dashboard は detection 全件を捕捉できる (action は label として区別)
+
+### Why
+
+`docs/inside/future.md` §1 で確立した Vision「Local LLM で agent を長時間回すための信頼性層」の P3 (Long-run Reliability) の最初の具体実装。L3 が最も isolated で実装シンプル / テスト容易 / 単独で価値があり、最初の sub-release に最適。
+
+「Claude Code が同じファイルを 5 回 Read し続ける」「Bash で同じコマンドを 3 回叩いて止まらない」というのは長時間 agent loop で頻出する典型症状で、L3 はその検知を request shape だけで完結させる (Claude Code は full conversation history を毎回送るので tail inspection で十分)。
+
+**競合状況** (future.md §3 referenced): L3 を体系的に対処する Claude Code 系 OSS は 2026-04-27 時点で調査リスト中ゼロ。本実装は単独差別化軸として位置づく。
+
+### Migration
+
+`pyproject.toml version 1.9.0a2 → 1.9.0a3`、`coderouter --version` は 1.9.0a3 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。新 schema フィールドはすべて default 値ありなので、既存 yaml はそのままロード可能で、警告の挙動も warn level (ログ出力のみ) なので既存処理に副作用なし。
+
+明示的に有効化したい operator は profile に以下を追加:
+
+```yaml
+profiles:
+  - name: long-running-agent
+    providers: [...]
+    tool_loop_window: 5
+    tool_loop_threshold: 3
+    tool_loop_action: inject   # または warn / break
+```
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/config/schemas.py
+M  coderouter/logging.py
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+A  coderouter/guards/__init__.py
+A  coderouter/guards/tool_loop.py
+A  tests/test_guards_tool_loop.py
+```
+
+### Out of scope (次回以降の v1.9-E phase)
+
+- **L2 (Memory pressure awareness)**: Ollama `/api/ps` / LM Studio `/v1/models` / llama.cpp `/proc/meminfo` 直読みで backend memory probe、95% 超で軽量 model に swap
+- **L5 (Backend health continuous monitoring)**: 60s 周期の健康 probe、UNHEALTHY を chain 末尾に降格 / 復帰時に元 priority 戻し、dashboard に effective chain order
+- **MetricsCollector への loop event 集計**: 現在は構造化 log のみ、将来 dashboard panel で「直近 24h の loop 検知 N 件」表示
+- **inject hint の operator override**: 現在 `DEFAULT_LOOP_INJECT_HINT` のみ、将来 profile-level `tool_loop_inject_hint` で日本語化等可能に
+
+---
+
+## [v1.9.0a2] — 2026-04-28 (v1.9-B: Cross-backend cache passthrough + capability gate + doctor cache probe)
+
+**Theme: v1.9-A の「観測」を「保証」へ。** capability registry に `cache_control` フィールドを新設し、Claude 4 family + LM Studio 経由 Qwen3.5/3.6 を bundled で宣言。doctor に新 probe `_probe_cache` を追加し、cache_control の round-trip (1 回目 creation → 2 回目 read) を実機 verify。
+
+`docs/inside/future.md` §5.2 の v1.9-B 範囲を実装。挙動変更は capability gate 拡張のみで、既存の `provider_supports_cache_control` 呼び出しは下位互換 (registry 未宣言 anthropic-kind は引き続き True)。
+
+- Tests: 759 → **779** (+20: registry resolution 12 / doctor cache probe 8)
+- Runtime deps: 5 → 5 (24 sub-release 連続据え置き)
+- Backward compat: 完全互換、`providers.yaml` / API 全部変更なし
+- Pre-release: `1.9.0a2`、`pip install --pre coderouter-cli` で取得可能
+
+### Changes
+
+#### Capability registry: `cache_control` フィールド新設
+
+- **`coderouter/config/capability_registry.py`**: `RegistryCapabilities` / `ResolvedCapabilities` に `cache_control: bool | None` フィールド追加。lookup walker に同フィールドを追加 (first-match-per-flag 既存 semantics に従う)。
+- **`coderouter/data/model-capabilities.yaml`**: bundled で 5 rule 宣言:
+  - `claude-opus-4-*` / `claude-sonnet-4-*` / `claude-haiku-4-*` (kind=anthropic): `cache_control: true` — api.anthropic.com で実機検証済 (2026-04-20、1321 tokens 書き / 1321 tokens 読み)
+  - `qwen3.5-*` / `qwen3.6-*` (kind=anthropic): `cache_control: true` — LM Studio 0.4.12 `/v1/messages` で v1.8.4 実機検証済 (`cache_read_input_tokens: 280` 観測)
+  - openai_compat 系は意図的に未宣言 (= None) → 既存の v0.5-B `capability-degraded reason=translation-lossy` log がそのまま fire
+
+#### Capability gate: registry を consult
+
+- **`coderouter/routing/capability.py`**: `provider_supports_cache_control` に `registry: CapabilityRegistry | None = None` kwarg を追加。解決順序を 3 段に:
+  1. `provider.capabilities.prompt_cache: true` → True (explicit per-provider)
+  2. registry の `cache_control: true|false` → 即決
+  3. fallback: `provider.kind == "anthropic"` → True (pre-v1.9-B 互換)
+- registry が `False` を返したら kind=anthropic でも False を返すので、upstream regression 時に operator が一時的に `cache_control: false` を user yaml で declare → `capability-degraded` log が fire するという escape hatch が成立
+
+#### Doctor: `_probe_cache` 新 probe 追加
+
+- **`coderouter/doctor.py`**: `_probe_cache` 関数を新設、orchestrator の最後 (streaming probe の後) に組み込み。auth fail 時の SKIP list にも追加。
+  - 動作: 同一 body (~1900 token system prompt + `cache_control: ephemeral`) を 2 回 POST、1 回目で `cache_creation_input_tokens > 0`、2 回目で `cache_read_input_tokens > 0` を期待
+  - **Verdict 4 種**:
+    - **OK**: 2 回目で read > 0 → cache_control 配管が end-to-end 機能している
+    - **NEEDS_TUNING**: 1 回目 creation 観測 / 2 回目 read=0 → TTL 短すぎ or cache key mismatch
+    - **NEEDS_TUNING**: 両方とも creation/read 観測なし → upstream が cache_control を silent ignore (Anthropic compat 不完全) or 1024 token 最低未達
+    - **SKIP**: not anthropic / 未宣言 / upstream 5xx / auth fail
+  - **Gate は意図的に tight**: 2 paid HTTP call を消費するので、registry に `cache_control: true` 明示宣言 OR `providers.yaml capabilities.prompt_cache: true` のときのみ実行。kind=anthropic だけで自動実行はしない (unverified model に対して無駄な call を避ける)
+
+#### Tests
+
+- **`tests/test_capability_registry_cache_control.py`** 新規 (+12): registry resolution 4 / capability gate 5 / bundled YAML 検証 3
+  - bundled が `claude-opus-4-8` / `claude-sonnet-4-7` / `claude-haiku-4-1` で `cache_control=true` を返すこと
+  - bundled が `qwen3.5-9b` / `qwen3.6-35b-a3b` で `cache_control=true` を返すこと
+  - bundled が `openai_compat` の `qwen2.5-coder:7b` で undeclared (None) のまま → translation-lossy gate fire を確実にする
+- **`tests/test_doctor_cache_probe.py`** 新規 (+8): probe gate / OK round-trip / NEEDS_TUNING (no hit / no creation) / explicit prompt_cache opt-in / 1st call 5xx → SKIP / auth fail → SKIP
+
+### Why
+
+v1.9-A で「観測」した cache の動作を、v1.9-B で **どの (kind, model) が cache_control を保証するか** という contract に格上げ。doctor cache probe は **どの競合 (LiteLLM / claude-code-router / etc.) にもない機能** で、operator が「LM Studio で本当に cache が効いてるのか」を 1 コマンドで確認できる単独差別化軸。
+
+LM Studio 0.4.12 を bundled YAML に組み込んだのは、v1.8.4 で実機確認した「Anthropic compat `/v1/messages` 経由で `cache_read_input_tokens: 280` が end-to-end 透過する」という事実を CodeRouter として保証宣言する意味がある。Qwen3.5/3.6 を `kind: anthropic` で declare している operator なら、`coderouter doctor --check-model lmstudio-qwen3-5-9b-anthropic` で OK が出れば prompt caching 実利用可能、という保証関係。
+
+### Migration
+
+`pyproject.toml version 1.9.0a1 → 1.9.0a2`、`coderouter --version` は 1.9.0a2 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。
+
+`provider_supports_cache_control` は kwarg `registry=None` を追加したので signature は backward-compatible (既存 caller は変更なし)。registry を consult した結果 `False` で hard-disable できるのが新機能だが、bundled YAML は positive 宣言のみ ship なので default 挙動は変化なし。
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/config/capability_registry.py
+M  coderouter/data/model-capabilities.yaml
+M  coderouter/doctor.py
+M  coderouter/routing/capability.py
+M  pyproject.toml
+A  tests/test_capability_registry_cache_control.py
+A  tests/test_doctor_cache_probe.py
+```
+
+### Out of scope (次回以降)
+
+- **v1.9-E (前倒し)**: Long-run Guards 三段 (L2 memory pressure / L3 tool loop / L5 backend health continuous) — Vision の核心実装
+- **v1.9-C**: Adaptive Routing (rolling latency window + health-based dynamic priority)
+- **v1.9-D**: Cost-aware Dashboard
+- streaming aggregation: cache 観測の streaming 時 `outcome` 値を `cache_hit/creation/no_cache` に格上げ (v1.9-A の `unknown` から)
+
+---
+
+## [v1.9.0a1] — 2026-04-28 (v1.9-A: Cache Observability — Anthropic prompt caching を観測可能に)
+
+**Theme: v1.9 シリーズ最初の alpha pre-release。Anthropic prompt caching の動作を CodeRouter 側で観測可能にし、`cache_read_input_tokens` / `cache_creation_input_tokens` を 4 分類 (cache_hit / cache_creation / no_cache / unknown) で per-provider 集計。**
+
+`docs/inside/future.md` §5.1 の v1.9-A 範囲を実装。挙動は変えず、観測経路を追加するだけの安全な追加。LiteLLM の `cache_creation_input_tokens` undercounting バグ (future.md §3) を最初から避ける厳密 4 分類集計を導入。次の v1.9-B (cross-backend cache passthrough + capability gate / doctor cache probe) で能動的な cache 制御を追加予定。
+
+- Tests: 737 → **759** (+22: classify_cache_outcome / collector dispatch / snapshot cache panel / Prometheus exposition / engine emission)
+- Runtime deps: 5 → 5 (23 sub-release 連続据え置き)
+- Backward compat: 完全互換、`providers.yaml` / `~/.coderouter/model-capabilities.yaml` / API 全部変更なし
+- Pre-release: `1.9.0a1` の `a1` は PEP 440 alpha pre-release。`pip install --pre coderouter-cli` で取得可能。`v1.9.0` 正式版は v1.9-B/E/C/D も完了次第
+
+### Changes
+
+#### `cache-observed` 構造化ログイベント新設
+
+- **`coderouter/logging.py`**: `CacheOutcome` Literal + `CacheObservedPayload` TypedDict + `log_cache_observed()` helper + `classify_cache_outcome()` 4 分類関数を追加。
+  - `cache_hit`: `cache_read_input_tokens > 0` (cache 再利用、〜10% input rate)
+  - `cache_creation`: `cache_creation_input_tokens > 0` かつ hit ではない (cache 書き込み、〜125% input rate)
+  - `no_cache`: usage 受信したが cache フィールド 0/欠損 (cache_control 無し or upstream が握り潰した)
+  - `unknown`: response に usage block 自体無し (streaming / openai_compat 経由 / pre-v1.9-A upstream)
+- **理由**: `provider-ok` event に cache フィールドを混ぜると downstream consumers (collector / JSONL mirror / tests) すべてが新 schema 検証必要。専用 event なら streaming 時の `outcome=unknown` も自然に表現できる
+
+#### Engine (`fallback.py`): 成功 response 毎に cache-observed を emit
+
+- **`coderouter/routing/fallback.py`**: `generate_anthropic` の `provider-ok` 直後に `_emit_cache_observed()` 呼び出しを追加。`AnthropicResponse.usage.model_extra` から `cache_read_input_tokens` / `cache_creation_input_tokens` を抽出 (Pydantic `extra="allow"` 経由でラウンドトリップ済み)。
+  - native Anthropic + LM Studio `/v1/messages` (`kind: anthropic`) → cache フィールド付き → 4 分類正しく出る
+  - openai_compat → anthropic 変換経由 → cache フィールド無し → `outcome=no_cache` or `unknown`
+- streaming aggregation は v1.9-B 送り (`message_delta` イベント集約が必要)、v1.9-A では非 streaming パスのみ対応
+
+#### MetricsCollector: per-provider cache 集計
+
+- **`coderouter/metrics/collector.py`**: `cache-observed` event を dispatch table に追加。新カウンタ:
+  - `_cache_read_tokens: Counter[str]` (per-provider)
+  - `_cache_creation_tokens: Counter[str]` (per-provider)
+  - `_cache_outcomes: dict[str, Counter[str]]` (per-provider × 4-class)
+  - `_cache_read_tokens_total: int` / `_cache_creation_tokens_total: int` (aggregate、毎 event で incremental 更新、snapshot 時の re-fold コスト回避)
+- `snapshot()` 拡張: `counters.cache_*` (per-provider + aggregate) + 各 provider row に `cache: {read_tokens, creation_tokens, outcomes, hit_rate, observations}` panel を追加
+  - **`hit_rate`** は `cache_hit / (cache_hit + cache_creation + no_cache)`、`unknown` は分母から除外 (signal 無しを 0% 表示するのを回避)
+  - 観測無しなら `hit_rate=None`、dashboard で「—」表示できる
+- `reset()` で v1.9-A state も clear
+
+#### Prometheus exposition: 3 つの新 counter
+
+- **`coderouter/metrics/prometheus.py`**:
+  - `coderouter_cache_read_tokens_total{provider="..."}` — cache 再利用された input token 累計
+  - `coderouter_cache_creation_tokens_total{provider="..."}` — cache 書き込み input token 累計
+  - `coderouter_cache_observed_total{provider="...", outcome="cache_hit|cache_creation|no_cache|unknown"}` — 4 分類イベント数
+- `hit_rate` を gauge で expose しないのは Prometheus 慣習に従い (`rate()` で derivative を計算する方が時間窓を正しく扱える)
+
+#### Tests (+22)
+
+- **`tests/test_metrics_cache.py`** (+11): `classify_cache_outcome` 4 cases / collector dispatch / snapshot cache panel / hit_rate=None for idle / unknown-only keeps None / reset clears state / 防御的非 int 受け入れ
+- **`tests/test_metrics_prometheus_cache.py`** (+5): empty-snapshot HELP/TYPE / per-provider read/creation labels / outcome label pair / `_total` suffix
+- **`tests/test_fallback_cache_observed.py`** (+6): cache_hit / cache_creation / no_cache outcome 別 / openai_compat 経路で no_cache or unknown / 失敗時 emit せず / chain fallthrough 時 winning provider のみ emit
+
+### Why
+
+`docs/inside/future.md` §1 で確立した Vision「Local LLM で agent を長時間回すための信頼性層」の 3 pillar 中、**P1 Connection Stability** の核心要素である Anthropic prompt caching を **観測可能に** することが v1.9 シリーズの最初のステップ。LM Studio 0.4.12 の Anthropic 互換 `/v1/messages` 経由で v1.8.4 に observed した `cache_read_input_tokens: 280` を、CodeRouter 側で **per-provider hit 率として集計・可視化** できるようになった。
+
+LiteLLM cluster は `cache_creation_input_tokens` を `no_cache` に丸めて undercount する既知バグ (future.md §3 referenced) があり、CodeRouter は最初から 4 分類厳密集計でこれを回避。Claude Code 特化 OSS の中で **唯一の cache 観測機能** として位置づけ。
+
+### Migration
+
+`pyproject.toml version 1.8.5 → 1.9.0a1`、`coderouter --version` は 1.9.0a1 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。
+
+`/metrics.json` の counters / providers schema は **追加のみ** (新 key `cache_read_tokens` / `cache_creation_tokens` / `cache_outcomes`、provider rows に `cache` panel)、既存 dashboards は壊れない。Prometheus scraper は新メトリクス自動 discovery。
+
+### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/logging.py
+M  coderouter/metrics/collector.py
+M  coderouter/metrics/prometheus.py
+M  coderouter/routing/fallback.py
+M  pyproject.toml
+A  tests/test_fallback_cache_observed.py
+A  tests/test_metrics_cache.py
+A  tests/test_metrics_prometheus_cache.py
+```
+
+### Out of scope (次回以降)
+
+- **v1.9-B**: cross-backend cache passthrough + capability gate (`capabilities.cache_control` registry / doctor cache probe / openai_compat strip warn) — 「観測」から「保証」へ
+- **v1.9-E (前倒し)**: Long-run Guards 三段 (L2 memory pressure / L3 tool loop / L5 backend health) — Vision の核心実装
+- streaming aggregation: `message_delta` event を集約して streaming 時も `outcome=cache_hit/creation/no_cache` を出せるようにする (v1.9-B 範囲)
+
+---
+
 ## [v1.8.5] — 2026-04-28 (doctor NEEDS_TUNING メッセージを v1.8.3 thinking-aware budget の事実に揃える + `docs/lmstudio-direct.md` 新規)
 
 **Theme: 文言の整合 patch + ドキュメント補完。**v1.8.3 で `tool_calls` / `num_ctx` / `streaming` の 3 probe に thinking-aware budget (256 / 1024) を入れた。今回はその事実を NEEDS_TUNING 時の detail メッセージに反映し、operator が「probe budget が小さすぎたのでは」と疑う余地をなくす。あわせて v1.8.4 で実機検証した LM Studio 0.4.12 経由経路を `docs/llamacpp-direct.md` と対をなす形で `docs/lmstudio-direct.md` (+ `.en.md`) として正式化。