coderouter-cli 2.9.1__tar.gz → 2.9.2__tar.gz

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/CHANGELOG.md

@@ -9,6 +9,42 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.9.2] — 2026-07-12 (config: no more dummy provider for swap-only setups)
+
+### Changed
+
+- **`providers` / `profiles` no longer require a dummy entry for swap-only
+  deployments.** Both top-level lists were `min_length=1` (or effectively
+  required), forcing an unreachable placeholder provider/profile (e.g.
+  `base_url: http://127.0.0.1:9`) into any config that only serves models
+  through `launcher.swap`. They are now optional (`providers: []` /
+  `profiles: []`, or omitted entirely) whenever `launcher.swap.enabled: true`
+  and `launcher.swap.models` has at least one entry — the injected
+  `launcher-swap-<name>` profile(s) already cover routing, and their
+  providers are registered at runtime on first on-demand spawn. Every other
+  deployment shape keeps the original fail-fast-at-load guarantee (now
+  enforced by `CodeRouterConfig._check_providers_and_profiles_nonempty`
+  rather than the field-level `min_length=1` it replaces), with an error
+  message pointing at the swap-only exemption. See
+  `tests/test_launcher_swap.py`
+  (`test_swap_only_config_loads_with_omitted_providers_and_profiles` and
+  neighbors) for the minimal swap-only config shape.
+
+### Docs
+
+- `docs/backends/launcher.md` / `.en.md` — added the `launcher.swap` (v2.9.1+)
+  reference: what it does, a minimal swap-only config (no `providers` /
+  `profiles`, verified against the real loader), a `launcher.swap.models[]`
+  field table, the Phase 2 schema-only fields, and behavioral notes
+  (auto-restart exclusion, streaming lease protection, catalog-miss
+  fallthrough, no simultaneous-load cap). Also documented the `launcher:`-level
+  `readiness_timeout_s` / `readiness_poll_interval_s` / `auto_restart*` fields
+  and the new `loading` process status in the configuration reference
+  section, and linked `docs/designs/launcher-model-swap.md` from "Related
+  docs" — closing the "残課題" noted in that design doc's §10.5.
+
+---
+
 ## [v2.9.1] — 2026-07-12 (launcher model swap Phase 1 — llama-swap-style on-demand models)
 
 **New: `launcher.swap`** — an opt-in, dependency-free equivalent of

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.9.1
+Version: 2.9.2
 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

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/coderouter/config/schemas.py

@@ -1951,8 +1951,16 @@ class CodeRouterConfig(BaseModel):
         description="Master switch. ALLOW_PAID=false blocks all paid providers (plan.md §2.3).",
     )
     default_profile: str = Field(default="default")
-    providers: list[ProviderConfig] = Field(..., min_length=1)
-    profiles: list[FallbackChain] = Field(..., min_length=1)
+    # [Unreleased]: relaxed from ``Field(..., min_length=1)`` so a
+    # swap-only deployment (``launcher.swap.enabled`` with a non-empty
+    # ``models`` catalog) can omit both fields entirely instead of
+    # writing an unreachable dummy provider/profile just to satisfy the
+    # schema. The "at least one" invariant is NOT dropped — it moves to
+    # ``_check_providers_and_profiles_nonempty`` below, which still
+    # fail-fasts at load for every other deployment shape (same
+    # philosophy as the min_length constraint it replaces).
+    providers: list[ProviderConfig] = Field(default_factory=list)
+    profiles: list[FallbackChain] = Field(default_factory=list)
     mode_aliases: dict[str, str] = Field(
         default_factory=dict,
         description=(
@@ -2159,6 +2167,52 @@ class CodeRouterConfig(BaseModel):
                 )
         return self
 
+    @model_validator(mode="after")
+    def _check_providers_and_profiles_nonempty(self) -> CodeRouterConfig:
+        """[Unreleased]: enforce "at least one" unless launcher.swap covers it.
+
+        ``providers`` / ``profiles`` were relaxed from ``min_length=1`` to
+        ``default_factory=list`` (see the field comments above) so a
+        swap-only deployment can omit them — every request in that shape
+        is routed through a ``launcher-swap-<name>`` profile that
+        :meth:`_inject_swap_profiles_and_auto_router_rules` synthesizes
+        below, and its backing provider is registered at runtime on first
+        spawn (``SwapManager.register_provider``), so there is genuinely
+        nothing to declare statically.
+
+        Runs BEFORE the swap injection (which only ever *adds* profiles,
+        never providers) so it observes the operator's raw, undecorated
+        input rather than the post-injection state — the injected
+        profiles are not a substitute for a real provider declaration in
+        every other deployment shape, only in the swap-only one this
+        validator carves out.
+
+        Outside that carve-out, an empty ``providers`` or ``profiles``
+        list has always been a load-time error (there would be nothing to
+        route to); this validator keeps that fail-fast guarantee instead
+        of silently trading it away when the ``min_length=1`` field
+        constraint was dropped.
+        """
+        swap_cfg = self.launcher.swap if self.launcher is not None else None
+        swap_covers_empty = (
+            swap_cfg is not None and swap_cfg.enabled and bool(swap_cfg.models)
+        )
+        if swap_covers_empty:
+            return self
+        if not self.providers:
+            raise ValueError(
+                "providers: at least one entry is required (empty/omitted "
+                "is only allowed when launcher.swap.enabled=true and "
+                "launcher.swap.models has at least one entry)."
+            )
+        if not self.profiles:
+            raise ValueError(
+                "profiles: at least one entry is required (empty/omitted "
+                "is only allowed when launcher.swap.enabled=true and "
+                "launcher.swap.models has at least one entry)."
+            )
+        return self
+
     @model_validator(mode="after")
     def _inject_swap_profiles_and_auto_router_rules(self) -> CodeRouterConfig:
         """§10 Q7 + design-deviation: bootstrap swap's dedicated profiles.

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/docs/backends/launcher.en.md

@@ -225,6 +225,88 @@ All of these are **estimates** — they don't account for other processes' memor
 
 ---
 
+## Automatic model swap (launcher.swap) — v2.9.1+
+
+An equivalent of [llama-swap](https://github.com/mostlygeek/llama-swap)'s core loop, built into CodeRouter itself with no extra dependencies. Opt-in and disabled by default (`enabled: false`).
+
+- Watches the request's `model` name and **starts the backing backend on demand** if it isn't already running
+- **Holds the request** until the model finishes loading — the response is only returned once the process passes its readiness check (no connection-refused / 503 against a still-loading model)
+- **Automatically unloads** an idle process (no in-flight requests) after `ttl_seconds`, freeing memory
+
+### Minimal configuration
+
+```yaml
+# ~/.coderouter/providers.yaml
+default_profile: auto
+
+auto_router:
+  default_rule_profile: launcher-swap-ornith-9b
+  rules: []
+
+launcher:
+  model_dirs:
+    - ~/models
+
+  swap:
+    enabled: true
+    ttl_seconds: 1800
+    readiness_timeout_s: 180
+
+    models:
+      - name: ornith-9b
+        backend: llama.cpp
+        model_path: ~/models/Ornith-1.0-9B-Q4_K_M.gguf
+        port: 18081
+        num_ctx: 32768
+        extra_args: "-ngl 99"
+
+      - name: qwen3-coder-30b
+        backend: llama.cpp
+        model_path: ~/models/Qwen3-Coder-30B-Q4_K_M.gguf
+        port: 18082
+        num_ctx: 32768
+```
+
+Note there's no `providers:` / `profiles:` at all here. **As of v2.9.2**, when `launcher.swap.enabled: true` and `launcher.swap.models` has at least one entry, the top-level `providers` / `profiles` lists can be omitted (or left empty, `[]`) — a `launcher-swap-<name>` profile for each catalog model is auto-injected at config load, and its backing provider is registered at runtime on first on-demand spawn. **Through v2.9.1**, this relaxation didn't exist, so you had to write an unreachable dummy `providers` / `profiles` entry (e.g. `base_url: http://127.0.0.1:9`).
+
+For a more realistic example that mixes swap with an always-on backend like Ollama, see [`examples/providers.swap.yaml`](../../examples/providers.swap.yaml).
+
+### `launcher.swap` fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | bool | `false` | Enable on-demand swap. `false` preserves manual-only startup exactly as before (no impact on existing deployments) |
+| `ttl_seconds` | float \| null | `1800.0` | Seconds of no in-flight requests after which the process is auto-stopped. `null` = disabled (runs until explicitly stopped), `0` = unload as soon as the last request completes. Phase 1 has a single global value only — no per-model override |
+| `readiness_timeout_s` | float | `120.0` (1–1800) | Upper bound (seconds) a **request** will wait for an on-demand spawn to become ready before the dispatch hook raises a retryable `AdapterError`. **Distinct from `launcher.readiness_timeout_s` below (default 300s)** — this one bounds "how long one request waits," that one bounds "the general readiness-monitoring window for a process" |
+| `sweep_interval_s` | float | `15.0` (1–600) | How often the TTL sweeper background task scans for idle processes |
+| `inject_auto_router_rules` | bool | `true` | Whether to auto-generate an `auto_router` rule per catalog model (`id: swap:<name>`, `model_pattern` is an exact match on the name). Set `false` to wire routing yourself (e.g. via the `X-CodeRouter-Profile` header) |
+| `models[].name` | str (required) | — | Logical name matched against the request's `model` field. The provider name and dedicated profile name are automatically `launcher-swap-<name>` |
+| `models[].backend` | `"llama.cpp" \| "vllm" \| "mlx"` (required) | — | Same backend set as the manual Launcher UI |
+| `models[].model_path` | str (required) | — | Absolute or `~`-relative model file path. Must be **under `launcher.model_dirs`** — re-validated both at config load and at spawn time (defense against path traversal) |
+| `models[].port` | int \| null | `null` | Fixed port recommended. When unset, an OS-assigned ephemeral port is used, with one retry on a different port if startup fails (best-effort — no strong TOCTOU guarantee) |
+| `models[].option_profile` | str \| null | `null` | Name of an existing preset in `launcher.option_profiles[backend]`. A name that doesn't exist is a config-load error |
+| `models[].num_ctx` | int | `8192` (≥256) | Baseline used for KV estimation / launch parameters |
+| `models[].extra_args` | str | `""` | One-off extra CLI flags (a single string, parsed with `shlex`; re-specifying the model/draft model is rejected) |
+| `models[].draft_model_path` | str \| null | `null` | Explicit MTP/draft companion gguf |
+| `models[].mtp_mode` | `"auto" \| "off"` | `"auto"` | Same meaning as the manual Launcher UI's **MTP** field |
+| `models[].model_pattern` | str \| null | `null` | Additional regex (`re.fullmatch`) accepted alongside an exact match on `name`. Only affects catalog matching (`SwapManager.match`) — the auto-injected auto_router rule always uses an exact match (`re.escape`) on `name` |
+
+> **Phase 2 fields (schema-declared only, not implemented)**: `models[].group` (`"swap" | "persistent" | "exclusive"`), `models[].est_weights_gb`, `launcher.swap.memory_budget_gb`, and `launcher.swap.max_loaded` exist in the schema but are never consulted by Phase 1 (as of v2.9.1) logic.
+
+### Behavioral notes
+
+- **Swap-managed processes are excluded from `launcher.auto_restart`.** Crash recovery is handled by SwapManager's own re-spawn on the next request, rather than the generic auto-restart supervisor — avoiding two supervisors fighting over the same fixed port
+- **Streaming responses are never TTL-evicted mid-stream.** A "lease" is held until the final chunk is reached, so a process is never killed while it's still generating
+- **A request whose `model` name doesn't match the catalog** falls through to `auto_router.default_rule_profile` (or ordinary profile resolution) — it never reaches a swap-dedicated profile
+- **There's no cap on how many models can be loaded simultaneously** (Phase 1) — as many models as fit in memory can run at once. Budgeting and eviction-based exclusive swap are planned for Phase 2
+- **Omitting `providers` / `profiles` is available as of v2.9.2** (see "Minimal configuration" above). Earlier versions required an unreachable dummy provider/profile
+
+Measured end-to-end (macOS, M3 Max, Metal, ~350MB-class GGUF): the `_run/swap-test/` automated test kit reported ALL PASS across cold spawn (~2s) → warm reuse (~0s, no re-spawn) → catalog-miss fallthrough → TTL unload → respawn. See the design doc's implementation record (§10.5) for details.
+
+For the full design — concurrency model, security considerations, and review decisions — see [`docs/designs/launcher-model-swap.md`](../designs/launcher-model-swap.md).
+
+---
+
 ## Configuration reference
 
 The MODELS list, option profiles, and binary paths are all loaded from the `launcher:` block in `~/.coderouter/providers.yaml`. **Shared between the desktop and Web editions**.
@@ -296,6 +378,23 @@ option_profiles:
 | `bool: true` | `--flag` only (no value) |
 | `bool: false` | this flag is omitted |
 
+### Readiness gating and auto-restart (v2.9.1+)
+
+These fields can be added directly under the `launcher:` block (same level as `model_dirs` / `backends`). They apply to both manual starts and swap's on-demand starts.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `readiness_timeout_s` | float | `300.0` (5–3600) | Maximum seconds to wait for a launched backend to become "ready." For llama.cpp / vllm, that means `GET /health` returns 200; other backends use a bare TCP connect. If the deadline is exceeded, the process is left running but never registered as a provider, and its status becomes `error`. The 5-minute default accounts for large GGUF load times |
+| `readiness_poll_interval_s` | float | `2.0` (0.2–60) | Seconds between readiness probes while a launched backend's status is `loading` |
+| `auto_restart` | bool | `false` | When `true`, a backend that crashes (non-zero exit — after the one-shot MTP startup-crash fallback, if applicable, has already been tried) is automatically relaunched, up to `auto_restart_max_attempts` times with exponential backoff. An intentional stop (the Stop button, or server shutdown) is never treated as a crash. Default `false`, matching the opt-in stance of `ProviderConfig.restart_command`. **Swap-managed processes are excluded** — SwapManager is their sole supervisor |
+| `auto_restart_max_attempts` | int | `3` (0–20) | Maximum consecutive auto-restart attempts before giving up. Resets to 0 once a restarted process passes its readiness check. Ignored when `auto_restart` is `false` |
+| `auto_restart_backoff_s` | float | `2.0` (0.1–300) | Initial backoff (seconds) before the first auto-restart attempt. Doubles on each subsequent attempt, capped at `auto_restart_backoff_max_s` |
+| `auto_restart_backoff_max_s` | float | `30.0` (1–600) | Cap (seconds) on the exponential auto-restart backoff |
+
+**New process status `loading`** — a launched process that's still waiting on its readiness check, alongside `starting` / `running` / `stopped` / `error` in the PROCESSES table. Once readiness passes, it transitions to `running`, and only then is it registered as a provider (previously it was registered the instant the process spawned, so requests could race a model that was still loading and get connection-refused / 503).
+
+> **Behavior change (v2.9.1)**: `POST /api/launcher/start` no longer performs provider sync synchronously — the response's `provider_sync` is always `null`. Check `/api/launcher/processes` or the `provider sync:` log line for the sync result.
+
 ### Extra options (free-form input)
 
 The string in the UI's "Extra options" field is parsed with `shlex.split()` and appended to the end of the command. Use this to try experimental flags not in a profile.
@@ -404,3 +503,4 @@ Restarting CodeRouter reflects it in the UI. `launcher_profiles.yaml.example` is
 - [Architecture details — Launcher section](../concepts/architecture.en.md#launcher--llamacpp--vllm-プロセス管理-v250)
 - [Usage Guide](../guides/usage-guide.md)
 - [llama.cpp direct connection guide](./llamacpp-direct.en.md)
+- [Model auto-swap design doc](../designs/launcher-model-swap.md) — `launcher.swap`'s concurrency model, security considerations, and review decisions

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/docs/backends/launcher.md

@@ -225,6 +225,88 @@ MODELS 一覧の各モデルには、CodeRouter を動かしているマシン
 
 ---
 
+## モデル自動スワップ (launcher.swap) — v2.9.1+
+
+[llama-swap](https://github.com/mostlygeek/llama-swap) 相当の機能を、追加の依存なしで CodeRouter 単体に組み込んだものです。既定は無効(`enabled: false`)の opt-in 機能です。
+
+- リクエストの `model` 名を見て、まだ起動していない backend を**オンデマンドで起動**します
+- モデルのロードが完了するまでリクエストは**保留**され、readiness を通過して初めて応答が返ります(ロード未完了への connection-refused / 503 は起きません)
+- 進行中リクエストが無い状態(アイドル)が `ttl_seconds` 続くと**自動アンロード**してメモリを解放します
+
+### 最小構成
+
+```yaml
+# ~/.coderouter/providers.yaml
+default_profile: auto
+
+auto_router:
+  default_rule_profile: launcher-swap-ornith-9b
+  rules: []
+
+launcher:
+  model_dirs:
+    - ~/models
+
+  swap:
+    enabled: true
+    ttl_seconds: 1800
+    readiness_timeout_s: 180
+
+    models:
+      - name: ornith-9b
+        backend: llama.cpp
+        model_path: ~/models/Ornith-1.0-9B-Q4_K_M.gguf
+        port: 18081
+        num_ctx: 32768
+        extra_args: "-ngl 99"
+
+      - name: qwen3-coder-30b
+        backend: llama.cpp
+        model_path: ~/models/Qwen3-Coder-30B-Q4_K_M.gguf
+        port: 18082
+        num_ctx: 32768
+```
+
+上記は `providers:` / `profiles:` を一切書いていません。**v2.9.2 以降**、`launcher.swap.enabled: true` かつ `launcher.swap.models` が1件以上あれば、トップレベルの `providers` / `profiles` は省略(または空リスト `[]`)で構いません — カタログの各モデルに対応する `launcher-swap-<name>` プロファイルが設定ロード時に自動注入され、対応する provider は初回のオンデマンド起動時にランタイム登録されます。**v2.9.1 まで**はこの緩和が無く、`providers` / `profiles` に到達不能なダミーエントリ(例: `base_url: http://127.0.0.1:9`)を書く必要がありました。
+
+Ollama など常用の backend と併用する、より実運用寄りの設定例は [`examples/providers.swap.yaml`](../../examples/providers.swap.yaml) を参照してください。
+
+### `launcher.swap` フィールド
+
+| フィールド | 型 | 既定値 | 説明 |
+|---|---|---|---|
+| `enabled` | bool | `false` | オンデマンドスワップを有効化。`false` ならこれまで通り手動起動のみ(既存デプロイに影響なし) |
+| `ttl_seconds` | float \| null | `1800.0` | 進行中リクエストが無い状態がこの秒数続くとプロセスを自動停止。`null` = 無効(明示停止まで起動し続ける)、`0` = 最後のリクエスト完了で即アンロード。Phase 1 はグローバル1値のみ(モデル毎の上書きは未対応) |
+| `readiness_timeout_s` | float | `120.0`(1〜1800) | オンデマンド起動したモデルの準備完了を**リクエスト側が待つ**上限秒数。超えると dispatch フックが retryable な `AdapterError` を送出する。**下記の `launcher.readiness_timeout_s`(既定 300s)とは別物** — こちらは「1リクエストが待つ上限」、あちらは「プロセスの readiness 監視全般の上限」 |
+| `sweep_interval_s` | float | `15.0`(1〜600) | TTL 監視(sweeper)がアイドルプロセスを走査する間隔 |
+| `inject_auto_router_rules` | bool | `true` | カタログの各モデル名ごとに `auto_router` ルール(`id: swap:<name>`、`model_pattern` は名前の完全一致)を自動生成するか。`false` にした場合は `X-CodeRouter-Profile` ヘッダ等で自分でルーティングを配線する |
+| `models[].name` | str(必須) | — | リクエストの `model` フィールドと照合される論理名。provider 名・専用プロファイル名は自動的に `launcher-swap-<name>` になる |
+| `models[].backend` | `"llama.cpp" \| "vllm" \| "mlx"`(必須) | — | 手動 Launcher UI と同じバックエンド種別 |
+| `models[].model_path` | str(必須) | — | モデルファイルの絶対または `~` 相対パス。**必ず `launcher.model_dirs` の配下**である必要があり、設定ロード時と起動時の2回検証される(パストラバーサル対策) |
+| `models[].port` | int \| null | `null` | 固定ポート推奨。省略時は OS 割当のエフェメラルポートを使い、起動失敗時に別ポートで1回だけリトライする(best-effort、強い TOCTOU 保証はない) |
+| `models[].option_profile` | str \| null | `null` | `launcher.option_profiles[backend]` の既存プリセット名。存在しない名前を指定すると設定ロード時にエラーになる |
+| `models[].num_ctx` | int | `8192`(≥256) | KV 見積り・起動パラメータの基準値 |
+| `models[].extra_args` | str | `""` | 追加 CLI フラグ(1本の文字列。`shlex` でパース。モデル/draft モデルの再指定は不可) |
+| `models[].draft_model_path` | str \| null | `null` | MTP/draft companion gguf の明示指定 |
+| `models[].mtp_mode` | `"auto" \| "off"` | `"auto"` | 手動 Launcher UI の **MTP** 欄と同じ意味 |
+| `models[].model_pattern` | str \| null | `null` | `name` の完全一致に加えて許容する正規表現(`re.fullmatch`)。カタログ内マッチング(`SwapManager.match`)のみに影響し、自動注入される auto_router ルールは常に `name` の完全一致(`re.escape`)を使う |
+
+> **Phase 2 フィールド(スキーマ宣言のみ・未実装)**: `models[].group`(`"swap" | "persistent" | "exclusive"`)、`models[].est_weights_gb`、`launcher.swap.memory_budget_gb`、`launcher.swap.max_loaded` はスキーマ上は存在しますが、Phase 1(v2.9.1時点)ではロジックから一切参照されません。
+
+### 挙動に関する注記
+
+- **swap プロセスは `launcher.auto_restart` の対象外**です。クラッシュ時の一次的な回復は次のリクエストによる SwapManager 自身の再 spawn に委ねられ、汎用の auto-restart 監督とは重複しません(同じ固定ポートを2つの監督者が取り合う事態を避けるため)
+- **ストリーミング応答中はTTLアンロードされません**。応答の最終チャンクに到達するまで「リース」を保持するため、生成途中でプロセスが停止されることはありません
+- **カタログに一致しない `model` 名**のリクエストは、`auto_router.default_rule_profile`(または通常のプロファイル解決)へフォールスルーします。swap 側の専用プロファイルには到達しません
+- **同時ロード数に上限はありません**(Phase 1)。メモリに載る範囲で複数モデルを同時に起動できます。予算管理・退避を伴う排他 swap は Phase 2 で予定
+- **`providers` / `profiles` の省略は v2.9.2 から**です(上記「最小構成」参照)。それ以前のバージョンでは到達不能なダミーの provider/profile を用意する必要がありました
+
+実機検証(macOS / M3 Max / Metal、350MB級 GGUF): `_run/swap-test/` の自動テストキットで cold spawn(約2秒)→ warm reuse(約0秒、再 spawn なし)→ catalog-miss フォールスルー → TTL unload → respawn の一連が ALL PASS。詳細は設計書の実装記録(§10.5)を参照してください。
+
+並行性モデル・セキュリティ考慮・レビュー決定事項などの設計の詳細は [`docs/designs/launcher-model-swap.md`](../designs/launcher-model-swap.md) を参照してください。
+
+---
+
 ## 設定リファレンス
 
 MODELS 一覧・オプションプロファイル・バイナリパスは `~/.coderouter/providers.yaml` の `launcher:` ブロックから読み込まれます。**デスクトップ版・Web版で共通**です。
@@ -296,6 +378,23 @@ option_profiles:
 | `bool: true` | `--flag` のみ(値なし) |
 | `bool: false` | このフラグを省略 |
 
+### readiness ゲーティングと自動再起動(v2.9.1+)
+
+`launcher:` ブロック直下(`model_dirs` / `backends` と同じ階層)に以下のフィールドを追加できます。手動起動・swap によるオンデマンド起動の両方が対象です。
+
+| フィールド | 型 | 既定値 | 説明 |
+|---|---|---|---|
+| `readiness_timeout_s` | float | `300.0`(5〜3600) | 起動した backend が「準備完了」になるまで待つ最大秒数。llama.cpp / vllm は `GET /health` が 200 を返すこと、それ以外の backend は TCP 接続成功をもって判定する。期限を超えるとプロセスは動かしたまま provider 登録はされず、status が `error` になる。既定 5 分は大きな GGUF のロード時間を見込んだ値 |
+| `readiness_poll_interval_s` | float | `2.0`(0.2〜60) | status が `loading` の間、readiness を再確認する間隔(秒) |
+| `auto_restart` | bool | `false` | `true` にすると、クラッシュ(0 以外の終了コード。MTP起動クラッシュの1回限りの自動フォールバックは別途優先して実行される)した backend を、`auto_restart_max_attempts` 回まで指数バックオフで自動再起動する。Stop ボタンによる意図的停止やサーバーシャットダウンはクラッシュ扱いにならない。既定 `false`(`ProviderConfig.restart_command` と同じ opt-in 方針)。**swap が管理するプロセスは対象外**(SwapManager が唯一の監督者) |
+| `auto_restart_max_attempts` | int | `3`(0〜20) | 自動再起動の最大連続試行回数。再起動したプロセスが readiness を通過すると 0 にリセットされる。`auto_restart: false` のときは無視される |
+| `auto_restart_backoff_s` | float | `2.0`(0.1〜300) | 最初の自動再起動までの初期バックオフ秒数。試行のたびに倍増し `auto_restart_backoff_max_s` で頭打ちになる |
+| `auto_restart_backoff_max_s` | float | `30.0`(1〜600) | 自動再起動バックオフの上限秒数 |
+
+**新しいプロセス status `loading`** — 起動直後で readiness 待ち中の状態です。`starting` / `running` / `stopped` / `error` に加えて PROCESSES テーブルに表示されます。readiness を通過すると `running` に遷移し、そこで初めて provider として登録されます(以前は spawn 直後に登録していたため、ロード未完了へのリクエストが connection-refused / 503 になる不具合がありました)。
+
+> **動作変更(v2.9.1)**: `POST /api/launcher/start` は provider 同期を同期的に行わなくなりました。レスポンスの `provider_sync` は常に `null` です。同期結果は `/api/launcher/processes` またはログの `provider sync:` 行で確認してください。
+
 ### 追加オプション(自由入力)
 
 UI の「追加オプション」欄の文字列は `shlex.split()` でパースされ、コマンド末尾に追加されます。プロファイルに無い実験的なフラグを試すときに使います。
@@ -404,3 +503,4 @@ CodeRouter を再起動すると UI に反映されます。`launcher_profiles.y
 - [アーキテクチャ詳細 — Launcher セクション](../concepts/architecture.md#launcher--llamacpp--vllm-プロセス管理-v250)
 - [利用ガイド](../guides/usage-guide.md)
 - [llama.cpp 直接接続ガイド](./llamacpp-direct.md)
+- [モデル自動スワップ 設計ドキュメント](../designs/launcher-model-swap.md) — `launcher.swap` の並行性モデル・セキュリティ考慮・レビュー決定事項

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/pyproject.toml

@@ -11,7 +11,7 @@
 # in plan.md §11.B; once granted, this name will become an alias and
 # `coderouter` will become the canonical distribution name.
 name = "coderouter-cli"
-version = "2.9.1"
+version = "2.9.2"
 description = "Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible."
 readme = "README.md"
 requires-python = ">=3.12"

{coderouter_cli-2.9.1 → coderouter_cli-2.9.2}/tests/test_launcher_swap.py

@@ -442,15 +442,30 @@ def test_swap_model_provider_and_profile_names() -> None:
 
 
 def _base_config_kwargs(swap_cfg: LauncherSwapConfig) -> dict[str, Any]:
+    """Swap-only config kwargs — ``providers``/``profiles`` start empty.
+
+    [Unreleased]: demonstrates the relaxed ``CodeRouterConfig`` schema
+    (``_check_providers_and_profiles_nonempty``) instead of the old
+    ``min_length=1``-driven dummy ``local`` provider / ``default``
+    profile placeholder that earlier revisions of this fixture carried
+    purely to satisfy the schema — a genuinely swap-only deployment
+    needs neither. ``default_profile`` is ``"auto"`` (the only value
+    exempt from the pre-injection default_profile-exists check) paired
+    with an explicit, empty-rules ``auto_router`` pointed at the first
+    swap model's to-be-injected profile — this sidesteps the bundled
+    ruleset merge path (which would otherwise demand unrelated
+    multi/coding/writing profiles), exactly like the documented
+    swap-only example config.
+    """
+    from coderouter.config.schemas import AutoRouterConfig
+
+    target_profile = swap_cfg.models[0].profile_name if swap_cfg.models else "default"
     return dict(
         allow_paid=False,
-        default_profile="default",
-        providers=[
-            ProviderConfig(
-                name="local", base_url="http://localhost:8080/v1", model="qwen"
-            )
-        ],
-        profiles=[FallbackChain(name="default", providers=["local"])],
+        default_profile="auto",
+        providers=[],
+        profiles=[],
+        auto_router=AutoRouterConfig(rules=[], default_rule_profile=target_profile),
         launcher=LauncherConfig(model_dirs=["/tmp"], swap=swap_cfg),
     )
 
@@ -473,6 +488,9 @@ def test_swap_injects_placeholder_profile_and_auto_router_rule() -> None:
     swap_cfg = LauncherSwapConfig(enabled=True, models=[_spec(name="qwen-coder-14b")])
     cfg = CodeRouterConfig(**_base_config_kwargs(swap_cfg))
 
+    # No static provider/profile was declared at all — swap alone fills
+    # both in (the provider is registered at runtime on first spawn).
+    assert cfg.providers == []
     profile = cfg.profile_by_name("launcher-swap-qwen-coder-14b")
     assert profile.providers == []
 
@@ -485,12 +503,31 @@ def test_swap_injects_placeholder_profile_and_auto_router_rule() -> None:
 
 
 def test_swap_rule_injection_disabled_by_flag() -> None:
+    """Needs a real ``default`` profile (unlike ``_base_config_kwargs``):
+
+    with ``inject_auto_router_rules=False`` swap never builds an
+    ``auto_router`` block, so ``default_profile: auto`` without one would
+    fall onto the *bundled* ruleset's multi/coding/writing requirement —
+    an unrelated concern this test isn't exercising. A normal static
+    profile sidesteps that, independent of the omission feature under
+    test elsewhere in this module.
+    """
     swap_cfg = LauncherSwapConfig(
         enabled=True,
         inject_auto_router_rules=False,
         models=[_spec(name="qwen-coder-14b")],
     )
-    cfg = CodeRouterConfig(**_base_config_kwargs(swap_cfg))
+    cfg = CodeRouterConfig(
+        allow_paid=False,
+        default_profile="default",
+        providers=[
+            ProviderConfig(
+                name="local", base_url="http://localhost:8080/v1", model="qwen"
+            )
+        ],
+        profiles=[FallbackChain(name="default", providers=["local"])],
+        launcher=LauncherConfig(model_dirs=["/tmp"], swap=swap_cfg),
+    )
     # Profile still pre-declared (needed for manual routing)...
     cfg.profile_by_name("launcher-swap-qwen-coder-14b")
     # ...but no rule was generated.
@@ -498,24 +535,146 @@ def test_swap_rule_injection_disabled_by_flag() -> None:
 
 
 def test_swap_rules_appended_after_user_auto_router_rules() -> None:
+    """Needs a real ``default`` profile (unlike ``_base_config_kwargs``):
+
+    the test asserts the user-supplied ``default_rule_profile: "default"``
+    passes through untouched, which requires ``"default"`` to actually be
+    a declared profile (``_check_auto_router_profiles_exist`` would
+    otherwise reject it) — independent of the omission feature under
+    test elsewhere in this module.
+    """
     from coderouter.config.schemas import AutoRouterConfig, AutoRouteRule, RuleMatcher
 
     swap_cfg = LauncherSwapConfig(enabled=True, models=[_spec(name="qwen-coder-14b")])
-    kwargs = _base_config_kwargs(swap_cfg)
-    kwargs["auto_router"] = AutoRouterConfig(
-        rules=[
-            AutoRouteRule(
-                id="user:my-rule", profile="default", match=RuleMatcher(has_image=True)
+    cfg = CodeRouterConfig(
+        allow_paid=False,
+        default_profile="default",
+        providers=[
+            ProviderConfig(
+                name="local", base_url="http://localhost:8080/v1", model="qwen"
             )
         ],
-        default_rule_profile="default",
+        profiles=[FallbackChain(name="default", providers=["local"])],
+        auto_router=AutoRouterConfig(
+            rules=[
+                AutoRouteRule(
+                    id="user:my-rule", profile="default", match=RuleMatcher(has_image=True)
+                )
+            ],
+            default_rule_profile="default",
+        ),
+        launcher=LauncherConfig(model_dirs=["/tmp"], swap=swap_cfg),
     )
-    cfg = CodeRouterConfig(**kwargs)
     ids = [r.id for r in cfg.auto_router.rules]
     assert ids == ["user:my-rule", "swap:qwen-coder-14b"]
     assert cfg.auto_router.default_rule_profile == "default"  # left untouched
 
 
+# ---------------------------------------------------------------------------
+# B2. [Unreleased]: swap-only minimal config — no dummy providers/profiles
+# ---------------------------------------------------------------------------
+
+
+def _write_swap_only_yaml(tmp_path: Path, *, include_empty_lists: bool) -> Path:
+    """The documented swap-only minimal config (top-level ``providers``/
+    ``profiles`` entirely omitted, or present-but-empty — both must load).
+    """
+    model_dir = tmp_path / "models"
+    model_dir.mkdir()
+    (model_dir / "a.gguf").touch()
+    empty_lists = "providers: []\nprofiles: []\n" if include_empty_lists else ""
+    content = f"""\
+default_profile: auto
+{empty_lists}auto_router:
+  default_rule_profile: launcher-swap-m1
+  rules: []
+launcher:
+  model_dirs: ["{model_dir}"]
+  swap:
+    enabled: true
+    models:
+      - name: m1
+        backend: llama.cpp
+        model_path: {model_dir / "a.gguf"}
+        port: 18081
+"""
+    cfg_path = tmp_path / "providers.yaml"
+    cfg_path.write_text(content)
+    return cfg_path
+
+
+def test_swap_only_config_loads_with_omitted_providers_and_profiles(
+    tmp_path: Path,
+) -> None:
+    """[Unreleased]: providers/profiles can be left out of the YAML entirely
+    for a swap-only deployment — no unreachable dummy entry required."""
+    from coderouter.config.loader import load_config
+
+    cfg = load_config(_write_swap_only_yaml(tmp_path, include_empty_lists=False))
+    assert cfg.providers == []
+    assert cfg.profile_by_name("launcher-swap-m1").providers == []
+    assert cfg.auto_router is not None
+    assert cfg.auto_router.default_rule_profile == "launcher-swap-m1"
+
+
+def test_swap_only_config_loads_with_explicit_empty_lists(tmp_path: Path) -> None:
+    """Same minimal config, but with ``providers: []`` / ``profiles: []``
+    spelled out explicitly — identical result to omitting them."""
+    from coderouter.config.loader import load_config
+
+    cfg = load_config(_write_swap_only_yaml(tmp_path, include_empty_lists=True))
+    assert cfg.providers == []
+    assert cfg.profile_by_name("launcher-swap-m1").providers == []
+    assert cfg.auto_router is not None
+    assert cfg.auto_router.default_rule_profile == "launcher-swap-m1"
+
+
+def test_empty_providers_without_swap_still_rejected() -> None:
+    """Regression: swap disabled + empty providers -> still a load-time
+    ValidationError (the min_length=1 fail-fast guarantee is preserved,
+    just moved into ``_check_providers_and_profiles_nonempty``)."""
+    with pytest.raises(ValidationError, match="providers"):
+        CodeRouterConfig(
+            allow_paid=False,
+            default_profile="auto",
+            providers=[],
+            profiles=[FallbackChain(name="default", providers=["local"])],
+            auto_router=None,
+        )
+
+
+def test_empty_profiles_without_swap_still_rejected() -> None:
+    """Regression: swap disabled + empty profiles -> still a load-time
+    ValidationError."""
+    with pytest.raises(ValidationError, match="profiles"):
+        CodeRouterConfig(
+            allow_paid=False,
+            default_profile="default",
+            providers=[
+                ProviderConfig(
+                    name="local", base_url="http://localhost:8080/v1", model="qwen"
+                )
+            ],
+            profiles=[],
+        )
+
+
+def test_empty_providers_and_profiles_rejected_when_swap_models_empty() -> None:
+    """Regression: swap enabled but its catalog is empty -> the relaxation
+    does not kick in (matches spec: models must have >=1 entry)."""
+    with pytest.raises(ValidationError, match="providers"):
+        CodeRouterConfig(
+            allow_paid=False,
+            default_profile="auto",
+            providers=[],
+            profiles=[],
+            auto_router=None,
+            launcher=LauncherConfig(
+                model_dirs=["/tmp"], swap=LauncherSwapConfig(enabled=True, models=[])
+            ),
+        )
+
+
 # ---------------------------------------------------------------------------
 # C. End-to-end via TestClient — real spawn, real local stub HTTP server
 # ---------------------------------------------------------------------------