coderouter-cli 1.10.0__tar.gz → 2.0.0__tar.gz

{coderouter_cli-1.10.0 → coderouter_cli-2.0.0}/CHANGELOG.md

@@ -6,6 +6,202 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.0.0] — 2026-05-05 (Context Budget Management — L1 overflow 防止)
+
+**Theme: 長時間 agent session の context overflow を未然に防止する guard を実装。** Claude Code / Cline / OpenClaw 等の agentic session が 8 時間超え loop で動くと messages が context window に漸近し、backend が 400 / truncation を返して session 死亡する問題 (L1) を根本解決。warn (80%) → auto trim (90%) の 2 段階 guard で overflow をゼロに。
+
+| 機能 | 説明 |
+|---|---|
+| `estimate_context_usage()` | char/4 heuristic で request の context 充填率を推定 (5-deps 不変) |
+| `trim_to_budget()` | 古い messages を先頭から削除、tool_use/tool_result ペアを tool_use_id ベースで atomic 保全 |
+| `context_budget_action: off/warn/trim` | profile 単位で guard 有効化 (default: off) |
+| `X-CodeRouter-Context-Budget` header | response header で warn/trimmed ステータスを通知 (streaming 対応) |
+| Prometheus metrics | `coderouter_context_budget_warnings_total`, `coderouter_context_budget_trims_total`, `coderouter_context_budget_usage_ratio` |
+| `coderouter stats` TUI | Fallback & Gates パネルに context budget warn/trim count + latest ratio 表示 |
+| model-capabilities.yaml | 主要モデル (Claude 200K, Qwen3/3.5/3.6 32-131K, Gemma4 131K, DeepSeek 131K 等) の max_context_tokens bundled |
+
+- Tests: 878 → **~930** (+50, token_estimation 13 + context_budget 22 + ingress header 5 + metrics 6 + prometheus 3)
+- Runtime deps: 5 → 5 (**35 sub-release 連続据え置き**)
+- Backward compat: 完全互換、`context_budget_action` default は `"off"` — opt-in するまで既存挙動完全一致
+
+### 設定例
+
+```yaml
+profiles:
+  - name: long-session
+    providers: [ollama-qwen3]
+    context_budget_action: trim          # off | warn | trim
+    context_budget_warn_threshold: 0.80  # ratio で警告
+    context_budget_trim_threshold: 0.90  # ratio で自動 trim
+    context_budget_trim_target: 0.75     # trim 後の目標充填率
+    context_budget_preserve_last_n: 4    # 直近 N messages は必ず保持
+
+providers:
+  - name: ollama-qwen3
+    base_url: http://localhost:11434/v1
+    model: qwen3:30b-a3b
+    max_context_tokens: 32768            # 明示 (registry に乗ってない場合)
+```
+
+### Files touched (主要)
+
+```
+A  coderouter/token_estimation.py
+A  coderouter/guards/context_budget.py
+M  coderouter/config/schemas.py
+M  coderouter/routing/fallback.py
+M  coderouter/routing/auto_router.py
+M  coderouter/ingress/anthropic_routes.py
+M  coderouter/logging.py
+M  coderouter/metrics/collector.py
+M  coderouter/metrics/prometheus.py
+M  coderouter/cli_stats.py
+M  coderouter/data/model-capabilities.yaml
+A  tests/test_token_estimation.py
+A  tests/test_context_budget.py
+M  tests/test_ingress_anthropic.py
+M  tests/test_metrics_collector.py
+M  tests/test_metrics_prometheus.py
+A  docs/inside/v2.0-F-context-budget-plan.md
+```
+
+---
+
+## [v1.10.1] — 2026-05-04 (Patch — tool-aware auto routing + Raspberry Pi starter)
+
+**Theme: 「ローカル小型モデルでは tool calling できないので tool-laden な request だけクラウドに逃がしたい」というユースケース (OpenClaw + Pi 8GB シナリオ) を declarative に解決。** v1.10.0 で feature complete を宣言した auto_router の 6 matcher を 7 matcher に拡張、`has_tools` を追加して「tools[] を宣言したリクエストか否か」で profile を分岐できるように。併せて Raspberry Pi 8GB 向けの starter YAML (`examples/providers.raspberrypi.yaml`) を同梱、SBC 上で OpenClaw / Claude Code 互換 agent を回すユーザーが yaml 1 個 copy するだけで動く状態にした。
+
+含まれる出荷 2 件:
+
+| # | sub-release | テーマ | LOC | tests |
+|---|---|---|---|---|
+| 1 | **has_tools matcher** | `RuleMatcher.has_tools` 7 番目 matcher 追加、OpenAI/Anthropic `tools[]` + OpenAI legacy `functions[]` を一括認識 (OpenClaw + Pi 由来) | ~80 | +7 |
+| 2 | **Raspberry Pi starter** | `examples/providers.raspberrypi.yaml` 新規、Ollama 小型モデル (≤4B) + OpenRouter free 系 + `has_tools` ベースの tool-aware profile 振り分け | YAML のみ | (loader 検証で +0 直接、既存 parametric test に乗る) |
+
+- Tests: 871 → **878** (+7、has_tools matcher の 6 シナリオ + `has_tools: false` の "set 扱いだがマッチしない" 安全網テスト)
+- Runtime deps: 5 → 5 (**34 sub-release 連続据え置き**)
+- Backward compat: 完全互換、既存 yaml / API / log payload schema 完全に同じ、新フィールド (`has_tools`) を使わない deployment は挙動完全一致
+- pyproject version: 1.10.0 → 1.10.1
+
+### Migration
+
+不要。**v1.10.0 からの自然なアップグレード**:
+
+- `coderouter` コマンド名 / Python import 名 / providers.yaml の format / env 変数 / ingress URL すべて完全に同じ
+- 既存 `auto_router.rules[]` は何も変わらない、`has_tools` matcher を使い始めるには yaml に 1 行足すだけ
+- v1.10.0 で v1.6 系 auto_router を「6 matcher で feature complete」と宣言した直後の追加だが、同じ宣言型 framework の延長線で構造変更なし — 「7 matcher で改めて feature complete」と読み替えて差し支えない
+
+### Out of scope (v1.11 以降)
+
+- **Provider capability gate for tools** — `capabilities.tools=false` を fallback chain の skip ゲートとして機能させる案。本 patch は profile レベルで振り分ける方針 (router で chain を切り替える) で `has_tools` matcher を採用、provider レベルの skip ゲートは別 issue。CodeRouter の chain semantics (順次フォールバック + downgrade) の互換性検討が必要なため、必要性が確認できてから着手。
+- **小型ローカルモデルの tool-call repair 強化** — 現状 `tool_repair.py` は `<tool_call>{...}</tool_call>` ラッパ形式の救済を行うが、1-4B モデルが返す自由形式の text からの推測救済は別領域 (`tool_emulation`)。プロンプトテンプレ書き換えで誘導する手段もあり、設計検討は v2.0 後送り。
+
+### Files touched
+
+```
+A  examples/providers.raspberrypi.yaml
+M  CHANGELOG.md
+M  coderouter/config/schemas.py
+M  coderouter/routing/auto_router.py
+M  pyproject.toml
+M  tests/test_auto_router.py
+```
+
+---
+
+### has_tools matcher (OpenClaw + Raspberry Pi 由来)
+
+**Theme: tools[] を宣言したリクエストだけクラウドに振り分け、ローカル小型モデルは tool 不要の素朴な chat に専念させる。** Raspberry Pi 8GB / Jetson Nano クラスの SBC で OpenClaw 等の tool-aware agent を動かしたい時、CPU 推論で実用域に入る Ollama モデル (≤4B) は tool calling が苦手 (`finish_reason: tool_calls` を返さない / 引数 JSON が壊れる / 自由形式 text に bury される) で、結果として agent 側からは「tool 呼び出しが起きてない」状態になる。`auto_router.rules[].if.has_tools` を 7 番目の matcher として追加することで、profile レベルで「tools あり → クラウド (Qwen3-Coder/gpt-oss/Gemini-Flash の OpenRouter free)」「tools 無し → ローカル小型」を declarative に切り替えられる。
+
+ユースケース例 (Raspberry Pi 8GB starter `examples/providers.raspberrypi.yaml` から抜粋):
+
+```yaml
+auto_router:
+  rules:
+    - id: user:has-tools-go-cloud
+      profile: with-tools         # OpenRouter free 系のみ
+      match:
+        has_tools: true
+    - id: user:image-go-cloud
+      profile: vision              # Gemini Flash 1M ctx
+      match:
+        has_image: true
+    - id: user:longcontext-go-cloud
+      profile: longcontext
+      match:
+        content_token_count_min: 32000
+  default_rule_profile: local-chat # qwen3.5:2b/4b / gemma3:1b ローカル
+```
+
+OpenClaw (毎ターン Bash/Read/Write 等の tool を declare する agent) を `OPENAI_BASE_URL=http://<pi-ip>:8088/v1` で繋ぐと、tool-laden traffic は自動でクラウドに飛び、軽い chat だけが Pi 上のローカルで処理される。OPENROUTER_API_KEY のみ設定すればよく、有料 API は不要 (`ALLOW_PAID=false` がデフォルト)。
+
+#### なぜ provider レベルの capability gate ではなく profile レベルなのか
+
+`ProviderConfig.capabilities.tools=false` フラグは既存 (v0.x からある) だが、現状は `coderouter doctor` の診断表示と `model-capabilities.yaml` registry の解決に使うだけで、fallback chain における skip ゲートには接続されていない。`thinking` / `cache_control` には `will_degrade` ゲート (capability.py の `provider_supports_*`) があるが、tools には同等の skip 機構がない。これは既存の v0.3-D 「downgrade path」(non-native + tools[] あり → 非ストリーミング + tool_repair) に依存していて、provider が tools を返せなくても adapter エラーは出ず、上流から見ると success (空 tool_calls) で chain が fallthrough せず止まってしまう (= 観測症状: 「tool call されてない」)。
+
+provider レベルの skip ゲートを後付けするのは chain semantics に踏み込む変更で互換性検討が要るため、本 patch では **profile レベルの宣言型 lever** に留める方針を採用。chain semantics を変えず、auto_router rule の追加で同じ効果を得られ、かつ既存の 6 matcher と完全に同じ規約 (exactly one + first match wins + fast-fail at load) で導入できる。
+
+- Tests: 871 → **878** (+7: OpenAI tools[] / Anthropic tools[] / OpenAI legacy functions[] / no-tools fallthrough / 空リスト fallthrough / has_tools rule が code-fence rule より優先 / `has_tools: false` の "set 扱いだがマッチしない" 安全網)
+- Runtime deps: 5 → 5 (34 sub-release 連続据え置き)
+- Backward compat: 完全互換、既存 `auto_router` rule は何も変わらない、`has_tools` を使わない deployment は挙動完全一致
+
+#### Changes
+
+- `coderouter/config/schemas.py`:
+  - `RuleMatcher` に `has_tools: bool | None = None` を追加、`_MATCHER_FIELDS` tuple に追加 (zero/multiple-fields の "exactly one" バリデータが自動適用)。
+  - docstring の Variants セクションに 7 番目として `has_tools` を追記、boolean 形状が `has_image` と同じである理由 (`True` のみ意味を持ち、`False` は "set" 扱いだが `_match_rule` の `is True` チェックでマッチしない安全網) と、provider レベルの `capabilities.tools` flag との違い (前者は profile-level routing、後者は doctor の診断補助で chain skip ゲートではない) を明示。
+
+- `coderouter/routing/auto_router.py`:
+  - `_has_tools_in_body(body)` ヘルパを新設 — body の top-level `tools[]` (OpenAI Chat Completions / Anthropic Messages API 共通) と `functions[]` (OpenAI legacy、deprecated だが pinned SDK で残存) を一括認識、空リスト / None は False (lazy init 対応)。
+  - `_match_rule(rule, message, text, model, estimated_tokens, has_tools)` シグネチャに `has_tools: bool` を追加、`has_tools is True` 分岐を 7 番目として実装。
+  - `classify(...)` 内で `_has_tools_in_body(body)` を一度だけ呼んで rule iteration に渡す。`user_msg is None` でも `has_tools` rule は評価する (system-only prompt + tools[] declaration の構成にも対応)。
+  - `_emit_resolved` / `_emit_fallthrough` の `signals` payload に `has_tools` を追記、`auto-router-resolved` log で「tools あり判定で routing したか」が dashboard / Prometheus exporter から見える。
+
+- `tests/test_auto_router.py` Group 8 (tool-aware routing) を新設、7 ケース:
+  - `test_classify_request_with_openai_tools_routes_to_with_tools` — 基本ケース、OpenAI 形式 `tools[].function` → `with-tools` profile。
+  - `test_classify_request_with_anthropic_tools_routes_to_with_tools` — Anthropic 形式 `tools[].input_schema` も同じ top-level `tools` キーなので、単一 matcher で両 ingress カバー。
+  - `test_classify_request_with_legacy_functions_routes_to_with_tools` — OpenAI legacy `functions[]` (deprecated だが pinned SDK で残存) も tool-laden 扱い。
+  - `test_classify_request_without_tools_falls_through` — 逆ケース、tools 宣言なしの plain chat は `default_rule_profile` (Pi の場合は `local-chat`) に落ちる。
+  - `test_classify_empty_tools_list_treated_as_no_tools` — `tools: []` / `functions: []` (lazy init shape) は False 扱い、no-spurious-match property を pin。
+  - `test_classify_has_tools_first_match_wins_over_later_content_rule` — has_tools rule が code_fence rule より前に置かれた時、両方マッチする body でも先勝、global "first match wins" を新 matcher にも適用。
+  - `test_has_tools_false_rejected_at_load` — `has_tools: False` が `_exactly_one` を通過するが `_match_rule` の `is True` チェックでマッチしない安全網を文書化、誤設定時もデフォルト経路に落ちることを保証。
+
+#### Files touched
+
+```
+M  CHANGELOG.md
+M  coderouter/config/schemas.py
+M  coderouter/routing/auto_router.py
+M  pyproject.toml
+M  tests/test_auto_router.py
+```
+
+---
+
+### Raspberry Pi 8GB starter (`examples/providers.raspberrypi.yaml`)
+
+**Theme: SBC で OpenClaw を動かす最小構成を yaml 1 個に集約。** v1.10.1 で追加した `has_tools` matcher を主役にした starter で、`coderouter serve` 1 発で Pi 上のローカル ollama (qwen3.5:2b/4b、qwen2.5:1.5b、gemma3:1b) と OpenRouter free 系 (qwen3-coder:free / gpt-oss-120b:free / gemini-2.5-flash:free) が tool-aware に振り分けられる。OPENROUTER_API_KEY のみ要設定、有料 API キー不要 (`ALLOW_PAID=false` がデフォルト)。
+
+#### 設計の要点
+
+- **ローカル全部 `tools: false`** — Pi 8GB に乗る ≤4B モデルは tool_calls を安定して返せないため capability で明示的に `false`。これは doctor 診断用の宣言で、実 routing は `has_tools` matcher が profile レベルで振り分けるので二重防御になる。
+- **`num_ctx: 8192` + `num_predict: 1024` 制限** — Pi の CPU 推論は context 縮めた方が prefill が現実的、デフォルト ollama の 2048 だと OpenClaw の system prompt で詰む & 2048 から 32K に上げると prefill が分単位になるので 8K が現実的中間点。
+- **画像 / 長尺 (32K+) もクラウドへ** — Pi では Gemma 4 E4B (vision capable だが 9.6GB で 8GB Pi に乗らない) の代わりに、`has_image` rule で OpenRouter Gemini Flash (1M ctx + vision native) に逃がす。
+- **OpenRouter free 3 モデルで vendor diversity** — qwen-coder / gpt-oss / gemini-flash の 3 ベンダーを並べて、daily cap (~200 req/day per model per account) 当たり時の rate-limit 逃げ場を確保。
+- **`output_filters: [strip_thinking, strip_stop_markers]` を Qwen 系で常時適用** — Pi で動かす Qwen 3.5 系は `<think>...</think>` リーク + `<|im_end|>` 漏れの両方を観測、両方 strip。
+
+#### Tests
+
+`tests/test_examples_yaml.py::test_example_yaml_loads` が `examples/providers*.yaml` を parametric にカバーしているため、`providers.raspberrypi.yaml` も自動でこの test に乗る。新たに pin したい invariant (例: ローカル全部 `tools: false`、`has_tools` rule の存在、auto_router default が `local-chat` 等) があれば後続 patch で個別 test 追加可能だが、本 patch では parametric の loader-clean property のみ確保。
+
+#### Files touched
+
+```
+A  examples/providers.raspberrypi.yaml
+```
+
+---
+
 ## [v1.10.0] — 2026-05-01 (Umbrella tag — Cost enforcement + Long-run reliability completion + Auto-router feature complete)
 
 **Theme: 「観測 → 理解 → 行動」を 3 軸で完成、Vision pillar P2/P3 が揃う。** v1.9.1 (patch) で取り切った 2 機能 (v1.9-B2 streaming usage 集約 + per-model auto-routing) は事実上 v1.10 backlog の助走、本 v1.10.0 で残り 3 機能を minor として束ねて出荷。CodeRouter は **「Local LLM で agent を長時間回すための信頼性層」** という Vision の v1.x 担当分が完成 — context overflow (L1) と quality drift (L4) を除く 4 系統障害 (L2/L3/L5/L6) を体系的に対処、auto-router の declarative 6 matcher も揃い、cost 系は観測 (v1.9-D) → enforcement (v1.10) で経路が閉じた。

{coderouter_cli-1.10.0 → coderouter_cli-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 1.10.0
+Version: 2.0.0
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml"><img src="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
   <a href=""><img src="https://img.shields.io/badge/status-stable-brightgreen" alt="status"></a>
-  <a href=""><img src="https://img.shields.io/badge/version-1.10.0-blue" alt="version"></a>
+  <a href=""><img src="https://img.shields.io/badge/version-2.0.0-blue" alt="version"></a>
   <a href=""><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="python"></a>
   <a href=""><img src="https://img.shields.io/badge/runtime%20deps-5-brightgreen" alt="deps"></a>
   <a href=""><img src="https://img.shields.io/badge/license-MIT-yellow" alt="license"></a>
@@ -90,7 +90,8 @@ Description-Content-Type: text/markdown
 - v1.9.0 から **adaptive routing** で「いま遅い provider」を自動降格（profile に `adaptive: true` を付けるだけ）、**tool-loop guard** で stuck loop を検出（`warn` / `inject` / `break` の 3 段階 policy）
 - **v1.10.0 で Long-run reliability pillar が完成**: `cost.monthly_budget_usd` で provider 月次 USD 予算を強制、**L2 memory pressure detector**（Ollama / LM Studio が VRAM 切れで OOM になった時に自動クールダウン）、**L5 backend health 状態機械**（連続失敗で UNHEALTHY → chain 末尾に降格、1 回成功で即復帰）
 - **v1.10.0 で auto-router が 6 matcher に揃う**: `has_image` / `code_fence_ratio_min` / `content_contains` / `content_regex` / `model_pattern`（Opus/Sonnet/Haiku 分岐）/ `content_token_count_min`（長文 → 1M ctx Gemini Flash 等へ自動切替）
-- ランタイム依存 5 個（`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`）— 純 Python、MIT、テスト 871 本緑
+- **v2.0.0 で Context Budget Management (L1 overflow 防止) を搭載**: 長時間 agent session で messages が context window に漸近 → backend 400 エラーで session 死亡する問題を根本解決。warn (80%) → auto trim (90%) の 2 段階 guard で **context overflow ゼロ**を実現。tool_use / tool_result ペアは atomic 保全、`X-CodeRouter-Context-Budget` ヘッダで状態通知、Prometheus メトリクス完備
+- ランタイム依存 5 個（`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`）— 純 Python、MIT、テスト 930 本緑
 
 → **Claude Code / gemini-cli / codex + Ollama / llama.cpp / NVIDIA NIM で、破綻しない local-first agent が組める**
 
@@ -102,11 +103,12 @@ Description-Content-Type: text/markdown
 | **使いこなす** | [利用ガイド](./docs/usage-guide.md) | HW 別モデル選定・チューニング既定値・OS ごとの起動フロー・`doctor` / `verify` の読み方 |
 | **無料で回す** | [無料枠ガイド](./docs/free-tier-guide.md) | NVIDIA NIM 40 req/min × OpenRouter 無料枠の使い分け・live 検証済みモデル表・地雷 5 点 |
 | **要るか判断する** | [要否判定ガイド](./docs/when-do-i-need-coderouter.md) | エージェント × モデルの詳細マトリクスで「そもそも自分に必要か」を決める |
+| **長時間 session** | [Context Budget](./docs/context-budget.md) | v2.0.0 新機能。長時間 agent session の context overflow を自動防止する guard の設定・仕組み・可観測性 |
 | **詰まったとき** | [トラブルシューティング](./docs/troubleshooting.md) | `doctor` の使い方、`.env` の export 必須、Ollama サイレント失敗 5 症状、Claude Code 連携の罠 |
 | **llama.cpp 直叩き** | [llama.cpp 直叩きガイド](./docs/llamacpp-direct.md) | Qwen3.6 を Ollama 詰みから救出する経路。`llama.cpp` build → Unsloth GGUF → `llama-server` → CodeRouter 接続を 7 step で（v1.8.3 実機検証済）|
 | **LM Studio 直接** | [LM Studio 直接ガイド](./docs/lmstudio-direct.md) | `qwen35` / `qwen35moe` を救う第 2 経路。LM Studio 0.4.12+ Local Server 経由で OpenAI 互換 + Anthropic 互換 (`/v1/messages`) 両対応、prompt caching 透過（v1.8.4 実機検証済）|
 | **安全に使う** | [セキュリティ方針](./docs/security.md) | 脅威モデル・秘密情報の扱い・脆弱性報告経路 |
-| **履歴** | [CHANGELOG](./CHANGELOG.md) | 全リリース履歴（最新: v1.10.0 — Cost enforcement (`monthly_budget_usd`) + Long-run reliability completion (L2 memory pressure / L5 backend health) + Auto-router feature complete (6 matcher) を 1 minor で出荷） |
+| **履歴** | [CHANGELOG](./CHANGELOG.md) | 全リリース履歴（最新: v2.0.0 — Context Budget Management (L1 overflow 防止) で長時間 agent session の安定性を根本改善） |
 | **設計を追う** | [plan.md](./plan.md) | 設計不変項・マイルストーン・今後のロードマップ |
 
 English versions: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-guide.en.md) · [Free-tier guide](./docs/free-tier-guide.en.md) · [When you need it](./docs/when-do-i-need-coderouter.en.md) · [Troubleshooting](./docs/troubleshooting.en.md) · [llama.cpp direct](./docs/llamacpp-direct.en.md) · [LM Studio direct](./docs/lmstudio-direct.en.md) · [Security](./docs/security.en.md)
@@ -122,7 +124,7 @@ CodeRouter は、コーディングエージェント（Claude Code / gemini-cli
 - **うっかり課金しない。** `ALLOW_PAID=false` が既定。有料プロバイダをチェーンから外したときは理由を 1 行ログに出すので、なぜ使われなかったかが後で grep できます。
 - **ローカル Ollama の上で Claude Code / gemini-cli / codex が動く。** Claude Code は Anthropic のワイアフォーマット、Ollama / llama.cpp / LM Studio は OpenAI。CodeRouter が双方向に変換し、小さいローカルモデルがテキストで吐いてしまう `{"name":..., "arguments":...}` を tool_use ブロックへ復元してからエージェントに渡します。
 - **「なぜか動かない」の原因を教えてくれる。** `coderouter doctor --check-model <provider>` が 6 種類の典型的な失敗モード（コンテキスト切り詰め / ストリーム早期終了 / ツール呼び出し欠落 / reasoning フィールド漏れ / 認証 / Anthropic `thinking`）を実地プローブし、コピペ可能な YAML パッチを出します。
-- **監査しやすい。** ランタイム依存 5 個（LiteLLM は 100+）。Pure Python、MIT、テスト 871 本緑。
+- **監査しやすい。** ランタイム依存 5 個（LiteLLM は 100+）。Pure Python、MIT、テスト 930 本緑。
 
 ```
 クライアント (Claude Code / OpenAI SDK / gemini-cli / codex / curl)
@@ -196,7 +198,7 @@ CodeRouter / Voice Bridge ともに独立した repo で進化していて、HTT
 
 ## クイックスタート（3 コマンド）
 
-**v1.7.0 で PyPI 公開**、**v1.8.0 で用途別 4 プロファイル + Z.AI/GLM 連携**、**v1.9.0 で Cache observability / Adaptive routing / Cost-aware dashboard / Tool-loop guard を pillar 化**、**v1.10.0 で Cost enforcement (`monthly_budget_usd`) / Long-run reliability (L2 memory pressure + L5 backend health) / Auto-router 6 matcher feature complete を出荷**しました。`uvx` 一発で動きます (Python 3.12 以上必須):
+**v2.0.0 で Context Budget Management (L1 overflow 防止) を搭載** — 長時間 agent session が context window を使い切って死ぬ問題を根本解決。`uvx` 一発で動きます (Python 3.12 以上必須):
 
 ```bash
 # 1. サンプル設定を置く
@@ -264,9 +266,9 @@ CodeRouter 自体は純 Python 3.12+ で、実質的な OS 対応範囲は `min(
 
 注意点や「ローカル GPU なし」向けレシピを含むフル版マトリクス: [利用ガイド §1](./docs/usage-guide.md#1-os-互換性)
 
-## ステータス — v1.10.0 minor (2026-05)
+## ステータス — v2.0.0 (2026-05)
 
-**テスト 871 本通過。ランタイム依存 5 個 (33 sub-release 連続据え置き)。macOS / Linux / Windows WSL2 で動作。** ルーターは日常的な Claude Code 用途で安定し、v1.10.0 で **Vision pillar P2 Long-run Reliability** が完成 (L2/L3/L5)、**Cost pillar** が観測 → 制約まで閉じる、**Auto-router** が 6 matcher で feature complete に到達しました。v1.0 の総まとめは [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md)。
+**テスト 930 本通過。ランタイム依存 5 個 (36 sub-release 連続据え置き)。macOS / Linux / Windows WSL2 で動作。** v2.0.0 で **Context Budget Management (L1 overflow 防止)** を搭載 — 長時間 agent session が context window を使い切って死ぬ問題を根本解決。v1.10.0 までに **Long-run Reliability** (L2/L3/L5)、**Cost pillar**、**Auto-router 6 matcher** が完成済み。v1.0 の総まとめは [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md)。
 
 今日の CodeRouter が届ける価値:
 

{coderouter_cli-1.10.0 → coderouter_cli-2.0.0}/README.en.md

@@ -20,7 +20,7 @@
 <p align="center">
   <a href="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml"><img src="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
   <a href=""><img src="https://img.shields.io/badge/status-stable-brightgreen" alt="status"></a>
-  <a href=""><img src="https://img.shields.io/badge/version-1.10.0-blue" alt="version"></a>
+  <a href=""><img src="https://img.shields.io/badge/version-2.0.0-blue" alt="version"></a>
   <a href=""><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="python"></a>
   <a href=""><img src="https://img.shields.io/badge/runtime%20deps-5-brightgreen" alt="deps"></a>
   <a href=""><img src="https://img.shields.io/badge/license-MIT-yellow" alt="license"></a>
@@ -49,7 +49,8 @@
 - v1.9.0 ships **adaptive routing** that auto-demotes a temporarily-slow provider (set `adaptive: true` on a profile) and a **tool-loop guard** that catches stuck-loop patterns with a 3-tier policy (`warn` / `inject` / `break`)
 - **v1.10.0 completes the long-run reliability pillar**: `cost.monthly_budget_usd` enforces a per-provider monthly USD cap, the **L2 memory-pressure detector** automatically cools down a backend when Ollama / LM Studio reports VRAM exhaustion, and the **L5 backend-health state machine** demotes UNHEALTHY providers to the back of the chain (consecutive-failure threshold, single-success recovery)
 - **v1.10.0 brings the auto-router to 6 matchers**: `has_image` / `code_fence_ratio_min` / `content_contains` / `content_regex` / `model_pattern` (Opus/Sonnet/Haiku branching) / `content_token_count_min` (long prompts → 1M-ctx Gemini Flash, etc.)
-- Five runtime dependencies (`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`) — pure Python, MIT, 871 tests green
+- **v2.0.0 ships Context Budget Management (L1 overflow prevention)**: long-running agent sessions approaching the context window are automatically trimmed — warn at 80%, auto-trim at 90%, tool_use/tool_result pairs preserved atomically, `X-CodeRouter-Context-Budget` response header, Prometheus metrics included
+- Five runtime dependencies (`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`) — pure Python, MIT, 930 tests green
 
 → **Claude Code / gemini-cli / codex on top of Ollama / llama.cpp / NVIDIA NIM, without the agent falling apart.**
 
@@ -65,7 +66,7 @@
 | **llama.cpp direct** | [llama.cpp direct guide](./docs/llamacpp-direct.en.md) | Rescue path for Qwen3.6 (Ollama is brittle). 7-step recipe: `llama.cpp` build → Unsloth GGUF → `llama-server` → CodeRouter wiring. Real-machine verified in v1.8.3. |
 | **LM Studio direct** | [LM Studio direct guide](./docs/lmstudio-direct.en.md) | Second rescue path for `qwen35` / `qwen35moe`. LM Studio 0.4.12+ Local Server with both OpenAI-compatible and Anthropic-compatible (`/v1/messages`) routes — prompt caching survives end-to-end. Real-machine verified in v1.8.4. |
 | **Operate safely** | [Security](./docs/security.en.md) | Threat model, secret handling, vulnerability reporting |
-| **History** | [CHANGELOG](./CHANGELOG.md) | All releases (latest: v1.10.0 — Cost enforcement (`monthly_budget_usd`) + Long-run reliability completion (L2 memory pressure / L5 backend health) + Auto-router feature complete (6 matchers) shipped in one minor) |
+| **History** | [CHANGELOG](./CHANGELOG.md) | All releases (latest: v2.0.0 — Context Budget Management (L1 overflow prevention) for rock-solid long-running agent sessions) |
 | **Track the design** | [plan.md](./plan.md) | Design invariants, milestones, roadmap |
 
 日本語版: [Quickstart](./docs/quickstart.md) · [利用ガイド](./docs/usage-guide.md) · [無料枠ガイド](./docs/free-tier-guide.md) · [要否判定](./docs/when-do-i-need-coderouter.md) · [トラブルシューティング](./docs/troubleshooting.md) · [LM Studio 直接](./docs/lmstudio-direct.md) · [Security](./docs/security.md)
@@ -81,7 +82,7 @@ Concretely, it takes care of things most beginners hit the hard way:
 - **No surprise bill.** `ALLOW_PAID=false` is the default; when CodeRouter drops a paid provider from the chain it logs one clear line so you can see why.
 - **Use Claude Code / gemini-cli / codex on top of local Ollama.** Claude Code speaks Anthropic wire format, Ollama / llama.cpp / LM Studio speak OpenAI. CodeRouter translates both directions, and repairs the malformed `{"name":..., "arguments":...}` JSON that small local models emit as plain text.
 - **Know *why* your local model is acting weird.** `coderouter doctor --check-model <provider>` probes six common failure modes (context truncation, streaming cutoff, missing tool-use, reasoning leaks, auth, Anthropic `thinking`) and prints a copy-paste YAML patch.
-- **Auditable.** 5 runtime dependencies (vs. 100+ for LiteLLM). Pure Python, MIT, 871 tests passing.
+- **Auditable.** 5 runtime dependencies (vs. 100+ for LiteLLM). Pure Python, MIT, 930 tests passing.
 
 ```
 Client (Claude Code / OpenAI SDK / gemini-cli / codex / curl)
@@ -155,7 +156,7 @@ CodeRouter and Voice Bridge live in separate repos and evolve independently, con
 
 ## Quickstart (2 commands)
 
-**v1.7.0 published to PyPI**, **v1.8.0 added use-case-aware 4 profiles + Z.AI/GLM integration**, **v1.9.0 promoted cache observability / adaptive routing / cost-aware dashboard / tool-loop guard to first-class pillars**, **v1.10.0 shipped Cost enforcement (`monthly_budget_usd`) / Long-run reliability completion (L2 memory pressure + L5 backend health) / Auto-router feature complete (6 matchers)**. `uvx` installs and runs in one shot (Python 3.12+ required):
+**v2.0.0 ships Context Budget Management (L1 overflow prevention)** — long-running agent sessions that approach the context window are automatically trimmed to prevent session death. `uvx` installs and runs in one shot (Python 3.12+ required):
 
 ```bash
 # 1. Drop a sample config
@@ -224,9 +225,9 @@ CodeRouter is pure Python 3.12+; OS support is effectively `min(coderouter, olla
 
 Full matrix with caveats and the "no local GPU" recipe: [usage guide §1](./docs/usage-guide.en.md#1-os-compatibility).
 
-## Status — v1.10.0 minor (2026-05)
+## Status — v2.0.0 (2026-05)
 
-**871 tests pass. 5 runtime dependencies (33 sub-releases held to the same 5).** Works on macOS / Linux / Windows WSL2. The router is stable for day-to-day Claude Code use, and v1.10.0 closes out the **Vision pillar P2 (Long-run reliability, L2/L3/L5)**, the **Cost pillar (observation → enforcement)**, and **Auto-router feature complete (6 matchers)**. The v1.0 wrap-up is in [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md).
+**930 tests pass. 5 runtime dependencies (36 sub-releases held to the same 5).** Works on macOS / Linux / Windows WSL2. v2.0.0 ships **Context Budget Management (L1 overflow prevention)** — the final piece for rock-solid long-running agent sessions. Previous milestones: **Long-run Reliability** (L2/L3/L5), **Cost pillar**, **Auto-router 6 matchers**. The v1.0 wrap-up is in [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md).
 
 What CodeRouter can do for you today:
 

{coderouter_cli-1.10.0 → coderouter_cli-2.0.0}/README.md

@@ -19,7 +19,7 @@
 <p align="center">
   <a href="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml"><img src="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
   <a href=""><img src="https://img.shields.io/badge/status-stable-brightgreen" alt="status"></a>
-  <a href=""><img src="https://img.shields.io/badge/version-1.10.0-blue" alt="version"></a>
+  <a href=""><img src="https://img.shields.io/badge/version-2.0.0-blue" alt="version"></a>
   <a href=""><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="python"></a>
   <a href=""><img src="https://img.shields.io/badge/runtime%20deps-5-brightgreen" alt="deps"></a>
   <a href=""><img src="https://img.shields.io/badge/license-MIT-yellow" alt="license"></a>
@@ -49,7 +49,8 @@
 - v1.9.0 から **adaptive routing** で「いま遅い provider」を自動降格（profile に `adaptive: true` を付けるだけ）、**tool-loop guard** で stuck loop を検出（`warn` / `inject` / `break` の 3 段階 policy）
 - **v1.10.0 で Long-run reliability pillar が完成**: `cost.monthly_budget_usd` で provider 月次 USD 予算を強制、**L2 memory pressure detector**（Ollama / LM Studio が VRAM 切れで OOM になった時に自動クールダウン）、**L5 backend health 状態機械**（連続失敗で UNHEALTHY → chain 末尾に降格、1 回成功で即復帰）
 - **v1.10.0 で auto-router が 6 matcher に揃う**: `has_image` / `code_fence_ratio_min` / `content_contains` / `content_regex` / `model_pattern`（Opus/Sonnet/Haiku 分岐）/ `content_token_count_min`（長文 → 1M ctx Gemini Flash 等へ自動切替）
-- ランタイム依存 5 個（`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`）— 純 Python、MIT、テスト 871 本緑
+- **v2.0.0 で Context Budget Management (L1 overflow 防止) を搭載**: 長時間 agent session で messages が context window に漸近 → backend 400 エラーで session 死亡する問題を根本解決。warn (80%) → auto trim (90%) の 2 段階 guard で **context overflow ゼロ**を実現。tool_use / tool_result ペアは atomic 保全、`X-CodeRouter-Context-Budget` ヘッダで状態通知、Prometheus メトリクス完備
+- ランタイム依存 5 個（`fastapi` / `uvicorn` / `httpx` / `pydantic` / `pyyaml`）— 純 Python、MIT、テスト 930 本緑
 
 → **Claude Code / gemini-cli / codex + Ollama / llama.cpp / NVIDIA NIM で、破綻しない local-first agent が組める**
 
@@ -61,11 +62,12 @@
 | **使いこなす** | [利用ガイド](./docs/usage-guide.md) | HW 別モデル選定・チューニング既定値・OS ごとの起動フロー・`doctor` / `verify` の読み方 |
 | **無料で回す** | [無料枠ガイド](./docs/free-tier-guide.md) | NVIDIA NIM 40 req/min × OpenRouter 無料枠の使い分け・live 検証済みモデル表・地雷 5 点 |
 | **要るか判断する** | [要否判定ガイド](./docs/when-do-i-need-coderouter.md) | エージェント × モデルの詳細マトリクスで「そもそも自分に必要か」を決める |
+| **長時間 session** | [Context Budget](./docs/context-budget.md) | v2.0.0 新機能。長時間 agent session の context overflow を自動防止する guard の設定・仕組み・可観測性 |
 | **詰まったとき** | [トラブルシューティング](./docs/troubleshooting.md) | `doctor` の使い方、`.env` の export 必須、Ollama サイレント失敗 5 症状、Claude Code 連携の罠 |
 | **llama.cpp 直叩き** | [llama.cpp 直叩きガイド](./docs/llamacpp-direct.md) | Qwen3.6 を Ollama 詰みから救出する経路。`llama.cpp` build → Unsloth GGUF → `llama-server` → CodeRouter 接続を 7 step で（v1.8.3 実機検証済）|
 | **LM Studio 直接** | [LM Studio 直接ガイド](./docs/lmstudio-direct.md) | `qwen35` / `qwen35moe` を救う第 2 経路。LM Studio 0.4.12+ Local Server 経由で OpenAI 互換 + Anthropic 互換 (`/v1/messages`) 両対応、prompt caching 透過（v1.8.4 実機検証済）|
 | **安全に使う** | [セキュリティ方針](./docs/security.md) | 脅威モデル・秘密情報の扱い・脆弱性報告経路 |
-| **履歴** | [CHANGELOG](./CHANGELOG.md) | 全リリース履歴（最新: v1.10.0 — Cost enforcement (`monthly_budget_usd`) + Long-run reliability completion (L2 memory pressure / L5 backend health) + Auto-router feature complete (6 matcher) を 1 minor で出荷） |
+| **履歴** | [CHANGELOG](./CHANGELOG.md) | 全リリース履歴（最新: v2.0.0 — Context Budget Management (L1 overflow 防止) で長時間 agent session の安定性を根本改善） |
 | **設計を追う** | [plan.md](./plan.md) | 設計不変項・マイルストーン・今後のロードマップ |
 
 English versions: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-guide.en.md) · [Free-tier guide](./docs/free-tier-guide.en.md) · [When you need it](./docs/when-do-i-need-coderouter.en.md) · [Troubleshooting](./docs/troubleshooting.en.md) · [llama.cpp direct](./docs/llamacpp-direct.en.md) · [LM Studio direct](./docs/lmstudio-direct.en.md) · [Security](./docs/security.en.md)
@@ -81,7 +83,7 @@ CodeRouter は、コーディングエージェント（Claude Code / gemini-cli
 - **うっかり課金しない。** `ALLOW_PAID=false` が既定。有料プロバイダをチェーンから外したときは理由を 1 行ログに出すので、なぜ使われなかったかが後で grep できます。
 - **ローカル Ollama の上で Claude Code / gemini-cli / codex が動く。** Claude Code は Anthropic のワイアフォーマット、Ollama / llama.cpp / LM Studio は OpenAI。CodeRouter が双方向に変換し、小さいローカルモデルがテキストで吐いてしまう `{"name":..., "arguments":...}` を tool_use ブロックへ復元してからエージェントに渡します。
 - **「なぜか動かない」の原因を教えてくれる。** `coderouter doctor --check-model <provider>` が 6 種類の典型的な失敗モード（コンテキスト切り詰め / ストリーム早期終了 / ツール呼び出し欠落 / reasoning フィールド漏れ / 認証 / Anthropic `thinking`）を実地プローブし、コピペ可能な YAML パッチを出します。
-- **監査しやすい。** ランタイム依存 5 個（LiteLLM は 100+）。Pure Python、MIT、テスト 871 本緑。
+- **監査しやすい。** ランタイム依存 5 個（LiteLLM は 100+）。Pure Python、MIT、テスト 930 本緑。
 
 ```
 クライアント (Claude Code / OpenAI SDK / gemini-cli / codex / curl)
@@ -155,7 +157,7 @@ CodeRouter / Voice Bridge ともに独立した repo で進化していて、HTT
 
 ## クイックスタート（3 コマンド）
 
-**v1.7.0 で PyPI 公開**、**v1.8.0 で用途別 4 プロファイル + Z.AI/GLM 連携**、**v1.9.0 で Cache observability / Adaptive routing / Cost-aware dashboard / Tool-loop guard を pillar 化**、**v1.10.0 で Cost enforcement (`monthly_budget_usd`) / Long-run reliability (L2 memory pressure + L5 backend health) / Auto-router 6 matcher feature complete を出荷**しました。`uvx` 一発で動きます (Python 3.12 以上必須):
+**v2.0.0 で Context Budget Management (L1 overflow 防止) を搭載** — 長時間 agent session が context window を使い切って死ぬ問題を根本解決。`uvx` 一発で動きます (Python 3.12 以上必須):
 
 ```bash
 # 1. サンプル設定を置く
@@ -223,9 +225,9 @@ CodeRouter 自体は純 Python 3.12+ で、実質的な OS 対応範囲は `min(
 
 注意点や「ローカル GPU なし」向けレシピを含むフル版マトリクス: [利用ガイド §1](./docs/usage-guide.md#1-os-互換性)
 
-## ステータス — v1.10.0 minor (2026-05)
+## ステータス — v2.0.0 (2026-05)
 
-**テスト 871 本通過。ランタイム依存 5 個 (33 sub-release 連続据え置き)。macOS / Linux / Windows WSL2 で動作。** ルーターは日常的な Claude Code 用途で安定し、v1.10.0 で **Vision pillar P2 Long-run Reliability** が完成 (L2/L3/L5)、**Cost pillar** が観測 → 制約まで閉じる、**Auto-router** が 6 matcher で feature complete に到達しました。v1.0 の総まとめは [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md)。
+**テスト 930 本通過。ランタイム依存 5 個 (36 sub-release 連続据え置き)。macOS / Linux / Windows WSL2 で動作。** v2.0.0 で **Context Budget Management (L1 overflow 防止)** を搭載 — 長時間 agent session が context window を使い切って死ぬ問題を根本解決。v1.10.0 までに **Long-run Reliability** (L2/L3/L5)、**Cost pillar**、**Auto-router 6 matcher** が完成済み。v1.0 の総まとめは [`docs/retrospectives/v1.0.md`](./docs/retrospectives/v1.0.md)。
 
 今日の CodeRouter が届ける価値:
 

{coderouter_cli-1.10.0 → coderouter_cli-2.0.0}/coderouter/cli_stats.py

@@ -112,6 +112,10 @@ class GatesSummary:
     degraded_breakdown: dict[str, int]  # capability → count
     filters_applied_total: int
     filters_breakdown: dict[str, int]  # filter name → count
+    # v2.0-F (L1): context budget guard summary
+    context_budget_warnings: int = 0
+    context_budget_trims: int = 0
+    context_budget_latest_ratio: dict[str, float] | None = None
 
 
 @dataclass(frozen=True)
@@ -252,6 +256,8 @@ def build_gates_summary(snapshot: dict[str, Any]) -> GatesSummary:
     )
     degraded_breakdown = dict(counters.get("capability_degraded", {}) or {})
     filters_breakdown = dict(counters.get("output_filter_applied", {}) or {})
+    # v2.0-F (L1): context budget guard counters
+    ctx_budget_latest = counters.get("context_budget_latest_ratio") or {}
     return GatesSummary(
         total_requests=total_requests,
         total_failed=total_failed,
@@ -261,6 +267,13 @@ def build_gates_summary(snapshot: dict[str, Any]) -> GatesSummary:
         degraded_breakdown=degraded_breakdown,
         filters_applied_total=sum(filters_breakdown.values()),
         filters_breakdown=filters_breakdown,
+        context_budget_warnings=int(
+            counters.get("context_budget_warnings_total", 0)
+        ),
+        context_budget_trims=int(
+            counters.get("context_budget_trims_total", 0)
+        ),
+        context_budget_latest_ratio=ctx_budget_latest if ctx_budget_latest else None,
     )
 
 
@@ -397,6 +410,19 @@ def format_text(snapshot: dict[str, Any], *, width: int = 80) -> str:
             else ""
         )
     )
+    # v2.0-F (L1): context budget guard stats
+    if gates.context_budget_warnings or gates.context_budget_trims:
+        ratio_str = ""
+        if gates.context_budget_latest_ratio:
+            top_profile = max(
+                gates.context_budget_latest_ratio,
+                key=gates.context_budget_latest_ratio.get,  # type: ignore[arg-type]
+            )
+            ratio_str = f"  (latest: {gates.context_budget_latest_ratio[top_profile]:.0%} {top_profile})"
+        lines.append(
+            f"  context-budget warn:   {gates.context_budget_warnings}  "
+            f"trim: {gates.context_budget_trims}{ratio_str}"
+        )
     lines.append("")
     lines.append("Recent")
     if not recent:
@@ -633,7 +659,28 @@ def _draw_frame(  # pragma: no cover - curses-only
         + (f"  ({_fmt_breakdown(gates.filters_breakdown)})" if gates.filters_breakdown else ""),
         width,
     )
-    row += 2
+    row += 1
+    # v2.0-F (L1): context budget guard line
+    if gates.context_budget_warnings or gates.context_budget_trims:
+        ratio_str = ""
+        if gates.context_budget_latest_ratio:
+            top_profile = max(
+                gates.context_budget_latest_ratio,
+                key=gates.context_budget_latest_ratio.get,  # type: ignore[arg-type]
+            )
+            ratio_str = f"  (latest: {gates.context_budget_latest_ratio[top_profile]:.0%} {top_profile})"
+        budget_line = (
+            f"  context-budget warn:   {gates.context_budget_warnings}  "
+            f"trim: {gates.context_budget_trims}{ratio_str}"
+        )
+        budget_color = (
+            _COLOR_YELLOW_PAIR
+            if gates.context_budget_trims == 0
+            else _COLOR_RED_PAIR
+        )
+        stdscr.addnstr(row, 0, budget_line, width, int(curses.color_pair(budget_color)))
+        row += 1
+    row += 1
 
     if row >= height - 2:
         return